# Installation

## Requirements

- **Python 3.12 or newer.** The code uses the 3.12 syntax and is typed against it.
- **[uv](https://docs.astral.sh/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

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

```bash
uv run alhorno-mcp serve
```

Or over HTTP:

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

!!! tip "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:

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

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

```bash
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](../operations/docker.md) for Compose,
environment and upgrade flow.

## Verify the server

### Health endpoint

```bash
curl -fsS http://127.0.0.1:8000/health
```

```json
{
  "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

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

!!! note "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:

```bash
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](../guides/data.md) for what the command validates.
