Port docs-mcp-template upgrades (eval, citations, prefixes) (#26)

Co-authored-by: claude <[email protected]>

docs_mcp/format.py

@@ -0,0 +1,43 @@
+"""Markdown formatters for MCP tool output.
+
+No third-party imports — tests can run without mcp/httpx/chromadb.
+Citation numbers are per-call (1-based, dense) and stateless.
+"""
+from __future__ import annotations
+
+
+def format_search_hit(
+    n: int,
+    title: str,
+    url: str,
+    text: str,
+    extra: str = "",
+) -> str:
+    """One numbered hit. `n` is 1-based in final reranked/fused order."""
+    head = f"[{n}] **{title}**"
+    if url:
+        head += f" — {url}"
+    parts = [head]
+    if extra:
+        parts.append(extra)
+    body = (text or "").strip()
+    if body:
+        parts.append(body)
+    return "\n".join(parts)
+
+
+def format_search_hits(
+    hits: list[tuple[str, str, str, str]],
+) -> str:
+    """Render hits as `[1] **title** — url` then text.
+
+    `hits` is a list of (title, url, text, extra) in display order.
+    Empty list → empty string (no invented citations).
+    """
+    if not hits:
+        return ""
+    blocks = [
+        format_search_hit(n, title, url, text, extra)
+        for n, (title, url, text, extra) in enumerate(hits, start=1)
+    ]
+    return "\n\n".join(blocks) + "\n"