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>
44 lines
1.2 KiB
Docker
44 lines
1.2 KiB
Docker
# Docs MCP server — production image.
|
|
#
|
|
# Structure: copy code first, then the regenerable indexes last so a
|
|
# code-only change doesn't invalidate the corpus COPY layer.
|
|
#
|
|
# The container runs the MCP server via streamable-http on PORT 8000.
|
|
# Override via MCP_HOST / MCP_PORT env if you front it with a different
|
|
# reverse-proxy setup.
|
|
|
|
FROM python:3.12-slim
|
|
|
|
WORKDIR /app
|
|
|
|
# Install Python deps first for cacheability.
|
|
COPY requirements.txt /app/
|
|
RUN pip install --no-cache-dir -r requirements.txt
|
|
|
|
# Code.
|
|
COPY scrape /app/scrape
|
|
COPY rag /app/rag
|
|
COPY docs_mcp /app/docs_mcp
|
|
|
|
# Catalog. Written by the scraper at CI time.
|
|
COPY bundles.json /app/
|
|
|
|
# Regenerable indexes. CI builds these from corpus/ in the same job
|
|
# that builds the image. Listed last so code changes don't invalidate
|
|
# the COPY layer cache for these (much larger) directories.
|
|
#
|
|
# bm25/ is only consulted when HYBRID_SEARCH=true (the server falls
|
|
# back to dense-only if it's missing).
|
|
COPY corpus /app/corpus
|
|
COPY chroma /app/chroma
|
|
COPY bm25 /app/bm25
|
|
|
|
ENV PYTHONUNBUFFERED=1 \
|
|
MCP_TRANSPORT=streamable-http \
|
|
MCP_HOST=0.0.0.0 \
|
|
MCP_PORT=8000
|
|
|
|
EXPOSE 8000
|
|
|
|
ENTRYPOINT ["python", "-m", "docs_mcp.server"]
|