Zephyr MCP server

Zephyr Scale MCP服务器

用于Zephyr Scale测试管理的模型上下文协议服务器，支持两者 Jira云和数据中心.通过带有的Atlassian REST API创建、读取和管理测试用例 符合API的官方模式通过统一的资源系统访问实时测试用例数据、示例有效载荷和文件资源。

特性

• ✅ Jira云和数据中心支持：通过自动配置检测无缝连接到Jira Cloud（使用API v2）和自托管数据中心实例（使用API v1）。
• ✅ 符合API的官方架构：工具和数据结构与官方Zephyr Scale REST API相匹配，确保兼容性和可靠性。
• ✅ 统一测试用例创建：单身 create_test_case 该工具处理所有脚本类型（BDD、分步、纯文本），以简化工作流程。
• ✅ 全测试生命周期管理：用于创建、读取、删除测试用例以及管理测试运行、执行和文件夹的综合工具。
• ✅ 实时模板系统：使用Zephyr实例中的真实测试用例作为模板(zephyr://testcase/KEY)确保一致性和正确的项目特定字段。
• ✅ 统一资源系统：访问Zephyr实时数据、本地文件(file://)，并通过一致的基于URI的系统内置示例。

安装和配置

您可以使用以下命令运行服务器 npx 无需安装，或从全局安装 npm.

使用npx（推荐）

使用以下结构配置MCP客户端。

Jira Cloud：

{
  "mcpServers": {
    "zephyr-server": {
      "command": "npx",
      "args": ["zephyr-scale-mcp-server@latest"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-company.atlassian.net",
        "ZEPHYR_API_KEY": "your-zephyr-api-key",
        "JIRA_USERNAME": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token"
      }
    }
  }
}

备注: JIRA_USERNAME 和 JIRA_API_TOKEN 是可选的，但如果您想使用 issue_links 创建测试用例时使用字段。没有它们，问题链接将失败，并显示401警告（测试用例仍在创建中）。在生成Jira API令牌 id.atlassian.com/manage-profile/security/api-tokens.

Jira Cloud（欧盟地区）：

{
  "mcpServers": {
    "zephyr-server": {
      "command": "npx",
      "args": ["zephyr-scale-mcp-server@latest"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-company.atlassian.net",
        "ZEPHYR_API_KEY": "your-zephyr-api-key",
        "JIRA_USERNAME": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "ZEPHYR_API_BASE_URL": "https://eu.api.zephyrscale.smartbear.com/v2"
      }
    }
  }
}

Jira数据中心：

{
  "mcpServers": {
    "zephyr-server": {
      "command": "npx",
      "args": ["zephyr-scale-mcp-server@latest"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-jira-server.com",
        "ZEPHYR_API_KEY": "your-api-token"
      }
    }
  }
}

使用全局npm安装

首先全局安装软件包：

npm install -g zephyr-scale-mcp-server

然后，更新 command 在MCP配置中 "command": "zephyr-scale-mcp".

核心概念

统一API

最新版本具有 统一的 create_test_case 工具 它通过一个一致的接口支持所有测试脚本类型（STEP_BY_STEP、PLAIN_TEXT和BDD）。这与官方Zephyr Scale REST API v1结构完全匹配，简化了测试创建过程。

Jira云与数据中心

服务器会自动检测您的Jira环境，并使用相应的API版本：

• 吉拉云：使用Zephyr Scale API v2。
• Jira数据中心：使用Zephyr Scale API v1。

有些工具是特定于平台的。例如， add_test_cases_to_run 仅在云上可用，因为数据中心API（v1）不支持在创建后修改测试运行。

资源系统

服务器通过URI方案提供对各种资源的访问：

• zephyr://testcase/YOUR-TEST-CASE-KEY：从Zephyr实例中获取真实的测试用例数据用作模板。
• file:///absolute/path/to/your/file.json：读取用户提供的文件。
• zephyr://examples/...：访问内置示例有效载荷。

工具参考

测试用例管理

• get_test_case：获取特定测试用例的详细信息。
• create_test_case：使用STEP_BY_STEP、PLAIN_TEXT或BDD内容创建测试用例。
• delete_test_case：删除特定的测试用例。
• update_test_case_bdd：使用BDD内容更新现有测试用例（可选地更新测试用例名称）。

试运行管理

• create_test_run：创建新的测试运行。
• get_test_run：获取有关特定测试运行的详细信息。
• get_test_run_cases：从测试运行中获取测试用例密钥。
• add_test_cases_to_run：将测试用例添加到现有测试运行中。 *（仅限云）*

测试执行和搜索

• get_test_execution：获取详细的单个测试执行结果。
• search_test_cases_by_folder：在特定文件夹中搜索测试用例。
• search_test_runs：按项目键和/或文件夹路径搜索测试运行。

组织

• create_folder：在Zephyr Scale中创建一个新文件夹。

用法示例

使用问题链接创建BDD测试用例

{
  "project_key": "PROJ",
  "name": "User Authentication",
  "test_script": {
    "type": "BDD",
    "text": "Given a user with valid credentials\nWhen the user attempts to log in\nThen the user should be authenticated successfully"
  },
  "issue_links": ["PROJ-123", "PROJ-456"]
}

备注: issue_links 需要 JIRA_USERNAME 和 JIRA_API_TOKEN 待设置（仅限云）。链接失败被报告为警告——测试用例仍在创建中。

使用实时测试用例作为模板

1. 获取现有测试用例： zephyr://testcase/PROJ-T123
2. 复制其结构（尤其是 customFields 和 folder).
3. 使用相同的项目特定配置创建新的测试用例。

创建测试运行

{
  "project_key": "PROJ",
  "name": "Sprint 1 Test Run",
  "test_case_keys": ["PROJ-T123", "PROJ-T124", "PROJ-T125"]
}

更新现有BDD测试用例

{
  "test_case_key": "PROJ-T123",
  "name": "Ensure the axial-flow pump is enabled",
  "bdd_content": "Feature: Pump Enablement\n\nScenario: Enable the pump\n  Given the system is powered on\n  When the operator enables the axial-flow pump\n  Then the pump should report as enabled"
}

备注：服务器将在可能的情况下将markdown风格的BDD转换为Gherkin，并保留所有其他现有的测试用例字段。

认证

Jira云配置

**\* JIRA_USERNAME + JIRA_API_TOKEN**：仅适用于 issue_links 云上的功能。Zephyr API密钥无法根据Jira REST API进行身份验证，因此需要一个单独的Jira凭据来解决数字ID的问题密钥。没有这些， issue_links 将失败并发出401警告——测试用例仍成功创建。

Jira数据中心配置

自动检测

服务器会根据以下内容自动检测您的Jira类型 ZEPHYR_BASE_URL --URL包含 .atlassian.net 被视为云，其他一切都被视为数据中心。覆盖 JIRA_TYPE="cloud" 或 JIRA_TYPE="datacenter".

许可证

麻省理工学院