7.3 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.