Metadata-Version: 2.4
Name: codegraph-nav
Version: 0.4.1
Summary: Graph-intelligent, token-efficient code navigation for AI assistants. Surgical reading, execution flows, risk scoring, and micro-metadata rendering.
Author-email: Efren Bautista <ing.efrenbl@gmail.com>
Maintainer-email: Efren Bautista <ing.efrenbl@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/efrenbl/codegraph-nav
Project-URL: Documentation, https://github.com/efrenbl/codegraph-nav#readme
Project-URL: Repository, https://github.com/efrenbl/codegraph-nav.git
Project-URL: Issues, https://github.com/efrenbl/codegraph-nav/issues
Project-URL: Changelog, https://github.com/efrenbl/codegraph-nav/blob/main/CHANGELOG.md
Keywords: mcp,model-context-protocol,code-navigation,code-graph,token-optimization,ast,code-search,execution-flows,risk-scoring,developer-tools,ai-coding,claude
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: mcp>=1.0.0; extra == "dev"
Provides-Extra: ast
Requires-Dist: tree-sitter>=0.23.0; extra == "ast"
Requires-Dist: tree-sitter-language-pack>=1.10.0; extra == "ast"
Provides-Extra: dart
Requires-Dist: tree-sitter>=0.23.0; extra == "dart"
Requires-Dist: tree-sitter-language-pack>=1.10.0; extra == "dart"
Provides-Extra: graph
Requires-Dist: networkx>=3.0; extra == "graph"
Requires-Dist: numpy>=1.21; extra == "graph"
Requires-Dist: scipy>=1.7; extra == "graph"
Provides-Extra: fast
Requires-Dist: ast-grep-py>=0.40.0; extra == "fast"
Provides-Extra: all
Requires-Dist: mcp>=1.0.0; extra == "all"
Requires-Dist: tree-sitter>=0.23.0; extra == "all"
Requires-Dist: tree-sitter-language-pack>=1.10.0; extra == "all"
Requires-Dist: networkx>=3.0; extra == "all"
Requires-Dist: numpy>=1.21; extra == "all"
Requires-Dist: scipy>=1.7; extra == "all"
Requires-Dist: ast-grep-py>=0.40.0; extra == "all"
Dynamic: license-file

<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.4.1-orange.svg" alt="Version 0.4.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 (tree-sitter)*† | ✅ (+records, annotations) | ✅ | ✅ Javadoc | ✅ | ✅ | ⭐⭐⭐⭐⭐ |
| Kotlin | AST (tree-sitter)* | ✅ (+objects, data classes) | ✅ | ✅ KDoc | ✅ | ✅ | ⭐⭐⭐⭐⭐ |
| Swift | AST (tree-sitter)* | ✅ (+protocols, extensions) | ✅ | ✅ `///` | ✅ | ✅ | ⭐⭐⭐⭐⭐ |
| C# | AST (tree-sitter)* | ✅ (+records, delegates) | ✅ | ✅ `///` | ✅ | ✅ `using` | ⭐⭐⭐⭐⭐ |
| C | AST (tree-sitter)*† | ✅ (+prototypes, typedefs) | — | ✅ | ✅ | ✅ includes | ⭐⭐⭐⭐⭐ |
| C++ | AST (tree-sitter)*† | ✅ (+out-of-line members) | ✅ | ✅ | ✅ | ✅ includes | ⭐⭐⭐⭐⭐ |
| PHP | AST (tree-sitter)*† | ✅ (+traits, enums) | ✅ | ✅ docblocks | ✅ | ✅ `use`/require | ⭐⭐⭐⭐⭐ |

*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 keep [ast-grep](https://ast-grep.github.io/) as an intermediate
fallback: with the `[fast]` extra installed but no tree-sitter grammar, they
get a real AST parse (symbols + parents) before degrading to regex.

Every tree-sitter language 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.
All except JS/TS also capture leading doc comments. Each symbol records which
engine produced it (`"source": "ast" | "ast-grep" | "regex"`), and
`codegraph_stats` shows the per-engine breakdown.

**AST grammars ship through `tree-sitter-language-pack`** (installed by the
`[ast]` extra): one dependency with 160+ pre-compiled grammars for
Linux/macOS/Windows — no C compiler needed. Installations that predate the
pack keep working: the grammar registry also resolves the old individual
`tree-sitter-<lang>` wheels. `[dart]` remains as a deprecated alias of
`[ast]`. Without any grammar installed, every language falls back to the
regex analyzer. 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>
