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>
73 lines
2.4 KiB
Python
73 lines
2.4 KiB
Python
"""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()
|