cookidoo-mcp-docker: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

MCP server (Python, FastMCP v3) that lets LLM sessions upload recipes as Cookidoo custom recipes for a Thermomix (TM7 by default), plus tools for recipe details, shopping list, and meal plan. The German authoring guide ships with the server (tool docstrings, MCP prompt, resource, server instructions), so clients need no recipe rules in their own prompts. The project is live: a home-server deployment serves claude.ai connectors through a Cloudflare Tunnel with GitHub OAuth. docs/plan-mcp-server-v1.md is the running decision log - keep it updated when working on features.

Commands

• uv sync - install dependencies (Python 3.12+, uv-managed)
• uv run pytest - full test suite; e2e tests auto-skip without real credentials in .env
• uv run pytest tests/test_models.py -q - single test file
• uv run pytest -m e2e - end-to-end tests against the live Cookidoo API (needs .env; uploads a test recipe and deletes it again)
• uv run ruff check src tests - lint
• uv run cookidoo-mcp - run the server (streamable HTTP on 127.0.0.1:8000/mcp; MCP_TRANSPORT=stdio for stdio)
• docker compose up -d --build - local container build and run
• CI (.github/workflows/docker.yml) runs ruff + pytest and publishes a multi-arch image to ghcr.io/jsaedtler/cookidoo-mcp-docker:latest on every push to main

Architecture

All code lives in src/cookidoo_mcp/; each module has one job:

• models.py - pydantic models converting an LLM-authored recipe into the exact Cookidoo PATCH payload. The LLM supplies semantics only (step text, time_seconds, temperature, speed, reverse); the server renders the German settings notation ("3 Min./120°C/Linkslauf/Stufe 1") and computes TTS/INGREDIENT annotation character offsets itself. Never let a model produce offsets or notation text.
• cookidoo_client.py - the only Cookidoo coupling point. Login/read/delete/shopping list/calendar go through the released cookidoo-api library; creating and listing custom recipes use raw POST+PATCH/GET on the undocumented created-recipes/{language} endpoints (reusing the library session and bearer token), because the released library cannot create recipes from scratch. When upstream ships create/list (see miaucl/cookidoo-api PR #179), only this adapter changes.
• guidance.py - German authoring rules (RECIPE_GUIDE, SERVER_INSTRUCTIONS).
• auth.py - optional GitHub OAuth (FastMCP GitHubProvider, active only when GITHUB_CLIENT_ID is set) plus a mandatory allowlist middleware: the provider alone would accept any GitHub account. OAuth state persists in a file store under MCP_STATE_DIR; storage keys are hashed because CIMD client IDs are URLs and raw slashes break file paths.
• server.py - FastMCP wiring (11 tools, prompt, resource), lazy Cookidoo login with re-login on auth expiry, and explicit dual-stack socket binding (asyncio forces IPV6_V6ONLY, which would silently black-hole IPv4 behind Docker ip6tables DNAT).