Metadata-Version: 2.4
Name: codegraph-nav
Version: 0.1.0
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; python_version >= "3.9" and extra == "ast"
Requires-Dist: tree-sitter-javascript>=0.23.0; python_version >= "3.9" and extra == "ast"
Requires-Dist: tree-sitter-typescript>=0.23.0; python_version >= "3.9" and extra == "ast"
Requires-Dist: tree-sitter-ruby>=0.23.0; python_version >= "3.9" and extra == "ast"
Requires-Dist: tree-sitter-go>=0.23.0; python_version >= "3.9" and extra == "ast"
Requires-Dist: tree-sitter-rust>=0.23.0; python_version >= "3.9" and extra == "ast"
Provides-Extra: dart
Requires-Dist: tree-sitter>=0.23.0; python_version >= "3.9" and extra == "dart"
Requires-Dist: tree-sitter-dart>=0.1.0; python_version >= "3.9" and 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-javascript>=0.23.0; extra == "all"
Requires-Dist: tree-sitter-typescript>=0.23.0; extra == "all"
Requires-Dist: tree-sitter-ruby>=0.23.0; extra == "all"
Requires-Dist: tree-sitter-go>=0.23.0; extra == "all"
Requires-Dist: tree-sitter-rust>=0.23.0; extra == "all"
Requires-Dist: tree-sitter-dart>=0.1.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.1.0-orange.svg" alt="Version 0.1.0">
  <img src="https://img.shields.io/badge/tools-19-purple.svg" alt="19 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 19 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` | Find central files (PageRank) | Architecture analysis |
| `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 | Quality |
|----------|---------------|---------|
| Python | Full AST (stdlib) | ⭐⭐⭐⭐⭐ |
| JavaScript | AST (tree-sitter)* | ⭐⭐⭐⭐⭐ |
| TypeScript | AST (tree-sitter)* | ⭐⭐⭐⭐⭐ |
| Ruby | AST (tree-sitter)* | ⭐⭐⭐⭐ |
| Go | AST (tree-sitter)* | ⭐⭐⭐⭐ |
| Rust | AST (tree-sitter)* | ⭐⭐⭐⭐ |
| Dart / Flutter | AST (tree-sitter)** | ⭐⭐⭐⭐ |
| Java | Regex-based | ⭐⭐⭐ |
| C/C++ | Regex-based | ⭐⭐⭐ |
| PHP | Regex-based | ⭐⭐⭐ |

*Install tree-sitter support: `pip install codegraph-nav[ast]`
All tree-sitter analyzers fall back to regex when tree-sitter is not installed.

**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 .

# Export as markdown
cgn export -f markdown -o docs/codebase.md
```

---

## 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>
