# alhorno-mcp

**A read-only [Model Context Protocol](https://modelcontextprotocol.io) server for the
[al.horno.con.papa](https://alhornoconpapa.com.ar) recipe catalog.** It serves the 246 recipes
published on Instagram through six small tools, using the same search the website runs today.

The server returns **raw, structured data** and **links back to the site**. It never calls a
model, never scrapes at runtime and never writes to the catalog: the snapshot ships inside the
package and is refreshed only when you run `sync`.

!!! warning "Status"

    `0.1.0` has not been tagged yet. The API documented here is the target contract, not a
    released one.

## What you get

- **Search parity.** The website filters recipes with Fuse.js 7.4.2, accent folding, Spanish
  stopwords and per-token thresholds. This project ports that matcher to Python, so
  `search_recipes("papas fritas")` returns exactly the recipes the website returns.
- **Zero tokens on the server.** No embeddings, no API keys, no model calls. The whole catalog
  lives in memory and answers in microseconds.
- **Actionable results.** Every recipe carries its `site_url`; every search carries a
  `site_search_url` that reproduces the query on the website.
- **One dependency-free runtime.** Python 3.12 and `mcp` are the only requirements; the catalog
  is a JSON file inside the package.

## Quick start

```bash
git clone https://github.com/FedeG/al_horno_con_papa_mcp.git
cd al_horno_con_papa_mcp
uv sync
uv run alhorno-mcp serve
```

That starts the server on **stdio**, ready for an MCP host that launches a local process. To run
it as an HTTP service instead:

```bash
uv run alhorno-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000
curl -fsS http://127.0.0.1:8000/health
```

The endpoint is `POST /mcp` (Streamable HTTP, stateless) and the health probe is
`GET /health`, which answers with the version, the recipe count and the upstream source.

## The six tools

Every tool is read-only (`readOnlyHint: true`, `openWorldHint: false`) and answers from the
in-memory snapshot.

| Tool | What it does |
| --- | --- |
| [`search_recipes`](guides/tools.md#search_recipes) | Website-parity fuzzy search with tag and easy-only filters, paging and a `site_search_url`. |
| [`get_recipe`](guides/tools.md#get_recipe) | One complete recipe: ingredients, method, URLs and the precomputed related recipes. |
| [`list_tags`](guides/tools.md#list_tags) | Every tag with its recipe count, featured tags first in the website's order. |
| [`find_recipes_by_ingredients`](guides/tools.md#find_recipes_by_ingredients) | The website's "Qué cocino": recipes that use what you have and none of what you avoid. |
| [`get_related_recipes`](guides/tools.md#get_related_recipes) | The related recipes the website precomputed, best first. |
| [`random_recipe`](guides/tools.md#random_recipe) | A surprise pick, optionally filtered, reproducible with a seed. |

`search_recipes`, `get_recipe` and `get_related_recipes` accept a slug or a numeric id. The
`slug` returned by search is the key callers should reuse.

## Where to go next

- [Installation](getting-started/installation.md) — uv, Docker and the first health check.
- [Configuration](getting-started/configuration.md) — every environment variable and flag.
- [Client setup](getting-started/clients.md) — OpenCode, Claude Code, Claude Desktop, ChatGPT,
  Gemini CLI and Cursor.
- [Tool reference](guides/tools.md) — arguments, responses and real examples.
- [Search behaviour](guides/search.md) — why the results match the website, and where they
  deliberately differ.
- [Deploy to a VPS](operations/deploy.md) — Docker Compose, Caddy and TLS on
  `mcp.alhornoconpapa.com.ar`.

## Public endpoint

The project's own deployment is `https://mcp.alhornoconpapa.com.ar/mcp`. It serves the same six
tools, needs no authentication and stores nothing about the caller. You can also run your own
copy: the snapshot is public and the image is self-contained.

## License and data

Code is MIT. Recipe content and images belong to
[@al.horno.con.papa](https://instagram.com/al.horno.con.papa); this project only indexes the
publicly published dataset.
