mcp-code-indexer: Instructions file for Claude Code

CLAUDE.md — mcp-code-indexer

Operational map for the code-intelligence engine. Full rationale in docs/DESIGN.md; usage in README.md.

Commands (turbo, from this dir)

pnpm build      # topo build: code-graph-core → _shared → code-indexer → indexer-server/web
pnpm typecheck  # tsc --noEmit across packages
pnpm lint       # eslint, shared flat config
pnpm test       # vitest (schemas + engine) + node:test (server) + web
pnpm index --root <path>   # index any repo → <path>/.code-graph/graph.json
pnpm serve --root <path>   # HTTP+WS server :3002, serving the built UI
pnpm ui                    # Vite dev server :5182 (proxies /api + /ws → :3002)
pnpm prove                 # run the engine against a corpus of real repos

pnpm build is required before running the CLI/MCP (compiled JS) or the server (runs via tsx but imports the compiled engine). If pnpm errors with "no importer manifest," you're in the wrong cwd — use pnpm -C /abs/path/to/mcp-code-indexer.

The model (the whole vocabulary)

• Nodes: repo · app · package · folder · file · component · function. Strict Zod discriminatedUnion — each variant carries only its legal fields (a repo has no span; only component/function have span+bundleBytes). Validation rejects illegal states.
• Edges: contains · imports · references · renders · calls · depends-on.
  • imports/references (type-only) = file-level, from ts-morph module resolution.
  • renders (component→component) / calls (symbol→symbol) = symbol-level, resolved in the semantic pass through each file's import bindings + local symbols. Conservative: an edge is emitted only when the target resolves to a real indexed node (no wrong edges; library/builtin names produce nothing).
  • depends-on = package→package, read from package.json (monorepos only).

Pipeline

discoverWorkspace → indexMacro → indexStructure → buildSnapshot → (progressive) enrichStatus