justin
9ba615c8ee
Template for building hosted MCP servers over a product's public
documentation. Distilled from one production build; everything
product-specific has been factored out.
Contents:
- PLAN.md — comprehensive build guide. 13 phases from project
skeleton through weekly_digest. Includes the gotchas
("fetch-depth: 0 always", reranker per-pair token limit,
Cloudflare body cap, dash-not-bash on Gitea runners), the
decisions worth carrying forward, and a per-product
customization checklist.
- CLAUDE.md — guidance for Claude Code working in a clone of this
template. Phase identification table, conventions (env-gating +
operator confirmation for side-effecting tools, defensive
fallback for retrieval components), common commands.
- README.md — quick-start summary.
Scaffolded code (all signature-stable, with NotImplementedError
stubs where phase-specific work is required):
docs_mcp/server.py FastMCP server, stateless_http=True, with
search_docs / get_page / list_versions
baseline tools and commented stubs for the
rest of the phase set.
docs_mcp/usage.py TimedCall telemetry, JSONL, daily rotation,
90-day retention. Reusable as-is.
rag/embeddings.py Ollama embedder (nomic-embed-text default),
load-balanced across N URLs. Reusable.
rag/chunk.py Paragraph-aware chunker with synthetic
chunk 0. Per-product tunable.
rag/index.py Chroma + BM25 builder. --rebuild and
--bm25-only flags.
rag/bm25.py SQLite FTS5 lexical index. Reusable.
scrape/changelog.py --cached / --ref / --json / --history-out.
Reusable.
scrape/README.md What you write per-product.
eval/queries.jsonl.example
Curate ~25 hand-labeled queries here.
eval/retrievers.py Retriever protocol + stub classes.
eval/run_eval.py MRR / Recall@K / nDCG@K harness skeleton.
scripts/usage_report.py
Standalone log analyzer; the
FOLLOW-UP CHECKS pattern noted in the
module docstring.
scripts/registry_gc.py
Gitea container registry cleanup. Reusable.
Deployment + CI:
Dockerfile Python 3.12-slim; COPY corpus + chroma
+ bm25 last for cache efficiency.
deploy/docker-compose.yml MCP + reranker sidecar + Watchtower.
Templated with <placeholders>.
.gitea/workflows/refresh.yml Weekly cron + manual dispatch.
fetch-depth: 0, retry-on-race,
three-tag image scheme.
.gitea/workflows/image-only.yml Code-only ship cycle, ~18min.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
112 lines
3.7 KiB
YAML
112 lines
3.7 KiB
YAML
# Hosting stack for a docs MCP server.
|
|
#
|
|
# Replace <product> below with your product name on first deploy.
|
|
# Volumes: usage logs are mounted to a host path so they survive
|
|
# Watchtower-driven container recreates.
|
|
#
|
|
# This template assumes a reverse proxy / Cloudflare Tunnel terminates
|
|
# TLS in front of port 8000. Adjust if your infra differs.
|
|
|
|
services:
|
|
|
|
# The MCP server. Watchtower auto-pulls on :latest changes.
|
|
<product>-docs-mcp:
|
|
image: <registry>/<owner>/<product>-docs-mcp:latest
|
|
container_name: <product>-docs-mcp
|
|
restart: unless-stopped
|
|
ports:
|
|
- "8000:8000"
|
|
environment:
|
|
PRODUCT_NAME: "<product>"
|
|
PRODUCT_DOCS_URL: "https://docs.example.com"
|
|
|
|
# Streamable-HTTP transport. Stateless mode is required for
|
|
# production: clients don't lose sessions when Watchtower
|
|
# recreates the container.
|
|
MCP_TRANSPORT: streamable-http
|
|
MCP_HOST: 0.0.0.0
|
|
MCP_PORT: "8000"
|
|
|
|
# If you run MetaMCP or another gateway in front and reach
|
|
# this container via its compose DNS name (e.g. <product>-docs-mcp:8000),
|
|
# add that hostname here. "*" disables the rebind check entirely.
|
|
MCP_ALLOWED_HOSTS: "<product>-docs-mcp,localhost,127.0.0.1"
|
|
|
|
# Phase 6 — reranker sidecar (jina-reranker-v2-base via llama.cpp).
|
|
RERANK_URL: http://<product>-rerank:8080
|
|
RERANK_POOL: "200"
|
|
RERANK_TIMEOUT: "30"
|
|
|
|
# Phase 8 — hybrid retrieval (BM25 + dense + RRF). Set true
|
|
# only after the eval harness shows the dense-only path
|
|
# missing technical-term queries that BM25 catches.
|
|
HYBRID_SEARCH: "true"
|
|
|
|
# Phase 10 — usage telemetry.
|
|
USAGE_LOG_DIR: /app/var/logs
|
|
USAGE_LOG_KEEP_DAYS: "90"
|
|
|
|
# Phase 12 — doc-bug submission gate. Off by default; on only
|
|
# in production after you've verified the endpoint contract.
|
|
DOC_BUG_SUBMIT_ENABLED: "false"
|
|
# DOC_BUG_API_URL: "https://docs-be.example.com/api/feedback"
|
|
volumes:
|
|
# Usage logs persist across container recreates.
|
|
- ./<product>-docs-mcp-logs:/app/var/logs
|
|
depends_on:
|
|
- <product>-rerank
|
|
labels:
|
|
# Watchtower polls *only* containers with this label set true.
|
|
com.centurylinklabs.watchtower.enable: "true"
|
|
networks:
|
|
- mcp
|
|
|
|
# Reranker sidecar — llama.cpp serving jina-reranker-v2-base.
|
|
# Requires GPU access; adjust runtime/devices for your hardware.
|
|
<product>-rerank:
|
|
image: ghcr.io/ggml-org/llama.cpp:server-cuda
|
|
container_name: <product>-rerank
|
|
restart: unless-stopped
|
|
# Mount the GGUF model from the host. Download from huggingface
|
|
# (gguf-org/jina-reranker-v2-base-multilingual-GGUF) first.
|
|
volumes:
|
|
- /path/to/models:/models:ro
|
|
command: >
|
|
--model /models/jina-reranker-v2-base.Q8_0.gguf
|
|
--reranking
|
|
--host 0.0.0.0
|
|
--port 8080
|
|
--n-gpu-layers 99
|
|
--ctx-size 4096
|
|
deploy:
|
|
resources:
|
|
reservations:
|
|
devices:
|
|
- driver: nvidia
|
|
count: 1
|
|
capabilities: [gpu]
|
|
networks:
|
|
- mcp
|
|
|
|
# Watchtower — auto-pulls :latest on push.
|
|
# Only watches containers labeled `com.centurylinklabs.watchtower.enable=true`.
|
|
watchtower:
|
|
image: containrrr/watchtower:latest
|
|
container_name: watchtower
|
|
restart: unless-stopped
|
|
volumes:
|
|
- /var/run/docker.sock:/var/run/docker.sock
|
|
environment:
|
|
WATCHTOWER_POLL_INTERVAL: "300" # 5 min
|
|
WATCHTOWER_LABEL_ENABLE: "true"
|
|
WATCHTOWER_CLEANUP: "true" # remove old images after pull
|
|
# If your registry requires auth, mount a docker config:
|
|
# volumes:
|
|
# - ./registry-auth.json:/config.json:ro
|
|
networks:
|
|
- mcp
|
|
|
|
networks:
|
|
mcp:
|
|
driver: bridge
|