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>

rag/embeddings.py

@@ -0,0 +1,72 @@
+"""Embedding function for Chroma — Ollama-hosted nomic-embed-text by default.
+
+Swappable: implement the same `embedding_function()` interface returning
+a Chroma `EmbeddingFunction` and the rest of the pipeline doesn't care.
+
+Defaults (override via env):
+  OLLAMA_URL    one or more comma-separated URLs (load-balanced)
+  EMBED_MODEL   model name; default 'nomic-embed-text'
+  EMBED_DIM     expected embedding dim; default 768 (nomic-embed-text)
+"""
+from __future__ import annotations
+
+import os
+import logging
+from typing import Any
+
+import httpx
+from chromadb import EmbeddingFunction, Documents, Embeddings
+
+log = logging.getLogger(__name__)
+
+OLLAMA_URLS = [u.strip() for u in os.environ.get("OLLAMA_URL",
+               "http://localhost:11434").split(",") if u.strip()]
+EMBED_MODEL = os.environ.get("EMBED_MODEL", "nomic-embed-text")
+EMBED_DIM = int(os.environ.get("EMBED_DIM", "768"))
+
+
+class OllamaEmbeddings(EmbeddingFunction):
+    """Calls /api/embed across N Ollama endpoints, naive round-robin.
+
+    For indexing throughput on multiple GPUs, run one Ollama container
+    per GPU (pinned via NVIDIA_VISIBLE_DEVICES) and pass all their URLs
+    in OLLAMA_URL — the embedder picks the next endpoint per batch.
+    """
+
+    def __init__(self, urls: list[str] = OLLAMA_URLS, model: str = EMBED_MODEL):
+        self.urls = urls
+        self.model = model
+        self._next = 0
+
+    def __call__(self, input: Documents) -> Embeddings:
+        url = self.urls[self._next % len(self.urls)]
+        self._next += 1
+        with httpx.Client(timeout=300) as c:
+            r = c.post(f"{url}/api/embed",
+                       json={"model": self.model, "input": list(input)})
+            r.raise_for_status()
+            data = r.json()
+        return data.get("embeddings") or []
+
+    def name(self) -> str:                  # newer chromadb requires this
+        return f"ollama:{self.model}"
+
+    @staticmethod
+    def build_from_config(config: dict) -> "OllamaEmbeddings":  # newer chromadb
+        return OllamaEmbeddings(
+            urls=config.get("urls", OLLAMA_URLS),
+            model=config.get("model", EMBED_MODEL),
+        )
+
+    def get_config(self) -> dict:           # newer chromadb
+        return {"urls": self.urls, "model": self.model}
+
+    def default_space(self) -> str:
+        return "cosine"
+
+    def supported_spaces(self) -> list[str]:
+        return ["cosine", "l2", "ip"]
+
+
+def embedding_function() -> EmbeddingFunction:
+    return OllamaEmbeddings()