mcp-code-indexer

The source monorepo for 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. 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, 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):

Faster (in-memory lookups, not re-reads) · cheaper (fewer tokens = lower bill) · reliable (compiler-resolved edges — no hallucinated callers, no missed impact).

Related MCP server: depwire

The graph model

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)

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):

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 front-end — a react-force-graph-3d 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 GraphPatches 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:

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.

3. CLI

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

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.

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

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