toolcairn-mcp

@neurynae/toolcairn-mcp

@neurynae/toolcairn-mcp 在 npm 上的源码。请通过软件包安装，而不是从此仓库安装。

ToolCairn 是一个 MCP 服务，可将你的 AI 编码 Agent 连接到持续更新的图谱，其中涵盖 npm、PyPI、Cargo、Maven、Go、Composer、RubyGems、NuGet、Homebrew 等平台上的 30,000 多种开源工具，以及 另外 35 多个注册表。你可以直接在 Claude Code、Cursor 或任何兼容 MCP 的客户端中搜索、比较、构建技术栈并检查版本兼容性。

具体示例。 你的 Agent 收到 “我需要一个适用于 Node 的快速 HTTP 客户端” → 调用 search_tools → ToolCairn 返回按排名排列的候选工具及其维护状况和社区信号、替代方案；如果首选工具近期活动情况存疑，还会发出警告。再也不用根据博客文章和过时教程猜测。

MCP 服务在本地运行，作为 Agent 的 stdio 子进程。工具调用通过 MCP 发送到此软件包；它会将需要联网的调用转发到 ToolCairn Cloud API，并在磁盘上处理仅限本地的调用（项目扫描、配置、审计日志）。

---

为什么选择 ToolCairn？

普通网页搜索和大模型训练数据不足以用于工具选择：知识截止时间会遗漏最新版本；搜索引擎优先展示教程，而不是权威排名；版本兼容性信息则散落在各处的问题讨论中。

ToolCairn 通过三项原始注册表 API 无法提供的能力解决这些问题：

• 基于图谱的排名 — 推荐会考虑工具之间的关系（依赖、集成、替代、冲突），而不仅仅是热度。
• 感知版本的兼容性检查 — 声明的对等版本范围和跨注册表版本元数据能告诉你 “Next.js 14 需要 React 18.x”，而不是 “它们都很受欢迎，大概没问题吧？”
• 持续学习闭环 — 每条被采纳、拒绝或替换的推荐都会反馈到图谱中，使用越多，质量越高。

---

快速开始

步骤 1。 在 toolcairn.neurynae.com/signup 创建免费账号。

步骤 2。 将其添加到 MCP 配置中，然后重启 Agent：

{
  "mcpServers": {
    "toolcairn": {
      "command": "npx",
      "args": ["@neurynae/toolcairn-mcp"]
    }
  }
}

步骤 3。 首次启动时会打开浏览器窗口供你登录。确认后即可立即使用所有工具，无需进一步设置。

需要 Node.js 22+。

---

配置 — Claude Code

最快的方式：

claude mcp add toolcairn -- npx @neurynae/toolcairn-mcp

或者将上方的 JSON 代码块粘贴到 ~/.claude/claude_desktop_config.json 中的 mcpServers 下。

其他兼容 MCP 的客户端（Cursor、Claude Desktop、VS Code Copilot、Windsurf、Zed，……）也可使用相同的 npx @neurynae/toolcairn-mcp 命令 — 各客户端的配置位置请参阅文档。

---

你可以做什么

查找工具

你的 Agent 收到 “我需要一个用于事件跟踪的实时分析数据库” → 调用 search_tools → 获取按相关性排序的候选项（ClickHouse、TimescaleDB、InfluxDB，……）及维护状况信号。如果意图不明确，响应会附带澄清问题；Agent 可通过 search_tools_respond 作答并获取优化后的结果。

构建技术栈

你的 Agent 收到 “帮我设计一个全栈 TypeScript SaaS” → 调用 refine_requirement 进行拆解，然后根据各层需求调用 get_stack → 获取一个由 3–5 个工具组成的技术栈（Web 框架 + 数据库 + 身份验证 + 支付），并附带版本兼容性矩阵，展示整个技术栈中哪些版本可以协同工作。

比较选项

“Express 和 Fastify，哪个更适合 REST API？” → compare_tools 返回并列的健康状况（星标数、维护评分、最近提交、未解决问题、贡献者趋势）、图谱关系（各自集成了什么、替代了什么），以及基于你说明的使用场景给出的建议。

检查版本兼容性

“我想将 Next.js 升级到 14，但保留 React 17。” → check_compatibility 会评估已声明的 peer 版本范围，并返回满足或不满足的检查结果及其来源（declared_dependency / graph_edges / shared_neighbors）。

跟踪项目工具

首次会话时，toolcairn_init 会遍历你的仓库，解析每个清单文件（package.json、requirements.txt、pyproject.toml、Cargo.toml、go.mod、pom.xml、Gemfile、composer.json，……），根据 ToolCairn 图谱为每个工具分类，并写入本地 .toolcairn/ 快照。后续会话会优先读取此快照 — 你的 Agent 不会再搜索它已了解的内容。

---

可用工具

MCP 服务提供 16 个工具，按用途分组。大多数工具在本地运行（无需网络）或以即发即弃的方式运行；搜索、比较和技术栈工具会调用 ToolCairn API。

发现

工具	功能
search_tools	使用自然语言搜索，并提供健康状况信号和替代选项。意图不明确时可能会提出澄清问题。
search_tools_respond	提交回答，以优化进行中的搜索。
refine_requirement	将模糊的使用场景（“构建 SaaS”）拆解为具体、可搜索的子需求。
verify_suggestion	检查 Agent 选择的工具是否已编入 ToolCairn 图谱索引。

技术栈与兼容性

工具	功能
get_stack	组合互补的工具技术栈，并提供跨版本兼容性矩阵。
compare_tools	并排比较：健康指标、图谱关系和建议。
check_compatibility	检查两个工具之间与版本相关的 peer 版本范围。

项目配置

工具	功能
toolcairn_init	发现项目根目录、扫描清单文件、为工具分类并写入 .toolcairn/。
read_project_config	加载本地 .toolcairn/config.json 快照（已确认的工具、待处理项、审计日志）。
update_project_config	原子性地添加、移除或更新工具 — 每次变更都会记录审计日志。

反馈循环

工具	功能
report_outcome	即发即忘：推荐的工具是否有效？完成学习闭环。
feedback	针对 ToolCairn 本身的 Agent 反馈。 仅当 ToolCairn 的响应有误、存在问题、质量低下或有所遗漏时调用——绝不要用于正面反馈。不占用每日配额。
suggest_graph_update	提交新的工具、边或用例以供管理员审核（暂存，不会自动升级）。
check_issue	最后手段。 搜索工具的 GitHub 问题，查找已知错误——仅在重试 4 次以上且检查过文档后使用。

会话

工具	功能
classify_prompt	本地判断是否需要搜索工具（对于非工具提示词，跳过 ToolCairn）。
toolcairn_auth	管理本地登录：login / status / logout。

---

配置

环境变量	默认值	用途
TOOLCAIRN_TRACKING_ENABLED	true	设置为 false 可禁用使用事件日志记录（参见隐私与遥测）。
LOG_LEVEL	info	设置为 debug 可输出详细的 stdio 诊断信息。
MCP_TRANSPORT	stdio	设置为 http 可使用 HTTP 传输（高级选项）。

文件位置

• 凭据 → ~/.toolcairn/credentials.json（权限模式 0600，有效期 90 天）。
• 各项目状态 → 每个检测到的项目根目录中的 .toolcairn/{config.json, audit-log.jsonl, tracker.html}。

tracker.html 文件是一个独立的仪表板——在任意浏览器中打开，即可实时查看每次工具调用、待评估项和审计记录。

---

会话管理

你的登录信息保存在 ~/.toolcairn/credentials.json 中，有效期为 90 天。在 Agent 中执行：

toolcairn_auth { action: "status" }   # check current sign-in
toolcairn_auth { action: "logout" }   # clear credentials

要重新进行身份验证，只需重启 Agent——登录流程会自动打开。

---

隐私与遥测

我们会明确说明哪些信息会离开你的设备。

发送至 ToolCairn（启用跟踪时）：

• 工具名称、耗时和成功／错误状态——用于服务健康监测和产品分析。
• 绝不会发送完整提示词、响应正文或项目文件内容。

保留在本地：

• 所有审计记录（.toolcairn/audit-log.jsonl）。
• 项目状态和工具快照。
• 你的凭据文件。

随时选择退出：

TOOLCAIRN_TRACKING_ENABLED=false

工具仍可正常使用；仅会跳过轻量级使用事件的记录。

完整隐私政策：toolcairn.neurynae.com/privacy。

---

故障排除

登录时浏览器未打开。 复制输出到 stderr 的 URL 并手动访问；输入显示的设备代码。

出现 Module not found 或版本错误。 使用 node --version 确认 Node 版本为 22 或更高。

位于企业代理之后。 设置 HTTPS_PROXY——npx 和 MCP 服务会遵循此设置。

可自托管的后端。 设置 TOOLPILOT_API_URL=https://your-host。

登录已过期。 重启 Agent——设备代码流程会自动重新运行。

详细日志。 设置 LOG_LEVEL=debug。

Agent 正在做什么？ 在浏览器中打开 .toolcairn/tracker.html，查看会自动刷新的工具调用仪表板。

---

CLI：scan

独立的健康扫描，不会启动 MCP 服务：

npx @neurynae/toolcairn-mcp scan [dir]

读取 [dir]（默认：当前目录）中的依赖清单——package.json、requirements.txt、pyproject.toml、Cargo.toml——并报告每项声明依赖的健康状况、替代方案和警告。

添加 --json 可输出机器可读格式。

---

链接

• 网站： toolcairn.neurynae.com
• 文档： toolcairn.neurynae.com/docs
• npm： @neurynae/toolcairn-mcp
• GitHub： neurynae/toolcairn-mcp
• 问题反馈： github.com/neurynae/toolcairn-mcp/issues
• 安全： 通过 [email protected] 负责任地披露安全问题

---

贡献

欢迎在 github.com/neurynae/toolcairn-mcp/issues 提交问题和功能请求。

图引擎、搜索流水线和索引器均为闭源。本仓库包含在用户机器上运行的公开 MCP 客户端和项目配置层。

---

许可证

MIT — © 2026 NEURYNAE。详见 LICENSE。