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>

eval/retrievers.py

@@ -0,0 +1,62 @@
+"""Retriever protocol + concrete implementations.
+
+A single matrix dimension per knob (dense / reranked / bm25 / hybrid)
+so the eval harness can compare them apples-to-apples. Implement these
+once at Phase 7 and reuse them across every retrieval change.
+
+Each retriever returns a ranked list of (bundle_id, page_id) tuples
+deduplicated to the page level (chunks within the same page collapse
+to one entry; the highest-ranked chunk's position wins).
+"""
+from __future__ import annotations
+
+from typing import Protocol, Iterable
+
+
+class Retriever(Protocol):
+    name: str
+
+    def retrieve(self, query: str, k: int = 10) -> list[tuple[str, str]]:
+        """Return up to k (bundle_id, page_id) tuples in rank order."""
+        ...
+
+
+def _collapse_to_pages(chunk_ids: Iterable[tuple[str, str, str]], k: int) -> list[tuple[str, str]]:
+    """Take a stream of (bundle_id, page_id, chunk_ordinal) and return
+    the first k unique pages in their first-seen order."""
+    seen: set[tuple[str, str]] = set()
+    out: list[tuple[str, str]] = []
+    for bid, pid, _ord in chunk_ids:
+        key = (bid, pid)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(key)
+        if len(out) >= k:
+            break
+    return out
+
+
+# TODO Phase 2/3 — implement these once Chroma + the bm25 module are
+# in place. Each one is small (15-30 LOC). The eval harness imports
+# from this module by class name.
+#
+# class DenseRetriever:
+#     name = "dense"
+#     def __init__(self, collection): self.col = collection
+#     def retrieve(self, query, k=10): ...
+#
+# class RerankedRetriever:
+#     name = "dense+rerank"
+#     def __init__(self, collection, rerank_url, pool=200): ...
+#     def retrieve(self, query, k=10): ...
+#
+# class BM25Retriever:
+#     name = "bm25"
+#     def __init__(self, bm25_index): ...
+#     def retrieve(self, query, k=10): ...
+#
+# class HybridRetriever:
+#     name = "bm25+dense+rrf"
+#     def __init__(self, dense, bm25, k_rrf=60): ...
+#     def retrieve(self, query, k=10): ...