MCP Code Indexer

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 exists

An agent asked "what breaks if I change this?" normally reads a pile of files into context and guesses. One graph query answers it exactly, for roughly 1% of the tokens — because edges come from the TypeScript resolver, not from grep.

The numbers behind that claim, and the query-by-query breakdown, are in the package README. This file is about working on the engine; that one is about using it.

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 all-MiniLM-L6-v2 embeddings (384-dim) via @huggingface/transformers — no API key, nothing leaves the machine. It is an optional dependency: if it isn't installed, semantic_search degrades to lexical search instead of failing.

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 on every push and PR (.github/workflows/ci.yml):

install → audit (fails on high) → build → typecheck → lint → test

The audit step is explicit because npm audit silently reports nothing on a pnpm workspace — there's no package-lock.json for it to read.