Yes Chef MCP

Self-hosted meal planning optimization server with macro-nutrient targeting. Exposes both a REST API (for web UIs) and an MCP server (for Claude Desktop) from a single process. It enables AI assistants (like Claude) to seamlessly integrate with your personal recipe database to search recipes, compose nutritionally balanced meals, optimize full-week plans based on member-specific macro targets, and generate consolidated grocery lists.

Key Features

• Hybrid Recipe Search: Combines Full-Text Search (FTS5) for keyword matching with semantic vector similarity (sqlite-vec) using Reciprocal Rank Fusion (RRF).

• Macro Optimization: Uses a tiered solving strategy (Mixed Integer Linear Programming via python-mip, followed by greedy heuristics and continuous relaxation) to find the best recipe combinations to meet per-member macro goals. Always returns a result.

• Interactive UI (MCP Apps): Provides embedded React-based UI components (like a macro target setter, recipe selector, and grocery checklist) that render directly within compatible MCP clients.

• Family Planning: Supports individual macro targets for different family members, calculating per-member serving sizes for shared meals.

• Smart Grocery Lists: Consolidates ingredients across meal plans, automatically merging similar items and excluding common pantry staples.

• Nutrition Enrichment: Auto-populate macro data from USDA FoodData Central or Nutritionix.

• Multi-source Import: Pull recipes from AnyList, Mealie, CSV, or enter manually.

Related MCP server: spoonacular-mcp

Prerequisites

• Python: 3.12 or higher.

• Package Manager: uv is recommended for Python dependency management.

• Node.js & npm: Required for building the React-based interactive UI components.

• Database: SQLite is used as the primary data store, leveraging the sqlite-vec extension for vector embeddings.

Quickstart

1. Install Python Dependencies

Navigate to the server directory and sync dependencies using uv:

cd backend
uv sync --all-extras

2. Build Frontend Views

The interactive MCP App components must be built before running the server:

cd frontend
npm install
npm run build

3. Run the Application

Start the unified FastAPI + FastMCP server:

cd backend
uv run python -m yes_chef_mcp.app
# OR
uv run uvicorn yes_chef_mcp.app:app --reload

By default, the server runs on http://127.0.0.1:8000.

• REST API: http://127.0.0.1:8000/api/*

• Static Views: http://127.0.0.1:8000/views/static/*

• MCP HTTP Endpoint: http://127.0.0.1:8000/mcp

Claude Desktop Integration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "yes-chef": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Configuration

• Database path: defaults to data/yes_chef_mcp.db, configurable via YES_CHEF_DB_PATH env var or configure_db_path() in core/db.py

• Nutrition APIs (optional): USDA FoodData Central and Nutritionix keys are passed to NutritionEnricher at construction time

Development

cd backend

# Install with dev dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Lint & format
uv run ruff check .
uv run ruff format .

# Type check
uv run mypy yes_chef_mcp/

Fake-host tests

frontend/tests/host/ holds Playwright tests that load the built MCP views into a fake MCP Apps host (a page that plays the host side of the protocol over postMessage) and assert the protocol messages each button sends (tools/call, ui/message, ui/update-model-context, ui/request-display-mode) plus what the view shows. They also cover host theming, the fullscreen toggle, and the SPA calendar with a mocked /api. No backend, model or network is involved: tool results come from JSON fixtures and the built files are served by vite preview.

cd frontend
npm install
npm run build        # the tests load dist/
npm run test:host

They use Playwright's own Chromium (installed with npx playwright install chromium, or found via PLAYWRIGHT_BROWSERS_PATH). To use another Chromium binary, set PW_CHROMIUM_PATH=/path/to/chrome. The preview server port defaults to 4319 (HOST_TEST_PORT to change it).

The fixtures in frontend/tests/host/fixtures/ are real show_* / set_macro_target results recorded from a seeded throwaway database. After changing a tool's output, refresh them with:

cd backend
uv run python scripts/record_view_fixtures.py

These tests check our side of the protocol against a host we wrote. They do not replace a smoke test in a real MCP host (e.g. Claude): host sandboxing, CSP, real capability sets and display-mode behavior can differ.

Architecture

backend/yes_chef_mcp/
├── app.py                # Unified FastAPI + FastMCP entry point
├── api/                  # REST API routes and HTML view controllers
│   └── routes.py         # REST API endpoints
├── mcp/                  # MCP server definition and tool wrappers (`server.py`)
│   └── server.py         # MCP tool definitions
├── core/                 # Core domain logic
│   ├── models.py         # Domain models (dataclasses)
│   ├── schemas.py        # API schemas (Pydantic)
│   ├── db.py             # Async SQLite connection pooling (WAL mode)
│   ├── recipe_store.py   # Recipe CRUD, FTS, and vector embeddings
│   ├── search.py         # Hybrid and macro-distance search algorithms
│   ├── meal_composer.py  # Ad-hoc meal composition and macro calculations
│   ├── planner.py        # Meal plan CRUD and scheduling
│   ├── optimizer.py      # MILP and greedy optimization engines
│   ├── constraint_relaxer.py  # Logic for relaxing optimization constraints
│   └── grocery.py        # Smart grocery list generation
├── pipeline/             # Data ingestion (Nutrition APIs, Mealie/AnyList imports)
│   ├── embeddings.py     # Sentence-transformer embeddings
│   ├── nutrition.py      # External nutrition APIs
│   └── providers/        # Recipe import plugins
└── tests/                # Comprehensive test suite for all core logic

frontend/                 # React/Vite source for interactive UI components
├── src/
│   ├── components/       # Shared React components
│   ├── entries/          # Per-page entry points
│   ├── bridge.ts         # API communication
│   ├── theme.ts          # Design token exports
│   └── types.ts          # Shared TypeScript types
└── dist/                 # Vite build output: SPA (served by FastAPI at /views/static/)
    └── views/            # Single-file MCP Apps views (JS/CSS inlined), served as ui:// resources

Key Design Choices

• Pydantic at edges, dataclasses internally — validation where data enters the system, lightweight models everywhere else

• Tiered optimization — MILP solver with progressive constraint relaxation, falling back to heuristics. Always returns a result.

• Hybrid search — FTS5 keyword search + 384-dim vector similarity fused via Reciprocal Rank Fusion

• Single process — FastAPI and FastMCP share one ASGI app, one SQLite database in WAL mode

• Async-first — aiosqlite for non-blocking database access, httpx for external API calls

License

MIT