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>
90 lines
3.0 KiB
YAML
90 lines
3.0 KiB
YAML
name: Image rebuild (skip scrape)
|
|
|
|
# Fast path for code-only changes. Skips the scrape and goes straight to:
|
|
# rebuild indexes (from corpus already committed on main) + image build
|
|
# + push. Runtime is ~18 min vs ~40 min for the full refresh.
|
|
#
|
|
# Use when a PR only changes code/config — anything where the upstream
|
|
# corpus hasn't moved but we want the new Python in the running image.
|
|
#
|
|
# IMPORTANT: fetch-depth: 0 is required for the digest-history step
|
|
# to find commits to walk. Don't change to 1.
|
|
|
|
on:
|
|
workflow_dispatch:
|
|
|
|
env:
|
|
REGISTRY_PUSH: <lan-host>:<port>
|
|
REGISTRY_PULL: <public-registry-hostname>
|
|
IMAGE: <owner>/<product>-docs-mcp
|
|
OLLAMA_URL: http://<gpu-host>:11434
|
|
EMBED_MODEL: nomic-embed-text
|
|
PRODUCT_NAME: <product>
|
|
|
|
jobs:
|
|
build:
|
|
runs-on: docker
|
|
container:
|
|
image: catthehacker/ubuntu:act-latest
|
|
steps:
|
|
- name: Checkout
|
|
uses: actions/checkout@v4
|
|
with:
|
|
# Full history (not shallow) so the digest-history step can
|
|
# walk git log up to --history-days back.
|
|
fetch-depth: 0
|
|
|
|
- name: Set up Python
|
|
uses: actions/setup-python@v5
|
|
with:
|
|
python-version: "3.12"
|
|
|
|
- name: Install dependencies
|
|
run: |
|
|
python -m pip install -q --upgrade pip
|
|
python -m pip install -q -r requirements.txt
|
|
|
|
- name: Refresh digest history
|
|
# Cheap (a few seconds); doesn't touch corpus content.
|
|
# Without this step, a code-only deploy would ship an
|
|
# increasingly-stale digest history relative to git.
|
|
run: |
|
|
mkdir -p corpus/.digest
|
|
python -m scrape.changelog \
|
|
--history-out corpus/.digest/history.jsonl \
|
|
--history-days 120
|
|
|
|
- name: Verify committed corpus is present
|
|
run: |
|
|
test -d corpus || { echo "ERROR: corpus/ missing on this ref"; exit 1; }
|
|
echo "corpus: $(du -sh corpus | cut -f1), $(find corpus -name '*.md' | wc -l) markdown files"
|
|
|
|
- name: Rebuild indexes from existing corpus
|
|
run: python -m rag.index --rebuild
|
|
|
|
- name: Log in to registry (LAN endpoint)
|
|
run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login "${REGISTRY_PUSH}" -u <user> --password-stdin
|
|
|
|
- name: Build & push image
|
|
run: |
|
|
SHA_TAG=$(echo "$GITHUB_SHA" | cut -c1-12)
|
|
DATE_TAG=$(date -u +%Y.%m.%d)
|
|
docker build \
|
|
-t "${REGISTRY_PUSH}/${IMAGE}:latest" \
|
|
-t "${REGISTRY_PUSH}/${IMAGE}:${SHA_TAG}" \
|
|
-t "${REGISTRY_PUSH}/${IMAGE}:${DATE_TAG}" \
|
|
.
|
|
docker push "${REGISTRY_PUSH}/${IMAGE}:latest"
|
|
docker push "${REGISTRY_PUSH}/${IMAGE}:${SHA_TAG}"
|
|
docker push "${REGISTRY_PUSH}/${IMAGE}:${DATE_TAG}"
|
|
|
|
- name: Prune old container versions
|
|
env:
|
|
GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
|
|
run: |
|
|
python scripts/registry_gc.py \
|
|
--owner <user> \
|
|
--package <product>-docs-mcp \
|
|
--keep-days 90 \
|
|
--keep-latest 5
|