# 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.

```text
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:

```bash
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.

```bash
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

```bash
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.
