Xray MCP Server

Xray MCP 服务器

模型上下文协议（MCP）服务器，用于将Xray Cloud API与Claude Code及其他MCP客户端进行集成。

特点/特性

这个MCP服务器提供了工具，可以使用官方GraphQL API在Xray Cloud中管理测试用例和测试执行：

测试用例（测试管理）

• 创建测试用例创建一个新的测试用例（使用GraphQL突变） createTest)
• 获取测试用例检索特定测试用例的详细信息（使用GraphQL查询） getTests)
• 删除测试用例删除一个测试用例（使用GraphQL突变） deleteTest）
• 搜索测试用例使用JQL（Jira查询语言）搜索测试用例
• 获取项目测试用例获取项目中的所有测试用例
• 更新测试用例⚠️ 不直接支持 - 请使用Jira REST API来更新标准字段

测试执行（测试自动化与持续集成/持续交付）

• 创建测试执行创建一个新的测试执行以运行测试
• 获取测试执行（信息/结果）获取包含所有测试运行的测试执行详情
• 搜索测试执行使用JQL搜索测试执行情况
• 获取项目测试执行情况获取项目的所有测试执行记录
• 更新测试运行状态更新测试运行的状态（通过、失败等）

测试计划（测试组织）

• 创建测试计划创建一个新的测试计划来组织测试
• 获取测试计划检索包含所有测试的特定测试计划的详细信息
• 搜索测试计划使用JQL搜索测试计划
• 获取项目测试计划检索一个项目的所有测试计划
• 向测试计划中添加测试向现有测试计划中添加测试
• 从测试计划中移除测试从测试计划中移除测试

测试集（测试分组）

• 创建测试集创建一个新的测试集以分组测试
• 获取测试集检索包含所有测试的特定测试集的详细信息
• 搜索测试集使用JQL搜索测试集
• 获取项目测试集获取一个项目的所有测试集
• 将测试添加到测试集中向现有测试集中添加测试
• 从测试集中移除测试从测试集中移除测试

先决条件

• Node.js 18 或更高版本
• Xray Cloud API 凭证（客户端ID和客户端密钥）

测试

这个项目涵盖了全面的测试范围：

• 单元测试快速测试，使用模拟的API响应（无需凭据）
• 集成测试使用真实的Xray Cloud API进行端到端测试

# Run unit tests
npm run test:unit

# Run integration tests (requires credentials)
npm run test:integration

# Run all tests
npm test

如需详细的测试文档，请参阅 TESTING.md 翻译为中文是：“测试说明文件.md” 或 “测试文档.md”（具体翻译可能根据上下文有所调整，但基本意思是指一个名为 TESTING 的 Markdown 文件，用于说明测试相关内容）

安装

1. 克隆或下载此仓库
2. 安装依赖项：

npm install

1. 构建项目：

npm run build

如何获取API凭据

1. 访问 https://xray.cloud.getxray.app/
2. 导航至 设置 → API密钥
3. 点击 创建API密钥
4. 复制生成的客户端ID和客户端密钥

使用

在Claude代码中的配置

要使用此MCP服务器与Claude Code配合，需将以下配置添加到您的MCP配置文件中（通常为 ~/Library/Application Support/Claude/claude_desktop_config.json （在 macOS 上）：

{
  "mcpServers": {
    "xray": {
      "command": "node",
      "args": ["/path/to/xray-mcp/dist/index.js"],
      "env": {
        "XRAY_CLIENT_ID": "your_client_id",
        "XRAY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

重要提示： 替换：

• /path/to/xray-mcp 带有项目绝对路径（例如。， /Users/manuel/repositories/xray-mcp）
• your_client_id 和 your_client_secret 使用您的Xray Cloud凭据

本地测试

在开发模式下测试服务器：

# Set environment variables
export XRAY_CLIENT_ID="your_client_id"
export XRAY_CLIENT_SECRET="your_client_secret"

# Run the server
npm run dev

使用示例

测试用例

创建一个测试用例

{
  "projectKey": "ABC",
  "summary": "Verify login functionality",
  "description": "Test that users can log in with valid credentials",
  "testType": "Manual",
  "labels": ["login", "authentication"],
  "priority": "High"
}

搜索测试用例

{
  "jql": "project = ABC AND labels = automation",
  "maxResults": 20
}

检索项目测试用例

{
  "projectKey": "ABC",
  "maxResults": 50
}

测试执行

创建测试执行

{
  "projectKey": "ABC",
  "summary": "Sprint 23 Regression Tests",
  "description": "Regression testing for sprint 23",
  "testIssueIds": ["10001", "10002", "10003"],
  "testEnvironments": ["Chrome", "Firefox"]
}

检索测试执行

{
  "testExecutionKey": "ABC-456"
}

更新测试运行状态

{
  "testRunId": "5acc7ab0a3fe1b6fcdc3c737",
  "status": "PASS"
}

搜索最近的测试执行记录

{
  "jql": "project = ABC AND created >= -7d",
  "maxResults": 20
}

项目结构

xray-mcp/
├── src/
│   ├── index.ts           # Main MCP server
│   └── xray-client.ts     # Client for Xray Cloud APIs
├── dist/                  # Compiled files (generated after build)
├── .env.example           # Template for environment variables
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

Xray 云APIs

此服务器使用以下Xray云API：

• 认证: POST /api/v1/authenticate （令牌有效期为24小时）
• GraphQL 端点： POST /api/v2/graphql

- 测试查询： getTests - 使用JQL检索测试 - 测试突变： createTest， deleteTest - 创建/删除测试 - 测试执行查询： getTestExecutions - 使用JQL检索执行记录 - 测试执行变异： createTestExecution， updateTestRunStatus - 管理执行过程和结果 - 测试计划查询： getTestPlans - 使用JQL检索测试计划 - 测试计划变异（或：测试计划的修改/变更）: createTestPlan， addTestsToTestPlan， removeTestsFromTestPlan - 管理测试计划 - 测试集查询: getTestSets - 使用JQL检索测试集 - 测试集突变: createTestSet， addTestsToTestSet， removeTestsFromTestSet - 管理测试集

如需完整的API文档，请访问：

• GraphQL API：https://docs.getxray.app/display/XRAYCLOUD/GraphQL+API
• GraphQL 模式（Schema）: https://us.xray.cloud.getxray.app/doc/graphql/
• REST API：https://docs.getxray.app/display/XRAYCLOUD/REST+API

用例

持续集成/持续交付（CI/CD）集成

使用此MCP服务器来：

1. 在CI/CD流水线中自动创建测试执行
2. 根据自动化测试结果更新测试运行状态
3. 跨不同环境跟踪测试执行情况
4. 为冲刺评审生成测试执行报告

测试管理

使用此MCP服务器来：

1. 创建并组织测试用例
2. 使用复杂JQL查询进行搜索测试
3. 管理手动测试执行
4. 跟踪随时间变化的测试状态

许可证

ISC（互联网标准委员会/国际标准委员会，具体含义根据上下文而定）

支持

关于Xray Cloud API的问题或疑问，请查阅官方文档：

• https://docs.getxray.app/ 的中文翻译可以是：“https://getxray文档中心/” 或者 “https://xray官方文档/”。这里，“getxray”或“xray”通常指的是一个用于测试管理的工具或平台，而“docs”则代表文档（documentation）部分。因此，整个网址可以理解为指向该工具或平台的官方文档页面
• https://support.getxray.app/（该网址可译为：“Xray应用支持页面”，但通常网址本身不直接翻译，此处仅为说明其可能的中文语境含义）