codegraph-nav

<p align="center"> <img src="https://img.shields.io/badge/MCP-1.0+-blue.svg" alt="MCP 1.0+"> <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"> <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"> <img src="https://img.shields.io/badge/version-0.3.1-orange.svg" alt="Version 0.3.1"> <img src="https://img.shields.io/badge/tools-20-purple.svg" alt="20 MCP Tools"> </p> <h1 align="center">codegraph-nav</h1> <p align="center"> <strong>Graph-intelligent, token-efficient code navigation for AI assistants</strong> </p> <p align="center"> <em>Surgical reading, execution flows, blast radius, risk scoring &mdash; 97% fewer tokens</em> </p> --- ## What is codegraph-nav? codegraph-nav is an **MCP server** that helps AI assistants explore codebases efficiently. Beyond basic search and read, it adds **graph intelligence**: blast radius analysis, execution flow tracing, risk-scored diffs, and community detection. ``` ┌─────────────────────────────────────────────────────────────┐ │ WITHOUT CODEGRAPH-NAV │ ├─────────────────────────────────────────────────────────────┤ │ User: "Fix the payment bug" │ │ │ │ Claude reads: │ │ • payments.py (500 lines) → 7,500 tokens │ │ • billing.py (300 lines) → 4,500 tokens │ │ • models/order.py (200 lines) → 3,000 tokens │ │ ───────────────────────────────────────────── │ │ Total: 15,000 tokens │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────┐ │ WITH CODEGRAPH-NAV │ ├─────────────────────────────────────────────────────────────┤ │ User: "Fix the payment bug" │ │ │ │ 1. codegraph_get_minimal_context → 100 tokens │ │ 2. codegraph_search("payment") → 100 tokens │ │ 3. codegraph_read(payments.py, 45, 89) → 400 tokens │ │ 4. codegraph_blast_radius → 100 tokens │ │ ───────────────────────────────────────────── │ │ Total: 700 tokens │ │ │ │ SAVINGS: 95% fewer tokens + impact analysis! │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Quick Start ### 1. Install ```bash pip install codegraph-nav[mcp] # MCP server + core pip install codegraph-nav[all] # Everything (tree-sitter, networkx, ast-grep) ``` ### 2. Configure Claude Code (CLI) Add to `~/.claude/mcp.json`: ```json { "mcpServers": { "codegraph-nav": { "command": "codegraph-nav-mcp" } } } ``` ### 3. Configure Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "codegraph-nav": { "command": "codegraph-nav-mcp" } } } ``` ### 4. Use It In Claude, just ask to explore your codebase: ``` "Scan this project and find the payment function" "What's the blast radius if I change auth.py?" "Show me the architecture of this codebase" ``` Claude will automatically use codegraph-nav's 20 tools to explore efficiently. --- ## Available Tools ### Core Navigation | Tool | Purpose | When to Use | |------|---------|-------------| | `codegraph_get_minimal_context` | ~100 token project orientation | **Always use first** | | `codegraph_scan` | Index codebase to `.codegraph.json` | First time on a project | | `codegraph_search` | Find symbols by name/pattern | Looking for functions/classes | | `codegraph_read` | Read specific line ranges | After finding symbol locations | | `codegraph_stats` | Codebase size overview | Understanding project scale | | `codegraph_get_hubs` | Central files, or `scope="symbol"` for PageRank symbol hubs | Architecture analysis | | `codegraph_get_context` | PageRank-ranked, budget-bounded context for a query | "What should I read to understand X?" | | `codegraph_get_structure` | File symbol outline | Before reading a file | | `codegraph_get_dependencies` | Import/export graph | Understanding coupling | | `codegraph_test_gaps` | Find untested symbols | Before/after changes | ### Graph Intelligence | Tool | Purpose | When to Use | |------|---------|-------------| | `codegraph_graph_build` | Build graph DB (`.codegraph.db`) | Before heavy graph analysis | | `codegraph_blast_radius` | Impact analysis (recursive CTE) | "What breaks if I change this?" | | `codegraph_list_flows` | Execution flows + criticality | Understanding call chains | | `codegraph_detect_changes` | Risk-scored git diff | Code review / PR analysis | | `codegraph_search_graph` | FTS5 + fuzzy + RRF search | Search by concept, not just name | ### Architecture & Domain | Tool | Purpose | When to Use | |------|---------|-------------| | `codegraph_list_communities` | Code communities + cohesion | Architecture grouping | | `codegraph_get_community` | Community details + members | Explore a 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 | --- ## How It Works ```mermaid flowchart TB subgraph SCAN["Step 1: Scan"] A[(Codebase)] --> B[codegraph_scan] B --> C[.codegraph.json] end subgraph NAVIGATE["Step 2: Navigate"] D[codegraph_search] --> E[file:line locations] E --> F[codegraph_read] F --> G[Only needed code] end subgraph GRAPH["Step 3: Analyze"] C --> H[codegraph_graph_build] H --> I[.codegraph.db] I --> J[blast_radius / flows / risk] end C --> D ``` 1. **Scan once** - Creates `.codegraph.json` with all symbols indexed 2. **Search & read surgically** - Find symbols and load only the lines you need 3. **Graph analysis** - Build `.codegraph.db` for blast radius, flows, and risk scoring --- ## Example Session ``` 1. codegraph_get_minimal_context(path="/project", task="fix auth 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="authenticate") → src/auth.py:L10-30 [fn] authenticate 3. codegraph_read(file_path="src/auth.py", start_line=10, end_line=30) → Only those 20 lines (~200 tokens) 4. codegraph_blast_radius(path="/project", changed_files=["src/auth.py"]) → blast(auth.py): 12 nodes · 5 files impacted 5. codegraph_detect_changes(path="/project") → risk: 0.78 HIGH | 3 files · 8 symbols changed ``` --- ## Detail Levels All tools accept a `detail_level` parameter: - **`minimal`** (default) - Compact, token-efficient output - **`standard`** - Adds signatures, language breakdown, bidirectional counts - **`verbose`** - Adds docstrings, dependency chains, per-file details --- ## Workflow Prompts 5 built-in prompts that enforce token discipline: | Prompt | Use Case | |--------|----------| | `investigate_bug` | Bug investigation: orient, search, read, dependencies | | `add_feature` | Feature implementation: orient, search similar, structure, read | | `review_changes` | Code review: orient, test gaps, search changed, read | | `understand_architecture` | Architecture analysis: orient, hubs, dependencies, structure | | `onboard_project` | Project onboarding: orient, stats, hubs, structure | Each prompt starts with `codegraph_get_minimal_context` and defaults to `detail_level="minimal"`. --- ## Supported Languages | Language | Analysis Type | Symbols | Parents | Doc comments | Calls (deps) | Imports | Quality | |----------|---------------|:------:|:-------:|:------------:|:------------:|:-------:|---------| | Python | Full AST (stdlib) | ✅ (+enums, constants, nested fns) | ✅ | ✅ docstrings | ✅ | ✅ resolved | ⭐⭐⭐⭐⭐ | | JavaScript | AST (tree-sitter)* | ✅ | ✅ | — | ✅ | ✅ resolved | ⭐⭐⭐⭐⭐ | | TypeScript | AST (tree-sitter)* | ✅ (+interfaces, enums, types) | ✅ | — | ✅ | ✅ resolved | ⭐⭐⭐⭐⭐ | | Ruby | AST (tree-sitter)* | ✅ | ✅ | ✅ `#` | ✅ | ✅ `require` | ⭐⭐⭐⭐⭐ | | Go | AST (tree-sitter)* | ✅ (+structs, interfaces) | ✅ | ✅ `//` | ✅ | ✅ resolved | ⭐⭐⭐⭐⭐ | | Rust | AST (tree-sitter)* | ✅ (+structs, traits, enums) | ✅ | ✅ `///` | ✅ (+macros) | ✅ `use` | ⭐⭐⭐⭐⭐ | | Dart / Flutter | AST (tree-sitter)** | ✅ (+mixins, extensions) | ✅ | ✅ `///` | ✅ | ✅ resolved | ⭐⭐⭐⭐⭐ | | Java | AST (ast-grep)† / Regex | ✅ | — | — | — | — | ⭐⭐⭐⭐ `[fast]` / ⭐⭐⭐ regex | | C/C++ | AST (ast-grep)† / Regex | ✅ | — | — | — | — | ⭐⭐⭐⭐ `[fast]` / ⭐⭐⭐ regex | | PHP | AST (ast-grep)† / Regex | ✅ | — | — | — | — | ⭐⭐⭐⭐ `[fast]` / ⭐⭐⭐ regex | *Install tree-sitter support: `pip install codegraph-nav[ast]` All tree-sitter analyzers fall back to regex when tree-sitter is not installed. †Java/C/C++/PHP use [ast-grep](https://ast-grep.github.io/) for a real AST parse (cleaner symbol boundaries and signatures than regex) when the `[fast]` extra is installed (`pip install codegraph-nav[fast]`); without it they degrade to the regex analyzer. Both tiers currently extract symbols only — parent linkage, call dependencies, doc comments, and imports are not yet available for these languages. The tree-sitter tier (Python/JS/TS/Ruby/Go/Rust/Dart) extracts symbols with parent context, cross-file call dependencies (`deps`), and import specifiers resolved to internal repo files — which the graph builder turns into `CALLS` and `IMPORTS_FROM` edges. Go/Rust/Ruby/Dart additionally capture leading doc comments. **Dart/Flutter ships as its own extra: `pip install codegraph-nav[dart]`. The grammar (`tree-sitter-dart`) provides pre-compiled wheels for Linux/macOS/Windows — no C compiler needed. Without it, Dart falls back to the regex analyzer (classes, mixins, enums, extensions, top-level functions). Flutter needs no separate grammar; widgets are ordinary Dart classes. --- ## Micro-Metadata Format The scan output uses a compact ASCII tree with inline metadata: ``` my-project/ ├── src/ │ ├── api/ │ │ ├── client.py [C:APIClient M:get,post] (5←) │ │ └── routes.py [F:handle,validate] (3←) │ └── core/ │ └── config.py [C:Config M:load] (Hub:8←) └── tests/ └── test_api.py [F:test_client] ═══ Summary ═══ 28 files · 142 symbols · 12 hubs ``` Each file shows: classes (C:), functions (F:), methods (M:), and importer count (N←). --- ## CLI Usage ```bash # Generate code map codegraph-nav scan /path/to/project cgn scan . # Short alias # Search for symbols cgn search "process_payment" cgn search -t class -o table # Read specific lines cgn read src/payments.py 45-89 cgn read src/payments.py 45-89 -c 3 # With context # Get codebase stats cgn stats # Incremental update (only changed files) cgn scan --incremental . # Build the graph DB (.codegraph.db) from the code map cgn graph build . # incremental (skip unchanged files) cgn graph build . --full # full rebuild cgn graph stats . # node/edge counts (add -o json) # Watch for changes; also rebuild the graph after each update cgn watch . --graph # Export as markdown cgn export -f markdown -o docs/codebase.md ``` The graph build also computes a symbol-level **PageRank** (with the `[graph]` extra: `pip install codegraph-nav[graph]`), surfaced via the `codegraph_get_hubs` (`scope="symbol"`) and `codegraph_get_context` MCP tools. --- ## Python API ```python from codegraph_nav import CodeNavigator, CodeSearcher, LineReader # Scan navigator = CodeNavigator("/path/to/project") code_map = navigator.scan() # Search searcher = CodeSearcher(".codegraph.json") results = searcher.search_symbol("payment", symbol_type="function") # Read surgically reader = LineReader(root_path="/path/to/project") content = reader.read_lines("src/pay.py", 45, 89) ``` ### Graph API ```python from codegraph_nav.graph import GraphStore, GraphBuilder, get_blast_radius, trace_flows # Build graph from code map store = GraphStore(".codegraph.db") builder = GraphBuilder(store) stats = builder.build_from_code_map(code_map) # Blast radius impact = get_blast_radius(store, changed_files=["src/auth.py"]) print(f"{impact['impacted_nodes']} nodes, {len(impact['impacted_files'])} files affected") # Execution flows flows = trace_flows(store) for f in flows[:5]: print(f"{f['name']} crit:{f['criticality']:.2f} depth:{f['depth']}") store.close() ``` ### Domain Intelligence API ```python from codegraph_nav.domain import detect_routes, detect_schemas, infer_project_tags # Detect routes (FastAPI, Express, Django, Gin, etc.) routes = detect_routes(code_map, root_path="/path/to/project") # Detect ORM schemas (SQLAlchemy, Django, Prisma, etc.) schemas = detect_schemas(code_map, root_path="/path/to/project") # Infer domain tags (auth, db, cache, api, etc.) tags = infer_project_tags(code_map) ``` --- ## Optional Dependencies | Extra | What it adds | |-------|-------------| | `[mcp]` | MCP server (FastMCP) | | `[ast]` | Tree-sitter analyzers (JS/TS/Ruby/Go/Rust) | | `[graph]` | PageRank hub detection (networkx) | | `[fast]` | ast-grep high-perf parsing | | `[all]` | Everything above | | `[dev]` | pytest, mypy, black, ruff, build, twine | --- ## Performance Tested on real-world open source projects: | Project | Files | Symbols | Map Size | Map Time | |---------|-------|---------|----------|----------| | Flask | 142 | 1,847 | 89 KB | 0.8s | | Django | 2,156 | 28,493 | 1.2 MB | 8.2s | | requests | 47 | 412 | 23 KB | 0.3s | **Token savings:** - Small projects (50-100 files): 85-90% reduction - Medium projects (100-500 files): 92-96% reduction - Large projects (500+ files): 97-99% reduction --- ## Development ```bash git clone https://github.com/efrenbl/codegraph-nav.git cd codegraph-nav python3 -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" python3 -m pytest tests/ -v ``` --- ## Requirements - Python 3.10+ - MCP SDK 1.0+ (for MCP server only) --- ## License MIT License - see [LICENSE](LICENSE) for details. --- <p align="center"> <strong>Stop burning tokens reading entire files.</strong><br> <em>Scan once, search instantly, read surgically, analyze impact.</em> </p>