@navigation-agent/mcp-server

Workspace-only MCP server for structural code navigation and repository inspection. It exposes a stable public code.* tool surface for finding symbol definitions, tracing upstream callers for impact analysis, tracing downstream execution flow before logic changes, listing routes/endpoints, searching text, and inspecting workspace trees without opening files blindly.

npm: @navigation-agent/mcp-server

Installation

The server runs via npx.

Requirements

• Node.js 18+

• ripgrep (rg) — optional, only needed for code.search_text

Claude Code

claude mcp add navigation-agent npx -- -y @navigation-agent/mcp-server

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "navigation-agent": {
      "type": "local",
      "command": ["npx", "-y", "@navigation-agent/mcp-server"],
      "enabled": true
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "navigation-agent": {
      "command": "npx",
      "args": ["-y", "@navigation-agent/mcp-server"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "navigation-agent": {
      "command": "npx",
      "args": ["-y", "@navigation-agent/mcp-server"]
    }
  }
}

OpenAI Codex

codex mcp add navigation-agent -- npx -y @navigation-agent/mcp-server

Or add to ~/.codex/config.toml:

[mcp_servers.navigation-agent]
command = "npx"
args = ["-y", "@navigation-agent/mcp-server"]

Workspace root

By default the server analyzes the current working directory. To pin a specific project, set NAVIGATION_MCP_WORKSPACE_ROOT in your MCP config.

Compatibility matrix

This table MUST stay in the README because it is the fastest way to understand the public support surface.

Legend:

• ✅ = verified in a real project during this documentation sync

• ⚠️ = publicly exposed, but not re-verified in this pass, not meaningful on the chosen validation project, or still has caveats

• ❌ = not working as public support today

• — = language-specific parsing not required

Important:

• Go is now part of the public contract and works well for symbol lookup, text search, trace flow, and trace callers on the validated example app.

• Rust trace tools work well, but method/impl symbols should be queried with their qualified name (for example JavaProjectIndex::build).

Public tools

The public contract exposes exactly these six tools:

• code.inspect_tree

• code.list_endpoints

• code.find_symbol

• code.search_text

• code.trace_flow

• code.trace_callers

Use snake_case parameters such as max_depth, include_hidden, and file_pattern.

Before changing a function or method

Use this workflow whenever you need to understand behavior or impact inside the workspace:

1. code.find_symbol — resolve the exact defining file first.

2. code.trace_callers — inspect upstream impact before renaming, deleting, or changing a signature.

3. code.trace_flow — inspect downstream execution before changing logic.

4. read only the files returned by the trace results that actually matter.

Rule of thumb:

• choose code.trace_callers for who depends on this?

• choose code.trace_flow for what does this reach or invoke?

• if you need both impact and behavior, run both before editing

Concrete workspace example:

1. Resolve the symbol definition:

{
  "symbol": "create_order",
  "language": "python",
  "kind": "function",
  "path": "examples/python"
}

2. Inspect upstream impact before changing the function:

{
  "path": "examples/python/app/api/endpoints.py",
  "symbol": "create_order",
  "language": "python",
  "recursive": true,
  "max_depth": 3
}

3. Inspect downstream behavior before changing the logic:

{
  "path": "examples/python/app/api/endpoints.py",
  "symbol": "create_order",
  "language": "python"
}

Expected agent behavior:

• use code.find_symbol first when the defining file is not already known

• use code.trace_callers first when the risk is breaking callers

• use code.trace_flow next when the risk is changing downstream behavior

• only then read the traced files you actually need

React Router example:

{
  "symbol": "action",
  "kind": "function",
  "framework": "react-router",
  "path": "app/routes"
}

{
  "path": "app/routes/change-password.tsx",
  "symbol": "action",
  "framework": "react-router",
  "recursive": true,
  "max_depth": 2
}

{
  "path": "app/routes/change-password.tsx",
  "symbol": "action",
  "framework": "react-router"
}

code.search_text response style

code.search_text is optimized for agents:

• results are grouped by file

• each match returns only line plus exact spans

• topFiles highlights the densest files first

• contextual before / after text is intentionally omitted from the public response to reduce noise and token cost

Example shape:

{
  "fileCount": 3,
  "matchCount": 19,
  "totalFileCount": 3,
  "totalMatchCount": 19,
  "topFiles": [
    {
      "path": "examples/go/internal/http/handlers/user_handler.go",
      "language": "go",
      "matchCount": 11
    }
  ],
  "items": [
    {
      "path": "examples/go/internal/http/handlers/user_handler.go",
      "language": "go",
      "matchCount": 11,
      "matches": [
        {
          "line": 28,
          "spans": [{ "colInit": 23, "colEnd": 32 }]
        }
      ]
    }
  ]
}

Quick examples

{
  "symbol": "RootUserGraphQLController",
  "language": "java",
  "kind": "class"
}

{
  "path": "app/routes/change-password.tsx",
  "symbol": "action",
  "framework": "react-router"
}

{
  "path": "src/main/java/com/example/FooController.java",
  "symbol": "getFoo",
  "framework": "spring"
}

Verified real-world behavior

These checks were verified against real projects instead of toy stubs:

Java (~/sias/app/back)

• code.inspect_tree works on real module trees

• code.find_symbol works on real Spring classes

• code.search_text works on real Java source

• code.list_endpoints inventories framework-detectable Spring REST controllers and GraphQL resolvers as likely public entrypoints

• code.trace_flow works on real controller/resolver entrypoints

• code.trace_callers works on Java use cases and can identify probable public entrypoints

Verified example:

• RootUserGraphQLController#getUsersByDependency

• traced into RootGetUserUseCase#getUsers

TypeScript / React Router (~/sias/app/front)

• code.inspect_tree works on real route trees

• code.find_symbol works on route-module exports

• code.search_text works on real route files

• code.list_endpoints inventories React Router route-module loader / action exports as likely route entrypoints

• code.trace_flow works for same-file route flow extraction

• code.trace_callers works for same-file helpers and marks route exports as probable entrypoints

Verified example:

• app/routes/change-password.tsx#action

• found calls to getUserIdAndTokenFromSession, changeMyPassword, getSession, commitSession, getRoleRoute

• reverse-traced getRoleRoute <- action

Python (examples/python)

• code.inspect_tree works on Python module trees

• code.find_symbol works on Python classes, functions, and methods

• code.search_text works on Python source files

• code.list_endpoints inventories FastAPI-style route decorators (@router.get, @app.post, etc.) as likely public API entrypoints

• code.trace_flow works end-to-end for multi-module Python scenarios, capturing deep recursive trees including branching calls, instance methods (self), and cross-file resolution.

• code.trace_callers works end-to-end for impact analysis, supporting recursive reverse-tracing across the entire workspace.

Verified example (Forward Trace):

• app/api/endpoints.py#create_order

• traced into order_service.process_order(...) -> _handle_payment(...) -> payment_service.authorize_payment(...)

• deep tree captures cross-file calls to AuditService, InventoryService, ProductRepository, etc.

Verified example (Backward Trace):

• app/services/audit.py#log_action

• reverse-traced to callers in UserService, OrderService

• recursively identifies entrypoints in app/api/endpoints.py (get_user, create_order)

Rust (this repository)

• code.inspect_tree works on real Rust source trees

• code.find_symbol works on Rust types/functions

• code.search_text works on real Rust source

• code.trace_flow works on real Rust methods when queried with the correct qualified symbol

• code.trace_callers works on real Rust methods when queried with the correct qualified symbol

Notes:

• code.list_endpoints returned zero results on this repository, which is expected for the chosen validation target because it is not a Rust web app

Verified example:

• crates/navigation-engine/src/capabilities/trace_flow.rs#JavaProjectIndex::build

• traced Self::new_empty(), index.scan_project(workspace_root), and index.is_empty()

• reverse-traced JavaProjectIndex::scan_project <- JavaProjectIndex::build

Go (./examples/go)

Real behavior today against examples/go:

• code.inspect_tree works

• code.search_text works

• code.find_symbol works for method lookup such as CreateUser

• code.trace_flow works end-to-end on the example app and returns the recursive internal call tree

• code.trace_callers works end-to-end on the example app, including callback/method-value references and interface-to-implementation reverse matches

• code.list_endpoints still returns no useful entrypoint inventory for the current Go example

Public language and framework filters

Current public language filters:

• typescript

• javascript

• go

• java

• python

• rust

Current public framework filters:

• react-router

• spring

Response shape

Every tool returns the same top-level envelope:

{
  "tool": "code.trace_flow",
  "status": "ok",
  "summary": "Traced 5 callees for 'action' from 'app/routes/change-password.tsx'.",
  "data": {},
  "errors": [],
  "meta": {
    "query": {},
    "resolvedPath": "app/routes/change-password.tsx",
    "truncated": false,
    "counts": {},
    "detection": {}
  }
}

Status meanings:

• ok — request succeeded, including zero-result success

• partial — request succeeded but was truncated/pruned

• error — request failed and includes stable error codes

Notes:

• code.trace_flow returns a rooted recursive tree under data.root

• code.trace_callers returns direct callers plus recursive reverse-trace metadata

• code.search_text returns compact grouped matches and topFiles, not full context blocks

Architecture

This repository has two main layers:

1. TypeScript MCP runtime (packages/mcp-server/)

   • validates the public code.* contract

   • exposes stdio / stdio-legacy transports

   • normalizes responses

2. Rust engine (crates/navigation-engine/)

   • parses source with tree-sitter

   • hosts language analyzers

   • includes internal AST/debug binaries under crates/navigation-engine/src/bin/

Important:

• packages/mcp-server/src/bin/ contains the runtime entrypoint (navigation-mcp.ts)

• AST inspection/debug binaries live in crates/navigation-engine/src/bin/, not in the TypeScript runtime

Contributing / local development

Key local commands:

npm install
npm --workspace @navigation-agent/mcp-server run check
npm --workspace @navigation-agent/mcp-server run test
cargo test --manifest-path crates/navigation-engine/Cargo.toml

Useful local runtime checks:

npx tsx packages/mcp-server/src/bin/navigation-mcp.ts --describe-tools
npx tsx packages/mcp-server/src/bin/navigation-mcp.ts --transport stdio-legacy --workspace-root /path/to/workspace

License

MIT