Skip to content

alhorno-mcp

A read-only Model Context Protocol server for the al.horno.con.papa 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.

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

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:

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 Website-parity fuzzy search with tag and easy-only filters, paging and a site_search_url.
get_recipe One complete recipe: ingredients, method, URLs and the precomputed related recipes.
list_tags Every tag with its recipe count, featured tags first in the website's order.
find_recipes_by_ingredients The website's "Qué cocino": recipes that use what you have and none of what you avoid.
get_related_recipes The related recipes the website precomputed, best first.
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 — uv, Docker and the first health check.
  • Configuration — every environment variable and flag.
  • Client setup — OpenCode, Claude Code, Claude Desktop, ChatGPT, Gemini CLI and Cursor.
  • Tool reference — arguments, responses and real examples.
  • Search behaviour — why the results match the website, and where they deliberately differ.
  • Deploy to a VPS — 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; this project only indexes the publicly published dataset.