Content
# mcp-code-indexer
The source monorepo for **[`code-graph-indexer`](https://www.npmjs.com/package/code-graph-indexer)** — a code-intelligence engine that turns any TypeScript / React / Next.js repo into a queryable **code graph** and serves it five ways: a **CLI**, an **MCP server** for AI agents, an **HTTP + WebSocket API**, a **3D web explorer with a built-in chatbot**, and **local semantic search**.
> **Just want to use it?** You don't need this repo. `npx code-graph-indexer ui --root .` gets you the whole thing — see the [package README](packages/code-indexer-dist/README.md). This repo is for working on the engine itself.
```
┌──────────────┐ ts-morph AST ┌───────────────┐ serve ┌───────────────────────────────────────┐
│ any TS/React │ ───────────────▶ │ code graph │ ─────────▶ │ CLI · MCP · HTTP/WS · 3D UI · semantic │
│ repo │ walk + resolve │ nodes + edges │ │ (consume from anywhere) │
└──────────────┘ └───────────────┘ └───────────────────────────────────────┘
```
Everything is built on [`ts-morph`](https://ts-morph.com), so edges are **resolved by the compiler, not grepped** — and conservative: an edge is drawn only when it resolves to a real indexed node. The indexer is **generic**; it discovers the workspace shape itself and handles monorepos (pnpm / turbo / lerna) and standalone single-package repos alike. Nothing about the target is hardcoded.
---
## Why it makes development faster, cheaper, and more reliable
Estimated cost of the same question with an agent reading files versus one graph query (typical mid-size repo):
| What you ask | Agent alone (read files) | With the code graph | You save |
| ------------------------------- | ----------------------------------- | ----------------------------- | --------------- |
| "What calls `format()`?" | ~30k tokens · ~40s | ~0.4k tokens · <1s | **~99% tokens** |
| "What breaks if I change this?" | ~50k tokens · ~60s _(misses edges)_ | ~0.6k tokens · <1s _(exact)_ | **~99% tokens** |
| "Where's the code that does X?" | ~25k tokens · ~30s | ~0.3k tokens · ~2s | **~98% tokens** |
| "Context to edit this safely" | ~40k tokens · ~50s _(5 reads)_ | ~0.8k tokens · <1s _(1 call)_ | **~98% tokens** |
| "Any dead code or cycles?" | ~60k tokens · manual audit | ~0.5k tokens · instant | **~99% tokens** |
**Faster** (in-memory lookups, not re-reads) · **cheaper** (fewer tokens = lower bill) · **reliable** (compiler-resolved edges — no hallucinated callers, no missed impact).
---
## The graph model
| Node types | Edge types |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `repo` · `app` · `package` · `folder` · `file` · `component` · `function` · `external` | `contains` · `imports` · `calls` · `renders` · `references` · `depends-on` |
Each node carries metrics (`loc`, `exportsCount`), a `status` block (type/lint/build health), and git metadata — enough to build codebase dashboards, impact analysis, and AI-agent navigation on top of.
---
## Quickstart (working on the engine)
```bash
pnpm install
pnpm build # turbo builds core → _shared → engine → server → web (topo order)
pnpm test # unit tests across the engine + schema packages
pnpm typecheck
pnpm lint
```
> Requires Node ≥ 20.19 and pnpm 10 (pinned via `packageManager`; `corepack enable` selects it). `pnpm build` is required before running the CLI or server from source.
Run the full explorer against this repo (or any path):
```bash
pnpm serve --root . # HTTP/WS server on :3002 (serves the built UI too)
pnpm ui # OR: Vite dev server on :5182 with HMR, proxying /api + /ws → :3002
```
`pnpm serve` serves the pre-built web bundle; `pnpm ui` is the hot-reloading dev server for working on the UI itself.
---
## The five surfaces
All resolve the **same engine** against a target repo root.
### 1. 3D explorer + chatbot
The [`apps/web/code-graph`](apps/web/code-graph) front-end — a [`react-force-graph-3d`](https://github.com/vasturiano/react-force-graph) viewer with folder drill-down, type/health coloring, hover tracing, blast-radius highlighting, a 2D fallback, and a chat panel grounded in the graph. It's a pure consumer of the HTTP/WS API: it loads `GET /api/graph`, then applies live `GraphPatch`es over `WS /ws` as you edit files. The published package bundles the built version so `npx code-graph-indexer ui` just works.
### 2. MCP server — 14 tools
Registers over stdio so Claude Code / Cursor can call it directly:
```bash
claude mcp add code-graph -- node "$(pwd)/tools/code-indexer/build/code-indexer/src/index.js"
```
Tools: `index_repo`, `get_graph`, `get_node`, `who_renders`, `who_calls`, `find_references`, `blast_radius`, `find_cycles`, `find_orphans`, `search_nodes`, `get_context_pack`, `build_embeddings`, `semantic_search`, and `open_explorer` (starts the 3D UI and returns its URL). Full descriptions are in the [package README](packages/code-indexer-dist/README.md#2-mcp-server--let-claude--cursor-query-your-code).
### 3. CLI
```bash
node tools/code-indexer/build/code-indexer/src/cli.js index --root /path/to/repo
node tools/code-indexer/build/code-indexer/src/cli.js query blast-radius --id "fn:src/util.ts#format" --root /path/to/repo
```
### 4. HTTP + WebSocket API
```bash
pnpm serve --root /path/to/repo
curl localhost:3002/api/graph | jq '.meta'
# { "root": "/…", "nodeCount": 908, "edgeCount": 2138, "indexerVersion": "…" }
```
Reads, reverse queries, `POST /api/reindex`, `POST /api/chat`, and `WS /ws` for live patches. Bound to `127.0.0.1` only — endpoints are unauthenticated and mutating, so never expose it off-host.
### 5. Semantic search
Local `Xenova/all-MiniLM-L6-v2` embeddings via transformers.js — no API key, nothing leaves the machine. Falls back to lexical search when the model isn't installed.
---
## Architecture
> Deeper rationale — the graph model, why ts-morph, the macro/micro split, and the honest trade-offs — is in [docs/DESIGN.md](docs/DESIGN.md).
A Turborepo of a few focused packages (plus shared config):
```
mcp-code-indexer/
├── packages/
│ ├── code-graph-core/ @repo/code-graph-core — Zod schemas: nodes, edges, snapshot, status
│ └── code-indexer-dist/ code-graph-indexer — the published npm bundle (tsup) + bundled web UI
├── tools/
│ ├── _shared/ @tools/shared — MCP server base (McpServerBase, ToolRegistry), utils
│ └── code-indexer/ code-indexer-mcp — the engine: ts-morph analysis, CLI, MCP server
└── apps/
├── indexer-server/ indexer-server — Express + ws runtime, file-watcher, REST/WS + chat
└── web/code-graph/ code-graph — the React + three.js 3D explorer
```
Dependency flow (leaves first):
```
code-graph-core ─┬─▶ code-indexer ─▶ indexer-server ─┐
_shared ──────┘ ├─▶ code-indexer-dist (the npm package)
web/code-graph ─────────────────────────────────┘
```
- **`code-graph-core`** — the contract. Zod schemas validate every node, edge, and snapshot, so the graph shape is guaranteed end-to-end. Pure and fully unit-tested.
- **`code-indexer`** — the analysis engine. `ts-morph` parsing plus workspace discovery (monorepo vs standalone), incremental snapshots to `.code-graph/`. Doubles as the MCP server.
- **`indexer-server`** — wraps the engine in Express + `ws`, indexes on boot, enriches node status in the background, watches files for live updates, and serves the chat endpoint (local `claude` CLI → API key → heuristic).
- **`web/code-graph`** — the 3D explorer, a pure API consumer.
- **`code-indexer-dist`** — bundles all of the above into the single `code-graph-indexer` npm package, web UI included.
---
## Scripts
| Command | What it does |
| -------------------------- | ---------------------------------------------------- |
| `pnpm build` | Build every package (topo order via turbo) |
| `pnpm typecheck` | `tsc --noEmit` across every package |
| `pnpm test` | Unit tests (schemas + engine) |
| `pnpm lint` | ESLint across all packages (shared flat config) |
| `pnpm serve --root <path>` | Run the server (with UI) against any repo on `:3002` |
| `pnpm ui` | Vite dev server for the explorer on `:5182` |
## Tech
TypeScript (strict) · Turborepo · pnpm workspaces · ts-morph · Zod · Express · ws · @parcel/watcher · React · three.js · Model Context Protocol SDK · transformers.js · Vitest · tsup.
## Status
`pnpm build` ✓ · `pnpm typecheck` ✓ · `pnpm lint` ✓ · `pnpm test` ✓. CI runs the same gate (`build → typecheck → lint → test`) on every push and PR (`.github/workflows/ci.yml`).
