Repository Intelligence Engine

A TypeScript repository indexing engine that builds a structural model of a codebase — symbols, imports/exports, and references — and answers precise navigation questions about it directly, instead of re-discovering structure by grepping every session.

The problem

AI coding agents start every session with zero structural memory of a repo. Answering "how does login work?" means an iterative grep → open → grep → open cycle, repeated from scratch each time. This engine replaces that with direct queries against a pre-built index.

Related MCP server: code-context-mcp

What it does

The engine parses a TypeScript repo with the TypeScript Compiler API and stores a structural model in SQLite. Five queries run over that index:

The engine/ functions are callable directly (CLI, tests) — the engine is the product. It also supports Claude Code and any other MCP-compatible client through an integrated MCP server.

Architecture

  Repository (.ts/.tsx)
          │
          ▼
  ┌───────────────────┐   TS Compiler API, two modes:
  │      Indexer      │   • ts.Program        → symbols + import edges (batch)
  │  src/indexer/     │   • ts.LanguageService → findReferences (separate pass)
  └───────────────────┘
          │
          ▼
  ┌───────────────────┐   symbols     (name, kind, file, line)
  │  Index (SQLite)   │   edges       (from_file → to_file, file-level)
  │  src/storage/     │   references_ (symbol → use site)
  └───────────────────┘
          │
          ▼
  ┌───────────────────┐   pure functions over the index —
  │   Query Engine    │   find_module, find_related_files,
  │  src/engine/      │   find_symbol_references, dependency_path, reindex
  └───────────────────┘
          │
          ▼
  ┌───────────────────┐   thin adapter: parse args → call engine.
  │    MCP Server     │   No query logic lives here.
  │  src/mcp-server/  │
  └───────────────────┘
          │
          ▼
  Claude Code / any MCP-compatible client

Two design decisions worth calling out:

• Edges are file-level, not symbol-level. An import statement lives at file scope — no single symbol "owns" it — and barrel re-exports, side-effect imports (import './styles'), and namespace imports have no symbol on one end at all. Storing from_file → to_file represents all of them cleanly; symbols.file_path bridges back to symbols for free, so dependency_path still answers symbol-to-symbol questions by resolving each end to its file and running a BFS over the edge table.

• The MCP server is an adapter, not the product. Everything is callable without MCP in the loop, which is what keeps the core testable — a test asserts that an MCP call and the equivalent direct engine call return identical results.

Benchmark

Measured against TypeORM @ 04ff4dae — 496 source files, 1,108 indexed symbols, 2,750 import edges. Six fixed navigation tasks with pre-registered oracle answers (verified by independent grep, not engine output), run under two arms with Claude Code in headless mode:

• baseline — built-in tools only (Read/Grep/Glob)

• assisted — same tools plus this engine's MCP server

Protocol: fresh session per run (no cross-run contamination), 5 runs per arm per task, medians reported, metrics machine-counted from session transcripts (tool_use blocks), never hand-tallied. Every run in both arms located its oracle answer.

Honest reading: the engine wins on multi-hop and structural queries (dependency paths halved; impact analysis −1 call) and ties on tasks a good grep already answers in 1–2 calls — a modern agent's baseline is strong, and single-symbol lookups have little headroom. ~30% fewer tool-calls overall.

† What the benchmark caught: the first measurement of the impact task showed the assisted arm losing (median 5 calls vs. 3, spread up to 11). Transcripts revealed an interface bug, not a data bug: the engine's path-taking tools did exact string matching, so the Windows-style backslash and repo-relative paths agents naturally pass returned empty results — and one tool answered "symbol not indexed" when only the path filter had failed. Agents did the rational thing and fell back to grep, doubling the work. After fixing path resolution (normalization + unique-suffix matching + honest "filter dropped" notes), the task flipped to a win and run-to-run variance collapsed from 3–11 calls to 2–3. The raw per-run data for both measurements is in benchmarks/results/.

Circular dependency detection

find_circular_dependencies() reports strongly connected components of the import graph (Tarjan's algorithm), each with one concrete example cycle. It reports components rather than enumerating every simple cycle, because a tangled component can contain exponentially many of those — the component is the actionable unit, the example makes it concrete.

On TypeORM it finds 2 groups in ~60 ms: a 2-file cycle (Brackets.ts ↔ WhereExpressionBuilder.ts) and one 227-file component seeded by DataSource.ts ↔ RelationLoader.ts. Both were confirmed by reading the imports directly, not taken on the engine's word.

Known limitation — type-only imports are counted. v1's edges table does not distinguish import type { X } from import { X }. TypeScript erases type-only imports at compile time, so they create no runtime cycle. Sampling the cycle-forming imports above, 3 of 4 were type-only — meaning the 227-file component substantially overstates what is a runtime circular dependency, even though every edge it reports is a real import statement in the source. Distinguishing the two (an is_type_only column, set from the AST during indexing) is the obvious next improvement and would make this tool's output directly actionable. Until then, treat the results as "files that reference each other," not "runtime cycles."

Development

npm install
npm run build           # tsc -> dist/
npm run index -- ./tsconfig.json repo-index.db   # index a repo
npm run mcp             # start the MCP server (stdio)
npm test                # vitest