内容
# Xray 云端 MCP for Cursor
一款 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，允许 Cursor 直接从代理读取和管理 [Xray 云端](https://www.getxray.app/) 测试工件 — 测试用例、计划、集合和执行。
仅使用 **Xray 云端 API 密钥**（客户端 ID + 密钥）进行身份验证。不需要单独的 Jira API 令牌。
> **仅支持 Xray 云端。** 不支持 Xray 服务器或数据中心。
## 工具
| 工具 | 描述 |
|---|---|
| `get_test_case` | 通过 Jira 问题密钥获取测试用例及其步骤 |
| `search_test_cases` | 通过 JQL（关键词、标签、状态等）搜索测试 |
| `get_test_plan` | 获取测试计划及其包含的所有测试 |
| `get_test_set` | 获取测试集合及其包含的所有测试 |
| `get_test_execution_report` | 测试执行的通过/失败总结 |
| `get_tests_for_requirement` | 涵盖 Jira 故事或需求的所有测试 |
| `create_test_case` | 创建带有步骤的新手动测试用例 |
| `create_test_execution` | 创建测试执行并添加测试用例 |
| `update_test_run_status` | 设置运行的通过 / 失败 / 阻塞 / 待处理 / 执行中状态 |
## 先决条件
- **Node.js ≥ 18** 在您的 PATH 中
- **Xray 云端 API 密钥** — 在 Jira 中：**Xray → 设置 → API 密钥** → 创建密钥 → 复制 **客户端 ID** 和 **客户端密钥**。[文档](https://docs.getxray.app/display/XRAYCLOUD/Global+Settings%3A+API+Keys)
## 从 Cursor 市场安装
1. 在 Cursor 侧边栏中打开 **自定义**。
2. 搜索 **Xray 云端** 并点击 **安装**。
3. 将您的凭证设置为环境变量（参见下文）并重启 Cursor。
## 手动安装
将以下内容添加到您的 `~/.cursor/mcp.json` 或 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"xray": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@tzur_avner/xray-mcp"],
"env": {
"XRAY_BASE_URL": "https://eu.xray.cloud.getxray.app",
"XRAY_CLIENT_ID": "您的客户端 ID",
"XRAY_CLIENT_SECRET": "您的客户端密钥"
}
}
}
}
```
保存后重启 Cursor。
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `XRAY_CLIENT_ID` | 是 | — | Xray 云端 API 密钥客户端 ID |
| `XRAY_CLIENT_SECRET` | 是 | — | Xray 云端 API 密钥客户端密钥 |
| `XRAY_BASE_URL` | 否 | `https://eu.xray.cloud.getxray.app` | 美国地区的覆盖：`https://xray.cloud.getxray.app` |
> **地区说明：** Xray 云端按地区分区。如果您的数据在 **美国地区**，请设置 `XRAY_BASE_URL=https://xray.cloud.getxray.app`。默认为欧盟。
## 使用示例
```
获取测试用例 XSP-684
搜索项目 XSP 中带有标签 "smoke" 的测试用例
获取测试计划 XSP-836 中的所有测试
显示 XSP-900 的执行报告
哪些测试涵盖故事 AIR-42？
```
## 验证连接
安装后，打开 **工具和 MCP**（`Ctrl+Shift+J`）— `xray` 服务器应显示已连接。如果未连接，请检查 **输出 → MCP 日志**。
## 致谢
基于 [SamtheIII/XRAY-MCP](https://github.com/SamtheIII/XRAY-MCP)（MIT）。
应用补丁：
- 通过 `XRAY_BASE_URL` 实现区域感知端点（上游硬编码美国；此处默认为欧盟）
- 带有完整分页的 `get_test_plan` 和 `get_test_set` 工具（本地添加）
## 许可证
MIT — 请参见 [LICENSE](LICENSE)。
