codegraph-nav 0.1.0__py3-none-any.whl

codegraph_nav/mcp/server.py

@@ -0,0 +1,2228 @@
+#!/usr/bin/env python3
+"""Codegraph-nav MCP Server - Token-efficient code navigation for AI assistants.
+
+This server implements the Model Context Protocol (MCP) using FastMCP to expose
+codegraph-nav's code navigation capabilities to Claude Desktop, Claude Code, and
+other MCP-compatible AI assistants.
+
+Usage:
+    python -m codegraph_nav.mcp
+    codegraph-nav-mcp
+"""
+
+import json
+import logging
+import os
+import re
+import subprocess
+from collections import Counter
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional, cast
+
+from mcp.server.fastmcp import FastMCP
+
+from ..code_navigator import CodeNavigator
+from ..code_search import CodeSearcher
+from ..line_reader import LineReader
+
+if TYPE_CHECKING:
+    from ..graph import GraphStore
+    from ..hints import SessionState
+
+# Optional imports
+try:
+    from ..token_efficient_renderer import TokenEfficientRenderer
+
+    HAS_RENDERER = True
+except ImportError:
+    HAS_RENDERER = False
+
+logger = logging.getLogger(__name__)
+
+# ==============================================================================
+# CONSTANTS
+# ==============================================================================
+
+DETAIL_LEVELS = ("minimal", "standard", "verbose")
+
+# Security limits
+MAX_LIMIT = 200
+MAX_DEPTH = 10
+
+# Regex patterns for identifying test files
+TEST_FILE_PATTERNS = [
+    re.compile(r"test_[^/]*\.py$"),
+    re.compile(r"[^/]*_test\.py$"),
+    re.compile(r"[^/]*\.test\.[jt]sx?$"),
+    re.compile(r"[^/]*\.spec\.[jt]sx?$"),
+    re.compile(r"(^|/)tests/"),
+    re.compile(r"(^|/)__tests__/"),
+    re.compile(r"(^|/)test/"),
+]
+
+
+def _validate_detail_level(level: str) -> str:
+    """Validate and normalize detail_level parameter."""
+    level = level.lower().strip()
+    if level not in DETAIL_LEVELS:
+        return "minimal"
+    return level
+
+
+# ==============================================================================
+# SYSTEM PROMPT - Instructions for AI agents
+# ==============================================================================
+
+SYSTEM_PROMPT = """# Codegraph-Nav - Graph-Intelligent, Token-Efficient Code Navigation
+
+You have access to Codegraph-Nav, an MCP server for exploring codebases efficiently while minimizing token usage.
+
+## Quick Start
+
+1. **Orient first** (`codegraph_get_minimal_context`): Get a ~100 token project overview. Always start here.
+2. **Scan if needed** (`codegraph_scan`): Generate the code index (creates `.codegraph.json`).
+3. **Search by symbol** (`codegraph_search`): Find functions, classes, methods by name. Returns file:line locations.
+4. **Read surgically** (`codegraph_read`): Load only the specific lines you need, never entire files.
+
+## Detail Levels
+
+All tools accept `detail_level` parameter: `minimal` (default), `standard`, or `verbose`.
+Start with `minimal`. Only escalate if you need more context.
+
+## Available Tools
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `codegraph_get_minimal_context` | ~100 token orientation | **Always use first** |
+| `codegraph_scan` | Index codebase | First time on a new project |
+| `codegraph_search` | Find symbols | Looking for specific function/class |
+| `codegraph_read` | Read lines | After finding symbol location |
+| `codegraph_stats` | Codebase overview | Understanding project size |
+| `codegraph_get_hubs` | Find central files | Architecture analysis |
+| `codegraph_get_structure` | File outline | Before reading a file |
+| `codegraph_get_dependencies` | Import graph | Understanding coupling |
+| `codegraph_test_gaps` | Find untested symbols | Before/after changes |
+| `codegraph_graph_build` | Build graph DB | Before using graph tools |
+| `codegraph_blast_radius` | Impact analysis | "What breaks if I change this?" |
+| `codegraph_list_flows` | Execution flows | Understanding call chains |
+| `codegraph_detect_changes` | Risk-scored diff | Code review / PR analysis |
+| `codegraph_search_graph` | FTS5 hybrid search | Search by concept, not just name |
+| `codegraph_list_communities` | Code communities | Architecture grouping |
+| `codegraph_get_community` | Community details | Explore a specific community |
+| `codegraph_get_architecture_overview` | Architecture summary | High-level structure |
+| `codegraph_list_routes` | HTTP routes (15+ frameworks) | API/route exploration |
+| `codegraph_list_schemas` | ORM schemas (8+ ORMs) | Data model exploration |
+
+## Example Session
+
+```
+User: "Fix the payment bug"
+
+1. codegraph_get_minimal_context(path="/project", task="fix payment bug")
+   → project: 142 files · 1847 symbols · py,js
+   → hubs: config.py(8←), models.py(5←)
+   → suggest: codegraph_search → codegraph_read → codegraph_get_dependencies
+
+2. codegraph_search(query="payment")
+   → payments.py:L45-89 [fn] process_payment
+
+3. codegraph_read(file_path="payments.py", start_line=45, end_line=89)
+   → Read only those 44 lines (~500 tokens vs ~15,000 for whole file)
+
+4. codegraph_test_gaps(path="/project", changed_only=True)
+   → 2 untested symbols | gaps: process_payment, validate_card
+```
+
+## Workflow Templates
+
+Use the built-in prompts for common tasks:
+- `investigate_bug` - Bug investigation workflow
+- `add_feature` - Feature implementation workflow
+- `review_changes` - Code review workflow
+- `understand_architecture` - Architecture analysis workflow
+- `onboard_project` - Project onboarding workflow
+
+Each enforces: start with minimal_context, use minimal detail_level, escalate only when needed.
+"""
+
+# ==============================================================================
+# SERVER INITIALIZATION
+# ==============================================================================
+
+# Create FastMCP server with instructions
+mcp = FastMCP(
+    "codegraph-nav",
+    instructions=SYSTEM_PROMPT,
+)
+
+# Global handler instance (initialized per-session)
+_handler: Optional["CodegraphToolHandler"] = None
+
+
+def get_handler() -> "CodegraphToolHandler":
+    """Get or create the tool handler."""
+    global _handler
+    if _handler is None:
+        _handler = CodegraphToolHandler()
+    return _handler
+
+
+# ==============================================================================
+# TOOL HANDLER CLASS
+# ==============================================================================
+
+
+class CodegraphToolHandler:
+    """Handles execution of Codegraph-nav MCP tools."""
+
+    def __init__(self, workspace_root: str | None = None):
+        self.workspace_root = workspace_root or os.getcwd()
+        self._code_map_cache: dict[str, dict] = {}
+        self._navigator_cache: dict[str, CodeNavigator] = {}
+        # Session hints. SessionState is imported lazily below (and under
+        # TYPE_CHECKING), so the annotation must stay a string forward-ref.
+        self._session: "SessionState | None"  # noqa: UP037 (lazy import below)
+        try:
+            from ..hints import SessionState
+
+            self._session = SessionState()
+        except ImportError:
+            self._session = None
+
+    def _get_map_path(self, path: str) -> Path:
+        """Get the .codegraph.json path for a directory."""
+        return Path(path) / ".codegraph.json"
+
+    def _check_map_exists(self, path: str) -> tuple[bool, str]:
+        """Check if code map is available (in cache or on disk)."""
+        abs_path = os.path.abspath(path)
+        if abs_path in self._code_map_cache:
+            return True, ""
+        map_path = self._get_map_path(path)
+        if not map_path.exists():
+            return False, (
+                f"No .codegraph.json found in {path}. "
+                "Run `codegraph_scan` first to index the codebase."
+            )
+        return True, ""
+
+    def _get_navigator(self, path: str) -> CodeNavigator:
+        """Get or create a CodeNavigator for the given path."""
+        abs_path = os.path.abspath(path)
+        if abs_path not in self._navigator_cache:
+            self._navigator_cache[abs_path] = CodeNavigator(abs_path)
+        return self._navigator_cache[abs_path]
+
+    def _get_code_map(self, path: str, force_rescan: bool = False) -> dict:
+        """Get or load a code map for the given path."""
+        abs_path = os.path.abspath(path)
+
+        # Check cache
+        if not force_rescan and abs_path in self._code_map_cache:
+            return self._code_map_cache[abs_path]
+
+        # Load from file
+        map_path = self._get_map_path(abs_path)
+        if map_path.exists():
+            with open(map_path, encoding="utf-8") as f:
+                code_map: dict = json.load(f)
+                self._code_map_cache[abs_path] = code_map
+                return code_map
+
+        return {}
+
+    # ------------------------------------------------------------------
+    # Hub computation (shared by scan, get_hubs, minimal_context)
+    # ------------------------------------------------------------------
+
+    def _compute_hubs(self, code_map: dict, top_n: int = 10, min_imports: int = 3) -> list[dict]:
+        """Compute hub files from a code map.
+
+        Returns list of {"file": str, "imports": int, "symbols": list[str]}.
+        """
+        import_counts: dict[str, int] = {}
+        file_symbols: dict[str, list[str]] = {}
+
+        for fpath, file_info in code_map.get("files", {}).items():
+            file_symbols[fpath] = [s["name"] for s in file_info.get("symbols", [])]
+            for imp in file_info.get("imports", []):
+                import_counts[imp] = import_counts.get(imp, 0) + 1
+
+        hubs = []
+        for file_path, count in import_counts.items():
+            if count >= min_imports:
+                hubs.append(
+                    {
+                        "file": file_path,
+                        "imports": count,
+                        "symbols": file_symbols.get(file_path, []),
+                    }
+                )
+
+        hubs.sort(key=lambda x: cast(int, x["imports"]), reverse=True)
+        return hubs[:top_n]
+
+    # ------------------------------------------------------------------
+    # Search result formatters
+    # ------------------------------------------------------------------
+
+    def _format_search_results_compact(self, results: list, limit: int) -> str:
+        """Format search results in compact single-line format (minimal)."""
+        if not results:
+            return "No matching symbols found."
+
+        lines = [f"Found {len(results)} matches:"]
+
+        for r in results[:limit]:
+            end_line = r.lines[1] if len(r.lines) > 1 else r.lines[0]
+            type_abbr = {"function": "fn", "class": "cls", "method": "mth"}.get(r.type, r.type[:3])
+            lines.append(f"{r.file}:L{r.lines[0]}-{end_line} [{type_abbr}] {r.name}")
+
+        if len(results) > limit:
+            lines.append(f"... +{len(results) - limit} more")
+
+        return "\n".join(lines)
+
+    def _format_search_results_standard(self, results: list, limit: int) -> str:
+        """Format search results with signatures (standard)."""
+        if not results:
+            return "No matching symbols found."
+
+        lines = [f"Found {len(results)} matches:"]
+
+        for r in results[:limit]:
+            end_line = r.lines[1] if len(r.lines) > 1 else r.lines[0]
+            type_abbr = {"function": "fn", "class": "cls", "method": "mth"}.get(r.type, r.type[:3])
+            sig = f" :: {r.signature}" if r.signature else ""
+            parent = f" ({r.parent})" if r.parent else ""
+            lines.append(f"{r.file}:L{r.lines[0]}-{end_line} [{type_abbr}] {r.name}{parent}{sig}")
+
+        if len(results) > limit:
+            lines.append(f"... +{len(results) - limit} more")
+
+        return "\n".join(lines)
+
+    def _format_search_results_verbose(self, results: list, limit: int) -> str:
+        """Format search results with signatures, docstrings, deps (verbose)."""
+        if not results:
+            return "No matching symbols found."
+
+        lines = [f"Found {len(results)} matches:"]
+
+        for r in results[:limit]:
+            end_line = r.lines[1] if len(r.lines) > 1 else r.lines[0]
+            type_abbr = {"function": "fn", "class": "cls", "method": "mth"}.get(r.type, r.type[:3])
+            parent = f" ({r.parent})" if r.parent else ""
+            lines.append(f"{r.file}:L{r.lines[0]}-{end_line} [{type_abbr}] {r.name}{parent}")
+            if r.signature:
+                lines.append(f"  sig: {r.signature}")
+            if r.docstring:
+                doc = r.docstring[:80] + "..." if len(r.docstring) > 80 else r.docstring
+                lines.append(f"  doc: {doc}")
+
+        if len(results) > limit:
+            lines.append(f"... +{len(results) - limit} more")
+
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Hub formatters
+    # ------------------------------------------------------------------
+
+    def _format_hubs_compact(self, hubs: list) -> str:
+        """Format hub files in compact list format (minimal)."""
+        if not hubs:
+            return "No hub files found."
+
+        lines = ["Architectural hubs (most imported):"]
+        for i, hub in enumerate(hubs, 1):
+            symbols_preview = ", ".join(hub.get("symbols", [])[:3])
+            if len(hub.get("symbols", [])) > 3:
+                symbols_preview += "..."
+            lines.append(f"{i}. {hub['file']} ({hub['imports']}← imports) [{symbols_preview}]")
+
+        return "\n".join(lines)
+
+    def _format_hubs_standard(self, hubs: list) -> str:
+        """Format hub files with full symbol lists (standard)."""
+        if not hubs:
+            return "No hub files found."
+
+        lines = ["Architectural hubs (most imported):"]
+        for i, hub in enumerate(hubs, 1):
+            symbols = ", ".join(hub.get("symbols", []))
+            lines.append(f"{i}. {hub['file']} ({hub['imports']}← imports)")
+            if symbols:
+                lines.append(f"   symbols: {symbols}")
+
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Stats formatters
+    # ------------------------------------------------------------------
+
+    def _format_stats_compact(self, stats: dict) -> str:
+        """Format stats as compact key-value pairs (minimal)."""
+        lines = [
+            f"root: {stats.get('root', 'unknown')}",
+            f"files: {stats.get('files', 0)}",
+            f"symbols: {stats.get('total_symbols', 0)}",
+        ]
+
+        by_type = stats.get("by_type", {})
+        if by_type:
+            type_parts = [f"{k}:{v}" for k, v in sorted(by_type.items())]
+            lines.append(f"by_type: {', '.join(type_parts)}")
+
+        if stats.get("generated_at"):
+            lines.append(f"generated: {stats['generated_at']}")
+
+        return "\n".join(lines)
+
+    def _format_stats_standard(self, stats: dict, code_map: dict) -> str:
+        """Format stats with language breakdown and hub count (standard)."""
+        lines = [self._format_stats_compact(stats)]
+
+        # Language breakdown
+        ext_counts: Counter = Counter()
+        for fpath in code_map.get("files", {}):
+            ext = Path(fpath).suffix
+            if ext:
+                ext_counts[ext] += 1
+        if ext_counts:
+            lang_parts = [f"{ext}:{n}" for ext, n in ext_counts.most_common(10)]
+            lines.append(f"languages: {', '.join(lang_parts)}")
+
+        # Hub count
+        hubs = self._compute_hubs(code_map, top_n=100, min_imports=3)
+        lines.append(f"hubs: {len(hubs)} files with 3+ importers")
+
+        return "\n".join(lines)
+
+    def _format_stats_verbose(self, stats: dict, code_map: dict) -> str:
+        """Format stats with per-file details (verbose)."""
+        lines = [self._format_stats_standard(stats, code_map)]
+
+        # Top files by symbol count
+        file_sym_counts = []
+        for fpath, info in code_map.get("files", {}).items():
+            sym_count = len(info.get("symbols", []))
+            if sym_count > 0:
+                file_sym_counts.append((fpath, sym_count))
+        file_sym_counts.sort(key=lambda x: x[1], reverse=True)
+
+        if file_sym_counts:
+            lines.append("top files by symbols:")
+            for fpath, count in file_sym_counts[:20]:
+                lines.append(f"  {fpath}: {count} symbols")
+
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Symbol context lookup (for codegraph_read standard mode)
+    # ------------------------------------------------------------------
+
+    def _find_containing_symbol(
+        self, code_map: dict, rel_file_path: str, line_number: int
+    ) -> dict | None:
+        """Find the symbol containing a given line number."""
+        file_info = code_map.get("files", {}).get(rel_file_path)
+        if not file_info:
+            # Try partial match
+            for fpath, info in code_map.get("files", {}).items():
+                if rel_file_path in fpath or fpath in rel_file_path:
+                    file_info = info
+                    break
+        if not file_info:
+            return None
+
+        best = None
+        for sym in file_info.get("symbols", []):
+            lines = sym.get("lines", [])
+            if len(lines) >= 2 and lines[0] <= line_number <= lines[1]:
+                # Prefer innermost (smallest range)
+                if best is None or (lines[1] - lines[0]) < (best["lines"][1] - best["lines"][0]):
+                    best = sym
+        if best:
+            return {
+                "name": best.get("name"),
+                "type": best.get("type"),
+                "lines": best.get("lines"),
+                "parent": best.get("parent"),
+            }
+        return None
+
+    # ------------------------------------------------------------------
+    # Test gap analysis
+    # ------------------------------------------------------------------
+
+    def _is_test_file(self, file_path: str) -> bool:
+        """Check if a file path matches test file patterns."""
+        for pattern in TEST_FILE_PATTERNS:
+            if pattern.search(file_path):
+                return True
+        return False
+
+    def _classify_test_files(self, code_map: dict) -> tuple[set, set]:
+        """Classify files into test and production sets."""
+        test_files = set()
+        prod_files = set()
+        for fpath in code_map.get("files", {}):
+            if self._is_test_file(fpath):
+                test_files.add(fpath)
+            else:
+                prod_files.add(fpath)
+        return test_files, prod_files
+
+    def _find_untested_symbols(
+        self, code_map: dict, changed_files: set | None = None
+    ) -> list[dict]:
+        """Find production symbols that lack test coverage.
+
+        Returns list of {"file": str, "name": str, "type": str, "confidence": str}.
+        """
+        test_files, prod_files = self._classify_test_files(code_map)
+
+        # Build set of tested symbol names from test files
+        tested_names: set[str] = set()
+        for fpath in test_files:
+            for sym in code_map.get("files", {}).get(fpath, {}).get("symbols", []):
+                name = sym.get("name", "")
+                # Strip test_ prefix to get production name
+                if name.startswith("test_"):
+                    tested_names.add(name[5:])
+                # Strip Test suffix for class-based tests
+                elif name.endswith("Test"):
+                    tested_names.add(name[:-4].lower())
+
+        # Build set of files that have corresponding test files
+        tested_file_stems: set[str] = set()
+        for fpath in test_files:
+            stem = Path(fpath).stem
+            # test_foo -> foo, foo_test -> foo, foo.test -> foo, foo.spec -> foo
+            for prefix in ("test_",):
+                if stem.startswith(prefix):
+                    tested_file_stems.add(stem[len(prefix) :])
+            for suffix in ("_test", ".test", ".spec"):
+                if stem.endswith(suffix):
+                    tested_file_stems.add(stem[: -len(suffix)])
+
+        untested = []
+        for fpath in prod_files:
+            if changed_files is not None and fpath not in changed_files:
+                continue
+
+            file_stem = Path(fpath).stem
+            has_test_file = file_stem in tested_file_stems
+
+            for sym in code_map.get("files", {}).get(fpath, {}).get("symbols", []):
+                sym_type = sym.get("type", "")
+                sym_name = sym.get("name", "")
+
+                # Only check functions and methods
+                if sym_type not in ("function", "method"):
+                    continue
+                # Skip private/dunder
+                if sym_name.startswith("_"):
+                    continue
+
+                if sym_name.lower() not in tested_names:
+                    confidence = "PARTIAL" if has_test_file else "NO_TEST_FILE"
+                    untested.append(
+                        {
+                            "file": fpath,
+                            "name": sym_name,
+                            "type": sym_type,
+                            "confidence": confidence,
+                        }
+                    )
+
+        return untested
+
+
+# ==============================================================================
+# MCP TOOLS
+# ==============================================================================
+
+
+@mcp.tool()
+def codegraph_scan(
+    path: str,
+    ignore_patterns: list[str] | None = None,
+    git_only: bool = False,
+    use_gitignore: bool = False,
+    max_depth: int = 0,
+    detail_level: str = "minimal",
+) -> str:
+    """Scan a codebase and generate a structural map with all symbols.
+
+    Use this tool first when starting work on any codebase. It creates a
+    .codegraph.json index file containing all functions, classes, and methods
+    with their exact line numbers.
+
+    Args:
+        path: Root directory to scan (absolute or relative path)
+        ignore_patterns: Glob patterns to ignore (e.g., ['*.test.py', 'vendor/'])
+        git_only: Only scan files tracked by git
+        use_gitignore: Also ignore patterns from .gitignore
+        max_depth: Maximum directory depth to display (0=unlimited)
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Token-efficient summary showing file tree with symbol metadata
+    """
+    handler = get_handler()
+    detail_level = _validate_detail_level(detail_level)
+
+    # Clamp max_depth to safe bounds
+    if max_depth <= 0:
+        max_depth = MAX_DEPTH
+    max_depth = max(1, min(max_depth, MAX_DEPTH))
+
+    try:
+        abs_path = os.path.abspath(path)
+        navigator = CodeNavigator(
+            abs_path,
+            ignore_patterns=ignore_patterns or [],
+            git_only=git_only,
+            use_gitignore=use_gitignore,
+        )
+        code_map = navigator.scan()
+        handler._code_map_cache[abs_path] = code_map
+
+        # Persist to disk so other tools can find it
+        map_path = handler._get_map_path(abs_path)
+        with open(map_path, "w", encoding="utf-8") as f:
+            json.dump(code_map, f, indent=2)
+
+        # Use token-efficient rendering if available
+        if HAS_RENDERER:
+            renderer = TokenEfficientRenderer(code_map, root_path=abs_path)
+            result = renderer.render_skeleton_tree(
+                max_depth=max_depth,
+                show_meta=True,
+                show_summary=True,
+            )
+        else:
+            files = code_map.get("files", {})
+            total_symbols = sum(len(f.get("symbols", [])) for f in files.values())
+            result = (
+                f"Scanned {len(files)} files, found {total_symbols} symbols. "
+                "Map saved to .codegraph.json"
+            )
+
+        if detail_level == "minimal":
+            return result
+
+        # Standard: add top hubs
+        hubs = handler._compute_hubs(code_map, top_n=5, min_imports=2)
+        if hubs:
+            result += "\n\n--- Top Hubs ---\n"
+            result += handler._format_hubs_compact(hubs)
+
+        if detail_level == "verbose":
+            # Add stats
+            map_file = handler._get_map_path(abs_path)
+            searcher = CodeSearcher(str(map_file))
+            stats = searcher.get_stats()
+            result += "\n\n--- Stats ---\n"
+            result += handler._format_stats_standard(stats, code_map)
+
+        return result
+
+    except Exception as e:
+        logger.exception(f"Error scanning {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_search(
+    query: str,
+    symbol_type: str = "any",
+    file_pattern: str | None = None,
+    limit: int = 20,
+    path: str | None = None,
+    detail_level: str = "minimal",
+) -> str:
+    """Search for symbols (functions, classes, methods) by name or pattern.
+
+    Use this after scanning to find where specific code is defined.
+    Returns compact file:line locations for efficient reading.
+
+    Args:
+        query: Search query (name, pattern, or regex)
+        symbol_type: Filter by type: 'function', 'class', 'method', 'variable', or 'any'
+        file_pattern: Filter by file glob pattern (e.g., '*.py', 'src/**/*.ts')
+        limit: Maximum results to return
+        path: Root directory (uses current dir if not specified)
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Compact list: file:L{start}-{end} [type] name
+    """
+    handler = get_handler()
+    detail_level = _validate_detail_level(detail_level)
+
+    # Clamp limit to safe bounds
+    limit = max(1, min(limit, MAX_LIMIT))
+
+    search_path = os.path.abspath(path or handler.workspace_root)
+
+    # Check if map exists
+    exists, error_msg = handler._check_map_exists(search_path)
+    if not exists:
+        return error_msg
+
+    try:
+        map_path = handler._get_map_path(search_path)
+        searcher = CodeSearcher(str(map_path))
+
+        # Search based on type
+        if symbol_type == "any":
+            results = searcher.search_symbol(query, limit=limit)
+        else:
+            results = searcher.search_symbol(query, symbol_type=symbol_type, limit=limit)
+
+        # Filter by file pattern if specified
+        if file_pattern:
+            import fnmatch
+
+            results = [r for r in results if fnmatch.fnmatch(r.file, file_pattern)]
+
+        if detail_level == "verbose":
+            return handler._format_search_results_verbose(results, limit)
+        elif detail_level == "standard":
+            return handler._format_search_results_standard(results, limit)
+        else:
+            return handler._format_search_results_compact(results, limit)
+
+    except Exception as e:
+        logger.exception(f"Error searching for {query}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_read(
+    file_path: str,
+    start_line: int,
+    end_line: int,
+    context: int = 0,
+    detail_level: str = "minimal",
+) -> dict:
+    """Read specific lines from a file with optional context.
+
+    Use this after finding a symbol's location to read its implementation.
+    Much more token-efficient than reading entire files.
+
+    Args:
+        file_path: Path to the file to read
+        start_line: First line to read (1-indexed)
+        end_line: Last line to read (inclusive)
+        context: Additional lines before/after the range
+        detail_level: Output detail: 'minimal' (default), 'standard' adds symbol context
+
+    Returns:
+        Dict with file, requested/actual ranges, total_lines, and lines
+        (each line has num, content, in_range fields)
+    """
+    handler = get_handler()
+    detail_level = _validate_detail_level(detail_level)
+
+    try:
+        reader = LineReader(root_path=handler.workspace_root)
+        content = reader.read_lines(file_path, start_line, end_line, context=context)
+
+        if detail_level in ("standard", "verbose"):
+            # Try to find the containing symbol
+            # Search up for .codegraph.json
+            search_dir = os.path.dirname(os.path.abspath(file_path)) or handler.workspace_root
+            map_dir = search_dir
+            while map_dir and map_dir != "/":
+                if handler._get_map_path(map_dir).exists():
+                    break
+                map_dir = os.path.dirname(map_dir)
+
+            if map_dir and map_dir != "/":
+                code_map = handler._get_code_map(map_dir)
+                abs_file = os.path.abspath(file_path)
+                rel_path = os.path.relpath(abs_file, map_dir)
+                sym = handler._find_containing_symbol(code_map, rel_path, start_line)
+                if sym:
+                    content["symbol_context"] = sym
+
+        return content
+
+    except Exception as e:
+        logger.exception(f"Error reading {file_path}")
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def codegraph_stats(
+    path: str | None = None,
+    detail_level: str = "minimal",
+) -> str:
+    """Get statistics about the indexed codebase.
+
+    Shows file count, symbol count, and breakdown by type.
+    Useful for understanding project size before diving in.
+
+    Args:
+        path: Root directory (uses current dir if not specified)
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Compact stats: files, symbols, breakdown by type
+    """
+    handler = get_handler()
+    detail_level = _validate_detail_level(detail_level)
+    stats_path = os.path.abspath(path or handler.workspace_root)
+
+    # Check if map exists
+    exists, error_msg = handler._check_map_exists(stats_path)
+    if not exists:
+        return error_msg
+
+    try:
+        map_path = handler._get_map_path(stats_path)
+        searcher = CodeSearcher(str(map_path))
+        stats = searcher.get_stats()
+
+        if detail_level == "verbose":
+            code_map = handler._get_code_map(stats_path)
+            return handler._format_stats_verbose(stats, code_map)
+        elif detail_level == "standard":
+            code_map = handler._get_code_map(stats_path)
+            return handler._format_stats_standard(stats, code_map)
+        else:
+            return handler._format_stats_compact(stats)
+
+    except Exception as e:
+        logger.exception(f"Error getting stats for {stats_path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_get_hubs(
+    path: str,
+    top_n: int = 10,
+    min_imports: int = 3,
+    detail_level: str = "minimal",
+) -> str:
+    """Identify architectural hub files - the most central files in the codebase.
+
+    Hub files are heavily imported by other files, making them critical
+    for understanding the architecture. Review these first.
+
+    Args:
+        path: Root directory to analyze
+        top_n: Number of top hubs to return
+        min_imports: Minimum import count to be considered a hub
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Ranked list of hub files with import counts
+    """
+    handler = get_handler()
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    # Check if map exists
+    exists, error_msg = handler._check_map_exists(abs_path)
+    if not exists:
+        return error_msg
+
+    try:
+        code_map = handler._get_code_map(abs_path)
+        hubs = handler._compute_hubs(code_map, top_n=top_n, min_imports=min_imports)
+
+        if detail_level == "verbose":
+            # Standard + dependency info per hub
+            result = handler._format_hubs_standard(hubs)
+            if result != "No hub files found.":
+                result += "\n\n--- Hub Dependencies ---"
+                for hub in hubs[:5]:
+                    file_info = code_map.get("files", {}).get(hub["file"], {})
+                    imports = file_info.get("imports", [])
+                    if imports:
+                        result += f"\n{hub['file']} imports: {', '.join(imports[:10])}"
+                        if len(imports) > 10:
+                            result += f" +{len(imports)-10} more"
+            return result
+        elif detail_level == "standard":
+            return handler._format_hubs_standard(hubs)
+        else:
+            return handler._format_hubs_compact(hubs)
+
+    except Exception as e:
+        logger.exception(f"Error getting hubs for {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_get_dependencies(
+    path: str,
+    file: str | None = None,
+    direction: str = "both",
+    depth: int = 1,
+    detail_level: str = "minimal",
+) -> str:
+    """Get the dependency graph for a file or the entire project.
+
+    Shows what a file imports and what imports it.
+    Useful for understanding coupling between modules.
+
+    Args:
+        path: Root directory or specific file to analyze
+        file: Specific file to get dependencies for (optional)
+        direction: 'imports', 'imported_by', or 'both'
+        depth: How many levels deep to traverse
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Import/export relationships in compact format
+    """
+    handler = get_handler()
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    # Check if map exists
+    exists, error_msg = handler._check_map_exists(abs_path)
+    if not exists:
+        return error_msg
+
+    try:
+        code_map = handler._get_code_map(abs_path)
+
+        if file:
+            # Find the file
+            file_info = None
+            matched_path = None
+            for fpath, info in code_map.get("files", {}).items():
+                if fpath == file or file in fpath:
+                    file_info = info
+                    matched_path = fpath
+                    break
+
+            if not file_info:
+                return f"File not found: {file}"
+
+            lines = [f"Dependencies for {matched_path}:"]
+
+            if direction in ("imports", "both"):
+                imports = file_info.get("imports", [])
+                lines.append(f"imports ({len(imports)}): {', '.join(imports[:10])}")
+                if len(imports) > 10:
+                    lines[-1] += f" +{len(imports)-10} more"
+
+            if direction in ("imported_by", "both"):
+                imported_by = []
+                for fpath, info in code_map.get("files", {}).items():
+                    if matched_path in info.get("imports", []):
+                        imported_by.append(fpath)
+                lines.append(f"imported_by ({len(imported_by)}): {', '.join(imported_by[:10])}")
+                if len(imported_by) > 10:
+                    lines[-1] += f" +{len(imported_by)-10} more"
+
+            if detail_level in ("standard", "verbose"):
+                # Add bidirectional summary
+                imports = file_info.get("imports", [])
+                imported_by_count = sum(
+                    1
+                    for info in code_map.get("files", {}).values()
+                    if matched_path in info.get("imports", [])
+                )
+                lines.append(f"summary: {len(imports)} imports, {imported_by_count} importers")
+
+            if detail_level == "verbose" and depth > 1:
+                # Add transitive dependencies
+                lines.append(f"\ntransitive (depth={depth}):")
+                visited = {matched_path}
+                frontier = file_info.get("imports", [])
+                for d in range(1, depth):
+                    next_frontier = []
+                    for dep in frontier:
+                        if dep not in visited:
+                            visited.add(dep)
+                            dep_info = code_map.get("files", {}).get(dep, {})
+                            sub_imports = dep_info.get("imports", [])
+                            lines.append(f"  {'  ' * d}{dep} → [{', '.join(sub_imports[:5])}]")
+                            next_frontier.extend(sub_imports)
+                    frontier = next_frontier
+                    if not frontier:
+                        break
+
+            return "\n".join(lines)
+        else:
+            # Project-wide summary
+            files = code_map.get("files", {})
+
+            if detail_level in ("standard", "verbose"):
+                # Bidirectional counts
+                import_counts: dict[str, int] = {}
+                for fpath, info in files.items():
+                    for imp in info.get("imports", []):
+                        import_counts[imp] = import_counts.get(imp, 0) + 1
+
+                conn_full = []
+                for fpath, info in files.items():
+                    out_deg = len(info.get("imports", []))
+                    in_deg = import_counts.get(fpath, 0)
+                    conn_full.append((fpath, out_deg, in_deg))
+                conn_full.sort(key=lambda x: x[1] + x[2], reverse=True)
+
+                lines = [f"Project dependencies ({len(files)} files):", "Most connected:"]
+                for fpath, out_d, in_d in conn_full[:15]:
+                    lines.append(f"  {fpath}: {out_d} imports, {in_d} importers")
+                return "\n".join(lines)
+            else:
+                conn_simple = [
+                    (fpath, len(info.get("imports", []))) for fpath, info in files.items()
+                ]
+                conn_simple.sort(key=lambda x: x[1], reverse=True)
+
+                lines = [f"Project dependencies ({len(files)} files):", "Most connected:"]
+                for fpath, count in conn_simple[:10]:
+                    lines.append(f"  {fpath}: {count} imports")
+
+                return "\n".join(lines)
+
+    except Exception as e:
+        logger.exception(f"Error getting dependencies for {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_get_structure(
+    file_path: str,
+    include_private: bool = False,
+    detail_level: str = "minimal",
+) -> str:
+    """Get the structure of a specific file showing all its symbols.
+
+    Use this to see what's in a file before reading it.
+    Helps decide which parts to read in detail.
+
+    Args:
+        file_path: Path to the file to analyze
+        include_private: Include private symbols (starting with _)
+        detail_level: Output detail: 'minimal' (default), 'standard' adds signatures, 'verbose' adds docstrings
+
+    Returns:
+        Hierarchical list of symbols with types and line numbers
+    """
+    handler = get_handler()
+    detail_level = _validate_detail_level(detail_level)
+
+    # Determine the project root from file path
+    file_dir = os.path.dirname(os.path.abspath(file_path)) or handler.workspace_root
+
+    # Check if map exists (try parent directories)
+    search_path = file_dir
+    map_found = False
+    while search_path and search_path != "/":
+        if handler._get_map_path(search_path).exists():
+            map_found = True
+            break
+        search_path = os.path.dirname(search_path)
+
+    if not map_found:
+        return "No .codegraph.json found. Run `codegraph_scan` first to index the codebase."
+
+    try:
+        code_map = handler._get_code_map(search_path)
+        abs_file_path = os.path.abspath(file_path)
+        rel_path = os.path.relpath(abs_file_path, search_path)
+
+        # Find the file in the code map
+        file_info = None
+        for fpath, info in code_map.get("files", {}).items():
+            if fpath == rel_path or fpath == abs_file_path or rel_path in fpath:
+                file_info = info
+                break
+
+        if not file_info:
+            return f"File not found in code map: {file_path}"
+
+        symbols = file_info.get("symbols", [])
+        if not include_private:
+            symbols = [s for s in symbols if not s["name"].startswith("_")]
+
+        # Group and format
+        classes = [s for s in symbols if s.get("type") == "class"]
+        functions = [s for s in symbols if s.get("type") == "function"]
+        methods = [s for s in symbols if s.get("type") == "method"]
+
+        lines = [f"Structure of {rel_path}:"]
+
+        def _format_sym(s: dict) -> str:
+            end = s.get("end_line", s["lines"][1] if len(s.get("lines", [])) > 1 else "?")
+            base = f"  {s['name']} L{s['lines'][0]}-{end}"
+            if detail_level in ("standard", "verbose") and s.get("signature"):
+                base += f" :: {s['signature']}"
+            return base
+
+        def _format_doc(s: dict) -> str | None:
+            if detail_level == "verbose" and s.get("docstring"):
+                doc = (
+                    s["docstring"][:80] + "..."
+                    if len(s.get("docstring", "")) > 80
+                    else s.get("docstring", "")
+                )
+                return f"    {doc}"
+            return None
+
+        if classes:
+            lines.append(f"classes ({len(classes)}):")
+            for c in classes:
+                lines.append(_format_sym(c))
+                doc = _format_doc(c)
+                if doc:
+                    lines.append(doc)
+
+        if functions:
+            lines.append(f"functions ({len(functions)}):")
+            for f in functions:
+                lines.append(_format_sym(f))
+                doc = _format_doc(f)
+                if doc:
+                    lines.append(doc)
+
+        if methods:
+            lines.append(f"methods ({len(methods)}):")
+            limit = 15 if detail_level == "minimal" else 30
+            for m in methods[:limit]:
+                lines.append(_format_sym(m))
+                doc = _format_doc(m)
+                if doc:
+                    lines.append(doc)
+            if len(methods) > limit:
+                lines.append(f"  ... +{len(methods)-limit} more")
+
+        return "\n".join(lines)
+
+    except Exception as e:
+        logger.exception(f"Error getting structure for {file_path}")
+        return f"Error: {e}"
+
+
+# ==============================================================================
+# NEW TOOLS - Phase A
+# ==============================================================================
+
+
+@mcp.tool()
+def codegraph_get_minimal_context(
+    path: str,
+    task: str = "",
+    base: str = "HEAD~1",
+) -> str:
+    """Get a quick ~100 token orientation for any codebase.
+
+    Always call this first. Returns project stats, top hubs, recent changes,
+    and suggested next tools based on your task.
+
+    Args:
+        path: Root directory of the project
+        task: What you're trying to do (e.g., "fix auth bug", "add feature")
+        base: Git ref for change detection (default: HEAD~1)
+
+    Returns:
+        Compact project primer under 100 tokens
+    """
+    handler = get_handler()
+    abs_path = os.path.abspath(path)
+
+    # Check if map exists
+    exists, error_msg = handler._check_map_exists(abs_path)
+    if not exists:
+        return f'no index. run codegraph_scan(path="{path}") first'
+
+    try:
+        code_map = handler._get_code_map(abs_path)
+        files = code_map.get("files", {})
+        lines_out = []
+
+        # Project primer: files, symbols, languages
+        total_symbols = sum(len(f.get("symbols", [])) for f in files.values())
+        ext_counts: Counter = Counter()
+        for fpath in files:
+            ext = Path(fpath).suffix.lstrip(".")
+            if ext:
+                ext_counts[ext] += 1
+        top_langs = ",".join(ext for ext, _ in ext_counts.most_common(3))
+        lines_out.append(f"project: {len(files)} files · {total_symbols} symbols · {top_langs}")
+
+        # Top 3 hubs
+        hubs = handler._compute_hubs(code_map, top_n=3, min_imports=2)
+        if hubs:
+            hub_strs = [f"{h['file']}({h['imports']}←)" for h in hubs]
+            lines_out.append(f"hubs: {', '.join(hub_strs)}")
+
+        # Git changes
+        try:
+            map_path = handler._get_map_path(abs_path)
+            searcher = CodeSearcher(str(map_path))
+            changes = searcher.get_changes_since_commit(base, abs_path)
+            if not changes.get("error") and changes.get("total_changed", 0) > 0:
+                changed_syms = sum(
+                    len(f.get("symbols", [])) for f in changes.get("changed_files", [])
+                )
+                lines_out.append(
+                    f"changes({base}): {changes['total_changed']} files · "
+                    f"{changed_syms} symbols modified"
+                )
+        except Exception:
+            pass  # Git not available, skip changes line
+
+        # Tool suggestions based on task keywords
+        if task:
+            task_lower = task.lower()
+            if any(kw in task_lower for kw in ("bug", "fix", "error", "crash", "fail")):
+                suggest = "codegraph_search → codegraph_read → codegraph_get_dependencies"
+            elif any(kw in task_lower for kw in ("add", "feature", "implement", "create", "new")):
+                suggest = "codegraph_get_structure → codegraph_search → codegraph_read"
+            elif any(kw in task_lower for kw in ("review", "pr", "diff", "change")):
+                suggest = "codegraph_test_gaps → codegraph_search → codegraph_read"
+            elif any(kw in task_lower for kw in ("understand", "architecture", "how", "what")):
+                suggest = (
+                    "codegraph_get_hubs → codegraph_get_dependencies → codegraph_get_structure"
+                )
+            elif any(kw in task_lower for kw in ("onboard", "learn", "explore")):
+                suggest = "codegraph_stats → codegraph_get_hubs → codegraph_get_structure"
+            else:
+                suggest = "codegraph_search → codegraph_read → codegraph_get_dependencies"
+            lines_out.append(f"suggest: {suggest}")
+
+        return "\n".join(lines_out)
+
+    except Exception as e:
+        logger.exception(f"Error getting minimal context for {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_test_gaps(
+    path: str,
+    changed_only: bool = False,
+    base: str = "HEAD~1",
+    detail_level: str = "minimal",
+) -> str:
+    """Find symbols that lack test coverage using index-based heuristics.
+
+    Matches production symbols against test symbols by naming convention
+    (test_foo tests foo). No code execution needed.
+
+    Args:
+        path: Root directory of the project
+        changed_only: Only check symbols in files changed since base
+        base: Git ref for change detection (default: HEAD~1)
+        detail_level: Output detail: 'minimal' (default) or 'standard' for per-file breakdown
+
+    Returns:
+        Test gap summary with untested symbol names
+    """
+    handler = get_handler()
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    # Check if map exists
+    exists, error_msg = handler._check_map_exists(abs_path)
+    if not exists:
+        return error_msg
+
+    try:
+        code_map = handler._get_code_map(abs_path)
+
+        # Get changed files if needed
+        changed_files = None
+        if changed_only:
+            try:
+                map_path = handler._get_map_path(abs_path)
+                searcher = CodeSearcher(str(map_path))
+                changes = searcher.get_changes_since_commit(base, abs_path)
+                if not changes.get("error"):
+                    changed_files = {f["file"] for f in changes.get("changed_files", [])}
+                else:
+                    return f"Git error: {changes['error']}"
+            except Exception as e:
+                return f"Error detecting changes: {e}"
+
+        untested = handler._find_untested_symbols(code_map, changed_files)
+
+        # Count total production symbols for context
+        test_files, prod_files = handler._classify_test_files(code_map)
+        total_prod_symbols = 0
+        for fpath in prod_files:
+            if changed_files is not None and fpath not in changed_files:
+                continue
+            for sym in code_map.get("files", {}).get(fpath, {}).get("symbols", []):
+                if sym.get("type") in ("function", "method") and not sym.get("name", "").startswith(
+                    "_"
+                ):
+                    total_prod_symbols += 1
+
+        scope = "changed" if changed_only else "total"
+
+        if detail_level in ("standard", "verbose"):
+            # Per-file breakdown
+            by_file: dict[str, list[dict]] = {}
+            for item in untested:
+                by_file.setdefault(item["file"], []).append(item)
+
+            lines = [
+                f"{len(untested)} untested symbols (of {total_prod_symbols} {scope})",
+                f"test files: {len(test_files)} | production files: {len(prod_files)}",
+                "",
+            ]
+            for fpath, items in sorted(by_file.items()):
+                file_total = 0
+                for sym in code_map.get("files", {}).get(fpath, {}).get("symbols", []):
+                    if sym.get("type") in ("function", "method") and not sym.get(
+                        "name", ""
+                    ).startswith("_"):
+                        file_total += 1
+                confidence = items[0]["confidence"] if items else "UNKNOWN"
+                lines.append(f"{fpath}: {len(items)}/{file_total} untested [{confidence}]")
+                names = [item["name"] for item in items[:10]]
+                lines.append(f"  untested: {', '.join(names)}")
+                if len(items) > 10:
+                    lines[-1] += f" +{len(items)-10} more"
+
+            return "\n".join(lines)
+        else:
+            # Minimal: one-line summary
+            gap_names = [item["name"] for item in untested[:10]]
+            gaps_str = ", ".join(gap_names)
+            if len(untested) > 10:
+                gaps_str += f" +{len(untested)-10} more"
+            return (
+                f"{len(untested)} untested symbols (of {total_prod_symbols} {scope}) "
+                f"| gaps: {gaps_str}"
+            )
+
+    except Exception as e:
+        logger.exception(f"Error analyzing test gaps for {path}")
+        return f"Error: {e}"
+
+
+# ==============================================================================
+# NEW TOOLS - Phase B (Graph Intelligence)
+# ==============================================================================
+
+# Lazy graph store cache on handler
+_graph_store_cache: dict[str, "GraphStore"] = {}
+
+
+def _get_graph_store(path: str, auto_build: bool = True) -> "GraphStore | None":
+    """Get or create a GraphStore for the given path. Auto-builds from JSON if needed."""
+    from ..graph import GraphBuilder, GraphStore
+
+    abs_path = os.path.abspath(path)
+    if abs_path in _graph_store_cache:
+        return _graph_store_cache[abs_path]
+
+    db_path = Path(abs_path) / ".codegraph.db"
+    json_path = Path(abs_path) / ".codegraph.json"
+
+    if db_path.exists():
+        store = GraphStore(db_path)
+        _graph_store_cache[abs_path] = store
+        return store
+
+    if auto_build and json_path.exists():
+        # Lazy build from JSON
+        import json as _json
+
+        with open(json_path, encoding="utf-8") as f:
+            code_map = _json.load(f)
+        store = GraphStore(db_path)
+        builder = GraphBuilder(store)
+        builder.build_from_code_map(code_map, root_path=abs_path)
+        _graph_store_cache[abs_path] = store
+        return store
+
+    return None
+
+
+@mcp.tool()
+def codegraph_graph_build(
+    path: str,
+    mode: str = "lazy",
+    detail_level: str = "minimal",
+) -> str:
+    """Build the optional graph database from the code index.
+
+    Creates .codegraph.db with nodes, edges, execution flows, and FTS5 index.
+    Required for blast_radius, detect_changes, list_flows, and search_graph tools.
+
+    Args:
+        path: Root directory of the project
+        mode: 'lazy' (skip unchanged files) or 'full' (rebuild everything)
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Build statistics
+    """
+    from ..graph import GraphBuilder, GraphStore
+    from ..graph.flows import store_flows, trace_flows
+
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+    json_path = Path(abs_path) / ".codegraph.json"
+
+    if not json_path.exists():
+        return f'No .codegraph.json found. Run codegraph_scan(path="{path}") first.'
+
+    try:
+        with open(json_path, encoding="utf-8") as f:
+            code_map = json.load(f)
+
+        db_path = Path(abs_path) / ".codegraph.db"
+        store = GraphStore(db_path)
+        builder = GraphBuilder(store)
+        stats = builder.build_from_code_map(
+            code_map, root_path=abs_path, incremental=(mode == "lazy")
+        )
+
+        # Trace flows
+        flows = trace_flows(store)
+        store_flows(store, flows)
+        stats["flows_detected"] = len(flows)
+
+        _graph_store_cache[abs_path] = store
+
+        if detail_level == "minimal":
+            return (
+                f"graph built: {stats['nodes_created']} nodes · {stats['edges_created']} edges "
+                f"· {stats.get('flows_detected', 0)} flows · {stats['build_time']}s"
+            )
+        else:
+            lines = [
+                f"Graph built in {stats['build_time']}s:",
+                f"  nodes: {stats['nodes_created']}",
+                f"  edges: {stats['edges_created']}",
+                f"  flows: {stats.get('flows_detected', 0)}",
+                f"  files processed: {stats['files_processed']}",
+                f"  files skipped: {stats['files_skipped']}",
+                f"  errors: {stats['errors']}",
+                f"  fts5: {'available' if store.fts_available else 'unavailable'}",
+            ]
+            return "\n".join(lines)
+
+    except Exception as e:
+        logger.exception(f"Error building graph for {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_blast_radius(
+    path: str,
+    changed_files: list[str] | None = None,
+    base: str = "HEAD~1",
+    max_depth: int = 2,
+    detail_level: str = "minimal",
+) -> str:
+    """Find what breaks if files change. Uses recursive graph traversal.
+
+    Auto-builds graph DB if not present. Uses git diff if changed_files not specified.
+
+    Args:
+        path: Root directory of the project
+        changed_files: Specific files to analyze (or auto-detect from git diff)
+        base: Git ref for auto-detecting changes (default: HEAD~1)
+        max_depth: How many hops to traverse (default: 2)
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Impact analysis showing affected files and nodes
+    """
+    from ..graph.query import format_blast_radius_minimal, get_blast_radius
+
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    store = _get_graph_store(abs_path)
+    if not store:
+        return f'No index found. Run codegraph_scan(path="{path}") first.'
+
+    try:
+        # Auto-detect changed files from git if not specified
+        if not changed_files:
+            try:
+                result = subprocess.run(
+                    ["git", "diff", "--name-only", base, "HEAD"],
+                    cwd=abs_path,
+                    capture_output=True,
+                    text=True,
+                    timeout=30,
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    changed_files = result.stdout.strip().split("\n")
+                else:
+                    return "No changes detected."
+            except (subprocess.TimeoutExpired, FileNotFoundError):
+                return "Git not available. Specify changed_files explicitly."
+
+        blast = get_blast_radius(store, changed_files, max_depth=max_depth)
+
+        if detail_level == "minimal":
+            return format_blast_radius_minimal(blast)
+        else:
+            lines = [format_blast_radius_minimal(blast)]
+            if blast["impacted_files"]:
+                lines.append("\nAll impacted files:")
+                for f in blast["impacted_files"]:
+                    lines.append(f"  {f}")
+            return "\n".join(lines)
+
+    except Exception as e:
+        logger.exception(f"Error computing blast radius for {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_list_flows(
+    path: str,
+    sort_by: str = "criticality",
+    limit: int = 10,
+    detail_level: str = "minimal",
+) -> str:
+    """List execution flows with criticality scores.
+
+    Flows trace call chains from entry points (main, route handlers, CLI commands).
+    Criticality scores (0-1) reflect security sensitivity, test coverage, and complexity.
+
+    Args:
+        path: Root directory of the project
+        sort_by: Sort order: 'criticality' (default) or 'name'
+        limit: Maximum flows to return
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Ranked list of execution flows with criticality scores
+    """
+    from ..graph.flows import format_flows_minimal, trace_flows
+
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    store = _get_graph_store(abs_path)
+    if not store:
+        return f'No index found. Run codegraph_scan(path="{path}") first.'
+
+    try:
+        # Check if flows exist in DB
+        flows_db = store.get_flows(sort_by=sort_by, limit=limit)
+        if flows_db:
+            flows = []
+            for f in flows_db:
+                path_ids = json.loads(f["path_json"])
+                path_names = []
+                for nid in path_ids:
+                    node = store.get_node_by_id(nid)
+                    path_names.append(node["name"] if node else "?")
+                flows.append(
+                    {
+                        "name": f["name"],
+                        "entry_point_id": f["entry_point_id"],
+                        "path_ids": path_ids,
+                        "path_names": path_names,
+                        "depth": f["depth"],
+                        "node_count": f["node_count"],
+                        "file_count": f["file_count"],
+                        "criticality": f["criticality"],
+                    }
+                )
+        else:
+            # Trace flows on demand
+            flows = trace_flows(store, limit=limit)
+
+        if detail_level == "minimal":
+            return format_flows_minimal(flows, limit=limit)
+        else:
+            from ..graph.flows import format_flow_minimal
+
+            lines = [f"{len(flows)} flows detected:"]
+            for flow in flows[:limit]:
+                lines.append(f"  {format_flow_minimal(flow)}")
+                if detail_level == "verbose":
+                    lines.append(
+                        f"    files: {', '.join(str(Path(f).name) for f in flow.get('files', []))}"
+                    )
+            if len(flows) > limit:
+                lines.append(f"  ... +{len(flows) - limit} more")
+            return "\n".join(lines)
+
+    except Exception as e:
+        logger.exception(f"Error listing flows for {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_detect_changes(
+    path: str,
+    base: str = "HEAD~1",
+    detail_level: str = "minimal",
+) -> str:
+    """Risk-scored change impact analysis.
+
+    Parses git diff, maps changed lines to symbols, computes risk scores.
+    Risk factors: flow participation, callers, test coverage, security keywords.
+
+    Args:
+        path: Root directory of the project
+        base: Git ref to compare against (default: HEAD~1)
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Risk report with scores, test gaps, and affected flows
+    """
+    from ..graph.query import detect_changes, format_changes_minimal
+
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    store = _get_graph_store(abs_path)
+    if not store:
+        return f'No index found. Run codegraph_scan(path="{path}") first.'
+
+    try:
+        result = detect_changes(store, root_path=abs_path, base=base)
+
+        if detail_level == "minimal":
+            return format_changes_minimal(result)
+        else:
+            lines = [format_changes_minimal(result)]
+            if detail_level == "verbose" and result["changed_nodes"]:
+                lines.append("\nAll changed symbols:")
+                for n in result["changed_nodes"]:
+                    lines.append(f"  {n['file']}::{n['name']} [{n['kind']}] risk:{n['risk']:.2f}")
+            return "\n".join(lines)
+
+    except Exception as e:
+        logger.exception(f"Error detecting changes for {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_search_graph(
+    query: str,
+    path: str | None = None,
+    kind: str | None = None,
+    limit: int = 20,
+    detail_level: str = "minimal",
+) -> str:
+    """Hybrid search: FTS5 full-text + fuzzy name matching + RRF fusion.
+
+    More powerful than codegraph_search — searches signatures, file paths, and
+    supports stemming (e.g., "authenticate" matches "authentication").
+    Falls back to standard search if no graph DB exists.
+
+    Args:
+        query: Search query (name, concept, or file path pattern)
+        path: Root directory (uses current dir if not specified)
+        kind: Filter by kind: 'Function', 'Class', 'Method', or None for all
+        limit: Maximum results to return
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Ranked search results with file:line locations
+    """
+    from ..graph.search import format_search_results_minimal, hybrid_search
+
+    detail_level = _validate_detail_level(detail_level)
+    handler = get_handler()
+    search_path = os.path.abspath(str(path or handler.workspace_root))
+
+    store = _get_graph_store(search_path, auto_build=False)
+    if not store:
+        # Fall back to standard search
+        return str(codegraph_search(query=query, path=path, limit=limit, detail_level=detail_level))
+
+    try:
+        results = hybrid_search(store, query, limit=limit)
+
+        # Filter by kind if specified
+        if kind:
+            results = [r for r in results if r["kind"] == kind]
+
+        if detail_level == "minimal":
+            return format_search_results_minimal(results, limit=limit)
+        else:
+            if not results:
+                return "No matching symbols found."
+            lines = [f"Found {len(results)} matches:"]
+            for r in results[:limit]:
+                abbr = {"Function": "fn", "Class": "cls", "Method": "mth"}.get(
+                    r["kind"], r["kind"][:3]
+                )
+                end = r["line_end"] or r["line_start"] or "?"
+                line = f"{r['file_path']}:L{r['line_start']}-{end} [{abbr}] {r['name']}"
+                if detail_level == "verbose" and r.get("signature"):
+                    line += f" :: {r['signature']}"
+                lines.append(line)
+            return "\n".join(lines)
+
+    except Exception as e:
+        logger.exception(f"Error in graph search for {query}")
+        return f"Error: {e}"
+
+
+# ==============================================================================
+# NEW TOOLS - Phase C (Communities, Domain, Architecture)
+# ==============================================================================
+
+
+@mcp.tool()
+def codegraph_list_communities(
+    path: str,
+    sort_by: str = "size",
+    limit: int = 10,
+    detail_level: str = "minimal",
+) -> str:
+    """List code communities with cohesion scores.
+
+    Communities group related code (by directory structure or graph clustering).
+    Cohesion (0-1) measures how tightly connected a community's code is.
+
+    Args:
+        path: Root directory of the project
+        sort_by: Sort by 'size' (default), 'cohesion', or 'name'
+        limit: Maximum communities to return
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Community list with sizes, cohesion scores, and keywords
+    """
+    from ..graph.communities import (
+        detect_communities,
+        format_communities_minimal,
+        get_coupling_warnings,
+        store_communities,
+    )
+
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    store = _get_graph_store(abs_path)
+    if not store:
+        return f'No index found. Run codegraph_scan(path="{path}") first.'
+
+    try:
+        # Check if communities already exist in DB
+        db_sort = {"size": "node_count", "cohesion": "cohesion", "name": "name"}.get(
+            sort_by, "node_count"
+        )
+        communities_db = store.get_communities(sort_by=db_sort, limit=limit)
+
+        if communities_db:
+            communities = [
+                {
+                    "name": c["name"],
+                    "node_count": c["node_count"],
+                    "cohesion": c["cohesion"],
+                    "file_prefix": c["file_prefix"],
+                    "keywords": json.loads(c["keywords"]) if c["keywords"] else [],
+                    "member_ids": [],
+                }
+                for c in communities_db
+            ]
+        else:
+            # Detect on demand
+            communities = detect_communities(store)
+            store_communities(store, communities)
+
+        output = format_communities_minimal(communities, limit=limit)
+
+        if detail_level in ("standard", "verbose"):
+            warnings = get_coupling_warnings(store, communities)
+            if warnings:
+                output += "\n\n--- Coupling ---"
+                for w in warnings[:5]:
+                    output += f"\n  {w}"
+
+        return output
+
+    except Exception as e:
+        logger.exception(f"Error listing communities for {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_get_community(
+    path: str,
+    community_id: int,
+    detail_level: str = "minimal",
+) -> str:
+    """Get details of a specific community: members, cohesion, coupling.
+
+    Args:
+        path: Root directory of the project
+        community_id: Community ID (from codegraph_list_communities)
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Community details with member list
+    """
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    store = _get_graph_store(abs_path)
+    if not store:
+        return f'No index found. Run codegraph_scan(path="{path}") first.'
+
+    try:
+        members = store.get_community_members(community_id)
+        if not members:
+            return f"Community {community_id} not found."
+
+        # Get community info
+        comm_row = store.conn.execute(
+            "SELECT * FROM communities WHERE id = ?", (community_id,)
+        ).fetchone()
+
+        if not comm_row:
+            return f"Community {community_id} not found."
+
+        lines = [
+            f"Community: {comm_row['name']}",
+            f"size: {comm_row['node_count']} · cohesion: {comm_row['cohesion']:.2f}",
+        ]
+
+        if detail_level == "minimal":
+            # Just names
+            names = [m["name"] for m in members[:10]]
+            lines.append(f"members: {', '.join(names)}")
+            if len(members) > 10:
+                lines[-1] += f" +{len(members) - 10} more"
+        else:
+            # Full member list with types
+            type_abbr = {"Function": "fn", "Class": "cls", "Method": "mth", "Variable": "var"}
+            lines.append("members:")
+            for m in members[:30]:
+                abbr = type_abbr.get(m["kind"], m["kind"][:3])
+                lines.append(f"  [{abbr}] {m['name']} ({m['file_path']})")
+            if len(members) > 30:
+                lines.append(f"  ... +{len(members) - 30} more")
+
+        return "\n".join(lines)
+
+    except Exception as e:
+        logger.exception(f"Error getting community {community_id}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_get_architecture_overview(
+    path: str,
+    detail_level: str = "minimal",
+) -> str:
+    """Compact architecture summary: communities, coupling, hubs, flows.
+
+    Provides a high-level view of the codebase architecture in under 150 tokens.
+
+    Args:
+        path: Root directory of the project
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Architecture overview with communities, coupling warnings, top hubs, flows
+    """
+    from ..graph.communities import (
+        detect_communities,
+        format_architecture_overview,
+        get_coupling_warnings,
+        store_communities,
+    )
+
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    store = _get_graph_store(abs_path)
+    if not store:
+        return f'No index found. Run codegraph_scan(path="{path}") first.'
+
+    try:
+        handler = get_handler()
+        code_map = handler._get_code_map(abs_path)
+
+        # Communities
+        communities_db = store.get_communities(limit=20)
+        if communities_db:
+            communities = [
+                {
+                    "name": c["name"],
+                    "node_count": c["node_count"],
+                    "cohesion": c["cohesion"],
+                    "member_ids": [],
+                }
+                for c in communities_db
+            ]
+        else:
+            communities = detect_communities(store)
+            store_communities(store, communities)
+
+        coupling_warnings = get_coupling_warnings(store, communities)
+        hubs = handler._compute_hubs(code_map, top_n=3, min_imports=2)
+        stats = store.get_stats()
+
+        output = format_architecture_overview(
+            communities, coupling_warnings, hubs, stats.get("flows", 0)
+        )
+
+        if detail_level in ("standard", "verbose"):
+            output += f"\n\ngraph: {stats['nodes']} nodes · {stats['edges']} edges"
+            output += f"\nroutes: {stats.get('routes', 0)} · schemas: {stats.get('schemas', 0)}"
+
+        return output
+
+    except Exception as e:
+        logger.exception(f"Error getting architecture overview for {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_list_routes(
+    path: str,
+    framework: str | None = None,
+    group_crud: bool = True,
+    detail_level: str = "minimal",
+) -> str:
+    """List detected HTTP routes with methods, paths, and domain tags.
+
+    Detects routes from 15+ frameworks: FastAPI, Flask, Django, Express,
+    Next.js, NestJS, Gin, Rails, Spring, and more.
+
+    Args:
+        path: Root directory of the project
+        framework: Filter by framework (e.g., 'fastapi', 'express')
+        group_crud: Group CRUD endpoints (default: True)
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Route list with methods, paths, handlers, and tags
+    """
+    from ..domain.routes import detect_routes, format_routes_minimal
+
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    store = _get_graph_store(abs_path, auto_build=False)
+
+    try:
+        # Check DB first
+        if store:
+            routes_db = store.get_routes(framework=framework)
+            if routes_db:
+                routes = [
+                    {
+                        "method": r["method"],
+                        "path": r["path"],
+                        "file_path": r["file_path"],
+                        "handler_name": r["handler_name"],
+                        "framework": r["framework"],
+                        "tags": json.loads(r["tags"]) if r["tags"] else [],
+                        "confidence": r["confidence"],
+                    }
+                    for r in routes_db
+                ]
+                return format_routes_minimal(routes, group_crud=group_crud)
+
+        # Detect on demand from code_map
+        handler = get_handler()
+        exists, error_msg = handler._check_map_exists(abs_path)
+        if not exists:
+            return error_msg
+
+        code_map = handler._get_code_map(abs_path)
+        routes = detect_routes(code_map, root_path=abs_path)
+
+        if framework:
+            routes = [r for r in routes if r["framework"] == framework]
+
+        # Store if we have a graph store
+        if store:
+            store.clear_routes()
+            for r in routes:
+                store.insert_route(**r)
+
+        return format_routes_minimal(routes, group_crud=group_crud)
+
+    except Exception as e:
+        logger.exception(f"Error listing routes for {path}")
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def codegraph_list_schemas(
+    path: str,
+    orm: str | None = None,
+    detail_level: str = "minimal",
+) -> str:
+    """List detected ORM models/schemas with fields and relations.
+
+    Detects schemas from 8+ ORMs: SQLAlchemy, Django, Prisma, Sequelize,
+    TypeORM, GORM, Drizzle, Mongoose.
+
+    Args:
+        path: Root directory of the project
+        orm: Filter by ORM (e.g., 'sqlalchemy', 'django')
+        detail_level: Output detail: 'minimal' (default), 'standard', or 'verbose'
+
+    Returns:
+        Schema list with model names, field counts, and ORM type
+    """
+    from ..domain.schemas import detect_schemas, format_schemas_minimal
+
+    detail_level = _validate_detail_level(detail_level)
+    abs_path = os.path.abspath(path)
+
+    store = _get_graph_store(abs_path, auto_build=False)
+
+    try:
+        # Check DB first
+        if store:
+            schemas_db = store.get_schemas(orm=orm)
+            if schemas_db:
+                schemas = [
+                    {
+                        "name": s["name"],
+                        "file_path": s["file_path"],
+                        "orm": s["orm"],
+                        "fields": json.loads(s["fields"]) if s["fields"] else [],
+                        "relations": json.loads(s["relations"]) if s["relations"] else [],
+                    }
+                    for s in schemas_db
+                ]
+                output = format_schemas_minimal(schemas)
+                if detail_level == "verbose":
+                    for s in schemas[:10]:
+                        if s["fields"]:
+                            fields_str = ", ".join(
+                                f"{f['name']}:{f['type']}" for f in s["fields"][:10]
+                            )
+                            output += f"\n  {s['name']}: {fields_str}"
+                return output
+
+        # Detect on demand
+        handler = get_handler()
+        exists, error_msg = handler._check_map_exists(abs_path)
+        if not exists:
+            return error_msg
+
+        code_map = handler._get_code_map(abs_path)
+        schemas = detect_schemas(code_map, root_path=abs_path)
+
+        if orm:
+            schemas = [s for s in schemas if s["orm"] == orm]
+
+        if store:
+            store.clear_schemas()
+            for s in schemas:
+                store.insert_schema(**s)
+
+        return format_schemas_minimal(schemas)
+
+    except Exception as e:
+        logger.exception(f"Error listing schemas for {path}")
+        return f"Error: {e}"
+
+
+# ==============================================================================
+# MCP RESOURCES
+# ==============================================================================
+
+
+@mcp.resource("codegraph://code-map")
+def get_code_map_resource() -> str:
+    """The current codebase structural map as JSON."""
+    handler = get_handler()
+    code_map = handler._get_code_map(handler.workspace_root)
+    return json.dumps(code_map, indent=2)
+
+
+@mcp.resource("codegraph://dependencies")
+def get_dependencies_resource() -> str:
+    """File dependency relationships as JSON."""
+    handler = get_handler()
+    code_map = handler._get_code_map(handler.workspace_root)
+    deps = {fpath: info.get("imports", []) for fpath, info in code_map.get("files", {}).items()}
+    return json.dumps(deps, indent=2)
+
+
+# ==============================================================================
+# MCP PROMPTS - Workflow Templates
+# ==============================================================================
+
+
+@mcp.prompt()
+def investigate_bug(path: str, description: str) -> str:
+    """Investigate a bug using token-efficient navigation.
+
+    Args:
+        path: Path to the codebase
+        description: Bug description or error message
+    """
+    return f"""Investigate a bug in the codebase at {path}.
+Bug: {description}
+
+Workflow:
+1. codegraph_get_minimal_context(path="{path}", task="fix {description}")
+2. codegraph_search(query="<keyword from bug description>", path="{path}")
+3. codegraph_read the relevant symbol locations (only the specific line ranges)
+4. codegraph_get_dependencies to understand what depends on the buggy code
+5. codegraph_test_gaps(path="{path}", changed_only=True) to check test coverage
+
+Rules:
+- Always start with codegraph_get_minimal_context for orientation
+- Use detail_level="minimal" unless you need more context
+- Read surgically: specific line ranges, never whole files
+- Only escalate to detail_level="standard" if minimal is insufficient"""
+
+
+@mcp.prompt()
+def add_feature(path: str, description: str) -> str:
+    """Plan and implement a new feature using token-efficient navigation.
+
+    Args:
+        path: Path to the codebase
+        description: Feature description
+    """
+    return f"""Add a feature to the codebase at {path}.
+Feature: {description}
+
+Workflow:
+1. codegraph_get_minimal_context(path="{path}", task="add {description}")
+2. codegraph_search for similar existing patterns to follow
+3. codegraph_get_structure on the target file to understand its layout
+4. codegraph_read the relevant sections for context
+5. Implement the feature following existing patterns
+
+Rules:
+- Always start with codegraph_get_minimal_context for orientation
+- Use detail_level="minimal" unless you need more context
+- Read surgically: specific line ranges, never whole files
+- Follow existing code patterns and conventions"""
+
+
+@mcp.prompt()
+def review_changes(path: str, base: str = "HEAD~1") -> str:
+    """Review code changes using token-efficient navigation.
+
+    Args:
+        path: Path to the codebase
+        base: Git ref to compare against (default: HEAD~1)
+    """
+    return f"""Review code changes in the codebase at {path} since {base}.
+
+Workflow:
+1. codegraph_get_minimal_context(path="{path}", task="review changes", base="{base}")
+2. codegraph_test_gaps(path="{path}", changed_only=True, base="{base}")
+3. codegraph_search for the changed symbols to understand their context
+4. codegraph_read the changed functions (only the specific line ranges)
+5. codegraph_get_dependencies for high-risk changed files
+
+Rules:
+- Always start with codegraph_get_minimal_context for orientation
+- Use detail_level="minimal" unless you need more context
+- Focus on untested changes first (from test_gaps)
+- Check dependencies of changed files for blast radius"""
+
+
+@mcp.prompt()
+def understand_architecture(path: str) -> str:
+    """Understand the architecture of a codebase.
+
+    Args:
+        path: Path to the codebase
+    """
+    return f"""Understand the architecture of the codebase at {path}.
+
+Workflow:
+1. codegraph_get_minimal_context(path="{path}", task="understand architecture")
+2. codegraph_get_hubs(path="{path}") to find central files
+3. codegraph_get_dependencies(path="{path}") for coupling overview
+4. codegraph_get_structure on the top hub files
+5. codegraph_read key sections of hub files for understanding
+
+Rules:
+- Always start with codegraph_get_minimal_context for orientation
+- Use detail_level="minimal" first, then "standard" for hubs only if needed
+- Read surgically: specific line ranges, never whole files
+- Summarize: overall structure, key modules, coupling patterns"""
+
+
+@mcp.prompt()
+def onboard_project(path: str) -> str:
+    """Get up to speed on a new project.
+
+    Args:
+        path: Path to the codebase
+    """
+    return f"""Get up to speed on the project at {path}.
+
+Workflow:
+1. codegraph_get_minimal_context(path="{path}", task="onboard to project")
+2. codegraph_stats(path="{path}") for project size overview
+3. codegraph_get_hubs(path="{path}") to find the most important files
+4. codegraph_get_structure on the top 3 hub files
+5. codegraph_read entry points and main abstractions
+
+Rules:
+- Always start with codegraph_get_minimal_context for orientation
+- Use detail_level="minimal" unless you need more context
+- Focus on understanding hubs and entry points first
+- Read surgically: specific line ranges, never whole files"""
+
+
+# ==============================================================================
+# ENTRY POINTS
+# ==============================================================================
+
+
+def create_server(workspace_root: str | None = None) -> FastMCP:
+    """Create and return the MCP server instance."""
+    global _handler
+    _handler = CodegraphToolHandler(workspace_root)
+    return mcp
+
+
+async def run_server(workspace_root: str | None = None):
+    """Run the MCP server using stdio transport."""
+    global _handler
+    _handler = CodegraphToolHandler(workspace_root)
+    await mcp.run_stdio_async()
+
+
+def main():
+    """Entry point for the MCP server."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Codegraph-nav MCP Server")
+    parser.add_argument(
+        "--workspace",
+        "-w",
+        default=os.getcwd(),
+        help="Workspace root directory",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging",
+    )
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.INFO)
+
+    global _handler
+    _handler = CodegraphToolHandler(args.workspace)
+
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()