122 lines
7.8 KiB
Markdown
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.
|