内容
nexus-mcp
一个社区 [模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器，用于 **Quantinuum Nexus**，
封装了官方的 [`qnexus`](https://github.com/Quantinuum/qnexus) Python 软件开发工具包，
以便任何支持MCP的代理（Claude Code、Cursor、VS Code、Codex等）都可以检查Nexus并可选地在免费的模拟器上运行电路。
> **与Quantinuum无关联、未获得Quantinuum的认可或支持，也不是Quantinuum的官方产品。** “Quantinuum”和“Nexus”是其各自所有者的商标，在此处仅用于描述兼容性。
<!-- mcp-name: io.github.Blite-HQ/qnexus-mcp -->
## 状态
早期开发。**默认情况下为只读。** 设计和原理在
[`docs/DESIGN.md`](docs/DESIGN.md) 中描述；相关的研究在 [`docs/research/`](docs/research/) 中。
## 要求
- Python 3.10+ 和 [`uv`](https://docs.astral.sh/uv/) （`uvx` 命令）。在 Windows 上，请注意
`uvx.exe` 的完整路径（在终端中运行 `where uvx`）- GUI 客户端不会继承您的 shell PATH。
- 一个 [Quantinuum Nexus](https://nexus.quantinuum.com) 账户。
## 1. 身份验证（一次性）
`qnexus-mcp` **从不处理您的Nexus令牌。** 使用 `qnexus` 命令行界面进行带外身份验证
（它会打开您的浏览器）：
```bash
uvx --from qnexus qnx login
```
在Nexus JupyterHub中，身份验证是自动的；请勿在那里运行 `qnx login`。
## 2. 将服务器添加到您的MCP客户端
启动命令在所有地方 - 只有配置文件因客户端而异：
```
uvx qnexus-mcp==0.2.0 # 只读（默认）
uvx qnexus-mcp==0.2.0 --toolsets read,execute # + 在免费的 H2-1LE 模拟器上运行电路
```
**固定版本** (`==0.2.0`)：`uvx` 否则会在每次启动时解析最新的 PyPI 版本 -
未固定的安装既不可复制也不可审计。避免在 Windows 上使用 `0.1.0`：其第一个工具调用会挂起（在 0.2.0 中已修复）。
> **启动时预期：** 首次启动会下载量子软件开发工具包堆栈（1-3 分钟）；
> 每次启动都会导入软件开发工具包，然后在服务器响应之前大约需要 30 秒 - 这是正常的。
### 克劳德桌面
设置 → 开发者 → 本地 MCP 服务器 → **编辑配置** （始终使用此按钮 -
Microsoft Store 版本将文件保存在 `%LOCALAPPDATA%\Packages\Claude_*\...`，而不是
`%APPDATA%\Claude`），然后添加：
```jsonc
{
"mcpServers": {
"nexus": {
"command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe", // 或 macOS/Linux 上的纯 "uvx"
"args": ["qnexus-mcp==0.2.0", "--toolsets", "read"]
}
}
}
**完全退出克劳德桌面并重新打开** - 配置仅在冷启动时读取，并且
关闭窗口会使旧进程继续运行（托盘图标 → 退出，或
`taskkill /F /IM claude.exe`）。
### VS 代码
命令调色板 → `MCP: 打开用户配置`（或工作区 `.vscode/mcp.json`）：
```jsonc
{
"servers": {
"nexus": {
"type": "stdio",
"command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe", // 或 macOS/Linux 上的纯 "uvx"
"args": ["qnexus-mcp==0.2.0", "--toolsets", "read,execute"]
}
}
}
```
### 克劳德代码
```bash
claude mcp add nexus -- uvx qnexus-mcp==0.2.0 --toolsets read,execute
```
### 其他MCP客户端（Cursor、Codex等）
相同的命令；配置形状是上述两种JSON形式之一（`mcpServers` vs
`servers` + `"type": "stdio"`）- 请查看客户端文档，了解应将配置文件放在哪里。
如果某些操作不正常？请参阅 [`docs/TROUBLESHOOTING.md`](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工具注释仅被视为UX提示。
请参阅 [`docs/DESIGN.md`](docs/DESIGN.md) §6–§7。
**提示注入（有意识的设计决策）。** Nexus返回的所有内容 - 作业名称、项目名称、
错误消息、结果 - 都是攻击者可影响的内容（任何Nexus用户都可以命名作业），并被视为
不受信任的数据。当前的MCP生态系统中没有将“数据”与“指令”分开的结构化标签；这里的结构边界是
**注入的内容无法升级**：具有后果的每个操作（花费积分、针对硬件、删除任何内容）都需要启动标志，
而代理无法设置 *plus* 协议内的人工确认，命名确切的目标和成本。注入的文本
最多会混淆代理的推理 - 它本身无法花费或销毁任何内容。这种残留
风险被接受并记录，而不是遗漏。
**治理。** 这是一个早期的、单维护者的项目（参见 `CODEOWNERS`）：发布版本
由一个人通过 GitHub-OIDC Trusted Publishing 发布（无长寿命 PyPI 令牌）。固定版本
（上面）如果该信任模型对您的部署很重要。
## 贡献
请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。在
[开发者证书来源](https://developercertificate.org/) 下接受贡献；用 `-s` 签署提交。
## 许可证
Apache-2.0。请参阅 [`LICENSE`](LICENSE) 和 [`NOTICE`](NOTICE)。
