mcp

scripts/mcp-server/src/mcp_server/docs_sync.py

@@ -0,0 +1,56 @@
+"""Documentation synchronization checks for MCP tool catalog."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp_server.tools import DocsPath, tool_catalog
+
+
+def check_catalog_parity() -> dict[str, object]:
+    """Compare documented anchors with the live tool catalog and report drift."""
+    missing_in_docs: list[str] = []
+    missing_in_catalog: list[str] = []
+    mismatches: list[dict[str, str]] = []
+
+    docs_tools = _doc_anchors()
+    catalog = tool_catalog()
+    for tool in catalog:
+        anchor_key = _anchor_key(tool.docs_anchor.path, tool.docs_anchor.anchor)
+        if anchor_key not in docs_tools:
+            missing_in_docs.append(tool.name)
+    for anchor_key, tool_name in docs_tools.items():
+        if tool_name not in {t.name for t in catalog}:
+            missing_in_catalog.append(anchor_key)
+    return {
+        "status": (
+            "ok"
+            if not missing_in_docs and not missing_in_catalog and not mismatches
+            else "drift_detected"
+        ),
+        "missingInDocs": missing_in_docs,
+        "missingInCatalog": missing_in_catalog,
+        "mismatches": mismatches,
+    }
+
+
+def _doc_anchors() -> dict[str, str]:
+    """Derive anchors from docs files to detect missing catalog entries."""
+    anchors: dict[str, str] = {}
+    files = list(DocsPath.rglob("*.md"))
+    for path in files:
+        tool_name = _derive_tool_name(path)
+        anchor_id = path.stem
+        anchors[_anchor_key(path, anchor_id)] = tool_name
+    return anchors
+
+
+def _derive_tool_name(path: Path) -> str:
+    """Create a best-effort tool name from a documentation path."""
+    parts = path.parts[-3:]
+    return "-".join(filter(None, parts)).replace(".md", "")
+
+
+def _anchor_key(path: Path, anchor: str) -> str:
+    """Build a stable key for an anchor path pair."""
+    return f"{path}#{anchor}"