Skip to content

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
  • sync downloads the payload, parses and validates it, then writes it through a temporary sibling file, so a crash never leaves a half-written snapshot.
  • --check exits 0 when the stored file is byte-identical to upstream and 1 when it drifted. Use it in a scheduled workflow to learn that new recipes exist, then run the real sync and commit the result yourself.
  • --url points at another source, which is useful for a fork or a local file served over HTTP.
  • --data-dir writes somewhere else, for example a mounted volume.
uv run alhorno-mcp sync --check || echo "new recipes upstream"

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_recipe when you pass a seed.

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.