使用说明

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 文件，用于说明测试相关内容）

安装

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

npm install

构建项目：

npm run build

如何获取API凭据

访问 https://xray.cloud.getxray.app/
导航至设置 → API密钥
点击 创建API密钥
复制生成的客户端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服务器来：

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

测试管理