Files

162 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Registered MCP tools
Source: `main/mcp_server/server.py` through `create_server()`, extracted by `main/mcp_server/tool_catalog_audit.py`. **93 tool decorators are registered in the current working tree.** This is a registration inventory; server-side API validation and scope checks remain authoritative. Parameters below are top-level names; typed nested fields and bounds are in `server.py`.
| Domain | Count |
| --- | ---: |
| dietary | 10 |
| dream | 5 |
| food | 10 |
| grocery | 6 |
| housekeeping | 5 |
| hydration | 6 |
| inventory | 12 |
| nutrition | 10 |
| recipe | 24 |
| stress | 5 |
## Dietary
| Tool | Purpose | Top-level parameters | API method/path |
| --- | --- | --- | --- |
| `dietary_preference_archive` | Archive an owned dietary preference after explicit confirmation | `preference_id`, `expected_revision`, `confirmed` | POST `f'dietary-preferences/{preference_id}/archive/'` |
| `dietary_preference_create` | Create a user-reported dietary or cooking preference only after the user explicitly confirms this exact proposed record | `category`, `target_type`, `target_name`, `enforcement`, `idempotency_key`, `impact_description`, `notes`, `confirmed` | POST `'dietary-preferences/'` |
| `dietary_preference_exception_add` | Add a narrow, exact product or food tolerance exception to an owned preference after explicit confirmation | `preference_id`, `target_name`, `idempotency_key`, `product_id`, `quantity`, `unit`, `preparation`, `form`, `conditions`, `notes`, `confirmed` | POST `f'dietary-preferences/{preference_id}/exceptions/'` |
| `dietary_preference_exception_archive` | Archive an owned exact tolerance exception after explicit confirmation | `preference_id`, `exception_id`, `expected_revision`, `confirmed` | POST `f'dietary-preferences/{preference_id}/exceptions/{exception_id}/'` |
| `dietary_preference_exception_update` | Correct an owned exact tolerance exception after explicit user confirmation | `preference_id`, `exception_id`, `expected_revision`, `changes`, `confirmed` | PATCH `f'dietary-preferences/{preference_id}/exceptions/{exception_id}/'` |
| `dietary_preference_update` | Update an owned dietary preference after explicit confirmation | `preference_id`, `expected_revision`, `changes`, `confirmed` | PATCH `f'dietary-preferences/{preference_id}/'` |
| `dietary_preferences_evaluate_recipe` | Evaluate one owned recipe against your saved dietary preferences | `recipe_id` | GET `'dietary-preferences/evaluate-recipe/'` |
| `dietary_preferences_get` | Read one of your own dietary preferences and its exact exceptions | `preference_id` | GET `f'dietary-preferences/{preference_id}/'` |
| `dietary_preferences_history` | Read bounded, content-free history of your dietary preference and exception changes | `limit`, `offset` | GET `'dietary-preferences/audit/'` |
| `dietary_preferences_list` | Read your own dietary and cooking preferences, including exact exceptions | `active_only`, `limit`, `offset` | GET `'dietary-preferences/'` |
## Dream
| Tool | Purpose | Top-level parameters | API method/path |
| --- | --- | --- | --- |
| `dream_create` | Create a private dream for its wake-up date | `entry`, `idempotency_key` | POST `'dreams/'` |
| `dream_delete` | Permanently delete an owned dream entry by ID | `entry_id` | DELETE `f'dreams/{entry_id}/'` |
| `dream_get` | Read one private dream entry by ID, including its original narrative and separately stored interpretation | `entry_id` | GET `f'dreams/{entry_id}/'` |
| `dream_search` | List or search your private dreams by keywords, tag, wake-up date or date range | `query`, `tag`, `date`, `date_from`, `date_to`, `limit`, `offset` | GET `'dreams/'` |
| `dream_update` | Update or append user-supplied corrections to an existing owned dream ID | `entry_id`, `changes`, `idempotency_key` | PATCH `f'dreams/{entry_id}/'` |
## Food
| Tool | Purpose | Top-level parameters | API method/path |
| --- | --- | --- | --- |
| `food_attach_image` | Attach a client-supplied JPEG, PNG, or WebP image to one owned food entry | `entry_id`, `image_base64`, `image_file`, `mime_type`, `filename`, `caption`, `idempotency_key` | via helper (`_attach`) |
| `food_create_product` | Create a manual food product owned by the authenticated user from supplied facts | `product`, `idempotency_key` | POST `'food/products/create/'` |
| `food_delete_entry` | Permanently delete one food log entry belonging to the authenticated user | `entry_id` | DELETE `f'food/log/{entry_id}/'` |
| `food_get_today` | Read the authenticated user’s food diary for a specific local calendar day, grouped by meal with totals, goals, and remaining calories/macros | `date` | GET `'food/today/'` |
| `food_import_product` | Save a selected Open Food Facts product by numeric barcode into your product catalogue | `barcode`, `idempotency_key` | POST `'food/products/import/'` |
| `food_log` | Create one Food Diary entry | `food`, `idempotency_key` | POST `'food/log/'` |
| `food_log_with_image` | Create one food entry and attach the user-supplied image in one operation | `food`, `image_base64`, `image_file`, `mime_type`, `filename`, `caption`, `idempotency_key` | POST `'food/log/'` |
| `food_lookup_product` | Find food product candidates in saved products and optionally Open Food Facts | `query`, `barcode`, `brand`, `package_quantity`, `package_unit`, `limit`, `include_open_food_facts` | GET `'food/products/lookup/'` |
| `food_search_products` | Search the authenticated user’s saved TaskNest food products before logging a known food | `query`, `limit`, `include_dietary_context` | GET `'food/products/'` |
| `food_update_entry` | Update only the supplied fields of one owned food log entry by opaque ID | `entry_id`, `changes` | PATCH `f'food/log/{entry_id}/'` |
## Grocery
| Tool | Purpose | Top-level parameters | API method/path |
| --- | --- | --- | --- |
| `grocery_add` | Add one item to your grocery list | `item`, `idempotency_key` | POST `'groceries/'` |
| `grocery_add_recipe` | Preview or confirm missing ingredients for an owned recipe, scaled to servings and selected substitutions | `recipe_id`, `options`, `confirm`, `confirm_uncertain`, `idempotency_key` | POST `f'groceries/recipe/{recipe_id}/'`; GET `f'groceries/recipe/{recipe_id}/'` |
| `grocery_delete` | Delete one owned grocery item by stable UUID | `item_id` | DELETE `f'groceries/{item_id}/'` |
| `grocery_edit` | Edit an owned grocery item, including purchase status | `item_id`, `changes` | PATCH `f'groceries/{item_id}/'` |
| `grocery_list` | List your grocery items by needed, purchased, or all status | `status`, `limit`, `offset` | GET `'groceries/'` |
| `grocery_search` | Search your grocery list by text, category, product, and purchase status | `query`, `category`, `product_id`, `status`, `limit`, `offset` | GET `'groceries/'` |
## Housekeeping
| Tool | Purpose | Top-level parameters | API method/path |
| --- | --- | --- | --- |
| `housekeeping_apply` | Apply a recent owner-scoped housekeeping preview after explicit confirmation | `confirmation`, `idempotency_key`, `confirmed_same_entity`, `confirmed_link` | POST `'housekeeping/apply/'` |
| `housekeeping_history` | Read the authenticated user’s housekeeping audit history | `limit`, `offset` | GET `'housekeeping/history/'` |
| `housekeeping_preview` | Preview an owned location/category rename or merge, a category reclassification, a canonical ingredient category/subcategory/descriptive-tag correction, or a canonical ingredient link/unlink | `dataset`, `action`, `source_id`, `new_name`, `target_id`, `target_dataset`, `relation_type`, `confidence`, `new_category`, `new_subcategory`, `new_tags` | POST `'housekeeping/preview/'` |
| `housekeeping_scan` | Scan owned records for label variants, missing categories and unlinked recipe ingredients | `dataset`, `limit`, `offset`, `candidate_type` | GET `'housekeeping/scan/'` |
| `housekeeping_search` | Search owned locations, categories, products, recipes, canonical ingredients, recipe ingredients, inventory items, source suggestions, recipe tags or reviewed ingredient links | `dataset`, `query`, `exact`, `limit`, `offset`, `category`, `status`, `min_confidence` | GET `'housekeeping/search/'` |
## Hydration
| Tool | Purpose | Top-level parameters | API method/path |
| --- | --- | --- | --- |
| `hydration_delete` | Delete an owned standalone manual hydration entry by ID | `entry_id` | DELETE `f'hydration/manual/{entry_id}/'` |
| `hydration_get_daily` | Read combined daily hydration, separate manual and Food Diary drink contributions, the daily goal, and remaining amount | `date` | GET `'hydration/daily/'` |
| `hydration_log` | Add a standalone manual fluid entry | `amount_ml`, `beverage_type`, `recorded_at`, `idempotency_key` | POST `'hydration/manual/'` |
| `hydration_settings_get` | Read hydration goal and automatic drink counting settings for the authenticated user. | — | GET `'hydration/settings/'` |
| `hydration_settings_update` | Update hydration goal, automatic Food Diary drink counting, liquid-food inclusion, widget breakdown, manual adjustment permission, or beverage-specific rules. | `changes` | PATCH `'hydration/settings/'` |
| `hydration_update` | Correct an owned standalone manual hydration entry by ID | `entry_id`, `amount_ml`, `beverage_type`, `recorded_at` | PATCH `f'hydration/manual/{entry_id}/'` |
## Inventory
| Tool | Purpose | Top-level parameters | API method/path |
| --- | --- | --- | --- |
| `inventory_add` | Add an owned saved food product to the authenticated user’s kitchen inventory | `product_id`, `quantity`, `location`, `category`, `notes`, `opened`, `best_before`, `original_amount`, `unit`, `pieces_per_package`, `remaining_pieces`, `piece_amount`, `inner_packs_per_package`, `pieces_per_inner_pack`, `inner_pack_amount`, `inner_pack_label`, `piece_label`, `idempotency_key` | POST `'kitchen/items/'` |
| `inventory_bulk_delete` | Preview or archive up to 20 explicit owned inventory rows, without deleting products or consumption history | `item_ids`, `idempotency_key`, `dry_run`, `confirm`, `atomic` | POST `'kitchen/bulk-delete/'` |
| `inventory_bulk_update` | Preview or update up to 50 owned inventory rows | `items`, `idempotency_key`, `dry_run`, `atomic` | POST `'kitchen/bulk-update/'` |
| `inventory_consume` | Consume an exact quantity from owned inventory packages atomically | `product_id`, `amount`, `unit`, `idempotency_key`, `package_id`, `source_reference`, `description`, `allow_partial` | POST `'kitchen/consumption/'` |
| `inventory_get_stock` | Read stock for an owned product ID or search query, optionally limited to a location ID | `product_id`, `query`, `location_id` | GET `'kitchen/stock/'` |
| `inventory_import_groceries` | Add up to 20 groceries to your inventory in one operation | `items`, `idempotency_key`, `create_missing_products` | POST `'kitchen/import-groceries/'` |
| `inventory_list` | List a bounded page of the authenticated user’s current kitchen inventory | `limit`, `offset`, `include_dietary_context` | GET `'kitchen/items/'` |
| `inventory_preview_consumption` | Preview package deductions for one owned product without changing stock | `product_id`, `amount`, `unit`, `package_id` | POST `'kitchen/consumption/preview/'` |
| `inventory_remove` | Permanently remove one kitchen inventory item belonging to the authenticated user | `item_id` | DELETE `f'kitchen/items/{item_id}/'` |
| `inventory_search` | Search the authenticated user’s current kitchen inventory by food name, brand, barcode, location, or category | `query`, `limit`, `include_dietary_context` | GET `'kitchen/items/'` |
| `inventory_undo_consumption` | Undo a previous owned inventory consumption transaction when its affected packages have not changed since | `transaction_id` | POST `f'kitchen/consumption/{transaction_id}/undo/'` |
| `inventory_update` | Update only supplied inventory fields | `item_id`, `changes` | PATCH `f'kitchen/items/{item_id}/'` |
## Nutrition
| Tool | Purpose | Top-level parameters | API method/path |
| --- | --- | --- | --- |
| `nutrition_find_meals` | Find existing owned recipes with exact ingredient-name or saved-alias matches to one imported nutrition source | `source_id`, `limit`, `offset`, `include_dietary_context` | GET `'nutrition/find-meals/'` |
| `nutrition_import_commit` | Commit exactly the previously previewed structured PDF extraction after explicit user approval | `payload`, `confirmation`, `idempotency_key` | POST `'nutrition/commit/'` |
| `nutrition_import_preview` | Read-only preview of one PDF (payload {source, ingredients}) or a batch of 1–10 PDFs (payload {documents:[{source, ingredients}]}), up to 100 rows total | `payload` | POST `'nutrition/preview/'` |
| `nutrition_ingredient_correct` | Manually correct the category, subcategory or aliases of one owned canonical ingredient after review | `ingredient_id`, `changes` | PATCH `f'nutrition/ingredients/{ingredient_id}/'` |
| `nutrition_ingredients_search` | Search your source-suggested canonical ingredients with category, source/week and frequency filters | `category`, `subcategory`, `programme`, `query`, `form`, `verified`, `inventory_status`, `source_id`, `week_start`, `week_end`, `minimum_frequency`, `excluded_only`, `limit`, `offset`, `include_links` | GET `'nutrition/ingredients/'` |
| `nutrition_recipe_feedback` | Record the authenticated user’s explicit decision on an existing owned recipe for one imported nutrition source | `source_id`, `recipe_id`, `decision`, `notes`, `adapted_recipe_id` | POST `'nutrition/recipe-feedback/'` |
| `nutrition_recipe_reviews` | Read persisted recipe decisions for the authenticated user, optionally filtered to one nutrition source, recipe, or decision | `source_id`, `recipe_id`, `decision`, `limit`, `offset` | GET `'nutrition/recipe-reviews/'` |
| `nutrition_source_get` | Read one owned source document record and its original ingredient occurrences, including source label, quantity, preparation, page and linked catalogue product | `source_id` | GET `f'nutrition/sources/{source_id}/'` |
| `nutrition_sources_list` | List owner-scoped Body Support/nutrition source documents with week dates, batch IDs, import time and row counts | `programme`, `week_start`, `week_end`, `limit`, `offset` | GET `'nutrition/sources/'` |
| `nutrition_suggestion_exclusion` | Exclude or restore one canonical ingredient in future suggestions after explicit user confirmation | `ingredient_id`, `excluded`, `idempotency_key`, `confirmed`, `note` | POST `'nutrition/suggestion-exclusions/'` |
## Recipe
| Tool | Purpose | Top-level parameters | API method/path |
| --- | --- | --- | --- |
| `recipe_check_inventory` | Check scaled ingredient availability and nutrition, with exact package deductions | `recipe_id`, `options` | POST `f'recipes/{recipe_id}/stock/preview/'` |
| `recipe_composition_create` | Create a new draft recipe that explicitly includes selected owned component recipes | `composition`, `idempotency_key` | POST `'recipes/compositions/'` |
| `recipe_composition_preview` | Preview an explicitly selected set of owned component recipes | `components` | POST `'recipes/compositions/preview/'` |
| `recipe_cook_later_add` | Save one owned recipe to your Cook Later list | `recipe_id` | POST `'recipes/cook-later/'` |
| `recipe_cook_later_list` | List your Cook Later recipes with stable recipe IDs, titles, summaries and save dates | `search`, `limit`, `offset` | GET `'recipes/cook-later/'` |
| `recipe_cook_later_remove` | Remove one owned recipe from your Cook Later list | `recipe_id` | DELETE `f'recipes/cook-later/{recipe_id}/'` |
| `recipe_create` | Create an owned recipe | `recipe`, `idempotency_key` | POST `'recipes/create/'` |
| `recipe_create_variation` | Create an independently editable copy linked as a variation of the owned recipe | `recipe_id`, `title`, `idempotency_key` | POST `f'recipes/{recipe_id}/variations/'` |
| `recipe_deduct_inventory` | Deduct the exact recipe packages approved in a recent recipe_check_inventory preview | `recipe_id`, `confirmation` | POST `f'recipes/{recipe_id}/stock/confirm/'` |
| `recipe_delete` | Delete one owned recipe and its ingredients | `recipe_id` | DELETE `f'recipes/{recipe_id}/'` |
| `recipe_get` | Read one owned recipe with Markdown instructions, ingredients, substitutions, related variations, and subrecipes | `recipe_id`, `include_dietary_context` | GET `f'recipes/{recipe_id}/'` |
| `recipe_ingredient_add` | Add a measured ingredient to one owned recipe | `recipe_id`, `ingredient`, `idempotency_key` | POST `f'recipes/{recipe_id}/ingredients/'` |
| `recipe_ingredient_delete` | Remove one ingredient from an owned recipe | `recipe_id`, `ingredient_id` | DELETE `f'recipes/{recipe_id}/ingredients/{ingredient_id}/'` |
| `recipe_ingredient_update` | Correct only the supplied fields of an ingredient in an owned recipe. | `recipe_id`, `ingredient_id`, `changes` | PATCH `f'recipes/{recipe_id}/ingredients/{ingredient_id}/'` |
| `recipe_link_create` | Create a one-way or reciprocal suggestion between two owned recipes | `recipe_id`, `link`, `idempotency_key` | POST `f'recipes/{recipe_id}/links/'` |
| `recipe_link_list` | List up to 100 linked recipe suggestions for an owned recipe | `recipe_id` | GET `f'recipes/{recipe_id}/links/'` |
| `recipe_link_remove` | Remove an owned suggestion link | `recipe_id`, `link_id` | DELETE `f'recipes/{recipe_id}/links/{link_id}/'` |
| `recipe_link_update` | Edit the relationship, note, or reciprocal visibility of an owned recipe link. | `recipe_id`, `link_id`, `changes` | PATCH `f'recipes/{recipe_id}/links/{link_id}/'` |
| `recipe_log_meal` | Log a personally consumed portion of an owned recipe using a historical nutrition snapshot | `recipe_id`, `consumed_servings`, `meal`, `servings`, `date`, `time`, `include_optional`, `substitutions`, `confirm_dietary`, `idempotency_key` | POST `f'recipes/{recipe_id}/log/'` |
| `recipe_search` | Search your own recipes by title, description, or ingredient name | `query`, `category`, `limit`, `include_nutrition_context`, `include_dietary_context`, `body_support` | GET `'recipes/'` |
| `recipe_subrecipe_add` | Attach another owned recipe as a reusable subrecipe | `recipe_id`, `component_id`, `quantity`, `unit`, `note`, `idempotency_key` | POST `f'recipes/{recipe_id}/subrecipes/'` |
| `recipe_subrecipe_remove` | Remove one reusable subrecipe link from an owned recipe; the component recipe remains. | `recipe_id`, `subrecipe_id` | DELETE `f'recipes/{recipe_id}/subrecipes/{subrecipe_id}/'` |
| `recipe_undo_inventory` | Undo a confirmed recipe inventory deduction when the affected packages have not changed since | `stock_use_id` | POST `f'recipes/stock-use/{stock_use_id}/undo/'` |
| `recipe_update` | Update supplied fields of one owned recipe, including Markdown and serving yield | `recipe_id`, `changes` | PATCH `f'recipes/{recipe_id}/'` |
## Stress
| Tool | Purpose | Top-level parameters | API method/path |
| --- | --- | --- | --- |
| `stress_create` | Create a private 0–10 stress check-in | `entry`, `idempotency_key` | POST `'stress/'` |
| `stress_delete` | Permanently delete one owned stress check-in | `entry_id` | DELETE `f'stress/{entry_id}/'` |
| `stress_get` | Read one stress check-in owned by the authenticated user using its ID | `entry_id` | GET `f'stress/{entry_id}/'` |
| `stress_search` | Search or list your private stress check-ins | `query`, `date`, `timing`, `limit`, `offset` | GET `'stress/'` |
| `stress_update` | Update only supplied fields of one owned stress check-in | `entry_id`, `changes` | PATCH `f'stress/{entry_id}/'` |
Errors: `api_request()` converts Django JSON `error.code` and `error.message` into MCP `ToolError`; transport failures and unexpected redirects have separate messages. Actual output shapes vary by endpoint. Structured output is requested on every tool decorator; inspect `main/food/api_schema.py` and endpoint tests for contracts.