Skip to content

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:

uv run alhorno-mcp serve

Or over HTTP:

uv run alhorno-mcp serve --transport streamable-http --host 127.0.0.1 --port 8000

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:

uv run --directory /absolute/path/to/al_horno_con_papa_mcp alhorno-mcp serve

From a wheel

The project is not published on PyPI yet. Build the wheel and install it as a tool:

uv build
uv tool install dist/alhorno_mcp-0.1.0-py3-none-any.whl
alhorno-mcp --version

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

docker build -t alhorno-mcp:local .
docker run --rm -p 8000:8000 alhorno-mcp:local

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

curl -fsS http://127.0.0.1:8000/health
{
  "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.