cookidoo-mcp

An MCP server for Cookidoo, built with NestJS. It exposes a Cookidoo account (recipes, shopping list, subscription) to AI tools (Claude, IDEs, agents, …) as a set of MCP tools.

The Cookidoo client is a TypeScript rewrite of the Python cookidoo-api library. This first migration covers the core: authentication, account info, recipe search & details, and shopping-list management.

Architecture

The project follows the same DDD + CQRS + Hexagonal layout as gardenia-api:

src/
  core/
    config/            env validation + Cookidoo config (env-var credentials)
    mcp/               shared MCP transport (Streamable HTTP) + tool discovery
  contexts/
    cookidoo/
      domain/          types, the ICookidooClient port, exceptions
      application/     CQRS commands & queries (dispatch to the port)
      infrastructure/  CookidooHttpClient — the TS rewrite of cookidoo-api
      transport/mcp/   MCP tools + Zod input schemas
  app.module.ts
  main.ts

• Transport: Streamable HTTP (stateless) at POST /api/mcp. GET/DELETE return 405 (no sessions). A fresh McpServer is built per request.

• Tools live in contexts/cookidoo/transport/mcp/ and only dispatch Commands/Queries through the CQRS bus — never call the client directly.

• The client (CookidooHttpClient) is a singleton behind the COOKIDOO_CLIENT port. It logs in lazily via the Cookidoo OAuth2 cookie flow and transparently re-authenticates on a 401.

Related MCP server: cookwith-mcp

Configuration

Credentials and localization come from environment variables (see .env.example):

Logging

src/support/logging/ wires up structured logging via @sisques-labs/nestjs-kit's createSharedWinstonLoggerOptions (winston + nest-winston under the hood, same as the org's other services). main.ts installs it as Nest's app-wide logger, so every existing Logger.log(...)/Logger.error(...) call is routed through it automatically. Colorized console output plus JSON daily-rotating file logs (logs/, gitignored) are always on; when OTEL_EXPORTER_OTLP_ENDPOINT is set, every log line is also forwarded via OTLP alongside traces/metrics, correlated with the active span.

OpenTelemetry

src/telemetry.ts bootstraps the OpenTelemetry Node SDK ahead of every other import in src/main.ts, so HTTP/Express auto-instrumentation can patch those modules before Nest requires them. It stays disabled until OTEL_EXPORTER_OTLP_ENDPOINT is set. When enabled, src/core/observability/ also wraps the CQRS command/query buses so every dispatch gets a trace span plus duration/count metrics, with no per-handler wiring required, and every Winston log line is forwarded too (see Logging above).

Session persistence

By default the session lives only in memory: a fresh start logs in again. Set COOKIDOO_COOKIE_FILE to a writable path and the client restores the session from it on startup and rewrites it after every successful login, so restarts reuse the existing session (an expired one self-heals on the next 401). The file holds session cookies — treat it like a credential and keep it out of version control.

Running

Local (pnpm)

pnpm install
cp .env.example .env   # then fill in your credentials
pnpm dev               # watch mode
# or
pnpm build && pnpm prod

Docker

docker build -t cookidoo-mcp .

With an env file:

cp .env.example .env   # then fill in your credentials
docker run --rm -p 3000:3000 --env-file .env cookidoo-mcp

Or pass variables directly:

docker run --rm -p 3000:3000 \
  -e COOKIDOO_EMAIL=your@email.com \
  -e COOKIDOO_PASSWORD=your-password \
  cookidoo-mcp

Optional localization and port overrides work the same way (-e PORT=3010, -e COOKIDOO_COUNTRY_CODE=es, etc.).

If you set a custom PORT, map the same port on the host and in the container (e.g. -p 3010:3010 when PORT=3010).

The MCP endpoint is then available at http://localhost:3000/api/mcp (or your custom port). A liveness probe is exposed at GET /api/health (handy for Docker/orchestrator health checks).

Cursor

Cookidoo credentials live in the server .env — Cursor only needs the HTTP endpoint. The server must be running (pnpm dev or pnpm prod) before Cursor connects.

1. Copy .cursor/mcp.json.example to .cursor/mcp.json.

2. If you changed PORT in .env, update the URL port to match (default 3000).

3. Restart Cursor (Settings → Tools & MCP should list cookidoo).

Authentication is handled by the NestJS process via COOKIDOO_EMAIL / COOKIDOO_PASSWORD; do not put Cookidoo credentials in mcp.json.

Tools

Adding a tool

1. Add a Zod input schema under transport/mcp/schemas/.

2. Add a Command/Query (+ handler) under application/ that dispatches to the ICookidooClient port; extend the port + CookidooHttpClient if the underlying Cookidoo endpoint isn't wired yet.

3. Add the tool under transport/mcp/tools/, tagged with @McpTool(), and register it in the MCP_TOOLS array of cookidoo.module.ts.

Migration status

The migration now covers the full upstream cookidoo-api surface: account, recipe search & details, shopping list (incl. ownership/edit), the meal-planning calendar, custom recipes, collections (managed/custom) and session persistence (save_cookies / load_cookies, here as the optional COOKIDOO_COOKIE_FILE).

License

Licensed under the GNU General Public License v3.0 — © Sisques Labs.