mcp-spec-nav — MCP Server for AI Code Search and Navigation

English · Tiếng Việt · 简体中文

mcp-spec-nav is a local MCP server for AI coding agents such as Claude Code. It reads the source code of the repository you choose and lets the agent:

• find existing functions across services and shared packages — by words, by what they call, or by behavioural similarity to a draft;

• read a function exactly: source, signature, documentation and the imports it uses;

• find callers before a change — type-checked in TypeScript/JavaScript/Vue, evidence-based in Python, Go, Java, Kotlin, Swift and other languages, with dynamic uses listed;

• map a pattern across supported source files, with the enclosing function of each match;

• trace flows across services from source code — HTTP client → route → handler, RPC call → handler, event/topic → consumers — with the evidence for each link and what could not be resolved (static analysis, supported frameworks).

The problem it addresses: before writing new logic or changing a function, an agent needs to know what already exists and what depends on it. With grep alone it can miss code written under other names, rewrite logic that already exists, or edit same-named calls on another class.

The MCP only reads code. Your coding agent decides what to reuse, edits the files and runs the tests. The MCP does not guarantee that every related function will be found.

When it helps

Every model turn with the MCP installed also carries its tool definitions (~3.8k tokens in the benchmark), so on small, single-concept changes the gain is small. In live runs on real tasks in a private production monorepo, the spec-nav setup (MCP + workflow instructions + a hook that blocks recursive grep) finished tasks about 28% sooner (about 32% on cross-service tasks) with about the same token use and average code quality 8.5/10. It did not reduce tool calls, and on small single-service tasks it costs more tokens. The MCP installed on its own has not been measured yet (Benchmark).

Related MCP server: codeweave-mcp

Example: change an order fee

docs/examples/order-fee is a runnable four-file example. Task: raise the handling fee from 5 to 7 and let every caller waive it. The output below comes from running the tools on before/, trimmed.

1. Find existing logic — MCP, spec_nav_find_functions with { "query": "order handling fee total" }:

#1  score 3.05  billing/fees.ts:35-43  (service ., typescript)
    [function, exported] calculateTotal
    why: handling→body  fee→path(stem:fees)  total→name

2. Read the implementation — MCP, spec_nav_read_function with { "file": "billing/fees.ts", "name": "calculateTotal" }:

35| export function calculateTotal(subtotal) {
39|   const handlingFee = HANDLING_FEE;
42|   return subtotal + handlingFee;
43| }

3. Find every caller — MCP, spec_nav_callers with { "symbol": "calculateTotal", "file": "billing/fees.ts" }:

"total": 3, "exhaustive": true,
"targets": [{ "file": "billing/fees.ts", "line": 35, "resolvedBy": "type checker" }],
"sites": [
  { "file": "billing/previewInvoice.ts", "line": 3, "enclosing": "previewInvoice", "resolution": "resolved" },
  { "file": "checkout/createOrder.ts", "line": 3, "enclosing": "createOrder", "resolution": "resolved" },
  { "file": "orders/updateOrder.ts", "line": 3, "enclosing": "updateOrder", "resolution": "resolved" }

4. Follow it across services — MCP. spec_nav_callers counts direct calls only and says so: calls through HTTP/RPC/queues are not counted. In the multi-service example docs/examples/order-flow, spec_nav_trace_flow with { "file": "services/checkout/src/handlers/createOrder.ts", "name": "createOrderHandler", "direction": "both" } shows who reaches the handler and where the total goes:

steps: 5 (5 resolved) — this page 1-5 — COMPLETE
gaps: none found among the supported adapters.
#1  d1 ↑ HTTP  POST http://checkout:3000/api/orders → POST /api/orders   [resolved · high]
    from  services/storefront/src/checkout-client.ts:3  submitOrder
#2  d1 ↓ call  createOrderHandler → calculateTotal   [resolved · high]
#4  d2 ↓ EVENT event order.created → event order.created (kafka)   [resolved · medium]
    to    services/invoicing/src/consumer.ts:12  handleOrderCreated

5. Edit the code — coding agent: sets HANDLING_FEE to 7, adds an options parameter to calculateTotal, and forwards waiveHandlingFee from the three callers. The result is in after/.

6. Run the tests — coding agent:

node --test docs/examples/order-fee/verify.mjs   # 6 tests pass

Quick start (Claude Code)

Requirements: Node.js 18+, npm/npx, Git, and a local checkout of the repository to scan. The first installation needs network access.

1. Create .mcp.json at the root of the target repository. If it already exists, add the spec-nav entry to its mcpServers and keep the other servers.

{
  "mcpServers": {
    "spec-nav": {
      "command": "npx",
      "args": ["-y", "github:khoitd-voyager/mcp-spec-nav"],
      "env": {
        "SPEC_NAV_ROOT": "/Users/you/code/your-repo"
      }
    }
  }
}

Replace /Users/you/code/your-repo with the absolute path of the code to scan (the monorepo root to cover every service) — not the installation directory of mcp-spec-nav.

2. Open Claude Code in that repository, restart the session, run /mcp and check that spec-nav is connected. Approve the configuration if your client asks.

3. Send Claude:

Use spec-nav to list the services in this repository.
Show the resolved repository root and any files it could not scan.

Check that the root and services match your project before continuing.

4. Try a real task:

I want to add a parameter to calculateFee. Use spec-nav to find its declaration,
read the implementation and check its callers before planning the change.
Report any callers you could not resolve.

Installing an MCP makes its tools available; it does not ensure the agent uses them. Add the CLAUDE.md section so Claude uses them during normal coding. More prompts, the Claude Desktop extension (no Node.js needed) and installing from a local checkout: Installation.

Tools

Arguments, JSON examples, pagination, coverage and result statuses: Tool reference.

Supported languages

TypeScript, JavaScript, Python, Go, Java, C#, Ruby, Rust, PHP, C, C++, Scala, Elixir, Bash, Kotlin, Swift, and Vue/Svelte/Astro components (script blocks). Callers are type-checked in TS/JS/Vue/Svelte/Astro and evidence-based in every other supported language. Cross-service flows are traced for TypeScript/JavaScript and Python frameworks only. Extensions and parsing details: Supported languages.

Benchmark

Live LLM run on a private production monorepo

Claude Code on real feature and bug-fix requests in a private TypeScript monorepo (4 backend services that call each other over HTTP, a storefront and an admin app), running a 4-step spec workflow (/discuss → /resolve-solution → /create → /ship) with and without the spec-nav setup. Claude Sonnet 5.5 and Claude Opus 5.5, the same model for both setups on each task; recorded 2026-10-16 to 2026-10-18.

The spec-nav setup is the MCP plus workflow instructions plus a hook that blocks recursive grep over source code and points to spec_nav_map. There is no edit gate: the agent is never forced to call a tool before editing. The hooks are in docs/examples/hooks/; see Hooks.

The setup did not reduce tool calls: the agent usually made more calls, grouped into fewer model turns. Time is what changes. On the smaller tasks the gain is about 8% in time for about 37% more tokens. One run per task, an LLM grader that is not blind; read the report before quoting these numbers.

Simulated agents

All results below come from simulated agents: deterministic policies, not an LLM, so the differences come from the tools. One agent has only Grep/Read/Edit (like Claude Code's built-in tools), the other has spec-nav plus Read/Edit. The no-MCP side is given an LLM's synonym knowledge and the same generous scoring. Each session is a whole feature request: reuse existing logic, change a function's signature and update every caller, change a constant everywhere, then read and edit every file. Repositories: a seeded synthetic monorepo (answers planted by the generator) and immich@cc7fd67 (answers from TypeScript findReferences, doc comments and ripgrep). Tokens are estimated at 3.5 characters/token.

Reading what you will edit costs the same either way; the saving is in the search phase. Quality gains come from finding code under other names (reuse) and from not editing same-named calls on other classes (callers).

Large repository — VS Code (14,306 files, ~4.5M lines, 154k catalogued functions), Apple M4: first index 31 s, then find_functions 2.6–4.3 s, map 0.5–1.8 s, similar_functions 0.9 s, read_function 0.15 s; callers 10 s for an ordinary function (isEqualOrParent), 26 s and 3.1 GB RAM for FileService.readFile, a name mentioned in hundreds of files (12 s when asked again; 0.7.0 on the same machine: 42 s, then 78 s, 3.6 GB). Server memory 0.7–0.9 GB outside callers.

Cross-service flows (no agent, no LLM) — spec_nav_trace_flow on generated repositories (14 services each, 5 held-out seeds, 598 labelled call sites): 100% precision with 0 wrong links (linking by name only: 136 wrong links), 100% recall (84% in 0.7.0, which did not follow calls made through a wrapper function or urljoin). First call ~0.1 s (0.7 s on a 1,000-file repository), then 1–10 ms per call. The generator and the adapters share an author, so this checks the linking rules, not coverage of real code.

Method, assumptions and limitations: bench/README.md. Reports: live · synthetic · immich · VS Code timings · flows · all results.

Limits

• Search is lexical. Words, called names, abbreviations, synonym and concept lists, IDF. spec_nav_similar_functions finds same-behaviour code under unrelated names only when it shares calls or vocabulary; two implementations with nothing in common are missed. Results are candidates, not proof that nothing else exists.

• Translation. Vietnamese written with diacritics is matched through a built-in dictionary of ~100 common domain terms; other words are not translated. Use English keywords for English-named code.

• Reuse. Check exports, behavior and package/service dependencies yourself.

• Callers. Outside TS/JS, binding is by evidence (imports, qualifiers, declared receiver types), not a type checker: inferred types, inheritance and overloads can leave sites likely/ambiguous. Names built at runtime, HTTP/RPC/queue calls and external repositories are not traced by spec_nav_callers (for HTTP/RPC/events between services, see spec_nav_trace_flow).

• Flows. Static, from source: links are inferred, never observed, and only for the supported frameworks. Not traced: gRPC, GraphQL, WebSockets, other queues (BullMQ, RabbitMQ, SQS…), Go, Java and other languages, generated API clients, wrappers more than three tiers deep, service discovery and configuration other than docker-compose, and more — see Not traced.

• Function forms. Inline anonymous callbacks are not individually catalogued (JS/TS counts them in coverage). JS/TS destructuring assignments, dynamic property assignments, factory-created functions, Object.assign/Object.defineProperty and some chained assignments are not fully covered. Other-language assigned lambdas/closures are not catalogued.

• Files. Dart, Lua, Objective-C, SQL and other unsupported source types are not parsed (they are counted in coverage). Dependency/build directories, hidden directories, virtualenvs, declaration files, minified JS and supported files over 1.5 MB are excluded.

• Types. Return types are reported when explicitly written; they are not inferred by the catalog.

• Large repos. Measured on VS Code (14k files): first index ~31 s, searches seconds. TS/JS callers type-check only files that mention the name — and, when many do, only those with an import path to a declaration — in batches, following imports two steps; a very common name takes tens of seconds and ~3 GB, and calls whose receiver type lies further away are reported unresolved.

• Dependencies. TS/JS type resolution is best with dependencies installed (node_modules); without them, library types are unknown and more calls end up unresolved.

The server reads the current local checkout. No search API key is required, and its search does not send code to an external search service. Results are returned to your connected coding agent; that client's model/data handling settings still apply.

Documentation

• Installation — Claude Code, Claude Desktop extension, CLAUDE.md section, local checkout

• Hooks — two example Claude Code hooks (block recursive grep, batch code reads) and how to write your own

• Tool reference — arguments, JSON examples, reading the results

• Trace flows across services — frameworks, link statuses, confidence, gaps

• Supported languages

• Troubleshooting

• Development — tests, packaging the extension, benchmarks, website

• Benchmark method · Website

License

MIT. See LICENSE.