Files
Django_TasksApp/main/mcp_server/TOOL_AUDIT.md
T

122 lines
7.8 KiB
Markdown

# MCP tool catalog audit
Card: [Audit all TasksNest MCP tools](https://projects.jorendegraaf.eu/projects/cards/358cce5d-056c-43b6-ae24-9ebf79fad64a/)
## Baseline, 3 November 2026
`python3 main/mcp_server/tool_catalog_audit.py` extracts the current registrations in
`server.py` into `tool_catalog_baseline.json`. The baseline contains **93 tools**,
with no duplicate names or empty descriptions. It records the declared parameter
names and direct API calls. `food_attach_image` uses the `_attach` helper; 42 tools
have at least one dynamic API path, so their recorded expressions require manual
review.
This is a source inventory, not a verified live MCP discovery snapshot. The existing
descriptions and inferred API methods must not be treated as verified scopes,
side effects, response schemas, or client behavior.
## Review tracker
| Batch | Scope | Status | Required evidence |
| --- | --- | --- | --- |
| 1 | Food diary, products, hydration | Scope mapping complete; first discovery changes tested; contract review pending | Input/output schemas, read/write/error responses |
| 2 | Inventory, grocery, housekeeping | Source scope mapping complete; first discovery changes tested | Response contracts, destructive confirmation, retries |
| 3 | Recipes and nutrition import | Source scope mapping complete; discovery preview scopes tested | Ownership, dietary warnings, provenance, response contracts |
| 4 | Journals and dietary preferences | Source scope mapping complete | Sensitive response contracts, time zones, archive/delete semantics |
| 5 | Cross-client discovery | Pending | Live list-tools snapshot, ChatGPT and Codex checks |
For each tool, verify the actual handler and response before changing metadata.
Record purpose, use and avoid cases, a natural-language example, required scope,
side effects, retry behavior, error response, and schema gaps. Preserve existing
client contracts unless a separately reviewed migration is necessary.
## Batch 1: verified endpoint scope and impact
The scope column comes from the Django `@api_view` decorator on the routed
endpoint, including the method-specific scope for shared endpoints. All results
are owner-scoped through the bearer token. `food_log_with_image` makes two
requests, so an attachment failure can follow a successful log creation.
| Tools | Scope | Impact / retry note |
| --- | --- | --- |
| `food_get_today`, `food_search_products`, `food_lookup_product` | `food:read` | Read only; lookup may call Open Food Facts |
| `food_create_product`, `food_import_product` | `food:write` | Create/reuse product; pass the same idempotency key on retry |
| `food_log` | `food:write` | Creates diary entry; exact package consumption only when explicitly requested |
| `food_update_entry`, `food_delete_entry` | `food:write` | Changes or deletes owned entry; deletion also removes attachments |
| `food_attach_image` | `food:write` | Adds private attachment to an owned entry; same key on retry |
| `food_log_with_image` | `food:write` | Creates entry then attaches image; inspect partial result before retry |
| `hydration_get_daily`, `hydration_settings_get` | `food:read` | Read only |
| `hydration_log`, `hydration_update`, `hydration_delete`, `hydration_settings_update` | `food:write` | Change manual entries or settings; creation supports idempotency key |
Source references: `main/food/api_urls.py`, `main/food/api.py`, and
`main/mcp_server/server.py`. The API returns structured `{error: {code, message}}`
for authentication, scope, validation and domain errors. The MCP adapter converts
most HTTP errors into `ToolError`; `food_import_product` is an exception that
returns a `{status: failed, reason}` result. Response schemas remain broadly
typed as `dict[str, Any]` in the adapter and need response-specific review.
### First implementation pass
Expanded the server description to identify its domains, OAuth scope rule and
confirmation/retry safeguards. Updated product search, lookup and import
descriptions to distinguish their use cases and scopes, and made the manual
hydration delete tool state the required user intent. `test_tool_catalog.py`
checks that the static inventory matches registered tools and that these
discovery cues appear in the registered metadata. This pass changes metadata
only; it does not alter tool arguments, response envelopes or API behavior.
## Batch 2: verified endpoint scope and impact
Inventory and grocery operations use `inventory:read` for reads and
`inventory:write` for mutations. Two read-only previews (`inventory_preview_consumption`
and `housekeeping_preview`) use POST but are governed by different scopes:
`inventory:read` and `inventory:write` respectively. The latter can prepare a
short-lived confirmation but does not apply changes. These distinctions come
from the routed Django `@api_view` decorators.
| Tools | Scope | Impact / use |
| --- | --- | --- |
| `inventory_list`, `inventory_search`, `inventory_get_stock`, `inventory_preview_consumption` | `inventory:read` | Read stock or preview a deduction |
| `inventory_add`, `inventory_import_groceries`, `inventory_update`, `inventory_bulk_update`, `inventory_bulk_delete`, `inventory_remove`, `inventory_consume`, `inventory_undo_consumption` | `inventory:write` | Change owned stock; bulk tools default to preview |
| `grocery_list`, `grocery_search`, `grocery_add_recipe` with `confirm=false` | `inventory:read` | Read shopping list or preview recipe needs |
| `grocery_add`, `grocery_edit`, `grocery_delete`, `grocery_add_recipe` with `confirm=true` | `inventory:write` | Change shopping list, never stock |
| `housekeeping_search`, `housekeeping_scan`, `housekeeping_history` | `inventory:read` | Discover candidates or read audit history |
| `housekeeping_preview`, `housekeeping_apply` | `inventory:write` | Preview or apply reviewed rename, merge, classification or link change |
Discovery text now calls out the inventory preview scope, separates stock from
shopping list operations, and directs stock consumption through a preview.
Response shapes and domain error contracts still require individual review.
## Batches 3 and 4: source permission audit
The recipe API uses `food:read` for search, get, link listing, cook-later
listing and component composition preview. Recipe creation, update, deletion,
variation, ingredients, links, cook-later changes, subrecipes and meal logging
use `food:write`. Recipe stock preview uses `inventory:read`; stock confirm
and undo use `inventory:write`. Grocery recipe preview/confirmation is covered
in batch 2. Composition preview uses POST but is read scoped.
Nutrition source ingredient/search/review reads use `food:read`.
Import preview and commit, ingredient correction, exclusion changes and recipe
feedback use `food:write`. Import preview uses POST and write scope but creates
no records. Its description now exposes that prerequisite.
Stress and dream collection/item reads use `journal:read`; create, update and
delete use `journal:write`. Dietary preference, exception, audit and recipe
evaluation reads use `dietary_preferences:read`; create, update and archive
use `dietary_preferences:write`. A token without dietary read scope cannot
implicitly evaluate a recipe against private preferences.
These are endpoint-source observations, not yet evidence that every client
receives accurate machine-readable output schemas. The adapter still advertises
generic object outputs for most tools.
## Output schema pass
The registered catalog initially advertised 93 generic object output schemas.
Three simple deletion results now have explicit required fields: `food_delete_entry`
returns `success` and `deleted_entry_id`; `inventory_remove` returns `success`
and `removed_item_id`; `hydration_delete` returns `deleted`. These shapes match
the adapter's returned objects or the routed Django response. The other tools
still need individual response review before narrowing their schemas.