麦克佩射线

作者：Korfu1 星标更新：2025-11-14

安装使用来源：spider==github.com

项目介绍

Xray MCP

一个集成Cursor IDE与Jira中的Xray测试管理的Model Context Protocol (MCP)服务器，允许您直接从开发环境中管理测试、测试执行和测试计划。

功能

测试

列出测试：从您的Jira项目中获取所有测试，并提供过滤选项
获取测试详情：检索详细的测试信息，包括通过GraphQL获取的测试步骤✨
获取带有步骤的测试：新功能！ 使用GraphQL getTests查询可靠地获取带有步骤的测试详情🚀
创建测试：创建新的手动或自动化测试
更新测试：修改现有测试

测试执行

列出测试执行：查看项目中的所有测试执行
获取测试执行详情：查看详细的执行结果，包括测试运行
创建测试执行：创建新的测试执行会话
更新测试运行：记录测试结果（PASS, FAIL, TODO, EXECUTING, ABORTED）

测试计划

列出测试计划：查看项目中的所有测试计划
获取测试计划详情：查看测试计划信息及其关联的测试
创建测试计划：创建新的测试计划
将测试添加到测试计划：将测试与现有的计划关联

测试集

列出测试集：查看项目中的所有测试集
获取测试集详情：查看测试集信息及其关联的测试

导入操作（CI/CD集成）🚀 新功能！

导入Xray JSON结果：导入Xray JSON格式的测试执行结果
导入Cucumber结果：导入Cucumber JSON测试结果
导入JUnit结果：导入JUnit XML测试结果
导入TestNG结果：导入TestNG XML测试结果
导入NUnit结果：导入NUnit XML测试结果
导入Robot Framework结果：导入Robot Framework XML测试结果
导入Behave结果：导入Behave JSON测试结果
导入特性文件：导入Cucumber .feature文件（BDD场景）

导出操作📤 新功能！

导出Cucumber特性：从Xray导出Cucumber特性文件

前提条件

Node.js 18或更高版本
npm 或 yarn
安装了Xray测试管理插件的Jira Cloud账户
用于身份验证的Jira API令牌

安装

方案1：从npm安装（推荐）

该包在npm上可用，可以直接使用npx：

npx @korfu/xray-mcp

无需安装！继续到生成Jira API令牌部分。

方案2：本地开发设置

如果您想贡献代码或修改代码：

1. 克隆仓库

git clone https://github.com/Korfu/mcp-xray.git
cd mcp-xray

2. 安装依赖

npm install

3. 构建项目

npm run build

设置

生成Jira API令牌

转到Atlassian账户设置
点击“创建API令牌”
给它一个描述性的名称（例如，“Xray MCP集成”）
复制生成的令牌——您将无法再次看到它！

配置环境变量

您需要以下环境变量：

必需：

JIRA_BASE_URL：您的Jira实例URL（例如，https://your-domain.atlassian.net）
JIRA_EMAIL：您的Jira账户电子邮件
JIRA_API_TOKEN：第3步中的API令牌

可选（用于测试步骤）：

XRAY_CLIENT_ID：您的Xray Cloud API客户端ID
XRAY_CLIENT_SECRET：您的Xray Cloud API客户端密钥

获取Xray Cloud API凭证（可选 - 用于测试步骤）

要从Xray获取测试步骤，您需要Xray Cloud API凭证：

登录到您的Jira实例
转到设置(⚙️) → 应用 → 管理应用
在左侧边栏中找到Xray部分
点击API密钥（或云API）
点击创建API密钥
给它一个名称（例如，“MCP集成”）
复制客户端ID和客户端密钥
安全保存这些信息——您将无法再次看到密钥！

注意：没有Xray Cloud API凭证，MCP仍然可以用于列出和管理测试，但不会获取测试步骤。

将配置添加到Cursor MCP设置

将以下配置添加到您的Cursor MCP设置文件中（通常位于~/.cursor/mcp.json或类似位置）：

对于npm安装（推荐）：

{
  "mcpServers": {
    "xray": {
      "command": "npx",
      "args": ["-y", "@korfu/xray-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token-here",
        "XRAY_CLIENT_ID": "your-xray-client-id",
        "XRAY_CLIENT_SECRET": "your-xray-client-secret"
      }
    }
  }
}

重要提示：

用实际凭据替换值
XRAY_CLIENT_ID和XRAY_CLIENT_SECRET是可选的——如果不需要测试步骤详细信息，则省略它们

重启Cursor

添加配置后，重启Cursor IDE以加载MCP服务器。

使用

配置完成后，您可以在Cursor中使用以下工具：

测试

list_tests - 列出项目中的所有测试
get_test - 获取详细的测试信息（可能不总是返回步骤）
get_test_with_steps - 新功能！ 获取带有步骤的详细测试信息（使用可靠的GraphQL查询）
create_test - 创建一个新的测试
update_test - 更新现有的测试

测试执行

list_test_executions - 列出测试执行
get_test_execution - 获取测试执行详情
create_test_execution - 创建新的测试执行
update_test_run - 更新测试运行状态

测试计划

list_test_plans - 列出所有测试计划
get_test_plan - 获取测试计划详情
create_test_plan - 创建新的测试计划
add_tests_to_test_plan - 将测试添加到计划

测试集

list_test_sets - 列出所有测试集
get_test_set - 获取测试集详情

导入操作🚀 新功能！

import_execution_results - 导入Xray JSON格式的结果
import_cucumber_results - 导入Cucumber JSON结果
import_junit_results - 导入JUnit XML结果
import_testng_results - 导入TestNG XML结果
import_nunit_results - 导入NUnit XML结果
import_robot_results - 导入Robot Framework XML结果
import_behave_results - 导入Behave JSON结果
import_feature_file - 导入Cucumber .feature文件

导出操作📤 新功能！

export_cucumber_features - 将Cucumber特性导出为.feature文件

示例

基本操作

获取带有步骤的测试（推荐）

获取带有步骤的测试 EXM-123

这使用了新的get_test_with_steps工具，可以可靠地获取测试步骤。

输出包含测试步骤：

**测试：EXM-123**
**摘要：** 验证用户登录功能

**测试类型：** 手动

**测试步骤：**

**步骤1：**
- **动作：** 导航至登录页面
- **数据：** URL: https://example.com/login
- **预期结果：** 显示登录页面

**步骤2：**
- **动作：** 输入有效凭证并点击提交
- **数据：** 用户名：testuser，密码：********
- **预期结果：** 用户成功认证

**步骤3：**
- **动作：** 验证用户仪表板是否显示
- **数据：** N/A
- **预期结果：** 仪表板显示用户资料和导航菜单

CI/CD集成示例🚀

导入JUnit结果

从文件test-results/junit.xml导入JUnit测试结果

导入Cucumber结果

从文件cucumber-report.json导入Cucumber结果

导出特性文件

为测试EXM-1,EXM-2,EXM-3导出Cucumber特性

旧版示例

列出项目中的测试

列出项目PROJ中标记为“回归”的所有测试

创建测试

在项目PROJ中创建一个新的手动测试，摘要为“登录验证测试”，描述为“验证用户可以使用有效凭证登录”

更新测试运行状态

更新测试PROJ-123在执行PROJ-456中的运行状态为PASS，并附注“所有断言通过”

创建测试执行

在项目PROJ中创建一个测试执行，摘要为“冲刺5回归”，并添加测试PROJ-123, PROJ-124, PROJ-125

开发

在开发模式下运行

npm run dev

构建

npm run build

项目结构

XRayMCP/
├── src/
│   ├── index.ts                  # 主MCP服务器
│   ├── types.ts                  # TypeScript接口
│   ├── services/
│   │   └── XrayCloudService.ts   # Xray Cloud API服务（GraphQL + REST）
│   └── tools/
│       ├── tests/                # 测试操作
│       │   ├── listTests.ts
│       │   ├── getTest.ts
│       │   ├── createTest.ts
│       │   └── updateTest.ts
│       ├── test-executions/      # 测试执行操作
│       │   ├── listTestExecutions.ts
│       │   ├── getTestExecution.ts
│       │   ├── createTestExecution.ts
│       │   └── updateTestRun.ts
│       ├── test-plans/           # 测试计划操作
│       │   ├── listTestPlans.ts
│       │   ├── getTestPlan.ts
│       │   ├── createTestPlan.ts
│       │   └── addTestsToTestPlan.ts
│       ├── test-sets/            # 测试集操作
│       │   ├── listTestSets.ts
│       │   └── getTestSet.ts
│       ├── import/               # 导入操作（新功能！）
│       │   ├── importExecutionResults.ts
│       │   ├── importCucumberResults.ts
│       │   ├── importJUnitResults.ts
│       │   ├── importTestNGResults.ts
│       │   ├── importNUnitResults.ts
│       │   ├── importRobotResults.ts
│       │   ├── importBehaveResults.ts
│       │   └── importFeatureFile.ts
│       └── export/               # 导出操作（新功能！）
│           └── exportC_ucumberFeatures.ts
├── dist/                         # 编译后的JavaScript输出
├── XRAY_CLOUD_API_V2_ENDPOINTS.md     # API文档
├── XRAY_CLOUD_V2_IMPLEMENTATION.md    # 实现细节
├── package.json
├── tsconfig.json
└── README.md

API架构

Xray Cloud API v2 - 双重方法

此MCP服务器使用Xray Cloud提供的两个互补API：

1. GraphQL API（用于查询）

端点： https://xray.cloud.getxray.app/api/v2/graphql
用途： 获取带有步骤的测试详情
原因： Xray Cloud仅通过GraphQL暴露测试步骤，而不是REST

query {
  getTest(issueId: "EXM-123") {
    issueId
    steps {
      id
      action
      data
      result
    }
  }
}

2. REST API v2（用于导入/导出）

基础URL： https://xray.cloud.getxray.app/api/v2
用途： 导入测试结果，导出特性
端点：
- POST /import/execution/* - 导入结果（多种格式）
- POST /import/feature - 导入BDD特性
- GET /export/cucumber - 导出BDD特性

认证

所有操作都使用通过以下方式获得的JWT Bearer令牌：

POST /api/v2/authenticate
Body: { client_id, client_secret }
Response: "eyJhbGciOiJIUzI1NiI..."

令牌：

缓存50分钟
自动刷新
仅存储在内存中（不持久化）

故障排除

认证问题

验证您的Jira电子邮件和API令牌是否正确
确保API令牌具有正确的权限
检查您的Jira基础URL是否正确（不应以斜杠结尾）

“测试类型未找到”错误

确保Xray已安装在您的Jira实例中
验证项目是否启用了Xray
检查您是否有权限在项目中创建问题

连接问题

验证您的互联网连接
检查您的Jira实例是否可访问
确保MCP服务器正在运行（检查Cursor的MCP日志）

测试未找到

验证测试键是否正确（例如，PROJ-123）
确保您有权访问该测试
检查该测试是否存在于Jira中

MCP服务器未加载

验证dist/index.js路径在您的Cursor配置中是否正确
确保Node.js已安装且可以从命令行访问
检查Cursor的MCP服务器日志中的错误消息
确保您已运行npm run build以编译TypeScript代码

测试步骤未出现

确保您已在MCP配置中设置了XRAY_CLIENT_ID和XRAY_CLIENT_SECRET
验证您的Xray Cloud API凭证是否正确
检查您的Xray许可证是否包括API访问
测试必须是手动测试类型（Cucumber和通用测试有不同的步骤格式）
检查Cursor的MCP日志中的认证错误

使用的API端点

此MCP使用以下Jira和Xray API端点：

Jira REST API v3：/rest/api/3/search/jql，/rest/api/3/issue/* 用于一般问题操作
Xray Cloud API v2：https://xray.cloud.getxray.app/api/v2/* 用于测试步骤和详细的测试信息（可选）

安全注意事项

保护好您的Jira API令牌，切勿将其提交到版本控制中
保护好您的Xray Cloud API凭证（客户端ID和密钥）
使用环境变量或安全配置管理来存储凭证
API令牌应仅具有所需的最小权限
考虑定期轮换API令牌
Xray API凭证与Jira凭证分开，并提供对测试数据的访问

贡献

分叉仓库
创建功能分支
进行更改
如适用，请添加测试
提交拉取请求

许可证

MIT许可证 - 详见LICENSE文件

作者

Korfu

致谢

根据Model Context Protocol规范构建
受BitbucketMCP实现模式启发
使用Xblend的Xray测试管理插件

麦克佩射线

项目介绍

Xray MCP

功能

测试

测试执行

测试计划

测试集

导入操作（CI/CD集成）🚀 新功能！

导出操作📤 新功能！

前提条件

安装

方案1：从npm安装（推荐）

方案2：本地开发设置

1. 克隆仓库

2. 安装依赖

3. 构建项目

设置

生成Jira API令牌

配置环境变量

获取Xray Cloud API凭证（可选 - 用于测试步骤）

将配置添加到Cursor MCP设置

重启Cursor

使用

测试

测试执行

测试计划

测试集

导入操作🚀 新功能！

导出操作📤 新功能！

示例

基本操作

获取带有步骤的测试（推荐）

CI/CD集成示例🚀

导入JUnit结果

导入Cucumber结果

导出特性文件

旧版示例

列出项目中的测试

创建测试

更新测试运行状态

创建测试执行

开发

在开发模式下运行

构建

项目结构

API架构

Xray Cloud API v2 - 双重方法

1. GraphQL API（用于查询）

2. REST API v2（用于导入/导出）

认证

故障排除

认证问题

“测试类型未找到”错误

连接问题

测试未找到

MCP服务器未加载

测试步骤未出现

使用的API端点

安全注意事项

贡献

相关资源

许可证

作者

致谢