Xray MCP

🚀 Xray MCP 服务器

Xray MCP 服务器用于将 Xray Cloud API 与 Claude Code 及其他 MCP 客户端集成，借助官方 GraphQL API 管理 Xray Cloud 中的测试用例和测试执行。

✨ 主要特性

此 MCP 服务器提供了一系列工具，可使用官方 GraphQL API 管理 Xray Cloud 中的测试用例和测试执行：

测试用例（测试管理）

• create_test_case：创建新的测试用例（使用 GraphQL 变异 createTest）
• get_test_case：检索特定测试用例的详细信息（使用 GraphQL 查询 getTests）
• delete_test_case：删除测试用例（使用 GraphQL 变异 deleteTest）
• search_test_cases：使用 JQL（Jira 查询语言）搜索测试用例
• get_project_test_cases：检索项目的所有测试用例
• update_test_case：⚠️ 不直接支持 - 使用 Jira REST API 更新标准字段

测试执行（测试自动化与 CI/CD）

• create_test_execution：创建新的测试执行以运行测试
• get_test_execution：检索包含所有测试运行的测试执行详细信息
• search_test_executions：使用 JQL 搜索测试执行
• get_project_test_executions：检索项目的所有测试执行
• update_test_run_status：更新测试运行的状态（通过、失败等）

测试计划（测试组织）

• create_test_plan：创建新的测试计划以组织测试
• get_test_plan：检索包含所有测试的特定测试计划的详细信息
• search_test_plans：使用 JQL 搜索测试计划
• get_project_test_plans：检索项目的所有测试计划
• add_tests_to_test_plan：将测试添加到现有测试计划中
• remove_tests_from_test_plan：从测试计划中移除测试

测试集（测试分组）

• create_test_set：创建新的测试集以分组测试
• get_test_set：检索包含所有测试的特定测试集的详细信息
• search_test_sets：使用 JQL 搜索测试集
• get_project_test_sets：检索项目的所有测试集
• add_tests_to_test_set：将测试添加到现有测试集中
• remove_tests_from_test_set：从测试集中移除测试

📦 安装指南

前提条件

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

安装步骤

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

npm install

3. 构建项目：

npm run build

如何获取 API 凭证

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

💻 使用示例

测试用例

创建测试用例

{
  "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
}

在 Claude Code 中配置

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

{
  "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 凭证

本地测试

要在开发模式下测试服务器，请执行以下操作：

# 设置环境变量
export XRAY_CLIENT_ID="your_client_id"
export XRAY_CLIENT_SECRET="your_client_secret"

# 运行服务器
npm run dev

📚 详细文档

项目结构

xray-mcp/
├── src/
│   ├── index.ts           # 主 MCP 服务器
│   └── xray-client.ts     # Xray Cloud API 客户端
├── dist/                  # 编译后的文件（构建后生成）
├── .env.example           # 环境变量模板
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

Xray Cloud API

此服务器使用以下 Xray Cloud 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 架构：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. 生成用于 sprint 评审的测试执行报告

测试管理

使用此 MCP 服务器可以：

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

📄 许可证

ISC

支持

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

• https://docs.getxray.app/
• https://support.getxray.app/