diff options
Diffstat (limited to 'mcp.md')
| -rw-r--r-- | mcp.md | 22 |
1 files changed, 14 insertions, 8 deletions
@@ -8,7 +8,7 @@ > Decisions locked in `plan.md §3` and `requirements.md §7`: a **separate > FastMCP "ai service"** (a pattern Tom already runs elsewhere) that talks to > the existing Django REST API, hosted on the same box at -> **`food.jihakuz.xyz/mcp`**, behind nginx, **bearer-token** auth. +> **`food.tomflux.xyz/mcp`**, behind nginx, **bearer-token** auth. --- @@ -43,7 +43,7 @@ blocks — now grounded instead of guessed. claude.ai (cooking mode) │ Streamable HTTP, secret in the URL path ▼ - nginx food.jihakuz.xyz/mcp (TLS, public) + nginx food.tomflux.xyz/mcp (TLS, public) │ proxy_pass 127.0.0.1:8765 ▼ FastMCP "ai service" (food-mcp.service, localhost only) @@ -71,7 +71,7 @@ localhost Django**. It holds no database connection of its own. - **Transport:** Streamable HTTP (the remote-MCP transport claude.ai connectors use). FastMCP served over HTTP, bound to `127.0.0.1:8765`. -- **Public route:** nginx on `food.jihakuz.xyz`, `location /mcp` → +- **Public route:** nginx on `food.tomflux.xyz`, `location /mcp` → `proxy_pass http://127.0.0.1:8765`. TLS via the existing Let's Encrypt setup. Note SSE/streaming needs `proxy_buffering off;` and a long `proxy_read_timeout` on that location. @@ -90,7 +90,7 @@ header**, so the original bearer-header plan isn't directly supported. Two ways to honour the "tight secret, single user" intent: - **Recommended — authless connector + secret in the URL path.** Register the - connector URL as `https://food.jihakuz.xyz/mcp/<long-random-secret>/`. To + connector URL as `https://food.tomflux.xyz/mcp/<long-random-secret>/`. To claude.ai it's an authless server; in reality nginx proxies *only* that exact secret prefix to the FastMCP service and 404s everything else. The URL **is** the bearer-equivalent — it matches Tom's "a tight enough secret, I'm the only @@ -178,11 +178,17 @@ A small package in this repo, its own process — not bolted into Django: ``` mcp_server/ __init__.py - __main__.py # FastMCP app; runs streamable-HTTP on 127.0.0.1:8765 + __main__.py # entrypoint: from .server import main; main() + server.py # FastMCP app + the @mcp.tool definitions (§5) + main() client.py # thin httpx client around the Django API (caine token) - tools.py # the @mcp.tool definitions from §5 + tests.py # FoodClient tests via httpx.MockTransport (no network) ``` +`main()` runs streamable-HTTP at path `/` on `127.0.0.1:8765` +(`mcp.run(transport="http", host, port, path="/")`); nginx maps +`/mcp/<secret>/` → that root. Client tests run with +`python -m unittest mcp_server.tests` (needs the `mcp` dep group). + - Deps via a uv group so they only install where needed: `[dependency-groups] mcp = ["fastmcp", "httpx"]`. Deploy with `uv sync --group mcp` on the box that runs the service. @@ -204,10 +210,10 @@ All out of git; the systemd unit loads the same `.env` the Django service uses. 1. `uv sync --group mcp` on the box. 2. Add the three env vars to `/var/lib/food/.env`; generate the bearer token. 3. Install `deploy/food-mcp.service`, `daemon-reload`, start, enable. -4. Add the `location /mcp` block to the `food.jihakuz.xyz` nginx config +4. Add the `location /mcp` block to the `food.tomflux.xyz` nginx config (`proxy_buffering off`, long read timeout), `nginx -t`, reload. 5. In claude.ai, add a custom connector pointing at the **secret URL** - `https://food.jihakuz.xyz/mcp/<secret>/` (authless connector — see §4). + `https://food.tomflux.xyz/mcp/<secret>/` (authless connector — see §4). 6. Smoke test: in cooking mode, "what's in my pantry?" → Claude calls `get_pantry` and lists real items. |