使用说明

X射线MCP

一个模型上下文协议（MCP）服务器，它将Cursor IDE与Jira的Xray测试管理集成在一起，允许您直接从开发环境中管理测试、测试执行和测试计划。

特性

测试

列出测试：使用筛选选项从Jira项目中获取所有测试
获取测试详细信息：检索详细的测试信息 包括通过GraphQL的测试步骤 ✨
分步获取测试: 新使用GraphQL通过步骤可靠地获取测试细节 getTests 怎么翻译🚀
创建测试：创建新的手动或自动测试
更新测试：修改现有测试

测试执行

列出测试执行：查看项目中的所有测试执行
获取测试执行详细信息：查看包括测试运行在内的详细执行结果
创建测试执行：创建新的测试执行会话
更新测试运行：记录测试结果（通过、未通过、待办、执行、中止）

测试计划

列出测试计划：查看项目中的所有测试计划
获取测试计划详细信息：查看相关测试的测试计划信息
创建测试计划：创建新的测试计划
将测试添加到测试计划中：将测试与现有计划联系起来

测试集

列出测试集：查看项目中的所有测试集
获取测试集详细信息：请参阅相关测试的测试集信息

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

导入X射线JSON结果：以Xray JSON格式导入测试执行结果
导入黄瓜结果：导入Cucumber JSON测试结果
导入JUnit结果：导入JUnitXML测试结果
导入测试结果：导入TestNG XML测试结果
导入NUnit结果：导入NUnit XML测试结果
导入机器人框架结果：导入Robot Framework XML测试结果
导入行为结果：导入Behave JSON测试结果
导入功能文件：导入Cucumber.feature文件（BDD场景）

出口业务📤 新

导出黄瓜特性：从X射线导出Cucumber特征文件

先决条件

Node.js 18或更高版本
npm或纱线
安装了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令牌”
给它一个描述性的名称（例如，“X射线MCP集成”）
复制生成的令牌- 你再也看不到了！

4.配置环境变量

您需要以下环境变量：

必修的：

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

可选（用于测试步骤）：

XRAY_CLIENT_ID：您的X射线云API客户端ID
XRAY_CLIENT_SECRET：您的X射线云API客户端机密

4.1.获取X射线云API凭据（可选-用于测试步骤）

若要从X射线获取测试步骤，您需要X射线云API凭据：

登录您的Jira实例
首选 设置(⚙️) → 应用 → 管理应用程序
在左侧边栏中，找到 X射线 章节
点击 API密钥 （或 云API)
点击 创建API密钥
为其命名（例如，“MCP集成”）
复制 客户端ID 和 客户端密钥
安全地保存这些——你将无法再看到这个秘密！

注：如果没有Xray Cloud API证书，MCP仍将用于列出和管理测试，但不会提取测试步骤。

5.添加到光标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 是可选的-如果您不需要测试步骤的详细信息，请省略它们

6.重新启动游标

添加配置后，重新启动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 -导入X射线JSON格式结果
import_cucumber_results -导入Cucumber JSON结果
import_junit_results -导入JUnitXML结果
import_testng_results -导入TestNG XML结果
import_nunit_results -导入NUnit XML结果
import_robot_results -导入机器人框架XML结果
import_behave_results -导入行为JSON结果
import_feature_file -导入Cucumber.feature文件

出口业务📤 新

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

例子

基本操作

分步测试（推荐）

Get test EXM-123 with steps

这使用了新 get_test_with_steps 该工具能够可靠地获取测试步骤。

输出包括测试步骤：

**Test: EXM-123**
**Summary:** Verify user login functionality

**Test Type:** Manual

**Test Steps:**

**Step 1:**
- **Action:** Navigate to the login page
- **Data:** URL: https://example.com/login
- **Expected Result:** Login page is displayed

**Step 2:**
- **Action:** Enter valid credentials and click Submit
- **Data:** Username: testuser, Password: ********
- **Expected Result:** User is successfully authenticated

**Step 3:**
- **Action:** Verify user dashboard is displayed
- **Data:** N/A
- **Expected Result:** Dashboard shows user profile and navigation menu

CI/CD集成示例🚀

导入JUnit结果

Import JUnit test results from file test-results/junit.xml

导入黄瓜结果

Import Cucumber results from file cucumber-report.json

导出要素文件

Export Cucumber features for tests EXM-1,EXM-2,EXM-3

遗留示例

列出项目中的测试

List all tests in project PROJ with label "regression"

创建测试

Create a new manual test in project PROJ with summary "Login validation test" and description "Verify user can login with valid credentials"

更新测试运行状态

Update test run for test PROJ-123 in execution PROJ-456 with status PASS and comment "All assertions passed"

创建测试执行

Create a test execution in project PROJ with summary "Sprint 5 Regression" and add tests PROJ-123, PROJ-124, PROJ-125

发展

以开发模式运行

npm run dev

建筑

npm run build

项目结构

XRayMCP/
├── src/
│   ├── index.ts                  # Main MCP server
│   ├── types.ts                  # TypeScript interfaces
│   ├── services/
│   │   └── XrayCloudService.ts   # Xray Cloud API service (GraphQL + REST)
│   └── tools/
│       ├── tests/                # Test operations
│       │   ├── listTests.ts
│       │   ├── getTest.ts
│       │   ├── createTest.ts
│       │   └── updateTest.ts
│       ├── test-executions/      # Test execution operations
│       │   ├── listTestExecutions.ts
│       │   ├── getTestExecution.ts
│       │   ├── createTestExecution.ts
│       │   └── updateTestRun.ts
│       ├── test-plans/           # Test plan operations
│       │   ├── listTestPlans.ts
│       │   ├── getTestPlan.ts
│       │   ├── createTestPlan.ts
│       │   └── addTestsToTestPlan.ts
│       ├── test-sets/            # Test set operations
│       │   ├── listTestSets.ts
│       │   └── getTestSet.ts
│       ├── import/               # Import operations (NEW!)
│       │   ├── importExecutionResults.ts
│       │   ├── importCucumberResults.ts
│       │   ├── importJUnitResults.ts
│       │   ├── importTestNGResults.ts
│       │   ├── importNUnitResults.ts
│       │   ├── importRobotResults.ts
│       │   ├── importBehaveResults.ts
│       │   └── importFeatureFile.ts
│       └── export/               # Export operations (NEW!)
│           └── exportCucumberFeatures.ts
├── dist/                         # Compiled JavaScript output
├── XRAY_CLOUD_API_V2_ENDPOINTS.md     # API documentation
├── XRAY_CLOUD_V2_IMPLEMENTATION.md    # Implementation details
├── package.json
├── tsconfig.json
└── README.md

API体系结构

X射线云API v2-双重方法

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

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是否正确（不应以斜线结尾）

“未找到测试问题类型”错误

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

连接问题

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

未找到测试

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

MCP服务器未加载

验证路径 dist/index.js 游标配置正确
确保Node.js已安装并可从命令行访问
检查Cursor的MCP服务器日志中的错误消息
确保你已经跑过了 npm run build 编译TypeScript代码

测试步骤未显示

确保您已配置 XRAY_CLIENT_ID 和 XRAY_CLIENT_SECRET 在MCP配置中
验证您的X射线云API凭据是否正确
检查您的X射线许可证是否包括API访问权限
测试必须是手动测试类型（Cucumber和Generic测试具有不同的步骤格式）
检查Cursor的MCP日志是否存在身份验证错误

使用的API端点

此MCP使用以下Jira和X射线API端点：

Jira REST API v3: /rest/api/3/search/jql, /rest/api/3/issue/* 用于一般发行操作
X射线云API v2: https://xray.cloud.getxray.app/api/v2/* 用于测试步骤和详细测试信息（可选）

安全说明

保持Jira API令牌的安全，并且永远不要将其提交给版本控制
确保您的X射线云API凭据（客户端ID和机密）的安全
使用环境变量或安全配置管理凭据
API令牌应仅具有所需的最低权限
考虑定期轮换您的API代币
X射线API凭证与Jira凭证分开，并提供对测试数据的访问

贡献

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

作者

科夫岛

致谢

按照模型上下文协议规范构建
受BitbucketMCP实现模式的启发
Xblend为Jira使用X射线测试管理

使用说明

X射线MCP

特性

测试

测试执行

测试计划

测试集

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

出口业务📤 新

先决条件

安装

选项1：从npm安装（推荐）

选项2：地方发展设置

1.克隆存储库

2.安装依赖项

3.建设项目

设置

生成Jira API代币

4.配置环境变量

4.1.获取X射线云API凭据（可选-用于测试步骤）

5.添加到光标MCP配置

6.重新启动游标

用法

测试

测试执行

测试计划

测试集

进口业务🚀 新

出口业务📤 新

例子

基本操作

分步测试（推荐）

CI/CD集成示例🚀

导入JUnit结果

导入黄瓜结果

导出要素文件

遗留示例

列出项目中的测试

创建测试

更新测试运行状态

创建测试执行

发展

以开发模式运行

建筑

项目结构

API体系结构

X射线云API v2-双重方法

1.GraphQL API（用于查询）

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

认证

故障排除

身份验证问题

“未找到测试问题类型”错误

连接问题

未找到测试

MCP服务器未加载

测试步骤未显示

使用的API端点

安全说明

贡献

相关资源

许可证

作者

致谢

相关 MCP

代码分析MCP服务器

AgentShield 智能体配置安全审计器

Jira集成服务

GitHub-Jira集成服务

Jira API集成工具

Schema版本控制工具包