# navigator [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/mentu-ai/mentu-navigator  
**GitHub Stars:** 0  
**npm Downloads (last month):** 255  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/navigator

## Description
Read-only repo navigation and progressive disclosure; BM25 locator with registered evidence.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "navigator": {
    "command": "npx",
    "args": ["-y","-p","mentu-navigator","mentu-nav"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/navigator/readme_