contextual-engine 0.1.0__py3-none-any.whl

contextual/mcp/docs_tools.py

@@ -0,0 +1,286 @@
+"""MCP tool definitions for Phase 2 docs search.
+
+Registers three tools onto the shared FastMCP instance:
+  docs_search        — hybrid BM25 + vector search over indexed docs
+  docs_get_section   — retrieve exact section by heading path (5-tier resolver)
+  docs_list_files    — enumerate indexed doc files with optional heading tree
+
+Feature-flag gate: tools are registered ONLY when the env var
+  CONTEXTUAL_DOCS_ENABLED=1
+is set.  The existing Phase 1 codebase.* tools are unaffected regardless.
+
+Import side-effects:
+  This module MUST be imported by ``contextual/mcp/tools.py`` (or server.py)
+  AFTER the shared ``mcp`` FastMCP instance is created.  It imports ``mcp``
+  from the sibling module — zero circular-import risk because tools.py does
+  not import from here.
+
+Usage in server.py / tools.py::
+
+    import os
+    if os.getenv("CONTEXTUAL_DOCS_ENABLED", "0") == "1":
+        import contextual.mcp.docs_tools  # noqa: F401 — registers tools as side-effect
+
+Never write to stdout — this server runs on stdio MCP transport.
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path
+
+import structlog
+
+# Import the shared FastMCP instance and pool helper from the existing tools module.
+# tools.py owns the singleton _pool and _get_pool(); we reuse them directly.
+from contextual.mcp.tools import _get_pool  # noqa: PLC2701 (internal import intentional)
+from contextual.mcp.server import mcp
+from contextual.embedding.embedder import get_docs_embedder, get_embedder
+from contextual.docs.retrieval import (
+    DocSearchHit,
+    DocSection,
+    DocFileInfo,
+    docs_search,
+    docs_get_section,
+    docs_list_files,
+)
+
+logger = structlog.get_logger(__name__)
+
+# Confirm gate at import time so the log is visible in server startup output
+_DOCS_ENABLED = os.getenv("CONTEXTUAL_DOCS_ENABLED", "0") == "1"
+logger.info("Docs tools module loaded", enabled=_DOCS_ENABLED)
+
+
+# ---------------------------------------------------------------------------
+# Serialisation helpers
+# ---------------------------------------------------------------------------
+
+def _hit_to_dict(hit: DocSearchHit) -> dict:
+    return {
+        "chunk_id":     hit.chunk_id,
+        "file_path":    hit.file_path,
+        "content":      hit.content,
+        "heading_path": hit.heading_path,
+        "heading_level":hit.heading_level,
+        "chunk_type":   hit.chunk_type,
+        "start_line":   hit.start_line,
+        "end_line":     hit.end_line,
+        "score":        hit.score,
+        "bm25_rank":    hit.bm25_rank,
+        "vector_rank":  hit.vector_rank,
+    }
+
+
+def _section_to_dict(sec: DocSection) -> dict:
+    d = {
+        "file_path":     sec.file_path,
+        "heading_path":  sec.heading_path,
+        "heading_level": sec.heading_level,
+        "content":       sec.content,
+        "start_line":    sec.start_line,
+        "end_line":      sec.end_line,
+    }
+    if sec.subsections:
+        d["subsections"] = [_section_to_dict(s) for s in sec.subsections]
+    return d
+
+
+def _fileinfo_to_dict(fi: DocFileInfo) -> dict:
+    d = {"file_path": fi.file_path, "chunk_count": fi.chunk_count}
+    if fi.headings:
+        d["headings"] = fi.headings
+    return d
+
+
+# ---------------------------------------------------------------------------
+# Tool 1: docs_search
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def docs_search_tool(
+    query: str,
+    k: int = 10,
+    source_filter: str | None = None,
+) -> str:
+    """Semantically search indexed documentation and markdown files.
+
+    Performs hybrid BM25 + vector search (RRF fusion) over all docs indexed
+    by Contextual (README, ADRs, wikis, changelogs, any .md/.mdx/.rst/.txt).
+
+    Args:
+        query:         Natural-language question or keyword string.
+        k:             Number of results to return (1-50).
+        source_filter: Optional JSON string with filter keys:
+                         repo        list[str] — restrict to files under this path prefix
+                         file        list[str] — exact file paths to restrict to
+                         heading     str       — LIKE pattern on heading_path
+                         source_type list[str] — "docs" | "docs_code" | both
+
+    Returns:
+        JSON array of search hits, each with: file_path, content, heading_path,
+        heading_level, chunk_type, start_line, end_line, score.
+
+    Examples:
+        docs_search_tool("how does the file watcher work")
+        docs_search_tool("installation prerequisites", k=5)
+        docs_search_tool("ADR decisions", source_filter='{"repo": ["docs/adr"]}')
+    """
+    if not _DOCS_ENABLED:
+        return json.dumps({"error": "Docs indexing is disabled. Set CONTEXTUAL_DOCS_ENABLED=1."})
+
+    k = max(1, min(k, 50))
+
+    parsed_filter: dict | None = None
+    if source_filter:
+        try:
+            parsed_filter = json.loads(source_filter)
+        except json.JSONDecodeError as exc:
+            return json.dumps({"error": f"Invalid source_filter JSON: {exc}"})
+
+    pool = _get_pool()
+    embedder = get_embedder()
+
+    try:
+        with pool.reader() as conn:
+            hits = docs_search(
+                query=query,
+                conn=conn,
+                embedder=embedder,
+                k=k,
+                source_filter=parsed_filter,
+            )
+    except Exception as exc:  # noqa: BLE001
+        logger.error("docs_search_tool failed", query=query, error=str(exc))
+        return json.dumps({"error": str(exc)})
+
+    logger.info("docs_search_tool", query=query[:80], k=k, hits=len(hits))
+    return json.dumps([_hit_to_dict(h) for h in hits], ensure_ascii=False, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Tool 2: docs_get_section
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def docs_get_section_tool(
+    file: str,
+    heading_path: str,
+    include_subsections: bool = False,
+    fuzzy: bool = True,
+) -> str:
+    """Retrieve an exact section from an indexed document by heading path.
+
+    Uses a 5-tier resolution strategy:
+      1. Exact heading_path match
+      2. GitHub-slug match (case/punctuation insensitive)
+      3. Suffix/leaf match (just the last heading segment)
+      4. Fuzzy match via RapidFuzz WRatio ≥ 72
+      5. FTS5 content search fallback
+
+    On miss, returns a JSON error object with ``did_you_mean`` suggestions.
+
+    Args:
+        file:                Repo-relative file path (e.g. "docs/README.md").
+        heading_path:        Section heading or breadcrumb path.
+                             Accepts: "Installation > macOS > Homebrew"
+                                      "installation/macos/homebrew"
+                                      "Homebrew"  (leaf-only)
+        include_subsections: If True, child sections are included in the response.
+        fuzzy:               Enable tiers 3-5 of resolver (default True).
+
+    Returns:
+        JSON object with: file_path, heading_path, heading_level, content,
+        start_line, end_line, and optionally subsections[].
+        On failure: {"error": "heading_not_found", "did_you_mean": [...]}
+
+    Examples:
+        docs_get_section_tool("docs/README.md", "Installation > macOS")
+        docs_get_section_tool("PHASE_1.md", "Success Criteria", include_subsections=True)
+        docs_get_section_tool("docs/adr/ADR-004.md", "Decision", fuzzy=False)
+    """
+    if not _DOCS_ENABLED:
+        return json.dumps({"error": "Docs indexing is disabled. Set CONTEXTUAL_DOCS_ENABLED=1."})
+
+    pool = _get_pool()
+
+    try:
+        with pool.reader() as conn:
+            result = docs_get_section(
+                file=file,
+                heading_path=heading_path,
+                conn=conn,
+                include_subsections=include_subsections,
+                fuzzy=fuzzy,
+            )
+    except Exception as exc:  # noqa: BLE001
+        logger.error("docs_get_section_tool failed", file=file, heading=heading_path, error=str(exc))
+        return json.dumps({"error": str(exc)})
+
+    if isinstance(result, dict):
+        # Error object from resolver
+        return json.dumps(result, ensure_ascii=False)
+
+    logger.info(
+        "docs_get_section_tool",
+        file=file,
+        heading=heading_path,
+        resolved=result.heading_path,
+    )
+    return json.dumps(_section_to_dict(result), ensure_ascii=False, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Tool 3: docs_list_files
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def docs_list_files_tool(
+    repo: str | None = None,
+    glob: str | None = None,
+    include_headings: bool = False,
+) -> str:
+    """List all documentation files currently indexed by Contextual.
+
+    Args:
+        repo:             Optional path prefix to restrict results
+                          (e.g. "docs" returns only files under docs/).
+        glob:             fnmatch glob pattern on file path
+                          (e.g. "docs/adr/*.md").
+        include_headings: If True, return heading_path list per file.
+                          Useful to understand a file's structure before
+                          calling docs_get_section.
+
+    Returns:
+        JSON array of file info objects with: file_path, chunk_count,
+        and optionally headings[].
+
+    Examples:
+        docs_list_files_tool()
+        docs_list_files_tool(repo="docs/adr", include_headings=True)
+        docs_list_files_tool(glob="**/*.md")
+    """
+    if not _DOCS_ENABLED:
+        return json.dumps({"error": "Docs indexing is disabled. Set CONTEXTUAL_DOCS_ENABLED=1."})
+
+    pool = _get_pool()
+
+    try:
+        with pool.reader() as conn:
+            files = docs_list_files(
+                conn=conn,
+                repo=repo,
+                glob=glob,
+                include_headings=include_headings,
+            )
+    except Exception as exc:  # noqa: BLE001
+        logger.error("docs_list_files_tool failed", error=str(exc))
+        return json.dumps({"error": str(exc)})
+
+    logger.info("docs_list_files_tool", count=len(files), repo=repo, glob=glob)
+    return json.dumps(
+        [_fileinfo_to_dict(f) for f in files],
+        ensure_ascii=False,
+        indent=2,
+    )

contextual/mcp/server.py

@@ -0,0 +1,118 @@
+"""FastMCP server for Contextual codebase tools.
+
+This module initializes the FastMCP server and registers all tools.
+Tools are defined in tools.py and registered here.
+
+Server configuration:
+- Name: "contextual"
+- Transport: stdio (MCP standard)
+- Structured logging to stderr (never stdout in stdio mode)
+- Graceful shutdown on SIGTERM/SIGINT
+"""
+
+from __future__ import annotations
+
+# Suppress warnings BEFORE any other imports to prevent stdout pollution
+import warnings
+warnings.filterwarnings('ignore')
+
+import signal
+import sys
+from typing import Any
+
+from fastmcp import FastMCP
+
+from contextual.observability.logging import configure_logging, get_logger
+
+# Configure logging IMMEDIATELY so structlog routes to stderr, not stdout.
+# structlog's default PrintLoggerFactory writes to stdout which breaks MCP stdio.
+configure_logging()
+
+logger = get_logger(__name__)
+
+# ============================================================================
+# SERVER INITIALIZATION
+# ============================================================================
+
+# Create FastMCP server instance
+mcp = FastMCP("contextual")
+
+
+# ============================================================================
+# GRACEFUL SHUTDOWN
+# ============================================================================
+
+
+def _handle_shutdown(signum: int, frame: Any) -> None:
+    """Handle shutdown signals gracefully.
+
+    On SIGTERM/SIGINT:
+    1. Log shutdown
+    2. Close database connections
+    3. Flush logs
+    4. Exit cleanly
+
+    Args:
+        signum: Signal number.
+        frame: Current stack frame.
+    """
+    logger.info("Shutdown signal received", signal=signum)
+
+    try:
+        # Close database pools
+        from contextual.mcp.tools import _pool
+        if _pool is not None:
+            _pool.close()
+            logger.debug("Database pool closed")
+        
+        logger.info("Shutdown complete")
+        sys.exit(0)
+    except Exception as e:
+        logger.error("Shutdown error", error=str(e))
+        sys.exit(1)
+
+
+# Register signal handlers
+signal.signal(signal.SIGTERM, _handle_shutdown)
+signal.signal(signal.SIGINT, _handle_shutdown)
+
+
+# ============================================================================
+# TOOL REGISTRATION
+# ============================================================================
+
+# Import tools module to register @mcp.tool() decorated functions
+# MUST come after mcp is created but before main() runs
+from contextual.mcp import tools  # noqa: F401, E402
+
+
+# ============================================================================
+# SERVER ENTRYPOINT
+# ============================================================================
+
+
+def main() -> None:
+    """Run the MCP server.
+
+    This is the main entry point called by the contextual CLI.
+    Starts the FastMCP server in stdio mode.
+    """
+    logger.info("Starting Contextual MCP server")
+
+    try:
+        # Run the server (blocking)
+        mcp.run()
+    except KeyboardInterrupt:
+        logger.info("Server interrupted")
+        sys.exit(0)
+    except Exception as e:
+        logger.error("Server error", error=str(e), exc_info=True)
+        sys.exit(1)
+
+import os
+if os.getenv("CONTEXTUAL_DOCS_ENABLED", "0") == "1":
+    import contextual.mcp.docs_tools  # noqa: F401
+
+
+if __name__ == "__main__":
+    main()