# Universal Code Review Graph

> Save 6-8× tokens on AI code reviews. Builds a structural call graph via Tree-sitter + MCP. Works with Claude, Kimi, Gemini, ChatGPT, Cursor, Windsurf — any AI assistant.

- **Type:** MCP server
- **Install:** `agentstack add mcp-cybernoman-universal-code-review-graph`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cyberNoman](https://agentstack.voostack.com/s/cybernoman)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cyberNoman](https://github.com/cyberNoman)
- **Source:** https://github.com/cyberNoman/universal-code-review-graph

## Install

```sh
agentstack add mcp-cybernoman-universal-code-review-graph
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🧠 Universal Code Review Graph

### One MCP Server · Any AI Assistant · 8–15× Fewer Tokens

[](https://github.com/cyberNoman/universal-code-review-graph/actions/workflows/tests.yml)
[](LICENSE)
[](https://python.org)
[](https://modelcontextprotocol.io)
[](universal-code-graph/CONTRIBUTING.md)
[](README.md)

> **Stop sending your entire codebase to AI on every request.**
> Build a code graph once. Review only what matters. Save 85–93% of tokens.

| 🔬 Physics-Inspired Math | 🌐 Universal AI Support | ⚡ One-Time Setup |
|:---:|:---:|:---:|
| 6 advanced optimization techniques | Claude, Kimi, Qwen, GPT, Cursor & more | Build graph once, use forever |

---

## 🎯 See It In Action

```bash
$ cd my-django-app/
$ code-graph-server &

You → AI:  "Build the code graph for this repo"
AI  →  ✅ Done. 2,341 symbols · 4,892 edges · 127 files indexed (8.3s)

You → AI:  "I changed checkout/views.py and checkout/serializers.py. Review my PR."

AI  →  [review_changes] scanning blast radius...

       📁 Files to review (5 of 127):
          checkout/views.py          ← changed
          checkout/serializers.py    ← changed
          checkout/models.py         ← downstream: CartItem, Order
          payments/stripe.py         ← downstream: charge()
          orders/tasks.py            ← upstream: calls process_checkout()

       ⚡ 2,100 tokens used  (was 18,400 without graph)
       🎯 Quality score: 8.7/10  (was 6.9/10)
       🧮 Optimized with: PageRank + Entropy + LSH + Physics

You → AI:  "What breaks if I rename process_checkout()?"
AI  →  [get_impact] upstream callers: orders/tasks.py, api/webhooks.py
                    downstream callees: payments/stripe.py, cart/models.py
```

---

## 📊 Real-World Results

```
Repository: Django e-commerce app — 127 Python files
Changed:    checkout/views.py + checkout/serializers.py

┌─────────────────┬──────────────────┬──────────────────┐
│     Metric      │  Without Graph   │   With Graph     │
├─────────────────┼──────────────────┼──────────────────┤
│ Files Read      │      127         │        5         │
│ Tokens Used     │    18,400        │     2,100        │
│ Review Time     │      45s         │       8s         │
│ Quality Score   │    6.9 / 10      │    8.7 / 10      │
│ Cost            │    $0.55         │     $0.06        │
└─────────────────┴──────────────────┴──────────────────┘

        ✅  8.7× fewer tokens   ·   89% cost reduction
```

---

## ✨ Why This Exists

| ❌ Traditional Approach | ✅ Our Approach |
|:---:|:---:|
| AI reads entire codebase every request | Build code graph once |
| 80–90% tokens wasted on irrelevant files | Mathematical optimization selects only relevant context |
| Slower · Expensive · Lower quality | 6–8× fewer tokens · Faster · Higher quality |

---

## 🔬 Mathematical Optimization Engine

**6 physics-inspired techniques working together for 8–15× token reduction**

| Technique | Foundation | Savings |
|:---|:---|:---:|
| **Shannon Entropy Filtering** | `H(X) = -Σ p(x) log₂ p(x)` | 1.5–2× |
| **Spectral Graph Centrality** | Eigenvector: `A·x = λx` | 1.8–2.5× |
| **Thermodynamic Pruning** | Free Energy: `F = E - T·S` | 1.6–2.2× |
| **Wave Function Collapse** | Quantum-inspired symbol merging | 1.3–1.8× |
| **Fractal Dimension Analysis** | Box-Counting: `D = log N(ε) / log(1/ε)` | 1.4–1.9× |
| **Renormalization Group Flow** | Statistical physics coarse-graining | 2.0–3.0× |
| **🔥 Combined Pipeline** | All techniques sequentially | **8–15×** |

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────┐
│              AI Assistant                               │
│    Claude · Kimi · Qwen · GPT · Cursor · Windsurf       │
└────────────────────────┬────────────────────────────────┘
                         │  MCP Protocol (JSON-RPC)
                         ▼
┌─────────────────────────────────────────────────────────┐
│              Universal MCP Server                       │
│  build_graph · review_changes · get_impact · find_paths │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│         Mathematical Token Optimizer (6 Techniques)     │
│  Entropy · Spectral · Thermodynamic · Wave · Fractal    │
│                    Renormalization                       │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│              Graph Engine                               │
│         NetworkX + Tree-sitter (AST Parsing)            │
│        Symbols (nodes) · Calls (edges) · Files          │
└────────────────────────┬────────────────────────────────┘
                         │  SQLite
                         ▼
              ┌──────────────────┐
              │  .code_graph.db  │
              │ Persistent Store │
              └──────────────────┘
```

---

## 🚀 Quick Start

### Option 1: pip Install

```bash
pip install universal-code-review-graph[all]
code-graph-server
```

### Option 2: From Source

```bash
git clone https://github.com/cyberNoman/universal-code-review-graph.git
cd universal-code-review-graph/universal-code-graph
pip install -r requirements.txt
python server.py
```

### Option 3: Docker

```bash
docker build -t code-graph .
docker run -v $(pwd):/workspace code-graph build /workspace
```

---

## 🔌 Connect Your AI

### Claude Code
```bash
claude mcp add code-graph code-graph-server
```

### Kimi / Qwen / ChatGPT / Any MCP Client
```json
{
  "mcpServers": {
    "code-graph": {
      "command": "python3",
      "args": ["/path/to/server.py"]
    }
  }
}
```

### Cursor / Windsurf
```json
{
  "servers": {
    "code-graph": {
      "command": "python3",
      "args": ["/path/to/server.py"],
      "type": "stdio"
    }
  }
}
```

---

## 🛠️ The 9 MCP Tools

| Tool | What It Does | Impact |
|:---|:---|:---:|
| `build_graph` | Index repo — parse + build graph + save to SQLite | Run once |
| **`review_changes`** | **Blast radius for changed files** | **6–8× savings** |
| `get_impact` | All callers + callees of a symbol | Refactoring safety |
| `find_paths` | Call chains between two symbols | Debugging |
| `search_symbols` | Find by name / wildcard (`parse*`) | Exploration |
| `get_symbol_details` | Location, callers, callees for one symbol | Deep dive |
| `get_file_symbols` | All symbols in a file | File overview |
| `export_graph` | JSON, DOT (Graphviz), or summary | Tooling |
| `get_stats` | Counts + most-connected nodes | Health check |

---

## 🌐 Supported AI Assistants

| AI Assistant | Token Savings | Best For |
|:---:|:---:|:---|
| **Kimi K2.5** | ~7.5× | Visual analysis, long context |
| **Claude / Claude Code** | ~6.8× | Complex reasoning |
| **Gemini Pro** | ~7.2× | Multimodal tasks |
| **ChatGPT / GPT-4o** | ~6.5× | General purpose |
| **Qwen** | ~6.7× | Fast inference, multilingual |
| **Cursor** | ~7.0× | IDE integration |
| **Windsurf** | ~7.0× | Workflow automation |
| **Any MCP Client** | ~6.5× | Universal |

---

## 💻 Supported Languages

| Language | Symbols | Call Edges | Status |
|:---:|:---:|:---:|:---:|
| Python | ✅ | ✅ | Production |
| JavaScript / JSX | ✅ | ✅ | Production |
| TypeScript / TSX | ✅ | ✅ | Production |
| Go | ✅ | ✅ | Production |
| Rust | 🟡 | 🟡 | Planned |
| Java | 🟡 | 🟡 | Planned |
| C / C++ | 🟡 | 🟡 | Planned |

---

## 🧪 CLI Usage

```bash
# Build graph for your project
code-graph build /path/to/repo

# Review changed files
code-graph review src/main.py src/utils.py --depth 3

# Search symbols
code-graph search "parse*" --type function

# Show stats
code-graph stats

# Run benchmark
python benchmark.py /path/to/repo
```

---

## 📦 Project Layout

```
universal-code-review-graph/
├── universal-code-graph/       ← THE PRODUCT
│   ├── server.py               # MCP server entry point
│   ├── code_graph.py           # Graph engine (NetworkX + Tree-sitter)
│   ├── token_optimizer/        # Mathematical optimization (6 techniques)
│   ├── cli.py                  # Command-line interface
│   ├── configs/                # Ready-made configs for every AI
│   └── tests/                  # 94 tests — all passing ✅
│
├── docs/                       # Full documentation
├── app/                        # Landing page (React + Vite)
├── hooks/                      # Pre-commit hooks
├── .github/                    # GitHub Actions CI
├── Dockerfile                  # Docker support
└── docker-compose.yml
```

---

## 🔒 Persistent Across Sessions

> **You only run `build_graph` once per project — not every session.**
> On startup, the server automatically finds and loads `.code_graph.db` in your working directory.

---

## 👥 Built by Human + AI Collaboration

### Human

| Contributor | Role |
|:---:|:---|
| **Noman** ([@cyberNoman](https://github.com/cyberNoman)) | Project Lead · Architect · Vision · Testing · Deployment |

### AI Assistants

| AI | Provider | Contributions |
|:---:|:---:|:---|
| **Claude** | Anthropic | Core architecture · MCP server · CI/CD |
| **Kimi K2.5** | Moonshot AI | Math optimization · Physics algorithms · Graph theory |
| **Qwen** | Alibaba | Code structure · Integration patterns · Test framework |

*Built with ❤️ by Human + AI collaboration. The future of software development.*

---

## 🤝 Contributing

See [CONTRIBUTING.md](universal-code-graph/CONTRIBUTING.md) for details.

**Most wanted contributions:**

- **Add Rust / Java / C++** — see [contributing guide](universal-code-graph/CONTRIBUTING.md)
- **Improve token optimization** — better algorithms, more techniques
- **Bug reports** — wrong blast radius results
- **Add IDE plugins** — JetBrains, Vim, Emacs

---

## 📝 License

MIT. See [LICENSE](LICENSE).

---

**One server. Any AI. Fewer tokens. Mathematical precision.**

⭐ **Star this repo if it saved you tokens** ⭐

[](https://github.com/cyberNoman/universal-code-review-graph/actions/workflows/tests.yml)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cyberNoman](https://github.com/cyberNoman)
- **Source:** [cyberNoman/universal-code-review-graph](https://github.com/cyberNoman/universal-code-review-graph)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cybernoman-universal-code-review-graph
- Seller: https://agentstack.voostack.com/s/cybernoman
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.