npx recon-mcp serve

# Index your project (zero config)
cd /path/to/your/project
npx recon-mcp index

# Start MCP server for AI agents
npx recon-mcp serve

# Or start HTTP REST API + interactive dashboard
npx recon-mcp serve --http
# → http://localhost:3100

npm install -g recon-mcp
recon index && recon serve

npm install @huggingface/transformers

# Mermaid flowchart for a package
recon export --package mcp --limit 20

# Ego graph around a symbol
recon export --symbol handleQuery --depth 2

# Filter by node types and edge types
recon export --type Function,Interface --edges CALLS

You add MCP config → Agent starts Recon automatically → Done.

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve", "--projects", "/path/to/frontend"],
      "cwd": "/path/to/backend"
    }
  }
}

{
  "mcpServers": {
    "recon-backend": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/backend"
    },
    "recon-frontend": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/frontend"
    }
  }
}

### Multi-Repo (Merged Graph)

For cross-project queries (e.g., tracing API calls from frontend to backend), use multi-repo mode:

// Code block

Then filter by repo in queries: `recon_find({query: "Auth", repo: "backend"})`.

### Auto-Indexing

`recon serve` handles indexing automatically:

| Scenario | Behavior |
|----------|----------|
| First run (no `.recon/`) | Full index → creates `.recon/recon.db` |
| Code changed since last index | Incremental re-index (only changed files) |
| No changes | Uses cached index → instant startup |
| Force re-index | `recon index --force` |
| Skip auto-index | `recon serve --no-index` |
| Index but no watcher | `recon serve --no-watch` |

> **Built-in Instructions:** Recon automatically injects [MCP server instructions](https://modelcontextprotocol.io/docs/concepts/server-instructions) into the agent's system prompt. The agent will proactively use `recon_impact` before editing, `recon_explain` for exploration, and `recon_rename` for safe renames — no manual prompting needed.

---

## CLI Commands

> **Auto-index:** `serve` checks if the index is up-to-date with the current Git commit. If stale, it re-indexes automatically before starting. Use `--no-index` to skip.

---

## Configuration

Create a `.recon.json` at your project root to persist settings:

**Priority:** CLI flags always override `.recon.json`, which overrides defaults.

With a config file, your MCP setup stays minimal:

> No more long `args` arrays — all config lives in `.recon.json`.

---

## Tool Reference

All 8 tools accept an optional `repo` parameter for multi-repo filtering.

### recon_map

Architecture overview: packages, tech stack, entry points, health.

### recon_find

Smart search: exact name, wildcard (`*Handler`), or natural language.

### recon_explain

Full 360° context: callers, callees, flows, cross-language links, tests.

### recon_impact

Blast radius analysis with affected tests.

**Risk levels:** `LOW` (0-2 d1) · `MEDIUM` (3-9) · `HIGH` (10-19) · `CRITICAL` (20+ or cross-app)

### recon_changes

Git diff to affected symbols, risk assessment, and affected tests.

### recon_rename

Graph-aware safe rename across files. Dry-run by default.

### recon_export

Generate Mermaid diagram.

### recon_rules

Code quality: dead code, circular deps, unused exports, large files, orphans.

---

## MCP Resources

Structured data via `recon://` URIs — agents READ these without making a tool call.

| Resource | URI | Description |
|----------|-----|-------------|
| Index Stats | `recon://stats` | Node and relationship counts by type and language |
| Symbol Detail | `recon://symbol/{name}` | Symbol definition, callers, callees, relationships |
| File Symbols | `recon://file/{path}` | All symbols in a file with types and line ranges |

---

## MCP Prompts

Three guided workflows that instruct AI agents step-by-step using Recon's tools:

| Prompt | Description | Usage |
|--------|-------------|-------|
| **`pre_commit`** | Pre-commit change analysis → risk report | `pre_commit(scope: "staged")` |
| **`architecture`** | Architecture documentation with mermaid diagrams | `architecture()` |
| **`onboard`** | New developer onboarding guide | `onboard(focus: "auth")` |

Each prompt returns a structured message with step-by-step instructions. The agent receives the message and autonomously executes each step using Recon tools.

---

## Dashboard

Start the HTTP server to access the interactive code intelligence dashboard:

**Features:**
- **Graph Tab** — Force-directed knowledge graph with type-colored nodes, community coloring toggle, and click-to-inspect
- **Processes Tab** — Execution flow viewer with call chains, branch counts, and community tags
- **Impact Tab** — Interactive blast radius analysis with risk levels and confidence tiers
- **Live Search** — Debounced search dropdown (200ms) with keyboard navigation (↑↓ Enter Esc)
- **Graph Legend** — Node type → shape/color mapping
- **Package Sidebar** — Filter graph by package with symbol counts

---

## Multi-Repo Support

Index and query multiple repositories from a single `.recon/` directory:

All tools accept an optional `repo` parameter. Per-repo indices are stored in `.recon/recon.db`.

---

## Search

### FTS5 Full-Text Search

FTS5 replaces custom BM25, with camelCase/snake_case tokenization built into SQLite.

- **Tokenizer** splits camelCase, PascalCase, snake_case, digit boundaries (`base64Decode` → `["base", "64", "decode"]`)
- **Name boost** — symbol names weighted 3x higher than file paths
- **Ranking** — FTS5 rank function with relevance scoring
- **Fallback** — substring matching when FTS5 returns nothing

### Hybrid Semantic Search

Enable with `recon index --embeddings`, then use `recon_find({query: "...", semantic: true})`.

- **Model:** `Xenova/all-MiniLM-L6-v2` (384-dim embeddings via `@huggingface/transformers`)
- **Fusion:** Reciprocal Rank Fusion (RRF) — `score = 1/(k + rank)`, k=60
- **Storage:** Persisted in recon.db

---

## Architecture

### Data Flow

---

## HTTP REST API

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/health` | Health check + index stats |
| `GET` | `/api/tools` | List available tools with schemas |
| `POST` | `/api/tools/:name` | Execute a tool (body = JSON params) |
| `GET` | `/api/resources` | List MCP resources + templates |
| `GET` | `/api/resources/read?uri=...` | Read resource by URI |

CORS enabled by default for browser clients.

> **Security:** HTTP server binds to localhost (127.0.0.1) by default. Use `--host 0.0.0.0` to expose on network.

---

## Graph Schema

### Node Properties

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Unique node identifier |
| `type` | `NodeType` | Function, Method, Struct, Interface, Class, etc. |
| `name` | `string` | Symbol name |
| `file` | `string` | Source file path |
| `startLine` / `endLine` | `number` | Line range in file |
| `language` | `Language` | Source language |
| `package` | `string` | Package/module path |
| `exported` | `boolean` | Whether the symbol is exported |
| `repo` | `string?` | Repository name (multi-repo) |
| `community` | `string?` | Community/cluster label (auto-detected) |
| `isTest` | `boolean?` | Whether the symbol is in a test file |

### Relationship Types

| Type | Meaning | Confidence |
|------|---------|------------|
| `CONTAINS` | Package/Module → File | 1.0 |
| `DEFINES` | File → Symbol | 1.0 |
| `CALLS` | Function → Function | 0.5–1.0 |
| `IMPORTS` | Package → Package / File → File | 1.0 |
| `HAS_METHOD` | Struct/Class → Method | 1.0 |
| `IMPLEMENTS` | Struct → Interface / Class → Trait | 0.8–0.9 |
| `EXTENDS` | Class → Class (inheritance) | 0.9 |
| `USES_COMPONENT` | Component → Component (JSX) | 0.9 |
| `CALLS_API` | TS Function → Go Handler (cross-language) | 0.85–0.95 |

---

## Testing

**541 tests** across **22 test suites:**

| Suite | Tests | Coverage |
|-------|-------|----------|
| `graph.test.ts` | 23 | KnowledgeGraph API — add, query, remove, serialize |
| `handlers.test.ts` | 30 | MCP tool dispatch with mock graph |
| `search.test.ts` | 27 | FTS5 tokenizer, ranking, serialization |
| `rename.test.ts` | 28 | Graph-aware rename, disambiguation, formatting |
| `resources.test.ts` | 35 | Resource URI parsing, all 3 resource types |
| `tree-sitter.test.ts` | 58 | Multi-language extraction, cross-language consistency |
| `multi-repo.test.ts` | 16 | Multi-repo storage, filtering |
| `community.test.ts` | 13 | Label propagation clustering, handler integration |
| `embeddings.test.ts` | 39 | Vector store, RRF fusion, hybrid search |
| `process.test.ts` | 21 | Execution flow detection, BFS, cycles |
| `http.test.ts` | 18 | HTTP REST API routes, CORS |
| `framework-detection.test.ts` | 27 | Path/name framework detection, multipliers |
| `augmentation.test.ts` | 28 | Augmentation engine, staleness check, MCP prompts |
| `sqlite.test.ts` | 32 | SQLite storage, migrations, FTS5 indexing |
| `find.test.ts` | 24 | Smart search — exact, wildcard, natural language |
| `rules.test.ts` | 29 | Dead code, circular deps, unused exports, orphans |
| `errors.test.ts` | 18 | Error handling, edge cases, graceful degradation |
| `migrate.test.ts` | 15 | JSON-to-SQLite migration, data integrity |

---

## Community Detection

After indexing, Recon automatically detects code communities using the **Label Propagation Algorithm (LPA)**:

- Each function/class/struct gets a `community` label based on its connections
- Communities are named after the most common package in each cluster
- `recon_explain` shows community membership
- `recon_impact` lists affected communities for cross-module awareness

---

## Live Re-Indexing

Recon watches source files and updates the knowledge graph **in real-time**:

| Feature | Detail |
|---------|--------|
| **File watcher** | chokidar v4 with 1.5s debounce, `awaitWriteFinish` for atomic writes |
| **Surgical update** | Remove old nodes → re-parse single file → insert new nodes + edges |
| **Speed** | ~50ms per file change |
| **TS files** | Full re-analysis: symbols, imports, calls, JSX components |
| **Tree-sitter files** | Full re-analysis: symbols, calls, heritage, methods (Python, Rust, Java, etc.) |
| **Edge reconstruction** | CALLS, IMPORTS, HAS_METHOD, EXTENDS, IMPLEMENTS, USES_COMPONENT |
| **Incoming callers** | Automatically re-linked after update |
| **FTS5 index** | Auto-updated in SQLite on every graph change |
| **Multi-project** | `--projects` flag watches additional directories |
| **Ignored** | `node_modules/`, `.git/`, `dist/`, `.next/`, `build/`, `coverage/` |

### Incremental Indexing

Files are hashed with SHA-256. On `recon index`, only changed files are re-analyzed:

- **TypeScript**: per-file granularity via Compiler API
- **Tree-sitter**: per-file granularity for all 13 languages
- **Auto-detection**: `serve` compares Git commit hashes to detect stale indexes
- Force full re-index with `--force`

---

## License

[MIT](LICENSE)