# code_nav MCP

AI-native deterministic code navigation MCP server for Codex / CodeCLI.

`code_nav` gives coding agents compact, structured repo context without making
them dump files into chat. It works in any git repo by detecting the repo root
and using git-visible files.

There is no semantic search, no embeddings, no vector database, no graph index,
no Qdrant, no CocoIndex, and no Zoekt.

Repository:

```text
https://github.com/ARQAWA/code-nav-mcp
```

## Install Prompt

Use `INSTALL_AGENT_PROMPT.md` with Codex / CodeCLI on the target machine.

The prompt installs one shared user-level `code_nav` MCP:

```text
$HOME/.local/share/code-nav-mcp/app
$HOME/.local/bin/code-nav-mcp
```

It also installs/checks Probe, ast-grep, ripgrep, and RTK, configures Codex
MCP globally, installs Code Navigation Rules, and verifies the MCP tools.

## Tools

| Tool | Purpose |
|---|---|
| `code_nav.health` | Check repo detection and dependency health. |
| `code_nav.search` | Main deterministic code discovery workflow. |
| `code_nav.find_file` | File/path discovery. |
| `code_nav.exact_search` | Ranked exact text search, not proof. |
| `code_nav.extract_context` | Compact code context extraction. |
| `code_nav.structural_search` | AST search with ast-grep. |
| `code_nav.exact_audit` | Exhaustive proof using raw rg/git grep. |
| `code_nav.coverage` | File coverage and no-semantic-index status. |

## Local Development

```bash
npm install
npm run build
npm test
npm run doctor
npm run self-test
```

Run the MCP server locally:

```bash
node dist/cli.js mcp
```

## Optional Repo Config

No per-repo config is required. Rare overrides can use `.code-navrc.json`:

```json
{
  "max_file_bytes": 2097152,
  "extra_exclude": [],
  "extra_include": [],
  "markdown": "normal",
  "result_limit": 12
}
```