initial: docs-mcp-template — build guide + scaffolded server

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>

README.md

@@ -0,0 +1,104 @@
+# docs-mcp-template
+
+A reusable template for building hosted MCP servers over a product's
+public documentation. Distilled from one production build; everything
+product-specific has been factored out.
+
+The end product is a streamable-HTTP MCP server with ~15 tools that
+any LLM client (Claude Desktop, Claude Code, Cursor, Copilot) can
+call to answer questions against the docs, surface what changed
+recently, find inconsistencies, and (optionally) submit doc bugs
+back upstream.
+
+## What's here
+
+- **[PLAN.md](PLAN.md)** — comprehensive build guide. Phased
+  approach (13 phases, ~2–3 weeks of focused work for the full
+  stack). Includes the design decisions, the gotchas, and a
+  per-product customization checklist.
+- **Scaffolded skeleton** — working FastMCP server with stub tools,
+  Dockerfile, docker-compose, CI workflows, eval harness layout,
+  usage logging. Everything you need to `git clone` and start
+  filling in the product-specific bits.
+
+## Quick start
+
+```bash
+git clone https://git.jpaul.io/justin/docs-mcp-template.git my-product-docs
+cd my-product-docs
+git remote remove origin  # detach from template
+python -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+
+# Read PLAN.md before doing anything else. Pay particular attention to
+# Phase 1 (scraper) — that's the most product-specific phase.
+
+# Run the stub server (no corpus yet — just verifies the wiring):
+python -m docs_mcp.server --transport stdio
+```
+
+## Repo layout
+
+```
+.
+├── PLAN.md                        # The build guide. Read first.
+├── README.md
+├── requirements.txt
+├── Dockerfile
+├── .gitignore
+├── .gitea/workflows/
+│   ├── refresh.yml                # Weekly scrape + index + image push
+│   └── image-only.yml             # On-demand code-only ship
+├── scrape/
+│   ├── README.md                  # Product-specific scraper goes here
+│   └── changelog.py               # Reusable: --json, --history-out
+├── rag/
+│   ├── embeddings.py              # Ollama embedder, swappable
+│   ├── chunk.py                   # Chunker — adjust per page format
+│   ├── index.py                   # Builds Chroma + (optionally) BM25
+│   └── bm25.py                    # SQLite FTS5 lexical index
+├── docs_mcp/
+│   ├── server.py                  # FastMCP server with stub tools
+│   └── usage.py                   # TimedCall + JSONL telemetry
+├── eval/
+│   ├── queries.jsonl.example      # Curate ~25 hand-labeled queries
+│   ├── retrievers.py              # Retriever protocol + implementations
+│   └── run_eval.py                # MRR / Recall@k / nDCG@k harness
+├── scripts/
+│   ├── usage_report.py            # Standalone log analyzer
+│   └── registry_gc.py             # Container registry cleanup
+└── deploy/
+    └── docker-compose.yml         # Hosting stack: MCP + reranker + Watchtower
+```
+
+## What's product-specific (must implement)
+
+- `scrape/` — the scraper itself. The template gives you the corpus
+  layout contract and a working `changelog.py`; the actual extraction
+  logic is yours.
+- The corpus on disk (gitignored; rebuilt by CI).
+- The reranker GGUF model and llama.cpp container (commented in
+  `deploy/docker-compose.yml`).
+- The reverse proxy / TLS layer in front of the public endpoint.
+- The hand-curated knowledge surface (your product's API gotchas,
+  example scripts, anything the LLM should know that the docs
+  don't say).
+
+## What's NOT product-specific (works as-is)
+
+- FastMCP server skeleton + tool decoration pattern
+- Chroma + Ollama embedding pipeline
+- BM25 / SQLite FTS5 lexical index
+- Hybrid retrieval (RRF) + reranker integration
+- Eval harness (Retriever protocol, MRR/Recall/nDCG)
+- Usage logging (TimedCall, JSONL, daily rotation)
+- CI workflow shape (weekly + on-demand, retry-on-race, three-tag
+  image scheme)
+- Registry GC script
+- Standard tools: `search_docs`, `get_page`, `list_versions`,
+  `diff_versions`, `bundle_changelog`, `weekly_digest`,
+  `find_doc_inconsistencies`, `submit_doc_bug`, etc.
+
+## License
+
+Internal template. Adjust before publishing.