mcp 2.0.0 removed `mcp.server.fastmcp`. This repo was pinned to <2
(6723829) to stop a rebuild from crash-looping the container the way
seed-mcp (2026-09-01) and zerto-docs (2026-08-11) did. This lifts the
pin by doing the port — the same mechanical change as
justin/seed-mcp#23 and justin/morpheus-docs#10.
- import: FastMCP -> MCPServer, plus TransportSecuritySettings
- constructor takes no transport options: MCPServer(f"{PRODUCT_NAME}-docs")
- host/port/stateless_http/transport_security are run() kwargs;
`mcp.settings` no longer exists
- requirement becomes plain `mcp>=2,<3` (2.x has no [fastmcp] extra)
@mcp.tool() decorators and all handler signatures are unchanged.
CI now smokes `import docs_mcp.server` twice in both workflows — once
after pip install, once inside the built image — so a green build can
never ship a non-importing container again.
Verified on python:3.12-slim (matches the image):
- tools/list dumped in wire format is BYTE-FOR-BYTE IDENTICAL between
mcp 1.30.0 and 2.2.0, all 10 tools
- streamable-http boots; initialize returns HTTP 200, both from
localhost and with a container-DNS `Host: hvm-docs-mcp:8000` header
(passing host= to run() keeps DNS-rebinding protection off)
- no mcp-session-id response header, i.e. stateless_http is in effect
- stdio boots; initialize + tools/list return 10 tools
- production image builds and imports under mcp 2.2.0; httpx 0.28.1 and
httpx2 2.12.0 coexist as expected
Retrieval is untouched, so no eval numbers are included.
Closes#12
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01QBx2P1VhKQEzJWoZ96QcnH
Match the OLLAMA_URLS pattern from zerto-docs-rag so every docs MCP
build fans out across the same two GPU-pinned Ollama containers on
192.168.0.2 (:11435 Titan X, :11436 1080 Ti). The host's primary
Ollama on :11434 is left alone for OpenWebUI.
rag.embeddings now reads OLLAMA_URLS (plural CSV) preferentially with
fallback to OLLAMA_URL, defaulting to http://192.168.0.2:11434 — same
shape as zerto's embeddings.py. The OllamaEmbeddings class already
round-robins per batch, so both GPUs run in parallel during the
chroma rebuild.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Phase 4/5 — adapt the template workflows to Justin's self-hosted Gitea
+ act_runner setup (see reference_gitea_server memory):
* PUSH via LAN endpoint 192.168.0.2:1234 (bypasses Cloudflare's 100 MB
request-body cap on the Free plan); PULL via git.jpaul.io.
* buildx with config-inline insecure-registry for the LAN endpoint —
docker/login-action can't be used there (host daemon rejects HTTP).
Auth is written into ~/.docker/config.json so buildx reads it
directly.
* docker/metadata-action labels org.opencontainers.image.source with
the PUBLIC URL so Gitea auto-links the package; explicit POST to
/api/v1/packages/.../-/link/{repo} as belt-and-suspenders (201 newly
linked, 400 already linked, both treated as success).
* deploy/docker-compose.yml: substitute <product> placeholders, point
image at git.jpaul.io/justin/hvm-docs:latest, set HYBRID_SEARCH=false
to match the eval winner (bm25+rerank), keep the llama.cpp + jina
GGUF reranker sidecar as the production target.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
First dispatch on the empty template failed at Chroma collection
creation because PRODUCT_NAME was the literal string "<product>"
(YAML doesn't expand placeholders), and Chroma rejects collection
names containing characters outside [a-zA-Z0-9._-]:
chromadb.errors.InvalidArgumentError: Validation error: name:
Expected a name containing 3-512 characters from [a-zA-Z0-9._-],
starting and ending with a character in [a-zA-Z0-9]. Got:
<product>_docs
Same fix as the IMAGE env: derive from the repo name dynamically
via ${{ github.event.repository.name }}. Cloners can still override
explicitly, but a fresh clone now runs the index-rebuild step
cleanly out of the box.
Verified by re-dispatch — should fail next at docker login (placeholder
REGISTRY_PUSH hostname), which is the next-expected fail point and a
real per-deployment config the cloner has to fill in.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Both workflows had a static IMAGE env (<owner>/<product>-docs-mcp)
and a static --package arg in the GC step. Switch both to Gitea
Actions context variables so a clone of the template into any repo
name works on the first CI run without find/replace:
IMAGE: ${{ github.repository_owner }}/${{ github.event.repository.name }}
--owner ${{ github.repository_owner }}
--package ${{ github.event.repository.name }}
Also add the "Link container package to this repo" step that was
missing from the template (and which, naively copy-pasted from the
reference build, would have linked everything back to docs-mcp-
template). The new step derives owner + package + link-target all
from the running repo's context.
The github.* namespace is Gitea Actions' inherited GitHub-Actions
context — values come from the Gitea server, not github.com. Same
mechanism the reference build's $GITHUB_SHA tag-builder uses.
CLAUDE.md updated to note that image and package naming are
repo-derived; only registry endpoints and the Ollama URL need
per-clone editing.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
justinandClaude Opus 5
claude