qnexus-mcp

qnexus-mcp

一个面向 Quantinuum Nexus 的社区 Model Context Protocol（MCP）服务，它封装了官方 qnexus Python SDK，使任何支持 MCP 的 Agent（Claude Code、Cursor、VS Code、Codex 等）都能检查 Nexus，并可选择在免费模拟器上运行电路。

与 Quantinuum 无关联、未获其认可，也不是其官方产品。“Quantinuum”和“Nexus”是各自所有者的商标，此处仅用于说明兼容性。

状态

早期开发阶段。**默认只读。**设计与原理见 docs/DESIGN.md；相关研究见 docs/research/。

要求

• Python 3.10+ 和 uv（uvx 命令）。在 Windows 上，请记下 uvx.exe 的完整路径（在终端中运行 where uvx）——GUI 客户端不会继承你的 shell PATH。
• 一个 Quantinuum Nexus 账号。

1. 进行身份验证（一次即可）

qnexus-mcp **绝不会处理你的 Nexus 令牌。**请在其他环境中使用 qnexus CLI 进行身份验证（它会打开浏览器）：

uvx --from qnexus qnx login

在 Nexus JupyterHub 中，身份验证会自动完成；请勿在其中运行 qnx login。

2. 将服务添加到 MCP 客户端

启动命令在所有客户端中都相同——只有各客户端的配置文件不同：

uvx qnexus-mcp==0.2.0                              # read-only (default)
uvx qnexus-mcp==0.2.0 --toolsets read,execute      # + run circuits on the free H2-1LE emulator

固定版本（==0.2.0）：否则，uvx 每次启动都会解析 PyPI 上的最新版本——不固定版本既无法复现，也无法审计。在 Windows 上请避免使用 0.1.0：其首次工具调用会卡住（已在 0.2.0 中修复）。

**启动时的预期情况：**首次启动会下载量子 SDK 依赖栈（1–3 分钟）；每次启动时，服务响应前都需要约 30 秒——SDK 会在 MCP 握手之前预先导入。在此期间显示“Waiting for server to respond to initialize”属于正常现象。

Claude Desktop

依次选择“设置”→“开发者”→“本地 MCP 服务”→编辑配置（请始终使用此按钮——Microsoft Store 版本会将文件保存在 %LOCALAPPDATA%\Packages\Claude_*\... 下，而非 %APPDATA%\Claude），然后添加：

{
  "mcpServers": {
    "nexus": {
      "command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe", // or plain "uvx" on macOS/Linux
      "args": ["qnexus-mcp==0.2.0", "--toolsets", "read,execute"]
    }
  }
}

然后完全退出 Claude Desktop 并重新打开——配置只会在冷启动时读取，而关闭窗口不会终止旧进程（点击托盘图标 → 退出，或运行 taskkill /F /IM claude.exe）。

VS Code

命令面板 → MCP: Open User Configuration（或工作区中的 .vscode/mcp.json）：

{
  "servers": {
    "nexus": {
      "type": "stdio",
      "command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe", // or plain "uvx" on macOS/Linux
      "args": ["qnexus-mcp==0.2.0", "--toolsets", "read,execute"]
    }
  }
}

Claude Code

claude mcp add nexus -- uvx qnexus-mcp==0.2.0 --toolsets read,execute

其他 MCP 客户端（Cursor、Codex 等）

命令相同；配置格式为上述两种 JSON 格式之一（mcpServers 或 servers + "type": "stdio"）——请查阅客户端文档，确认应将其放入哪个文件。

遇到问题？请参阅 docs/TROUBLESHOOTING.md——其中涵盖了实际客户端配置中观察到的所有故障模式（配置路径错误、首次启动缓慢、身份验证、速率限制、已知的 Nexus 端错误）。

配置

标志	环境变量	默认值	作用
--toolsets	QNEXUS_MCP_TOOLSETS	read	要公开的能力领域（read,execute,manage,destructive）
--allow-spend	QNEXUS_MCP_ALLOW_SPEND	false	允许消耗额度（HQC）的执行操作
--allow-hardware	QNEXUS_MCP_ALLOW_HARDWARE	false	允许使用真实 QPU 目标
--allow-destructive	QNEXUS_MCP_ALLOW_DESTRUCTIVE	false	允许删除／取消／归档
--max-credits	QNEXUS_MCP_MAX_CREDITS	0	单次调用的 HQC 硬性上限；0 会阻止所有额度消耗
--max-outcomes	QNEXUS_MCP_MAX_OUTCOMES	100	每个结果最多返回的不同测量结果数；始终会报告截断情况
--max-submissions-per-minute	QNEXUS_MCP_MAX_SUBMISSIONS_PER_MINUTE	6	滑动窗口提交上限；批次中的每个电路都计为一次提交
--projects	QNEXUS_MCP_PROJECTS	（全部）	以逗号分隔的项目允许列表；对每个变更类工具强制执行

安全

默认情况下为只读。任何会消耗额度或更改云端状态的操作，都需要明确的选择启用标志，并且需要协议内确认；默认执行后端是免费、无噪声的 H2-1LE 模拟器。提交操作设有速率限制，云端变更会串行执行；破坏性项目操作通过精确名称确定目标（绝不使用子字符串）；服务绝不会读取、存储或返回你的 Nexus 令牌。所有控制都由服务端强制执行；MCP 工具注释仅作为用户体验提示。请参阅 docs/DESIGN.md §6–§7。

提示词注入（有意的设计决策）。 Nexus 返回的所有内容——作业名称、项目名称、错误消息、结果——都可能受到攻击者影响（任何 Nexus 用户都可以为作业命名），因此一律视为不可信数据。当前 MCP 生态系统中，没有结构化标记可将“数据”与“指令”区分开来；这里的结构性边界是：注入内容无法提升权限：所有可能产生后果的操作（消耗额度、指定硬件、删除任何内容）都需要 Agent 无法设置的启动标志，并且需要协议内的人为确认，其中必须注明精确目标和成本。注入文本最多只能干扰 Agent 的推理——无法独自消耗额度或破坏任何内容。我们接受并记录了这项剩余风险，并非疏漏。

治理。 这是一个早期阶段、由单人维护的项目（请参阅 CODEOWNERS）：版本发布由一人通过 GitHub-OIDC Trusted Publishing 完成（不使用长期有效的 PyPI 令牌）。如果这种信任模型对你的部署很重要，请固定版本（见上文）。

贡献

请参阅 CONTRIBUTING.md。我们依据开发者来源证书接受贡献；请使用 -s 为提交签署。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。