Data and sync¶
The project has exactly one input: a JSON array of recipes published by the website repository. It ships inside the package, so the server starts without network access and answers deterministically.
https://raw.githubusercontent.com/FedeG/al.horno.con.papa/refs/heads/main/src/data/recipes.json
│
│ alhorno-mcp sync (manual, authenticated by nothing but HTTPS)
▼
src/alhorno_mcp/data/recipes.json → validated at startup → in-memory dataset
The snapshot¶
| Property | Value |
|---|---|
| Recipes | 246 public recipes (the file also carries drafts, which are never served) |
| Size limit | 8 MiB; a larger payload is rejected |
| Fetch timeout | 30 seconds |
| Runtime reads | Once, at process start |
| Runtime writes | None |
The file is validated field by field on load. A recipe needs id, name, description, tags,
instagramUrl, imageUrl, ingredients, date, easy, hidden, shortcode,
cleaned_ingredientes, slug and related_recipes. Unknown fields are preserved rather than
rejected, so the website can add data without breaking the server. The full upstream object is
available through get_recipe as raw.
Fields the tools use¶
| Upstream field | Used for |
|---|---|
id, slug |
Lookup keys; id is exposed as a string. |
name, tags, cleaned_ingredientes |
The three searchable keys, weights 2 / 1.5 / 1. |
description |
The method, plus the excerpt in search results. |
ingredients |
Raw published lines, shown to the model. |
imageUrl |
Turned into an absolute image URL. |
easy, hidden |
Easy-only filter; hidden recipes are dropped entirely. |
related_recipes |
Resolved into get_related_recipes; relations pointing at hidden recipes are skipped. |
Refreshing the catalog¶
Recipes are immutable once published. Only tags and related_recipes change over time, and new
recipes appear weekly. Because of that, refreshing is a deliberate step you run, not a background
job:
uv run alhorno-mcp sync # download, validate, write
uv run alhorno-mcp sync --check # compare with upstream, write nothing
syncdownloads the payload, parses and validates it, then writes it through a temporary sibling file, so a crash never leaves a half-written snapshot.--checkexits0when the stored file is byte-identical to upstream and1when it drifted. Use it in a scheduled workflow to learn that new recipes exist, then run the realsyncand commit the result yourself.--urlpoints at another source, which is useful for a fork or a local file served over HTTP.--data-dirwrites somewhere else, for example a mounted volume.
Restart the process after a sync, or rebuild the image: the snapshot is read once at startup, which is what makes responses free of file-system races.
What validation protects¶
sync fails — and writes nothing — when:
- the payload is not JSON, or not a JSON array;
- a recipe is not an object, or a required field is missing or malformed;
- two recipes share an
id; - two recipes share a
slug; - the payload exceeds 8 MiB (typically an HTML error page instead of JSON);
- the download fails, times out or returns an HTTP error.
This is why the packaged snapshot is always a document the server can serve. A broken upstream file never reaches a release.
Immutability in practice¶
- No runtime writes. Tools are annotated read-only and the process never touches the snapshot file.
- No runtime network. No scrapers, no revalidation, no embeddings refreshed in the background.
- No database. 246 recipes fit in memory; the dataset is built once and shared by every request.
- Deterministic responses. For a given snapshot, the same call returns the same data, including
random_recipewhen you pass aseed.
Testing a candidate snapshot¶
uv run alhorno-mcp sync --data-dir /tmp/candidate
ALHORNO_DATA_DIR=/tmp/candidate uv run alhorno-mcp serve --transport streamable-http
If the candidate is invalid, the process exits with error: ... and a non-zero code instead of
serving it. This is the cheapest way to review a weekly update before committing it.