What can you do with this server?

mcp-spec-nav is a local, read-only MCP server that indexes the source code of a chosen repository so an AI coding agent can search, read, and trace code across services. * Survey the repo (spec_nav_services): list discovered projects/services under SPEC_NAV_ROOT with file and function counts and a coverage summary. * Find existing logic (spec_nav_find_functions): ranked candidates by describing behaviour in words, matched against names, signatures, docs, paths, calls and bodies (lexical, cross-service). * Find behavioural duplicates (spec_nav_similar_functions): locate functions that behave like a candidate, a draft (code), or an existing function, whatever they are named. * Browse the catalog (spec_nav_functions): list functions/methods/constructors/accessors with signatures, kinds, line ranges, exports, docs and stable ids — filtered and paged. * Read code precisely (spec_nav_read_function): get exact source, signature, docs and used imports for up to 10 functions per call, without reading whole files. * Find callers (spec_nav_callers): list call sites, dynamic uses and unresolved usages before changing a signature — type-checked in TS/JS/Vue/Svelte/Astro, evidence-based elsewhere. * Map a pattern (spec_nav_map): run one regex across every supported source file, each hit tagged with its enclosing function (paged, with hit counts). * Trace cross-service flows (spec_nav_trace_flow): follow HTTP client → route → handler, RPC call → handler, and event/topic → consumers, upstream or downstream, with evidence, confidence and unresolved gaps. It only reads code: the agent decides what to reuse and makes the edits. Search is lexical, and results are candidates rather than proof of completeness.

mcp-spec-nav

by khoitd-voyager

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Parses Astro component script blocks for the function catalog, ranked function search and exact function reading, with callers resolved through the type checker, and reports any files it could not scan.

Evidence-based navigation of C and C++ sources: function search, exact function reading and call-site listing resolved by same file/class, qualifier, include or alias evidence, with ambiguous, likely and dynamic usages reported apart.

Evidence-based navigation of Elixir code: finds existing functions by name or behaviour, reads their definitions with doc comments and imports, and reports call sites with the evidence used to bind them plus dynamic uses such as event names.

Analyzes JavaScript code with the same type-checked caller resolution and function catalog as TypeScript, covering named functions, arrow/function expressions assigned to variables or properties and CommonJS exports, plus ranked function search and pattern mapping with the enclosing function of each match.

Evidence-based code navigation for Kotlin: locates existing functions by words, calls or behavioural similarity, reads their exact source and documentation, and enumerates call sites with evidence-based binding and dynamic uses flagged separately.

Evidence-based navigation of PHP source: function/method search, exact function reading, caller inspection with per-site binding reasons, and regex mapping of a concept across files tagged with the enclosing function.

Evidence-based navigation of Python code: ranks existing functions and classes by name, path, docstring, calls and body, reads a function's exact source and imports, and lists call sites bound by evidence (same file/class, qualifier, import, alias, receiver type) with dynamic uses such as getattr or event names reported separately. Also traces FastAPI/Flask routes, requests/httpx/aiohttp calls and event consumers across services.

Evidence-based navigation of Ruby code: finds and reads functions and methods, resolves call sites using same file/class, qualifier, import or alias evidence with a stated reason per site, and lists unresolved, likely and ambiguous usages as well as dynamic uses like send(:x) before changing a method.

Evidence-based code navigation for Rust: searches the function catalog by words or behaviour, reads exact function source with signatures and doc comments, and reports call sites with the binding evidence used and any dynamic or unresolved usages.

Evidence-based navigation of Scala source: function search across services, exact function reading, call-site listing with per-site binding evidence, and pattern mapping that attributes each match to its enclosing function.

Parses Svelte components (script blocks and templates) and resolves callers with the TypeScript type checker, so calls through aliases, re-exports or default imports are found while same-named methods on other classes are excluded; flow tracing also covers SvelteKit file routes.

Evidence-based navigation of Swift code: ranked candidate search for existing logic, exact function reading, and caller/usage inspection with binding evidence and unresolved references reported before a signature change.

Provides type-checked static analysis of TypeScript source code: ranked search for existing functions by words, calls or behaviour, exact function reading (signature, doc comment, imports, source), exhaustive caller lookup resolved with the TypeScript type checker (finds aliases, re-exports, default imports, obj"name", call/apply; excludes same-named methods on other classes), regex mapping to enclosing functions, and cross-service flow tracing over HTTP routes, RPC calls and events.

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

Scenario	Value of the MCP
Logic is spread across multiple services	High: searches broadly and helps reduce missed code.
You want to reuse functions instead of rewriting them	High, when the query finds the right candidates.
You change function parameters and need to find callers	Useful.
You follow a request or event from one service to another	Useful for the supported frameworks: static links with evidence; unknowns are reported, not guessed.
You make a simple edit within one file	Limited benefit; may add tool calls.

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

Tool	Use it when you want to…
`spec_nav_services`	Check the scan root, discovered projects, counts and coverage.
`spec_nav_find_functions`	Find ranked candidates for existing logic across services.
`spec_nav_similar_functions`	Find functions that behave like a candidate or a draft, whatever they are named.
`spec_nav_read_function`	Read one candidate's exact source and context.
`spec_nav_functions`	Browse the function catalog with filters and pagination.
`spec_nav_callers`	Inspect calls, references, dynamic uses and unresolved usages before a change.
`spec_nav_map`	Find regex matches with the enclosing function.
`spec_nav_trace_flow`	Follow HTTP, RPC and event links between services, upstream or downstream, with evidence and what is unresolved.

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.

With the spec-nav setup	All tasks	Larger, cross-service tasks
Time per task	−28% (13.7 → 9.9 min)	−32%
Tokens	+5% (about the same)	+2%
Average code quality (answer key, 1–10)	8.5	8.6
Tasks finished sooner	83%	100%

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.

	Synthetic, 100 sessions	Synthetic, 50 large sessions	immich (real), 20 sessions	immich (real), 10 large sessions
Context per session, no MCP → MCP	31k → 24k (−25%)	92k → 71k (−24%)	116k → 98k (−16%)	302k → 227k (−25%)
…of which search phase	−57%	−55%	−70%	−69%
Input tokens with prompt caching	−18%	−26%	−16%	−38%
Tool calls (model turns)	−10%	−9%	−2%	−20%
Existing function reused	97% → 99%	90% → 95%	55% → 90%	40% → 93%
Callers complete, nothing extra	100% → 100%	100% → 100%	85% → 90%	53% → 73%
Wrong edits per session	0 → 0	0 → 0	0.3 → 0.2	14.4 → 2.4
Session fully correct	97% → 99%	70% → 86%	50% → 85%	0% → 30%
Tool time incl. MCP cold start	+4.1 s	+6.1 s	+3.2 s	+6.6 s

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.

Available Tools

8 tools

spec_nav_callersA

Call sites of a function or method across the repo, before changing its signature or behaviour. Narrow with "Class.method", className or file. TS/JS (and Vue/Svelte/Astro) are resolved with the type checker, so same-named methods on other classes are excluded; other languages are bound by evidence and each site's reason says which. likely, ambiguous, unresolved and dynamic sites are listed apart and are not confirmed callers. exhaustive is true only when type-checked targets have nothing left open; names computed at runtime, HTTP/RPC/queue calls and code outside the repo are never counted. Paged: partial names what is not shown yet.

ParametersJSON Schema

Name	Required	Description
`file`	No	File declaring the function, relative to the root (narrows the target).
`limit`	No	Sites per page (default 100).
`cursor`	No	The nextCursor from the previous page. Repeat the other arguments unchanged.
`format`	No	"text" (default, compact) or "json" (structured).
`symbol`	Yes	Function or method name, e.g. "recordHistory" or "OrderService.recordHistory"
`service`	No	Where the function is declared (narrows which declaration is meant). Call sites are searched repo-wide.
`className`	No	Class (or object/namespace) declaring the method.
`searchServices`	No	Services/directories relative to the root (e.g. "services/api"); "." is the root project's own files. Default: the whole repo.

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations the description carries the full burden and does so richly: type-checker resolution for TS/JS/Vue/Svelte/Astro, evidence-based binding elsewhere, the separation of likely/ambiguous/unresolved/dynamic from confirmed callers, the meaning of `exhaustive`, explicit exclusions (runtime-computed names, HTTP/RPC/queue calls, out-of-repo code), and pagination via `partial`.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and every sentence carries information, but it is a dense unbroken paragraph; light structuring would improve scannability without losing content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description explains the returned categories (likely/ambiguous/unresolved/dynamic), the `reason` field, and the `exhaustive`/`partial` flags. For a tool of this complexity, an agent has what it needs to interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds combined meaning — how symbol/className/file/service/searchServices narrow the target, the 'Class.method' syntax, and the paging contract. It clarifies interplay the per-parameter schema text leaves implicit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource — 'Call sites of a function or method across the repo' — and immediately frames the intent ('before changing its signature or behaviour'). This is clearly distinguishable from definition-oriented siblings like spec_nav_find_functions or spec_nav_read_function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear use context ('before changing its signature or behaviour') and narrowing guidance ('Narrow with Class.method, className or file'). It does not explicitly name an alternative sibling or state when-not to use it, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_nav_find_functionsA

Before writing new logic: find existing functions by describing the behaviour in words ("calculate order fee"). Lexical ranking over name, aliases, class, signature, doc comment, path, called names and body, with stem, abbreviation and synonym matching; each candidate says why it matched, and matches only via calls or body rank lower. Not semantic: if nothing fits, use spec_nav_similar_functions. Returns ids for spec_nav_read_function. Paged by limit/cursor.

ParametersJSON Schema

Name	Required	Description
`file`	No	Only files whose path contains this, matches it as a * glob, or as a regex (/…/, or a value with \| ( ^ $ \, e.g. "services/(order\|payment)").
`limit`	No	Candidates per page (default 20, max 100).
`query`	No	What the function does, in words. E.g. "calculate order fees"
`cursor`	No	The nextCursor from the previous page. Repeat the other arguments unchanged.
`format`	No	"text" (default, compact) or "json" (structured).
`queries`	No	Up to 5 phrasings (synonyms, another language), ranked together in one call; each result says which matched.
`language`	No	e.g. "typescript", "javascript", "python", "go"
`services`	No	Services/directories relative to the root (e.g. "services/api"); "." is the root project's own files. Default: the whole repo.
`searchBodies`	No	Also match words in function bodies (default true; weighted low; body-only matches need every word). false drops body-only matches.

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and mostly does: it discloses the matched fields, stemming/abbreviation/synonym handling, that each candidate explains its match, and that call-only or body-only matches rank lower. It does not state the read-only nature explicitly or describe output shape beyond 'ids', but the behavioural disclosure is well above average.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The most important sentence, the pre-writing trigger, is front-loaded, and the whole thing fits in a dense paragraph with no filler. It is semicolon-heavy and slightly crowded, but each clause carries distinct information rather than restating the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter search tool with full schema coverage and no output schema, the description covers the two things the schema cannot: the ranking model and the handoff to spec_nav_similar_functions / spec_nav_read_function. It omits any description of the returned candidate fields and how 'text' vs 'json' output differ, which keeps it short of a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so limit/cursor/file/queries/format are all already documented; the description mostly repeats paging ('Paged by limit/cursor') and adds no syntax or format detail beyond the schema. The one value-add is the ranking note that body-only matches need every word, which is already stated in the searchBodies field description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('find existing functions') plus the unusual input mode ('describing the behaviour in words'), which is enough to separate it from spec_nav_functions and the sibling tools. It also names the lexical ranking surface it searches, so the agent knows exactly what this tool does rather than having to infer it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Opens with an explicit trigger ('Before writing new logic') and gives an explicit when-not plus alternative ('Not semantic: if nothing fits, use spec_nav_similar_functions'). It also routes the follow-up step ('Returns ids for spec_nav_read_function'), so the agent knows both when to enter and what to do next.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_nav_functionsA

Function catalog of a file, directory or service without bodies: qualified name, kind, signature, line range, export status, doc summary and id. Filter by services, file, name, kind, language. Paged; a coverage line names the files not read (syntax errors, unsupported languages, skipped), and the catalog is complete only when it says so. Inline anonymous callbacks are counted, not listed.

ParametersJSON Schema

Name	Required	Description
`file`	No	Only files whose path contains this, matches it as a * glob, or as a regex (/…/, or a value with \| ( ^ $ \, e.g. "services/(order\|payment)").
`kind`	No	e.g. "method", "function", "constructor", "arrow"
`name`	No	Case-insensitive substring of the qualified name, or /regex/.
`limit`	No	Functions per page (default 200, max 1000).
`cursor`	No	The nextCursor from the previous page. Repeat the other arguments unchanged.
`format`	No	"text" (default, compact) or "json" (structured).
`language`	No
`services`	No	Services/directories relative to the root (e.g. "services/api"); "." is the root project's own files. Default: the whole repo.
`exportedOnly`	No	Only functions known to be exported/public.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden, and it delivers real behavioral context beyond the schema: a coverage line names files not read (syntax errors, unsupported languages, skipped), completeness is only guaranteed when stated, and inline anonymous callbacks are counted rather than listed. Pagination is also disclosed. It stops short of describing error behavior or result ordering.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the purpose and returned fields come first, then filters, then paging and completeness caveats. Every clause carries information, though the telegraphic style takes some unpacking.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, zero-required read tool with no output schema, the description covers what is returned, how filtering works, the pagination contract, and the important caveat that results may be incomplete. What remains missing is guidance on choosing this tool over its siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high (89%) and the schema already documents glob/regex semantics, defaults, and the cursor contract. The description's filter list (services, file, name, kind, language) largely restates schema fields without adding syntax or edge-case meaning beyond what is already present.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: a function catalog for a file/directory/service, explicitly enumerated return fields (qualified name, kind, signature, line range, export status, doc summary, id). The 'without bodies' qualifier implicitly separates it from spec_nav_read_function, but it does not explicitly contrast with spec_nav_find_functions, so sibling differentiation is only partial.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives filter dimensions and notes paging, which implies a list/enumerate use case, but it never states when to prefer this over spec_nav_find_functions or spec_nav_map, nor any exclusion conditions. Usage is inferable but not guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_nav_mapA

Regex search across every project under the root (code, then config/docs/SQL), each code hit tagged with the function it sits in. When the service or file is known, narrow with services/file. Paged, never silently cut: the header says COMPLETE or gives a cursor. Default view: every matching line; view: "summary" groups them by function and says it does not show every line. Long lines end with ….

ParametersJSON Schema

Name	Required	Description
`file`	No	Only files whose path contains this, matches it as a * glob, or as a regex (/…/, or a value with \| ( ^ $ \, e.g. "services/(order\|payment)").
`view`	No	"detail" (default): every matching line. "summary": hits grouped by function, with counts and line numbers; a short result is shown in full.
`cursor`	No	The nextCursor from the previous page. Repeat the other arguments unchanged.
`context`	No	Lines shown before and after each hit, like grep -C (default 0; above 10 is read as 10).
`pattern`	Yes	Regex, case-insensitive. E.g. "handl(e\|ing)_?fee\|handling_charge"
`pageSize`	No	Max hits per page (summary: max functions); pages are also cut at ~30k characters.
`services`	No	Services/directories relative to the root (e.g. "services/api"); "." is the root project's own files. Default: the whole repo.
`includeText`	No	Also search config, docs and other text files (default true).
`includeComments`	No	Include comment and import lines (skipped by default as noise)

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses pagination semantics ('Paged, never silently cut: the header says COMPLETE or gives a cursor'), default vs summary view behavior, and truncation ('Long lines end with …'). It omits permissions, error behavior, and rate limits, but covers the operationally important traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose before behavioral notes, and every sentence carries information (search order, narrowing, pagination, view modes, truncation). It is somewhat run-on with several clauses packed into one paragraph but wastes little.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-param search tool with no output schema and no annotations, the description covers pagination, result header semantics, view modes, and truncation. Missing permissions and error-handling context, but the operational essentials an agent needs to invoke it are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 9 parameters in detail. The description adds only light meaning (summary grouping, narrowing with services/file, view caveat), largely echoing the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Regex search across every project under the root,' with the search order (code, then config/docs/SQL) and the tagging behavior (each code hit tagged with its enclosing function). This clearly distinguishes it from function-level siblings like spec_nav_read_function and spec_nav_callers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete usage context: 'When the service or file is known, narrow with services/file.' This tells the agent how to scope a search, but names no alternative tool or when-not condition (e.g., when to prefer a function-level tool instead). Clear context, no exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_nav_read_functionA

Read functions in full (signature, doc comment, imports used, source with line numbers), up to 10 per call with functions. For code you will not edit; to edit a file, Read it (Edit requires that). Identify by id, or file+name (+line). For a long function or lines outside any function, pass lines to get only ±around lines. Long functions come in parts with a cursor; nothing is cut silently. Answers STALE if the code changed since the id was issued. Does not say whether another service may import it.

ParametersJSON Schema

Name	Required	Description
`id`	No
`file`	No	Path relative to the repo root.
`line`	No	A line inside the function, to disambiguate.
`name`	No	Qualified ("OrderService.calculateFee"), short, or exported name.
`lines`	No	Read only ±`around` lines around these file lines. With `file` alone: windows anywhere in the file.
`around`	No	Lines either side of each of `lines` (default 15, max 60).
`cursor`	No	nextCursor from the previous part; refuses if the function changed.
`format`	No	"text" (default, compact) or "json" (structured).
`fromLine`	No	Continue a long function from this file line.
`maxLines`	No	Lines per part (default 400).
`functions`	No	Up to 10 functions, each by `id` or `file`+`name` (+`line`), or only windows with `lines`. Instead of the single-function fields.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does well: it discloses the 10-per-call limit, cursor-based pagination for long functions, that nothing is cut silently, staleness behavior for issued ids, and cursor refusal on changed functions. It omits permission/error-shape details, and the closing note about not reporting cross-service imports is a useful but narrow caveat.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and front-loaded, with the core purpose and return shape first, then usage routing, then pagination and limits. Nearly every clause carries information, though the parenthetical-heavy style and the trailing import caveat make it slightly heavier than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, zero-annotation tool with no output schema, the description covers the modes of use, batching, pagination, truncation, and staleness. What remains thin is the distinction from non-sibling tools and any note on permissions, but nothing essential to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 91% so the baseline is 3, but the description adds relational meaning the schema does not: the id-vs-file+name(+line) identification alternatives, the windowed lines/cursor workflow for long functions, and the batch functions array replacing the single-function fields. That is genuine semantics beyond the per-property descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (read functions in full) and enumerates exactly what is returned: signature, doc comment, imports used, source with line numbers. This clearly distinguishes it from the discovery-oriented siblings like spec_nav_find_functions and spec_nav_functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames when to use it (code you will not edit) and when not (to edit a file, use Read, since Edit requires it), naming the alternative tool. It also states the acceptable identification modes (id, or file+name+line), so the agent knows how to select and route.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_nav_servicesA

The projects under the root as services values, with file and function counts and a coverage summary. Use when unsure of service names or whether SPEC_NAV_ROOT is right; not needed otherwise.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full transparency burden. It does disclose the shape of the response (services values, file/function counts, coverage summary), which is valuable given there is no output schema, but it never states that the call is read-only, whether it hits the filesystem/network, or any cost/latency characteristic.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, and the return content is front-loaded before the usage note. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read tool with no output schema, the description supplies both the return contents and a routing rule, which is enough for an agent to call it correctly. The only gap is the absence of any safety/read-only statement, which matters because annotations are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the schema baseline of 4 applies. No parameter information is needed or expected in the description, and the description correctly says nothing about arguments.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete resource and payload: the projects under the root exposed as `services` values, plus file/function counts and a coverage summary. It is clearly a discovery/listing tool, though it never names the sibling tool it complements (e.g. spec_nav_map), so differentiation is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit when-to-use ('unsure of service names or whether SPEC_NAV_ROOT is right') and an explicit when-not ('not needed otherwise'), which is stronger than most siblings. It stops short of naming the alternative tool to use once the names are known, so it is not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_nav_similar_functionsA

Find functions that behave like a given one, whatever they are named, by comparing the calls they make and their body vocabulary. Subject: id, file+name, or code (a draft). Use on a draft before adding code, on a candidate to find siblings, or before changing logic that may be copied elsewhere. Ranked candidates list the calls and words they share. Similar is not interchangeable: read both.

ParametersJSON Schema

Name	Required	Description
`id`	No	Function id from another spec_nav tool.
`code`	No	Source of a draft or external function to compare instead.
`file`	No	File of the subject function, relative to the root.
`line`	No	A line inside the subject, to disambiguate.
`name`	No	Name of the subject function in `file`.
`limit`	No	Candidates per page (default 10, max 100).
`cursor`	No	The nextCursor from the previous page. Repeat the other arguments unchanged.
`format`	No	"text" (default, compact) or "json" (structured).
`inFile`	No	Only candidates in files whose path contains this (or matches it, with * globs).
`language`	No
`minScore`	No	Lowest similarity listed (default 0.2).
`services`	No	Services/directories relative to the root (e.g. "services/api"); "." is the root project's own files. Default: the whole repo.

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses the comparison mechanism, the ranked-candidate output shape (with shared calls/words), and an important caveat ('Similar is not interchangeable: read both'), which warns against treating results as drop-in replacements. It does not state read-only status or pagination behavior, though cursor/limit in the schema imply paging.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then subject forms, then usage, then output, then caveat. Every sentence carries information with no filler; the caveat sentence in particular earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter, no-annotation, no-output-schema tool, the description covers mechanism, subject selection, usage context, output shape, and a caution. The remaining filtered parameters (services, inFile, minScore, format) are well documented by the schema itself, so little is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 92%, so the baseline is 3, but the description adds genuine value by clarifying the three alternative subject forms (id, file+name, or code for a draft) that the schema lists only as separate undifferentiated properties. It also hints at output content ('ranked candidates list the calls and words they share').

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (find), resource (functions), and the distinctive mechanism (comparing calls made and body vocabulary) plus the key differentiator 'whatever they are named'. An agent can immediately distinguish this semantic-similarity search from siblings like spec_nav_find_functions (name search) and spec_nav_callers (reverse call lookup).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives three concrete use scenarios: on a draft before adding code, on a candidate to find siblings, and before changing logic that may be copied elsewhere. The contrast with name-based search is implied by 'whatever they are named', but no sibling tool is named explicitly and there is no 'when not to use' exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_nav_trace_flowA

Trace a flow across services, statically from source: HTTP client → route → handler, RPC call → handler, event/topic → consumers, plus direct calls inside each service. Use when a change touches an endpoint, RPC call or event. Start from a function (id or file+name), an endpoint or a topic; no start lists every link found. Each step has evidence, a confidence and a status (resolved, partial, ambiguous, unresolved, unmatched); partial, ambiguous and unresolved links are leads to check, and stacks without an adapter are reported as not traced.

ParametersJSON Schema

Name	Required	Description
`id`	No	Start function id.
`file`	No	Start function's file (with `name`).
`line`	No
`name`	No
`limit`	No	Steps per page (default 30).
`topic`	No	Event, topic or RPC pattern: "order.created", "{ cmd: 'sum' }".
`cursor`	No	The nextCursor from the previous page. Repeat the other arguments unchanged.
`format`	No	"text" (default, compact) or "json" (structured).
`endpoint`	No	"GET /api/orders/:id" or "/orders/42".
`maxDepth`	No	Default 6, max 20.
`direction`	No	Default downstream.
`followCalls`	No	Follow direct calls inside a service (default true).
`includePartial`	No	Follow partial links (default true).

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses per-step evidence, confidence, the five status values, that partial/ambiguous/unresolved links are leads rather than facts, and that stacks lacking an adapter are reported as not traced. That is genuine behavioral disclosure of result semantics and limitations, not a restatement of the name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what is traced and when to use it, then start points, then result semantics. The parenthetical status list is compact and every clause carries information; nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter, no-output-schema tool the description supplies what an agent needs to choose it and pick a start point, and it partially characterizes the return shape (steps, evidence, confidence, status). Minor gaps remain on pagination/limit behavior and how unmatched versus unresolved links differ in practice.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 85%, so baseline is 3; the description adds real value above that by explaining the start-point combinations (id, file+name, endpoint, topic) and the important default behavior that omitting a start lists every link found. It also reinforces direction/depth defaults, though those are already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

A concrete verb ('trace a flow across services, statically from source') plus an explicit enumeration of the link types it walks: HTTP client→route→handler, RPC→handler, topic→consumers, and intra-service calls. The static-analysis constraint is spelled out. It does not, however, name or differentiate itself from sibling tools like spec_nav_callers or spec_nav_map, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use when a change touches an endpoint, RPC call or event' gives a clear triggering condition, and the sentence about valid start points states the entry contexts. There is no explicit when-not guidance or named alternative (e.g. 'for pure caller chains use spec_nav_callers'), so it is clear context without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.8.0Oct 19, 2026

Changedspec_nav_callers1 field changed

changedInput schema / properties / searchServices / description

Previous value: -"Limit to these services/directories, relative to SPEC_NAV_ROOT (e.g. \"services/api\", \"packages\"). \".\" is the root project's own files. Omit to cover the whole repo — the default."New value: +"Services/directories relative to the root (e.g. \"services/api\"); \".\" is the root project's own files. Default: the whole repo."

Changedspec_nav_find_functions4 fields changed

changedInput schema / properties / file / description

Previous value: -"Only files whose path contains this (or matches it, with * globs)."New value: +"Only files whose path contains this, matches it as a * glob, or as a regex (/…/, or a value with | ( ^ $ \\, e.g. \"services/(order|payment)\")."

addedInput schema / properties / queries

Added value: +{
+  "description": "Up to 5 phrasings (synonyms, another language), ranked together in one call; each result says which matched.",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 5,
+  "type": "array"
+}

changedInput schema / properties / services / description

Previous value: -"Limit to these services/directories, relative to SPEC_NAV_ROOT (e.g. \"services/api\", \"packages\"). \".\" is the root project's own files. Omit to cover the whole repo — the default."New value: +"Services/directories relative to the root (e.g. \"services/api\"); \".\" is the root project's own files. Default: the whole repo."

removedInput schema / required
```
Removed value: -[
-  "query"
-]
```

Changedspec_nav_functions2 fields changed

changedInput schema / properties / file / description

Previous value: -"Only files whose path contains this (or matches it, with * globs)."New value: +"Only files whose path contains this, matches it as a * glob, or as a regex (/…/, or a value with | ( ^ $ \\, e.g. \"services/(order|payment)\")."

changedInput schema / properties / services / description

Previous value: -"Limit to these services/directories, relative to SPEC_NAV_ROOT (e.g. \"services/api\", \"packages\"). \".\" is the root project's own files. Omit to cover the whole repo — the default."New value: +"Services/directories relative to the root (e.g. \"services/api\"); \".\" is the root project's own files. Default: the whole repo."

Changedspec_nav_map6 fields changed

addedInput schema / properties / context

Added value: +{
+  "description": "Lines shown before and after each hit, like grep -C (default 0; above 10 is read as 10).",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / file

Added value: +{
+  "description": "Only files whose path contains this, matches it as a * glob, or as a regex (/…/, or a value with | ( ^ $ \\, e.g. \"services/(order|payment)\").",
+  "type": "string"
+}

addedInput schema / properties / includeText

Added value: +{
+  "description": "Also search config, docs and other text files (default true).",
+  "type": "boolean"
+}

changedInput schema / properties / pageSize / description

Previous value: -"Max hits per page (pages are also cut at ~30k characters)."New value: +"Max hits per page (summary: max functions); pages are also cut at ~30k characters."

changedInput schema / properties / services / description

Previous value: -"Limit to these services/directories, relative to SPEC_NAV_ROOT (e.g. \"services/api\", \"packages\"). \".\" is the root project's own files. Omit to cover the whole repo — the default."New value: +"Services/directories relative to the root (e.g. \"services/api\"); \".\" is the root project's own files. Default: the whole repo."

addedInput schema / properties / view

Added value: +{
+  "description": "\"detail\" (default): every matching line. \"summary\": hits grouped by function, with counts and line numbers; a short result is shown in full.",
+  "enum": [
+    "detail",
+    "summary"
+  ],
+  "type": "string"
+}

Changedspec_nav_read_function6 fields changed

addedInput schema / properties / around

Added value: +{
+  "description": "Lines either side of each of `lines` (default 15, max 60).",
+  "minimum": 0,
+  "type": "integer"
+}

changedInput schema / properties / cursor / description

Previous value: -"nextCursor from the previous part: continues there even if the function moved; refuses if it changed."New value: +"nextCursor from the previous part; refuses if the function changed."

changedInput schema / properties / functions / description

Previous value: -"Read up to 10 functions at once, each by `id` or `file`+`name` (+ `line`). Use instead of the single-function fields below."New value: +"Up to 10 functions, each by `id` or `file`+`name` (+`line`), or only windows with `lines`. Instead of the single-function fields."

addedInput schema / properties / functions / items / properties / around
```
Added value: +{
+  "minimum": 0,
+  "type": "integer"
+}
```

addedInput schema / properties / functions / items / properties / lines

Added value: +{
+  "items": {
+    "exclusiveMinimum": 0,
+    "type": "integer"
+  },
+  "maxItems": 40,
+  "type": "array"
+}

addedInput schema / properties / lines

Added value: +{
+  "description": "Read only ±`around` lines around these file lines. With `file` alone: windows anywhere in the file.",
+  "items": {
+    "exclusiveMinimum": 0,
+    "type": "integer"
+  },
+  "maxItems": 40,
+  "type": "array"
+}

Changedspec_nav_similar_functions1 field changed

changedInput schema / properties / services / description

Previous value: -"Limit to these services/directories, relative to SPEC_NAV_ROOT (e.g. \"services/api\", \"packages\"). \".\" is the root project's own files. Omit to cover the whole repo — the default."New value: +"Services/directories relative to the root (e.g. \"services/api\"); \".\" is the root project's own files. Default: the whole repo."

1 tool updatev0.7.0Oct 16, 2026

Changedspec_nav_read_function7 fields changed

changedInput schema / properties / cursor / description

Previous value: -"nextCursor from the previous part: continues there even if the code moved; refuses if it changed."New value: +"nextCursor from the previous part: continues there even if the function moved; refuses if it changed."

changedInput schema / properties / file / description

Previous value: -"Path relative to the repo root. Alone (no `name`): the whole file."New value: +"Path relative to the repo root."

changedInput schema / properties / fromLine / description

Previous value: -"Continue a long function, class or file from this file line."New value: +"Continue a long function from this file line."

changedInput schema / properties / functions / description

Previous value: -"Read up to 10 at once: a function by `id` or `file`+`name` (+ `line`), a class by `file` + its name, a whole file by `file` alone. Use instead of the single-read fields below."New value: +"Read up to 10 functions at once, each by `id` or `file`+`name` (+ `line`). Use instead of the single-function fields below."

changedInput schema / properties / line / description

Previous value: -"A line inside the function or class, to disambiguate."New value: +"A line inside the function, to disambiguate."

changedInput schema / properties / maxLines / description

Previous value: -"Lines per part (default 400 for a function, 1000 for a class or file)."New value: +"Lines per part (default 400)."

changedInput schema / properties / name / description

Previous value: -"Function: qualified (\"OrderService.calculateFee\"), short, or exported name. Class: its name (\"OrderService\") — the whole class."New value: +"Qualified (\"OrderService.calculateFee\"), short, or exported name."

1 tool updatev0.6.0Oct 16, 2026

Changedspec_nav_read_function7 fields changed

changedInput schema / properties / cursor / description

Previous value: -"nextCursor from the previous part: continues there even if the function moved; refuses if it changed."New value: +"nextCursor from the previous part: continues there even if the code moved; refuses if it changed."

changedInput schema / properties / file / description

Previous value: -"Path relative to the repo root."New value: +"Path relative to the repo root. Alone (no `name`): the whole file."

changedInput schema / properties / fromLine / description

Previous value: -"Continue a long function from this file line."New value: +"Continue a long function, class or file from this file line."

addedInput schema / properties / functions

Added value: +{
+  "description": "Read up to 10 at once: a function by `id` or `file`+`name` (+ `line`), a class by `file` + its name, a whole file by `file` alone. Use instead of the single-read fields below.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "file": {
+        "type": "string"
+      },
+      "id": {
+        "type": "string"
+      },
+      "line": {
+        "exclusiveMinimum": 0,
+        "type": "integer"
+      },
+      "name": {
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "maxItems": 10,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / line / description

Previous value: -"A line inside the function, to disambiguate."New value: +"A line inside the function or class, to disambiguate."

changedInput schema / properties / maxLines / description

Previous value: -"Lines per part (default 400)."New value: +"Lines per part (default 400 for a function, 1000 for a class or file)."

changedInput schema / properties / name / description

Previous value: -"Qualified (\"OrderService.calculateFee\"), short, or exported name."New value: +"Function: qualified (\"OrderService.calculateFee\"), short, or exported name. Class: its name (\"OrderService\") — the whole class."

8 tool updatesv0.4.0Oct 15, 2026
- First observedspec_nav_callers
- First observedspec_nav_find_functions
- First observedspec_nav_functions
- First observedspec_nav_map
- First observedspec_nav_read_function
- First observedspec_nav_services
- First observedspec_nav_similar_functions
- First observedspec_nav_trace_flow

Deploy Server

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.1/5.0

Scored 2026-10-19 07:30 across 8 tools

Disambiguation4/5

Most tools target distinct operations: regex text search (map), behavior-keyword search (find_functions), structural similarity (similar_functions), catalog listing (functions), full read (read_function), call sites (callers), flow tracing (trace_flow), and service listing (services). The main risk is overlap among map, find_functions, and similar_functions, but the descriptions explicitly differentiate them (regex vs lexical vs call/body comparison) and cross-reference each other. Boundaries are clear enough that misselection is unlikely.

Naming Consistency5/5

Every tool uses the same snake_case style under a uniform spec_nav_ prefix, with predictable noun/verb phrases (find_functions, read_function, trace_flow, callers). No mixing of camelCase or alternate conventions. The convention is consistent and readable throughout.

Tool Count5/5

Eight tools is well-scoped for a read-only code navigation server, with each tool covering a distinct navigation concern (search, discovery, similarity, catalog, read, callers, flow, services). No tool feels redundant or padded.

Completeness4/5

The surface covers the core navigation lifecycle: discover, list, read, find similar, find callers, and trace cross-service flows, plus a service inventory. Gaps are minor: no dependency/import-graph or class-hierarchy tool, and non-call symbol references (constants, types) aren't directly searchable, but agents can largely work around these with map and functions.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

gread A
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5365
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
Symvanta A
com.symvanta
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Code Analysis Developer Tools
271
noteit-mcpOAuth
io.github.bahfahh
MCP server for AI agent profiles and smart notes. 60+ coding prompt packs with expert personas.
Note Taking Developer Tools Coding Agents
25

Related MCP Servers

Axon.MCP.Server
Code Analysis Developer Tools Search
ali-kamali
F
license
Not graded
quality
D
maintenance
An MCP server that transforms codebases into intelligent, queryable knowledge bases, enabling AI assistants to perform semantic search, explore architecture, and analyze code relationships.
Updated 4 months ago (2026-06-30 01:32 UTC)
166
-
codeweave-mcp
Code Analysis Developer Tools RAG Systems
semihkayan
A
license
Not graded
quality
D
maintenance
An MCP server that gives AI agents structured code understanding and precise code intelligence via local indexing of AST, call graphs, and semantic search.
Updated 5 months ago (2026-05-26 10:13 UTC)
42 npm
4
Apache 2.0
reference-mcp
Code Analysis Developer Tools
mark-burg
A
license
A
quality
D
maintenance
An MCP server that helps AI agents comprehend a codebase by providing tools for navigating, searching, and understanding code structure and history.
Updated 4 months ago (2026-06-15 01:29 UTC)
10
MIT
mcp-code-indexer
Code Analysis Developer Tools
Nielsen642
A
license
Not graded
quality
D
maintenance
An MCP server that enables AI agents to navigate and understand codebases through file descriptions, semantic search, and code recommendations without repeatedly scanning files.
Updated 4 months ago (2026-06-24 01:30 UTC)
MIT

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

When it helps

Example: change an order fee

Quick start (Claude Code)

Tools

Supported languages

Benchmark

Live LLM run on a private production monorepo

Simulated agents

Limits

Documentation

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers