Files
Django_TasksApp/docs/mcp/tools.md
T

20 KiB
Raw Blame History

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.