Installation¶
Requirements¶
- Python 3.12 or newer. The code uses the 3.12 syntax and is typed against it.
- uv for the source install. Any isolated Python environment
works, but every command in these docs uses
uv. - Docker 24+ only if you prefer the container image.
The runtime has one dependency, mcp==2.3.0, plus pydantic. There is no database, no build
step and no native extension.
From source¶
git clone https://github.com/FedeG/al_horno_con_papa_mcp.git
cd al_horno_con_papa_mcp
uv sync
uv run alhorno-mcp --version
uv sync installs the runtime dependencies and the dev group. The catalog ships inside the
package at src/alhorno_mcp/data/recipes.json, so nothing else downloads at runtime.
Start the server on stdio:
Or over HTTP:
Local hosts want an absolute path
An MCP host launches the command from its own working directory, so it cannot rely on a relative checkout. Use the absolute path:
From a wheel¶
The project is not published on PyPI yet. Build the wheel and install it as a tool:
uv tool install puts alhorno-mcp on your PATH and keeps it in its own environment. Uninstall
with uv tool uninstall alhorno-mcp.
With Docker¶
The image runs alhorno-mcp serve with the HTTP transport on 0.0.0.0:8000, as the unprivileged
user app, with a health check that polls /health. See
Docker for Compose,
environment and upgrade flow.
Verify the server¶
Health endpoint¶
{
"status": "ok",
"version": "0.1.0",
"recipe_count": 246,
"tag_count": 69,
"source_url": "https://raw.githubusercontent.com/FedeG/al.horno.con.papa/refs/heads/main/src/data/recipes.json"
}
The route is unauthenticated, cacheable and safe to use as a container or load-balancer probe. It returns no user data.
MCP handshake¶
curl -sS -X POST http://127.0.0.1:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {"name": "curl", "version": "0"}
}
}'
A 200 response means the transport is live. clientInfo is mandatory: without it the server
rejects the handshake.
Host allowlist
The HTTP transport enables DNS-rebinding protection. A request with a Host header outside
ALHORNO_ALLOWED_HOSTS gets a 421 Misdirected Request. When you deploy behind a reverse
proxy, add the public hostname to that list.
Updating the catalog¶
The packaged snapshot does not update itself. Recipes are immutable once published, so refreshing is a deliberate, manual step:
uv run alhorno-mcp sync # download, validate, store
uv run alhorno-mcp sync --check # report drift without writing
Rebuild or restart after a sync so the process loads the new file. See Data and sync for what the command validates.