cookidoo-mcp: Instructions file for Codex

AGENTS.md

This file is the canonical context for an AI coding agent entering this repository without prior conversation history. Read it before changing code. It applies to the entire repository.

Project purpose

This repository contains an unofficial FastMCP server for Thermomix Cookidoo. It lets an AI client authenticate to a Cookidoo account and work with:

• official and customer recipes;
• full recipe copying and translation workflows;
• structured guided-cooking settings;
• custom recipe images;
• the Cookidoo shopping list;
• the Cookidoo meal-planning calendar.

The implementation combines the third-party cookidoo-api Python package with direct requests to undocumented Cookidoo endpoints that the package does not cover. Cookidoo may change these endpoints without notice, so API-facing changes require both unit tests and, where safe, live contract tests.

This project is not affiliated with Vorwerk, Thermomix, or Cookidoo.

Non-negotiable rules

Keep ingredient and machine steps separate

Every created, translated, enhanced, or repaired recipe must separate ingredient handling from Thermomix actions:

1. A weighing/adding step contains only ingredient handling and INGREDIENT annotations.
2. The following step contains chopping, mixing, heating, cooking, kneading, or another machine action and uses a TTS or MODE annotation.

Never put INGREDIENT together with TTS or MODE in the same step. RecipeStep validation enforces this for structured payloads. Apply the rule even when a recipe currently contains only plain text.

Protect account data and credentials

• Never commit .env, cookies, session data, account identifiers, or secret values.
• Never print COOKIDOO_EMAIL or COOKIDOO_PASSWORD in test output.
• COOKIDOO_EMAIL is the Cookidoo login identifier. It may be an email address or a phone number; when it is a phone number, keep it without spaces.
• Use only .env.example placeholders in documentation and fixtures.
• Do not delete or overwrite an existing customer recipe unless the user explicitly identifies it and asks for that change.
• Live tests may create a temporary recipe only when they guarantee cleanup in a finally block.
• Only upload images the account owner is allowed to use.