Navigator

What the navigator MCP server does

The navigator MCP server provides read-only navigation for a repository on the local machine. It accepts a question or an explicit command and returns material that an agent or reviewer can inspect. Results preserve file paths, line ranges, snippets, scores, routing reasons, and retriever attribution, so a caller can see why a location was selected.

Its main use is progressive disclosure. Rather than placing a whole repository in context, an agent can first locate likely evidence and then request a bounded range. The tool does not write to the repository it examines. It also excludes known secret-bearing paths before reading content.

How it works

The default locate path uses in-memory Okapi BM25 over files produced by the repository walker. English and Spanish Snowball stemmers are available, with document language taken from frontmatter when present and detected as a logged fallback otherwise. The default returns eight hits and permits up to 40; snippets are capped at 240 characters.

Each locate result is a pointer to read, not a generated answer. read-range retrieves the selected lines and can widen the range in 20-line increments, stopping at the surrounding heading boundary. Frontmatter is returned separately from the body. The handles path exposes document pointers and typed relationships, but every pointer requires hydration before it should be treated as evidence.

The implementation also retains exact and fused retrieval arms through --retriever, primarily for the registered measurement workflow. Demotion files can reduce a document's score without removing it from results.

Setup and configuration

Node.js 20 or newer is required. Install the package globally with npm; this provides the mentu-nav CLI and the mentu-navigator-mcp MCP server. The CLI can also run through npx -p mentu-navigator mentu-nav ...; invoking npx mentu-navigator alone does not resolve the binary because the package and command names differ.

Run the command from a repository directory. Interactive terminals receive a human-oriented response, while pipes receive compact JSON. Use --json for the full envelope or --agent for a compact JSON contract intended for agents. Telemetry is local JSONL under ~/.mentu/pd1/ and can be disabled with MENTU_NAV_TELEMETRY=off.

Tools and capabilities

• map reports files, languages, manifests, contracts, typed documents, and Git state.
• query finds matching evidence through the legacy exact-search pipeline.
• locate ranks likely document ranges with BM25 or another selected retrieval arm.
• read-range returns a heading-bounded slice from a path and line range.
• handles resolves frontmatter pointers and relationships and reports diagnostics.
• symbol gathers definitions, references, tests, documentation, and configuration around a symbol.
• impact reports Git ranges, tickets, contracts, tests, and risk signals related to a change.

Limitations and notes

The evidence behind the BM25 default covers one bilingual, 141-document operational markdown corpus and a 115-question evaluation set. It does not establish equivalent retrieval quality for source code. The repository-wide map, symbol, and impact commands support code repositories, but their usefulness was not measured in the provided evidence. The server is intentionally deterministic: it uses no embeddings, background index, or target-repository writes.