Files
Django_TasksApp/main/mcp_server/TOOL_AUDIT.md
T

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.