Nexus-MCP

Nexus-MCP

让编码 Agent 用少 95% 的 token 找到正确文件。 Nexus-MCP 是一个本地 MCP 服务，为 Claude Code、Codex、Cursor 以及任何 MCP 客户端提供混合代码搜索和代码 图。Agent 只需提出一个问题，就能获取代码，无需在 grep 和读取文件之间来回折腾。 无需 API 密钥，无需云服务，采用 MIT 许可。

uvx --python 3.12 nexus-mcp-ci setup

setup 会查找你机器上的 MCP 客户端，显示每项更改，并在写入前征求你的同意。 你需要安装 uv。或者告诉你的 Agent： "从 https://github.com/jaggernaut007/Nexus-MCP 安装 Nexus-MCP"。

⭐ 如果 Nexus-MCP 帮你节省了 token，请为仓库点个星。 这能帮助其他开发者发现它。

---

效果

在 12 个使用 10 种语言的开源仓库上进行测量，并与仅使用内置 Grep 和 Read 的 Agent 对比。以下数据都不是估算值：每个数字都链接到一个固定版本的仓库和原始运行记录。

在使用 10 种语言的 10 个开源仓库上，Nexus-MCP 找到正确文件时的 token 数量（中位数）减少了 95%，搜索速度比 Grep 和 Read 快 9 倍。在 11 个仓库的 Claude Code 实际运行中，11 项任务有 8 项成本更低，66 项任务中有 64 项正确，而对照组为 66 项中有 61 项正确。

找到正确文件（nexus-mcp-ci eval：离线，无需大模型）。Grep 和 Read → Nexus-MCP：

语言	仓库	首次找到正确文件	找到正确文件所需的 token	搜索耗时
Python	pallets/flask（83 个文件）	20% → 93%	26,720 → 1,388	108 → 23 ms
TypeScript	vitejs/vite（429 个文件）	43% → 83%	16,520 → 1,286	159 → 25 ms
JavaScript	webpack/webpack（822 个文件）	37% → 67%	25,634 → 1,251	564 → 34 ms
Java	apache/commons-lang（264 个文件）	23% → 87%	48,176 → 1,241	201 → 31 ms
C#	JamesNK/Newtonsoft.Json（242 个文件）	23% → 73%	14,004 → 1,547	154 → 25 ms
PHP	laravel/framework（1,751 个文件）	50% → 83%	13,479 → 1,086	712 → 39 ms
C++	chromium/chromium（3,641 个文件）	43% → 80%	19,768 → 1,243	1,851 → 88 ms
Go	prometheus/prometheus（201 个文件）	40% → 83%	41,034 → 1,195	600 → 24 ms
C	redis/redis（229 个文件）	40% → 87%	37,139 → 988	331 → 34 ms
Rust	tokio-rs/tokio（381 个文件）	33% → 93%	21,138 → 830	215 → 27 ms

Agent 实际运行（Claude Code 搭配 Claude Sonnet，中等工作量，无头模式，每个仓库 6 项任务，各运行 3 次，按每项任务取中位数）。Grep 和 Read → Nexus-MCP：

语言	仓库	每项任务的令牌数	每项任务的成本	轮次	正确数
Python	home-assistant/core	65,990 → 42,458 (-36%)	$0.050 → $0.037 (-27%)	7 → 3	6 → 6 of 6
Python	django/django	45,102 → 41,916 (-7%)	$0.048 → $0.035 (-26%)	5.5 → 2.5	5 → 6 of 6
TypeScript	vitejs/vite	69,790 → 52,411 (-25%)	$0.059 → $0.046 (-22%)	5.5 → 4	6 → 6 of 6
JavaScript	webpack/webpack	100,320 → 74,638 (-26%)	$0.077 → $0.068 (-11%)	6 → 4.5	6 → 6 of 6
Java	apache/commons-lang	50,448 → 32,862 (-35%)	$0.044 → $0.022 (-49%)	4.5 → 2	6 → 6 of 6
C#	JamesNK/Newtonsoft.Json	41,929 → 42,139 (+1%)	$0.030 → $0.030 (+1%)	3 → 2.5	6 → 6 of 6
PHP	laravel/framework	52,919 → 51,994 (-2%)	$0.051 → $0.039 (-24%)	5 → 3	5 → 5 of 6
C++	chromium/chromium	70,495 → 60,622 (-14%)	$0.065 → $0.055 (-16%)	6.5 → 4.5	6 → 6 of 6
Go	prometheus/prometheus	52,014 → 45,214 (-13%)	$0.047 → $0.037 (-22%)	4.5 → 2.5	5 → 6 of 6
C	redis/redis	41,752 → 50,578 (+21%)	$0.031 → $0.030 (-3%)	3.5 → 3	6 → 6 of 6
Rust	tokio-rs/tokio	41,188 → 61,816 (+50%)	$0.029 → $0.041 (+42%)	3.5 → 4.5	4 → 5 of 6

尚未达标：C（redis/redis，令牌数 +21%，构建版本 2.2.2+e5a9d9a）和 Rust（tokio-rs/tokio，令牌数 +50%，构建版本 2.2.2+0430f01）。这些测试运行时间较早；当前构建版本的重新测试仍待进行。每行展示该仓库的最新一次测试；每行对应的构建版本见基准测试页面。同一代码在每项任务运行 3 次时，成本可能相差约 20%（测量日期：2026-10-28）。

所有数据、方法和原始测试结果：基准测试页面 · JSON · CSV · 测试运行记录。

数据的含义：

• **首先找到正确文件：**第一个结果就是定义答案的文件的问题所占比例。正确文件由解析器确定，绝不由 Nexus-MCP 排名决定。
• **找到正确文件所需的令牌数：**Agent 找到该文件前读取的内容量。
• **搜索时间：**建立索引后，在笔记本电脑上执行一次查找所需的时间。
• **每项任务的令牌数和成本：**在真实问题上进行的真实 Claude Code 会话；两种条件使用相同的模型、提示词和工具。节省主要来自减少轮次：每一轮都会重新读取整个对话。

---

先在自己的代码上测一测

检查免费、离线运行、不调用大模型，只需几分钟：

uvx --python 3.12 nexus-mcp-ci eval                                   # the current folder
uvx --python 3.12 nexus-mcp-ci eval https://github.com/pallets/flask  # a public repo
uvx --python 3.12 nexus-mcp-ci eval --example                         # the Nexus-MCP source

它会根据你的代码生成约 30 个问题并给出结论：“高度匹配”“可能匹配”或“匹配度低”。在小型项目中，Grep 和 Read 表现更好，报告会如实说明。要了解实际 Agent 成本，可运行 nexus-mcp-ci eval --agent claude，使用你自己的 Claude Code 登录账号进行付费 A/B 测试。它会显示成本并先征求确认。指南：docs/EVALUATE.md。

---

安装

客户端	操作
机器上的任意客户端	uvx --python 3.12 nexus-mcp-ci setup（添加 --dry-run 可查看变更，添加 --uninstall 可移除）
Claude Code 插件	/plugin marketplace add jaggernaut007/Nexus-MCP，然后运行 /plugin install nexus-mcp@nexus-mcp
VS Code	在 VS Code 中安装
Cursor	网站上的“Add to Cursor”链接
Claude Desktop	打开最新版本中的 nexus-mcp.mcpb
Gemini CLI	gemini extensions install https://github.com/jaggernaut007/Nexus-MCP
Docker	docker run -i --rm -v "$PWD:/workspace" -v nexus-data:/data ghcr.io/jaggernaut007/nexus-mcp
手动安装	运行 pip install nexus-mcp-ci，然后运行 claude mcp add nexus-mcp -- nexus-mcp-ci

在 Claude Code 中使用 setup 或插件，不能同时使用两者。然后启动新会话，并询问与代码相关的问题，例如 “失败的付款在哪里重试？”。Agent 会在后台为项目建立一次索引，文件监视器会持续更新索引。所有渠道的说明见：docs/DISTRIBUTION.md。支持 Python 3.10 至 3.12；uvx 启动命令会固定使用 3.12。

---

Agent 能获得什么

服务默认显示五个工具。每个工具都能替代多次 grep 和读取调用。

工具	用途
search(query)	回答“……在哪里？”、“……如何工作？”等问题。混合搜索：语义（本地嵌入）加关键词（BM25）。顶部结果会附带完整代码。
find_symbol(symbol_name)	查找已知名称。一次调用即可获取多个函数或类的代码，以及它们的调用方和被调用方。较长的类会以大纲形式返回。
graph(symbol_name)	回答“谁调用了 X？”、“如果我修改 X，会影响什么？”等问题。重构前查看调用方、被调用方以及传递影响范围。
map(detail)	回答“从哪里开始？”等问题。查看仓库的层级、入口点、核心符号和语言。
index(path)	在项目中首次调用时使用。此后会进行增量索引，也支持单体仓库中的多个文件夹。
memory(action)	可选。保存可跨会话保留的决策和笔记。存在记忆时默认启用。
analyze(path)	可选。分析指定路径的复杂度、代码异味和依赖指标。
status()	可选。查看索引状态及是否过期。

设置 NEXUS_EXTRA_TOOLS=all 可显示三个可选工具。连接时，服务会发送自己的路由说明，让 Agent 知道哪个工具能回答哪个问题。完整参考：docs/USAGE_GUIDE.md。

保留 Agent 自带的 grep。对于可以直接输入的精确名称或字符串，请使用 grep；当答案需要语义或结构信息时，请使用 Nexus-MCP。

---

语言

支持情况	语言
搜索、符号、调用图	Python、TypeScript、JavaScript、Go、Java、Rust、C、C++、C#、PHP
搜索和符号	Bash、Kotlin
搜索（文本和嵌入）	通过 tree-sitter 支持 25 种以上语言

以上结果涵盖了支持调用图的十种语言。Python 的调用图覆盖范围最广。

---

隐私

你的代码保留在本机。服务不会进行网络调用，也没有遥测功能。

• **输入：**仅需获取一次 PyPI 软件包和 Hugging Face 嵌入模型。之后设置 NEXUS_OFFLINE=1。
• **输出：**不会发送任何内容，除非你运行 eval --agent（通过你自己的 Claude 或 Codex CLI）或 eval share（仅数字）。两者都会先征求同意。
• **存储：**索引位于 <project>/.nexus/（请将其添加到 .gitignore）。 nexus-mcp-ci data where 会列出所有文件；nexus-mcp-ci data clear 会将其删除。

详情：docs/PRIVACY.md。

---

已知限制

• 调用图是静态的。 边来自解析，而非运行代码。动态分派、回调和反射不会显示出来，因此应将 graph 结果视为下限。
• 在较旧的 2.2.2 版本中，C 和 Rust 的实时运行比 Grep 和 Read 消耗更多令牌（见“结果”）。当前版本的重新运行尚待进行。
• 内存： 空闲时约为 90 MB，加载嵌入模型后约为 460 MB（测量数据）。
• 更新及时性： 编辑会在几秒钟的防抖延迟后生效，而非即时生效。
• 传输方式： 仅支持 stdio。

---

文档

• 基准测试：所有数字、每行所用的版本、方法和原始数据
• 评估、安装、使用、配置、故障排除、常见问题
• 架构、与其他工具的比较、决策记录、变更日志
• 所有文档：docs/README.md。面向 Agent：llms.txt。

---

贡献

欢迎提交问题和拉取请求。请先阅读 CONTRIBUTING.md 和 开发者指南：

git clone https://github.com/jaggernaut007/Nexus-MCP.git && cd Nexus-MCP
pip install -e ".[dev]"
pytest -v && ruff check .

只有在降低 Agent 的令牌用量并通过搜索准确率门槛 （python -m evals.retrieval.run）后，变更才会发布。规则见 CONTRIBUTING.md。

Nexus-MCP 源自两个 MIT 项目：CodeGrok MCP，由 rdondeti 开发；以及 code-graph-mcp，由 entrepeneur4lyf 开发（ADR-001）。

---

许可证

MIT。