7.8 KiB
MCP tool catalog audit
Card: Audit all TasksNest MCP tools
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.