feat(api): serve a public demo with question limits, MCP over HTTP, and a Docker image

[cl0ver012]

Summary

Milestone 9, first part: everything the hosted demo needs except the hosting itself.

• chatlore serve --public serves a library to the internet safely enough for a demo, with limits on the questions paid for with the host's key.
• chatlore serve now also serves MCP over HTTP at /mcp, which is how ChatGPT connects.
• A Docker image runs the demo library in public mode. CI builds it and checks it.

Deploying the image is left for a later PR, once a host is chosen.

Changes

Public mode (chatlore serve --public), for a server behind a proxy on the internet:

• Question limits. Only questions that reach the language model count against them. The defaults are 10 an hour per visitor and 300 a day for everyone; --questions-per-hour and --questions-per-day change them. When a limit is reached, chat streams an error that says why and suggests pip install chatlore. Questions that find no passages never reach the model and are not counted. The counter (_Allowance) is shared by the request threads. It keeps a sliding hour per visitor and a UTC day for everyone, and forgets idle visitors once it tracks 10,000.
• Visitors by proxy address. uvicorn runs with proxy_headers and trusts forwarded addresses, since behind a proxy every visitor would otherwise share the proxy's address.
• Demo note. /health reports "public": true. The web interface then shows a short note in the sidebar and changes the ask screen's line to say the conversations are made up.
• MCP from any host name. /mcp accepts requests for any host.

A private server is unchanged, except for /mcp.

MCP over HTTP. The API app now serves the same MCP server as chatlore mcp at /mcp. It uses the SDK's streamable HTTP transport, stateless with plain JSON replies, so any worker can answer any request. The session manager runs in the app's lifespan. A private server keeps the SDK's DNS rebinding protection, so /mcp only answers requests addressed to 127.0.0.1 or localhost.

Docker image (Dockerfile, .dockerignore):

• Built on uv's Python 3.12 image, installing the locked dependencies without dev tools.
• Loads the demo library and downloads the embedding model while building, so a container answers at once.
• Runs as user 1000 and serves the public demo on $PORT or 7860.
• .dockerignore sends only pyproject.toml, uv.lock, README.md, LICENSE, and src/ to the build, so a local .env or library cannot end up in the image.
• The model key is passed at run time, e.g. -e OPENROUTER_API_KEY=....

CI. A new Docker image job builds the image, starts it, and checks four things: /health says public, the web interface loads, /stats has the 32 demo conversations, and a search tool call over /mcp finds the Postgres to SQLite conversation.

Docs.

• New docs/hosting.md: the image, the model key and why to cap it, what --public changes, and what a host needs.
• docs/mcp.md gains "Over HTTP", covering local use with Claude Code and the hosted demo for ChatGPT, Claude, and Cursor.
• README docs links and roadmap updated: M9 has its server and image; deployment is next.
• CHANGELOG updated.

How it was tested

• 9 new tests, 312 in total:
  • the per-visitor hour and the daily limit that resets at midnight UTC, with a fake clock;
  • a public server refusing the third question with the reason;
  • questions that find nothing not being counted;
  • a private server without limits, and /health in both modes;
  • listing and calling tools over /mcp;
  • a private server refusing an MCP request for another host (421) and answering one for 127.0.0.1;
  • serve --public passing the proxy options and limits to uvicorn.
• Ran chatlore serve --public on the demo library:
  • the SDK's own MCP client connected over HTTP, listed the six tools, and ask_context returned the cited passages;
  • the web interface showed the demo note, and the third question gave the limit message;
  • the process used about 400 MB after searches through both the API and MCP.
• The Docker image could not be built locally (no Docker here), so the new CI job is the image's first build.
• ruff, ruff format --check, strict mypy, and pytest pass locally on Python 3.14.

Checklist

• uv run ruff check . and uv run ruff format --check . pass
• uv run mypy passes
• uv run pytest passes
• No real exports, databases, or keys are included
• CHANGELOG.md updated under Unreleased