# CodeGraph Smart MCP

Code Intelligence MCP Server for Claude — auto-indexes your codebase into a knowledge graph with GraphRAG + hybrid search, and opens a live dashboard.

## Features

- **Zero config** — one command to index, search, and visualize any codebase
- **GraphRAG** — builds a knowledge graph of symbols, calls, imports, and clusters
- **Hybrid search** — BM25 + vector similarity (local embeddings, no API key needed)
- **MCP Server** — exposes tools to Claude Desktop for deep code understanding
- **Live dashboard** — Next.js + D3.js interactive graph visualization
- **Multi-language** — Python, JavaScript, TypeScript, JSX, TSX via Tree-sitter

## Quick Start

```bash
npm install -g codegraph-smart-mcp
```

Then navigate to any project and run:

```bash
codegraph
```

That's it. First run indexes your code and opens the dashboard. Next runs are instant.

### Requirements

- **Node.js** >= 18
- **Python** >= 3.9 (auto-detected, venv created automatically)

## Usage

```bash
# Smart start — index + dashboard + open browser
codegraph /path/to/your/project

# Force re-index
codegraph --reindex

# Configure Claude Desktop (standby mode)
codegraph setup

# Index + configure Claude Desktop
codegraph init /path/to/project

# MCP stdio server (for Claude Desktop)
codegraph serve /path/to/project

# API server only (no browser)
codegraph start /path/to/project

# Check index status
codegraph status

# Diagnose installation
codegraph doctor
```

## MCP Tools (for Claude)

| Tool | Purpose |
|------|---------|
| `index_project` | Index a directory on demand |
| `query` | Hybrid BM25 + semantic search over symbols |
| `context` | 360-degree view: callers, callees, file location |
| `impact` | Blast radius — downstream/upstream traversal |
| `get_content` | Read raw file content |
| `list_clusters` | Functional module overview |
| `explore_process` | Execution flow traces |
| `get_status` | Check index and search status |

## Claude Desktop Integration

After installing, run:

```bash
codegraph setup
```

This auto-configures Claude Desktop. Restart Claude Desktop, then ask:

> "Index my project at /path/to/project"

Or pre-index a project:

```bash
codegraph init /path/to/project
```

## Architecture

```
Your Project
    |
    v
Ingestion Pipeline (7 phases)
    |- Filesystem walk -> FileNodes
    |- Tree-sitter AST -> SymbolNodes + edges
    |- Cross-file import/call resolution
    |- Community detection (label propagation)
    |- Entry point detection + call chains
    |- Markdown/txt doc chunking
    |- Sentence-transformer embeddings
    |
    v
Storage: Neo4j (graph) + Qdrant (vectors)
    |
    v
Interfaces: MCP Server + REST API + Next.js Dashboard
```

## Search Modes

- **BM25 only** — always available, no external dependencies
- **Hybrid (BM25 + vectors)** — requires Qdrant. Default local model: `all-MiniLM-L6-v2` (~80MB, CPU)
- **OpenAI embeddings** — optional, set `CODEGRAPH_OPENAI_API_KEY`

## Configuration

All settings use `CODEGRAPH_` prefix:

```bash
CODEGRAPH_NEO4J_URI=bolt://localhost:7687
CODEGRAPH_NEO4J_PASSWORD=codegraph123
CODEGRAPH_QDRANT_MODE=disk            # memory | disk | server
CODEGRAPH_EMBEDDING_BACKEND=local     # local | openai
CODEGRAPH_OPENAI_API_KEY=sk-...       # required if backend=openai
```

## License

MIT