内容
# 上下文导航
[](https://www.npmjs.com/package/contextpilotmcp)
[](#许可证)
**上下文导航自动为 AI 编程代理构建尽可能小的上下文。**
与其将整个代码仓库（甚至是关键字匹配的子集）倒入 LLM 的上下文窗口，不如使用上下文导航，它会索引代码库并返回与任务相关的几个函数 — 作为 MCP 服务器，Claude Code、Claude Desktop 和其他 MCP 兼容的代理可以直接调用。
## 问题
每个 AI 编程代理在提供帮助之前都必须回答同一个问题：*对于这个任务，代码库的哪一部分实际上是相关的？* 将整个代码仓库喂给它会浪费令牌、时间和金钱。简单的关键字搜索更便宜但更肤浅 — 它可以轻松找到 `Login()` 和 `LoginForm()`，但会错过 `verifyPassword()`、`createJWT()` 或 `isLoggedIn()`，因为这些函数不共享“登录”这个词，即使它们可能正是登录错误出现的地方。
**在一个包含 815 个文件的生产代码库中进行测量**，搜索任务 *"用户在刷新后无法保持登录状态"*（一个从未包含“登录”一词的查询）：
| 方法 | 上下文发送 | 大约令牌 |
|---|---|---|
| 整个代码仓库 | 815 文件 | ~325,000 |
| 上下文导航 | 5 个函数 | ~960 |
这意味着整个代码仓库的上下文减少了超过 **99.7%** — 同时仍然显示了实际相关的代码（`isLoggedIn()`、`getServerUser()`），而不是不相关的 UI 页面，因为匹配是语义的，而不仅仅基于关键字。
## 工作原理
1. **索引** — 上下文导航扫描项目，解析函数/方法（基于正则表达式和括号深度），并将它们存储在本地 SQLite 数据库中，同时带有每个函数的语义嵌入（`all-MiniLM-L6-v2`，通过 `@xenova/transformers` 完全本地运行 — 无需 API 密钥，无需数据离开您的机器）。
2. **搜索** — 像 `"修复登录错误"` 这样的查询被嵌入并与每个索引函数进行比较，使用余弦相似度，并混合关键字重叠评分以实现精确的名称匹配。
3. **上下文** — 顶部匹配结果作为一个可粘贴的代码块返回，大小适合任务，而不是整个代码仓库。
4. 默认增量 — 重新索引一个包含 800 个文件的项目，在修改一个文件后仍然很快，因为未更改的文件通过 mtime/大小检查被跳过。
## 安装
```bash
npm install -g contextpilotmcp
```
## CLI 使用
```bash
contextpilot index /path/to/project
contextpilot search "fix login bug" -d /path/to/project
contextpilot context "fix login bug" -d /path/to/project # 顶部匹配结果的完整源代码
```
## 作为 MCP 服务器使用
上下文导航作为模型上下文协议服务器，因此任何 MCP 兼容的客户端（Claude Desktop、Claude Code、Cursor 等）都可以在对话期间将其作为工具调用 — 无需手动将代码复制到聊天中。
**Claude Desktop** — 添加到您的配置（设置 → 开发者 → 编辑配置）：
```json
{
"mcpServers": {
"contextpilot": {
"command": "npx",
"args": ["-y", "contextpilotmcp"]
}
}
}
```
重启 Claude Desktop。在新的聊天中，询问类似：
> “索引 /path/to/my-project，然后找到与修复登录错误相关的函数。”
Claude 将自动调用 `contextpilot_index` 和 `contextpilot_search`。
### 可用工具
| 工具 | 描述 |
|---|---|
| `contextpilot_index` | 扫描项目并构建/更新函数索引 |
| `contextpilot_search` | 返回任务描述的排名函数匹配 |
| `contextpilot_context` | 返回顶部匹配结果的完整源代码，准备粘贴 |
这三个工具都接受一个可选的 `projectPath` 参数。如果省略，上下文导航将默认为 MCP 服务器的当前工作目录。
- **Claude Code** — 由于它通常从项目目录内部启动（`cd my-project && claude`），工作目录通常是您的项目，因此您可以经常完全跳过 `projectPath` 并直接说“索引此项目”或“查找与 X 相关的函数”。
- **Claude Desktop** — MCP 服务器从与项目文件夹无关的工作目录启动。始终显式传递 `projectPath`，例如“索引 /Users/you/projects/my-app，然后搜索 X。”
如果有疑问，只需显式传递 `projectPath` — 它始终有效，无论客户端如何。
## 许可证
MIT
