mcp-spec-nav
Local MCP server · Open source

Give your agent
a map of your code.

The logic you need might already exist. Help your AI coding agent find it, understand it, and check what a change affects.

Get started →Explore the repo ↗
Runs locally / Claude Code + Claude Desktop / MIT
spec-nav / illustrative session
// Before writing another fee calculation…

agent → spec_nav_find_functions
{ "query": "calculate order fees" }
↳ Find existing implementations
services/billing/src/fees.ts

calculateFee(order)
Read source. Check dependencies. Decide.
agent → spec_nav_callers
{ "symbol": "calculateFee",
  "file": "services/billing/src/fees.ts" }

// Inspect callers before changing the signature.
ready ▌
ACROSS YOUR CODEBASE
TypeScriptJavaScriptPythonGoJavaKotlinSwift+ more ↗
01 / Explore before you edit

Less guessing.
More source code.

Tools to help your agent inspect the repository before committing to an implementation.

⌕

Find logic worth reusing.

Search across services by words, called functions, or similarity to a draft. Get ranked candidates with reasons for matching.

spec_nav_find_functions
{ }

Read the whole picture.

Inspect a function’s implementation, signature, documentation, and relevant imports before deciding how to use it — up to 10 functions in one call.

spec_nav_read_function
↳

Check what calls it.

Inspect callers, dynamic uses, and unresolved references before changing a function’s signature or behavior.

spec_nav_callers
Try the workflow

One task.
A clearer starting point.

EXAMPLE PROMPT → TOOL INPUT

“Before adding an order fee calculation, find existing implementations across services and read the best candidates.”

spec_nav_find_functions
{ "query": "calculate order fees", "limit": 20 }

Then read the matching functions and check service boundaries before importing. Your coding agent decides what fits.

Explore all tools in the README ↗
Watch / Same task. Same rules.

Grep + rules.
MCP + rules.

Follow one order-fee request from the user prompt to discovery, edits, tests, and delivery. Both agents follow the same rule.

spec_nav_servicesspec_nav_functionsspec_nav_find_functionsspec_nav_read_functionspec_nav_similar_functionsspec_nav_callersspec_nav_mapspec_nav_trace_flow
One request · Start to finish

Across billing, checkout, orders, invoicing and shipping: add an optional handling-fee waiver, change the central fee from 5 to 7, reuse existing total calculations instead of duplicating them, update affected callers, inspect all fee spellings, and verify ordinary and waived totals. Follow the same reuse-and-caller rules.

SHARED RULE · CLAUDE.md / RULE.md / CLIENT INSTRUCTIONSBefore writing: find existing functions, read them, and reuse when appropriate.
Before editing: inspect related code and callers, then update the affected sites.
01 / Map the services before starting
Grep + ruleAgent assembles the evidence
Discovery calls shown · scripted0
ILLUSTRATIVE COMMANDS & OUTPUT
rg --files -g 'package.json' services/ packages/ \
  && cat package.json services/*/package.json
Identify billing, checkout, orders, invoicing and shipping. Agent combines file lists and project configuration.
1 Bash call shown: list projects and read their manifests together.
spec-nav + ruleTools organize the evidence
Discovery calls shown · scripted0
ILLUSTRATIVE COMMANDS & OUTPUT
spec_nav_services
{}
Repository root + discovered projects Source coverage + file/function counts Inspect excluded or unsupported files.
1 discovery call shown: project map and coverage together.
✓ MCP ADVANTAGEStart with a map, not scattered file lists.spec_nav_services packages discovered projects, counts, and scan coverage. Both agents still check the root and boundaries before touching code.
Rules guide the process. Grep and file reads can work well when the agent chooses useful queries and follows references carefully.
MCP adds structure. Ranked candidates, function context, caller evidence, and matches grouped with their enclosing functions.

Illustrative large-task walkthrough: 11 Grep/Read discovery calls and 9 spec-nav discovery calls shown, with the Grep side chaining several searches and reads in one Bash call, as real agents do. These are scripted counts, not recorded agent measurements. Edits, tests and pagination are extra. The measured Immich benchmark averages 146.9 vs 117.7 total calls per large session; it does not prove that a whole task finishes in a few calls or that MCP tool time is faster.

02 / Connect your agent

A small config.
A better starting point.

Use Node.js 18+, npm/npx, Git, and a local checkout of the repository you want to scan.

  1. Add this config to .mcp.json in your target repository.
  2. Replace SPEC_NAV_ROOT with the absolute path to your codebase.
  3. Restart Claude Code, run /mcp, and check that spec-nav is connected.
Prefer Claude Desktop? Install the extension ↗
.mcp.json
{
  "mcpServers": {
    "spec-nav": {
      "command": "npx",
      "args": [
        "-y",
        "github:khoitd-voyager/mcp-spec-nav"
      ],
      "env": {
        "SPEC_NAV_ROOT": "/absolute/path/to/your-repo"
      }
    }
  }
}
Use your monorepo root to cover multiple services.
03 / Inspect the evidence

Benchmarks you
can read and rerun.

Compare spec-nav with a Grep/Read/Edit baseline across code reuse, caller discovery, and change surveys.

Read the methodology ↗
Live LLM sessions · 8 Grafana PRsClaude Sonnet 5.5
Generated polyglot monorepobench/run.mjs
Real repository evaluationbench/real.mjs
Large repository performancebench/perf.mjs

Live run: Claude Code (Claude Sonnet 5.5) on 8 Grafana PRs, plain vs. a spec-nav setup that is not the MCP alone: MCP + instructions + a hook that forces spec-nav calls. Both passed every hidden test; quality differences were within noise and the forced setup cost about 58% more per session. The MCP alone has not been measured yet. The other benchmarks use deterministic agent policies with estimated token counts. Read the methodology and limitations before quoting results.

Read the live LLM report ↗
Browse recorded results ↗
Measured / Recorded benchmark results

See the difference in the data.

immich@cc7fd67 · 10 large sessions · Recorded 2026-10-13

Baseline: Grep / Read / Editspec-nav + Read / Edit

Fully correct sessions

Higher is better
Baseline
0%
spec-nav
30%
0

Existing function reused

Higher is better
Baseline
40%
spec-nav
93%
0

Search-phase context tokens

Lower is better · estimate
Baseline
67,345
spec-nav
21,188
0

Final session context tokens

Lower is better · estimate
Baseline
302,494
spec-nav
226,515
0

Wrong edits per session

Lower is better · measured
Baseline
14.4
spec-nav
2.4
0

Tool calls per session

Lower is better · measured
Baseline
146.9
spec-nav
117.7
0
The tradeoff: MCP cold-start overhead.

Mean tool execution time includes a fresh MCP server per session. It excludes model thinking time; this is not end-to-end LLM latency.

Read this dataset’s full report ↗

Deterministic agent policies, not live LLMs. Values are averages per session. Tokens are estimated at 3.5 characters/token. Large sessions combine 3 feature requests. Immich is one real repository; results are not universal.

Know the limits: search remains lexical; callers are type-checked in TS/JS/Vue/Svelte/Astro and evidence-based in other supported languages. Coverage can be incomplete. A simple edit in one file may benefit little.

Find it. Read it. Check it.

Your next function
might already be there.

Give your coding agent a place to look before it starts writing.

Connect spec-nav →Feedback & issues ↗