Navigation Agent MCP

@导航代理/mcp服务器

仅限工作区的MCP服务器，用于结构代码导航和存储库检查。它暴露了稳定的公众 code.* 用于查找符号定义、跟踪上游调用者以进行影响分析、在逻辑更改之前跟踪下游执行流、列出路由/端点、搜索文本和检查工作区树而无需盲目打开文件的工具界面。

npm： @navigation-agent/mcp-server

______________________________________________________________________

安装

服务器通过运行 npx.

需求

• Node.js 18+
• ripgrep (rg)--可选，仅需要 code.search_text

克劳德代码

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

OpenCode

添加 ~/.config/opencode/opencode.json:

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

Gemini CLI

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

或手动添加到 ~/.gemini/settings.json 或 .gemini/settings.json:

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

使用带连字符的服务器名称 navigation-agent。避免在Gemini MCP服务器名称中使用下划线，因为Gemini从服务器名称派生出完全限定的工具名称。

光标

添加 ~/.cursor/mcp.json 或 .cursor/mcp.json:

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

OpenAI 代码专家

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

或添加到 ~/.codex/config.toml:

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

工作区根目录

默认情况下，服务器会分析当前工作目录。要固定特定项目，请设置 NAVIGATION_MCP_WORKSPACE_ROOT 在您的MCP配置中。

______________________________________________________________________

代理使用指南

此服务器是为 模型控制MCP工具的使用：当任务涉及工作区代码结构时，代理应在打开源文件之前发现并调用其工具。

它发布了每个工具的描述和服务器指令，因此MCP客户端可以在不依赖私人技能注册表的情况下向模型传授工作流程。

代理商如何学习使用它

MCP客户通过几个标准渠道提供模型指导：

重要部分：服务器指令是MCP握手的一部分，因此遵守MCP指令的客户端可以在选择工具之前将它们注入模型。

skills/navigation-mcp/SKILL.md 是支持技能的客户的可选便携式技能模板。MCP正常运行不需要；特别是对于OpenCode，技能是从以下方面发现的 .opencode/skills//SKILL.md，全局OpenCode技能，或与Claude/agents兼容的技能目录。

代理的快速路径

1. 使用 code.inspect_tree 在未知模块或目录中定向而不读取文件。
2. 使用 code.find_symbol 当你知道一个类、函数、方法、类型、枚举或注释名称，但不知道定义文件时。
3. 通过 find_symbol已返回 items[].path 进入：

- code.trace_callers 对于上游影响： 谁叫这个？ - code.trace_flow 对于下游行为： 这个呼叫或到达什么？

1. 使用 code.list_endpoints 在更改REST、GraphQL或路由曲面之前。
2. 使用 code.search_text 对于文本模式、导入、装饰器，或者当符号查找不够时。
3. 只读导航工具返回的相关文件。

后备代理应使用

不要把空的结果本身当作证据。使用一个范围内的回退，然后在结果仍然为空时解释限制。

客户端中的工具命名

规范的公共合同是 code.*一些客户端使用服务器前缀或规范化分隔符公开MCP工具，例如 navigation-agent_code_find_symbol 或 mcp_navigation-agent_code.find_symbol。将这些名称视为相同规范工具的别名。

使用 navigation-agent 作为示例中的服务器名称。它是可读的，避免了冲突，并避免了从服务器id导出完全限定工具名称的客户端中与下划线相关的解析器问题。

客户惯例说明

支持的筛选器代理应该知道

• 语言： typescript, javascript, go, java, php, python, rust, csharp
• 框架： react-router, spring

请勿将此MCP用于web搜索、外部存储库、任意文件系统访问或读取文件内容。它是一个仅限工作区的导航层。

______________________________________________________________________

兼容性矩阵

此表必须保留在README中，因为这是理解公共支持面的最快方法。它是有意组织的 语言作为行 和 工具作为列 因此，添加更多的语言会向下增长，而不是扩大表格。

工具列省略了 code. 前缀以保持矩阵可读。

传说：

• ✅ = 在此文档同步期间在真实项目中验证
• ⚠️ = 公开披露，但在此过程中未重新验证，对所选验证项目没有意义，或仍有警告
• ❌ = 今天不作为公众支持
• code.inspect_tree 和 code.search_text 也可以在没有语言过滤器的情况下跨通用工作区文件工作。

重要提示：

• 公共语言过滤器是 typescript, javascript, go, java, php, python, rust，以及 csharp.
• Go、PHP、Python、Rust、Java、TypeScript、JavaScript和C#都是公共合约的一部分；上面的矩阵显示了每个工具的当前验证级别。
• Rust跟踪工具工作良好，但应使用其限定名查询方法/impl符号（例如 JavaProjectIndex::build).

______________________________________________________________________

公共工具

公共合同正好暴露了这六个工具：

• code.inspect_tree
• code.list_endpoints
• code.find_symbol
• code.search_text
• code.trace_flow
• code.trace_callers

使用 snake_case 参数，例如 max_depth, include_hidden，以及 file_pattern.

在更改函数或方法之前

当您需要了解工作空间内的行为或影响时，请使用此工作流：

1. code.find_symbol --首先解析精确的定义文件。
2. code.trace_callers --在重命名、删除或更改签名之前检查上游影响。
3. code.trace_flow --在更改逻辑之前检查下游执行。
4. read 只有跟踪结果返回的文件才真正重要。

经验法则：

• 选择 code.trace_callers 为了 谁依赖这个？
• 选择 code.trace_flow 为了 这达到或唤起了什么？
• 如果您需要影响和行为，请在编辑前运行两者

具体工作空间示例：

1. 解析符号定义：

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

1. 更改功能前检查上游冲击：

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

1. 在更改逻辑之前检查下游行为：

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

预期代理行为：

• 使用 code.find_symbol 首先，当定义文件未知时
• 使用 code.trace_callers 首先，当风险在于打断来电者时
• 使用 code.trace_flow 接下来，当风险正在改变下游行为时
• 只有那时 read 您实际需要的跟踪文件

React路由器示例：

{
  "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 响应风格

code.search_text 针对代理进行了优化：

• 结果按文件分组
• 每场比赛只返回 line 加上精确 spans
• topFiles 首先突出显示最密集的文件
• 上下文的 before / after 为了降低噪音和代币成本，公众反应中故意省略了文本

示例形状：

{
  "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 }]
        }
      ]
    }
  ]
}

快速示例

{
  "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"
}

______________________________________________________________________

验证真实世界的行为

这些检查是根据实际项目而不是玩具存根进行验证的：

Java~/sias/app/back)

• code.inspect_tree 在真实的模块树上工作
• code.find_symbol 在真实的春季课堂上工作
• code.search_text 使用真实的Java源代码
• code.list_endpoints 清单框架可检测的Spring REST控制器和GraphQL解析器作为可能的公共入口点
• code.trace_flow 在真实控制器/解析器入口点上工作
• code.trace_callers 适用于Java用例，可以识别可能的公共入口点

验证示例：

• RootUserGraphQLController#getUsersByDependency
• 追溯到 RootGetUserUseCase#getUsers

Types/React路由器(~/sias/app/front)

• code.inspect_tree 在真实的路线树上工作
• code.find_symbol 处理路由模块导出
• code.search_text 处理真实路线文件
• code.list_endpoints 库存React Router路由模块 loader / action 出口作为可能的路线入口点
• code.trace_flow 适用于同一文件路由流提取
• code.trace_callers 适用于相同的文件助手，并将路线导出标记为可能的入口点

验证示例：

• app/routes/change-password.tsx#action
• 找到呼叫 getUserIdAndTokenFromSession, changeMyPassword, getSession, commitSession, getRoleRoute
• 反向追踪 getRoleRoute _handle_payment(...) -> payment_service.authorize_payment(...)`
• deep tree捕获跨文件调用 AuditService, InventoryService, ProductRepository等等。

验证示例（反向跟踪）：

• app/services/audit.py#log_action
• 反向追踪呼叫者 UserService, OrderService
• 递归识别中的入口点 app/api/endpoints.py (get_user, create_order)

PHP(examples/php)

• code.inspect_tree 在PHP项目树上工作
• code.find_symbol 处理PHP类和方法
• code.search_text 处理PHP源文件
• code.trace_flow 用于PHP服务到存储库的端到端调用
• code.trace_callers 用于PHP影响分析的端到端工作

笔记：

• code.list_endpoints 在当前示例中，已公开PHP，但未重新验证有用的端点清单

验证示例：

• src/Service/UserService.php#UserService::persistUser
• 追踪 $this->repository->save($user) 到 src/Repository/MemoryUserRepository.php#save

Rust（这个仓库）

• code.inspect_tree 在真实的Rust源代码树上工作
• code.find_symbol 使用Rust类型/函数
• code.search_text 在真实的Rust源代码上工作
• code.trace_flow 当使用正确的限定符号进行查询时，它适用于真正的Rust方法
• code.trace_callers 当使用正确的限定符号进行查询时，它适用于真正的Rust方法

笔记：

• code.list_endpoints 此存储库上返回零结果，这是所选验证目标的预期结果，因为它不是Rust web应用程序

验证示例：

• crates/navigation-engine/src/capabilities/trace_flow.rs#JavaProjectIndex::build
• 追踪 Self::new_empty(), index.scan_project(workspace_root)，以及 index.is_empty()
• 反向追踪 JavaProjectIndex::scan_project <- JavaProjectIndex::build

C./examples/csharp)

• code.inspect_tree 作品
• code.search_text 作品
• code.find_symbol 用于方法查找，例如 OrderWorkflowService.ProcessOrderAsync
• code.trace_flow 在示例应用程序上端到端工作，并返回递归内部调用树
• code.trace_callers 在示例应用程序上端到端工作

去吧(./examples/go)

今天的真实行为 examples/go:

• code.inspect_tree 作品
• code.search_text 作品
• code.find_symbol 用于方法查找，例如 CreateUser
• code.trace_flow 在示例应用程序上端到端工作，并返回递归内部调用树
• code.trace_callers 在示例应用程序上端到端工作，包括回调/方法值引用和实现反向匹配的接口
• code.list_endpoints 对于当前的Go示例，仍然没有返回有用的入口点库存

______________________________________________________________________

公共语言和框架过滤器

当前公共语言筛选器：

• typescript
• javascript
• go
• java
• php
• python
• rust
• csharp

当前公共框架筛选器：

• react-router
• spring

______________________________________________________________________

响应形状

每个工具都返回相同的顶级信封：

{
  "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": {}
  }
}

状态含义：

• ok --请求成功，包括零结果成功
• partial --请求成功，但被截断/修剪
• error --请求失败，并包含稳定的错误代码

笔记：

• code.trace_flow 返回一个根递归树 data.root
• code.trace_callers 返回直接调用者和递归反向跟踪元数据
• code.search_text 返回紧凑分组的匹配结果，以及 topFiles，不是完整的上下文块

______________________________________________________________________

建筑

此存储库有两个主要层：

1. TypeScript MCP运行时 (packages/mcp-server/)

- 验证公众 code.* 合同 - 暴露stdio/stdio遗留传输 - 使反应正常化

1. 生锈的发动机 (crates/navigation-engine/)

- 使用树状图解析源代码 - 主机语言分析器 - 包含内部AST/debug二进制文件 crates/navigation-engine/src/bin/

重要提示：

• packages/mcp-server/src/bin/ 包含运行时入口点(navigation-mcp.ts)
• AST检查/调试二进制文件已上线 crates/navigation-engine/src/bin/，不在TypeScript运行时

______________________________________________________________________

贡献/地方发展

关键本地命令：

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

有用的本地运行时检查：

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

许可证

麻省理工学院