nimbus

@nimbus-dev/mcp

这是什么

一个小型启动器，可将本地 Nimbus 索引和 Agent 暴露给任何 MCP（Model Context Protocol） 客户端——编辑器、聊天客户端或其他支持 MCP 的工具。它本身不执行任何工作：它会找到已安装在你机器上的 Nimbus CLI 二进制文件，并以 nimbus mcp-server --stdio 启动它，随后便不再介入，让标准输入输出直接传递。

本软件包采用 MIT 许可证，不依赖（也不导入）AGPL-3.0 许可的 packages/cli 或 packages/gateway Nimbus 源码——它只负责查找已安装的二进制文件，绝不会自行运行网关。

要求 Nimbus 网关已安装并运行。 此启动器不会安装或捆绑 Nimbus；请先运行常规的 Nimbus 安装程序，并按平时的方式配置网关（mcp-server --stdio 命令会连接你现有的本地索引）。使用 nimbus start 启动网关：即使不启动网关，MCP 服务也会启动，但此时工具调用会返回错误，提示你启动网关。

范围

查找二进制文件、以继承标准输入输出的方式启动它，并且只在需要将子进程的退出状态传回客户端期间留在进程树中，这就是本工具的全部工作。保持这样的设计，才能让本软件包采用 MIT 许可证，而它启动的网关采用 AGPL-3.0 许可证。具体来说，它不会：

• 安装、捆绑、更新 Nimbus，也不会检查其版本。 请使用常规的 Nimbus 安装程序。
• 实现任何 MCP 工具。 索引和 Agent 工具由 Nimbus 单体仓库中的 nimbus mcp-server 提供（packages/cli、packages/gateway）。缺失或运行异常的工具属于那里的问题，而不是这里的问题。
• 解析、过滤、代理或改写 MCP 数据流。 子进程会继承标准输入输出，流量在两个方向上都原样传递。
• 管理网关配置、身份验证或索引本身。 请按平时的方式进行配置；此启动器会原样传递你的环境变量，除此之外不做干预。
• 引入运行时依赖。 package.json 仅包含 devDependencies。这关乎许可证和供应链边界，而非风格偏好——在此添加运行时依赖是需要慎重考虑的决定，而不是为了方便随手做出的选择。

安装

无需全局安装，可直接从 MCP 客户端配置中运行（见下文），也可以显式安装：

npm install -g @nimbus-dev/mcp

快速开始

在 MCP 客户端的服务配置中添加 nimbus-mcp 命令，例如：

{
  "mcpServers": {
    "nimbus": {
      "command": "npx",
      "args": ["-y", "@nimbus-dev/mcp"]
    }
  }
}

从 MCP Registry 安装的客户端可以找到此服务，名称为 io.github.nimbus-agent/nimbus。

从本地克隆运行

若要直接从 此仓库的克隆运行启动器——例如在开发时，或在发布更改前进行尝试——请将 MCP 客户端指向入口文件本身。请使用绝对路径：由编辑器启动的 MCP 服务不会继承你 shell 的工作目录。

{
  "mcpServers": {
    "nimbus": {
      "command": "bun",
      "args": ["/absolute/path/to/nimbus-mcp/src/index.ts"]
    }
  }
}

如果你已经安装了 Nimbus CLI，可以完全跳过启动器，让客户端直接运行 nimbus mcp-server --stdio——启动器存在的唯一目的就是帮你找到该二进制文件。

如何查找二进制文件

启动器按以下顺序查找 Nimbus 二进制文件：

1. NIMBUS_BIN — 如果已设置，则使用指定的二进制文件完整路径。若 NIMBUS_BIN 指向的文件不存在，会报告错误，绝不会静默忽略。

2. PATH — 在 PATH 中找到的第一个 nimbus（Windows 上为 nimbus.exe）。

3. 已知的平台安装目录：先查找安装程序自身的输出目录，再查找其他 Nimbus 分发渠道使用的目录：

   平台	按顺序搜索
   Windows	%LOCALAPPDATA%\Programs\Nimbus\bin（安装程序和 .msi/winget），然后是 Scoop 的 shims — %SCOOP%\shims 或 %USERPROFILE%\scoop\shims，接着是 %SCOOP_GLOBAL%\shims 或 %ProgramData%\scoop\shims
   macOS	~/.local/bin（安装程序和 .pkg），然后是 /opt/homebrew/bin 和 /usr/local/bin（Homebrew）
   Linux	~/.local/bin（安装程序），然后是 /usr/local/bin（apt/yum）和 /usr/bin，接着是 /home/linuxbrew/.linuxbrew/bin 和 ~/.linuxbrew/bin（Homebrew）

第 3 步可让通过 GUI 启动的 macOS 编辑器找到二进制文件，因为这类编辑器通常会在不使用 shell 的 PATH 的情况下启动 MCP 服务。如果这些位置都找不到二进制文件，启动器会退出并提示如何修复，而不会只返回一个退出代码。

如果你将 Nimbus 安装在其他位置，请设置 NIMBUS_BIN，而不是等待将该目录添加到这里。

环境变量

• NIMBUS_BIN — 覆盖解析出的二进制文件路径。请将其指向 Nimbus CLI 可执行文件的确切路径 — 在 Windows 上，指向 nimbus.exe 本身。Node 不会在没有 shell 的情况下启动 .cmd 或 .bat 包装脚本，因此启动失败时会报错 Failed to start the Nimbus MCP server: spawn EINVAL。
• NIMBUS_MCP_TIMEOUT_MS — Nimbus CLI 的 MCP 适配器等待 Agent 简报的时长，超时后会返回明确的超时错误；默认值为 60 s。如果编辑器自身的 MCP 传输超时时长更短，请调低此值，这样工具会报告超时，而不是让调用在底层被中断。这是适配器自身的时间预算 — 网关不会施加此类超时。该值由底层的 nimbus mcp-server 进程读取；启动器会以原样继承的环境变量执行该进程。

另请参阅

• docs/architecture.md — Nimbus 子系统设计和 MCP 连接器标准。
• 主 Nimbus 仓库中的 CLI mcp-server 命令（位于 packages/cli，为网关提供来自 packages/gateway 的索引和 Agent）— 此软件包会启动它，但不包含也不授权使用它。

许可证

MIT — 请参阅 LICENSE。请注意，此启动器执行的 Nimbus 网关和 CLI 分别基于 AGPL-3.0 许可。