Architecture¶
The codebase is deliberately small. The catalog is 246 recipes; that fits in memory, so the project has no database, no build step and no cache invalidation problem.
Module map¶
src/alhorno_mcp/
├── __init__.py version and package metadata
├── __main__.py python -m alhorno_mcp
├── cli.py serve / sync commands and exit codes
├── constants.py every product constant in one place
├── snapshot.py fetch, validate, load and write recipes.json
├── models.py pydantic models for upstream data and tool responses
├── records.py immutable, indexed view of a recipe
├── dataset.py the in-memory catalog: lookup, tags, relations
├── settings.py environment variables and command line overrides
├── tools.py the six tools, the Toolbox and the log decorator
├── server.py MCP server wiring, transports and /health
├── urls.py website URLs with URLSearchParams-compatible encoding
├── data/recipes.json the packaged snapshot
└── search/
├── bitap.py Fuse.js Bitap port, int32 masks, UTF-16 units
├── fuse.py keys, weights, field norms and the search index
├── tokens.py tokenization, stopwords and per-token thresholds
├── normalize.py accent folding and normalized containment
├── ingredients.py the website's "Qué cocino" ranking
└── service.py the pipeline: filters, strategies, ordering, excerpts
tools.py is the only module that talks to MCP. search/ is a port of the website's algorithm
with no MCP knowledge, which keeps it testable against the JavaScript goldens.
Request flow¶
MCP host
│ JSON-RPC over stdio or Streamable HTTP
▼
MCPServer (server.py)
│ tool dispatch, validated arguments
▼
Toolbox method (tools.py)
│ validates tag/ingredients, builds links
▼
RecipeDataset (dataset.py) ──▶ RecipeSearch (search/service.py)
│
└─ pydantic response model ──▶ JSON-RPC result
Startup does the expensive work once:
Settings.from_env()
→ load_recipes() read 1 file, validate 246 recipes
→ RecipeDataset index by slug and id, count tags, build the search index
→ MCPServer(...) register six tools and /health
No per-request file reads, no locks, no connection pool.
Design decisions¶
In-memory catalog, no database. A previous iteration built an SQLite catalog with FTS5. It was removed: it needed a build step, a schema, a resolver, migrations and 20 files of plumbing to serve 246 rows. A tuple of records plus the Fuse port is faster to start, simpler to test and impossible to get out of sync with the snapshot.
One dependency for MCP. mcp==2.3.0 provides MCPServer, tool registration, schema
generation from type hints, transports and the rebinding protection. The project adds no web
framework of its own.
Tools are methods on a frozen dataclass. Toolbox(dataset, base_url) holds exactly the two
things a tool needs. Each tool is a plain method with type-annotated arguments, so the MCP schema is
generated from the signature and the docstring stays honest. TOOL_SPECS stores the name, title and
description in one table; register_tools only replays it.
No functions defined inside functions. Registration is a loop over TOOL_SPECS, not a nest of
closures. The one exception is the logging decorator, where the wrapper is the point.
Constants in one place. constants.py owns the product values: site base URL, page size, the
Todas sentinel, featured tags, snapshot limits, server name and instructions, transport
defaults, MAX_RELATED and the read-only annotations. Algorithm numbers — Bitap masks, Fuse
weights, token thresholds — stay beside the algorithm they belong to, because moving them away
would make that code harder to read.
Read-only by contract. Every tool carries readOnlyHint: true and openWorldHint: false. The
server never writes, never reaches the network at runtime, and holds no credentials.
Links, not prose. The server returns data and site_url/site_search_url values. Writing the
answer is the host model's job, and the recipe always links back to the author's site.
Errors teach. A missing recipe, an unknown tag or an unknown ingredient raises a tool error
with close matches (Did you mean: ...?), so the model can correct itself instead of reporting an
empty catalog.
Validation strategy¶
The suite is end-to-end on purpose: five files, ~35 tests, and no unit test per helper.
| File | What it proves |
|---|---|
test_site_parity.py |
100 recorded search cases and 12 ingredient cases return the same recipes as the website's own JavaScript. |
test_server.py |
The six tools answer through a real MCP client: paging, filters, errors, relations, random seeds. |
test_http.py |
The HTTP transport: handshake, tool call, /health, and a 421 for a foreign Host. |
test_data.py |
Snapshot validation: duplicates, missing fields, size limits, hidden recipes. |
test_cli.py |
serve/sync flags, exit codes and --check. |
Goldens are recorded, not hand-written: tools/goldens.mjs imports the website's
src/utils/index.js and src/utils/queCocino.js and writes the outputs together with hashes of
the dataset, the two scripts and the site commit. A website change is therefore a reviewable diff,
not a guess.
Coverage is gated at 80 % in CI. The remaining lines are mostly transport error paths and Bitap fallbacks that an end-to-end suite cannot reach without duplicating the algorithm in a test.
What this project is not¶
- Not a scraper: it reads a public JSON file, manually, with
sync. - Not a model: no prompts, no embeddings, no API keys.
- Not a database service: one process, one immutable snapshot, no persistence.
- Not the website: it exposes the catalog through MCP and links back for everything visual.