Helping coding agents find existing code before writing more with mcp-spec-nav

When a coding agent adds a feature, finding the right code is part of the task. An existing function might have an unexpected name, or its callers might be spread across several services.

I built mcp-spec-nav, an open-source, local MCP server, to help agents navigate those situations.

It gives agents tools to search for existing functions, read individual implementations, inspect callers, and trace selected cross-service flows.

Example: changing an order fee

Consider this task:

Add a waiveHandlingFee option to the order total calculation and update the callers that need it.

Before editing, the agent needs to find the calculation and understand where it is used.

With spec-nav, the workflow is:

1. Find candidates: search for “order handling fee total” using spec_nav_find_functions.
2. Read the implementation: use spec_nav_read_function to retrieve the function’s source, signature, documentation, and imports.
3. Check callers: use spec_nav_callers to inspect usages before changing the signature.
4. Edit and test: the coding agent makes the changes and runs the project’s tests.

The repository includes a runnable example of this workflow.

What it adds to text search

Text search remains useful, especially when you know the exact symbol or file.

Spec-nav adds ranked function candidates with reasons for each match. Search considers names, paths, documentation, called functions, and body vocabulary.

For caller lookup, it uses the TypeScript type checker for TS/JS and supported component files. This helps distinguish calls to the target from calls to unrelated methods with the same name. Other supported languages use evidence-based matching and report uncertain results separately.

There is also a static flow-tracing tool for HTTP, RPC, and events in selected TypeScript, JavaScript, and Python frameworks.

Try it on your repository

Once installed, try asking your coding agent:

Use spec-nav to find the existing order total calculation. Read the best candidates and check their callers before proposing changes. Report anything you could not resolve.

The server reads your local checkout. It does not edit files or require an external search API key. Tool results are returned to your connected coding agent, whose model and data-handling settings still apply.

Installing the MCP makes the tools available, but agents may need workflow instructions to use them consistently.

Limitations

Search is lexical: equivalent implementations with different vocabulary can be missed. Similarity results are candidates to inspect, not proof of equivalent behavior.

Dynamic calls can remain unresolved, and cross-service tracing covers supported frameworks rather than every possible integration. For a small change in one known file, the extra tools may add overhead.

Source and documentation

• Website
• GitHub — installation, examples, and benchmarks
• Glama — listing and tool description evaluations

If you try it, I’d appreciate a reproducible example of a useful function or caller it misses. Those cases help identify what needs improving next.