Reference / 16 tools
Tool reference
Authenticate once, then coordinate recipe reads, validated writes, shopping data, and calendar actions through purpose-built MCP calls.
Call connect_to_cookidoo before any tool that accesses Cookidoo. Most failures are returned as descriptive strings rather than raised through MCP.
Safe changes
Preview before you apply
Every tool that creates or changes a recipe, image, or meal-plan entry accepts dry_run. Call it with dry_run=true first to validate the input and receive will_mutate: false, the exact target, planned changes, and safety notes. Review the JSON, then repeat the same call with dry_run=false to apply it.
An image preview reads and converts the local file in memory to verify its format and size, but does not upload or attach it.
Authentication
connect_to_cookidoo
connect_to_cookidoo()
Loads COOKIDOO_EMAIL and COOKIDOO_PASSWORD, validates the optional COOKIDOO_COUNTRY and COOKIDOO_LANGUAGE pair (default ro + en), creates the shared cookie-authenticated session, and stores it for later tools.
Returns: a success message containing the configured login identifier, or a configuration/authentication error.
Recipe read
get_recipe_details
get_recipe_details(recipe_id: str)
Reads an official recipe’s name, serving size, times, difficulty, ingredient descriptions, image, thumbnail, and URL.
| Parameter | Description |
|---|---|
recipe_id | Official ID such as r460132. |
The official details endpoint genuinely omits instructions. Use copy_recipe_to_custom when full steps are required.
Recipe read
get_custom_recipe_details
get_custom_recipe_details(recipe_id: str)
Reads full ingredients, instructions, tools, timings, servings, image data, and URL from a customer recipe.
Returns: formatted JSON with ingredients and steps.
Shopping
get_shopping_list_ingredients
get_shopping_list_ingredients(recipe_id=None, include_owned=False, include_additional_items=True)
| Parameter | Description |
|---|---|
recipe_id | Optional exact shopping-list recipe ID. |
include_owned | Include ingredients marked as already owned. |
include_additional_items | Include manually added shopping items. |
Returns: JSON containing recipe groups, a flat ingredient list, additional items, and summary counts.
Meal planning
get_meal_plan_week
get_meal_plan_week(date: str)
Reads the rolling seven-day window beginning on the supplied ISO date and resolves private recipe IDs to names and images.
Example date: 2026-07-29.
Meal planning
add_recipes_to_meal_plan
add_recipes_to_meal_plan(date, recipe_ids, recipe_source="auto", dry_run=false)
| Parameter | Description |
|---|---|
date | Target day in YYYY-MM-DD format. |
recipe_ids | Comma, whitespace, or newline-separated IDs. |
recipe_source | auto, official, or custom. |
dry_run | Validate and preview without changing the calendar. |
Mixed official and customer IDs are partitioned into the correct Cookidoo calls.
Meal planning
remove_recipe_from_meal_plan
remove_recipe_from_meal_plan(date, recipe_id, recipe_source="auto", dry_run=false)
Removes one official or customer recipe from one day and refreshes the resulting day state.
Meal planning
move_recipe_in_meal_plan
move_recipe_in_meal_plan(recipe_id, from_date, to_date, recipe_source="auto", dry_run=false)
Adds to the target day first, removes from the source second, and rolls back a newly added target entry if source removal fails.
Recipe copy
copy_recipe_to_custom
copy_recipe_to_custom(recipe_id: str, servings: int = 4, dry_run: bool = false)
Copies an official recipe into the account’s private customer recipes. The returned copy includes full ingredients and instructions, making it the standard starting point for translation and guided-cooking enhancement.
Use dry_run=true to inspect the planned copy first, then apply only when you want the private recipe to remain in your account.
Recipe generation
generate_recipe_structure
generate_recipe_structure(name, ingredients, steps, servings=4, prep_time=30, total_time=60, hints="")
Parses newline-separated ingredients and steps, creates a validated recipe model, and returns upload-ready JSON. Input times are minutes; Cookidoo request times are converted to seconds.
Validation
validate_guided_recipe_structure
validate_guided_recipe_structure(recipe_json: str)
Validates the complete custom-recipe schema, annotation positions, allowed settings, and the mandatory separation between ingredient handling and machine actions.
Validation
calculate_annotation_position
calculate_annotation_position(text, marker, occurrence=1)
Finds the requested marker occurrence and returns the offset and length in JavaScript UTF-16 code units. Use it whenever emoji or other non-BMP characters may appear before an annotation.
Recipe write
update_custom_recipe_steps
update_custom_recipe_steps(recipe_id, steps_json, dry_run=false)
Validates and replaces only the instructions array, preserving all unrelated customer-recipe fields.
Recipe write
update_custom_recipe_ingredients
update_custom_recipe_ingredients(recipe_id, ingredients_json, dry_run=false)
Validates and replaces only the ingredients array, including supported structured amounts.
Image write
upload_custom_recipe_image
upload_custom_recipe_image(recipe_id, image_path, dry_run=false)
Reads a local image, normalizes it to JPEG, obtains Cookidoo’s signed upload authorization, uploads it to the customer-recipe image namespace, and attaches it to the recipe.
Arbitrary external URLs and official stock-image URLs are not valid customer-recipe image values.
Recipe write
upload_custom_recipe
upload_custom_recipe(recipe_json: str, dry_run: bool = false)
Validates a complete recipe object and creates a private customer recipe in Cookidoo using the authenticated account.
Machine-readable reference
Use tools.json
Agents and documentation generators can consume the same inventory as structured JSON.