使用说明

Zephyr Scale MCP服务器

模型上下文协议（MCP）服务器，用于管理Zephyr Scale Data Center中的测试案例。通过支持Stepu byu Step、Plainu Text和BDD格式的Atlassian REST API创建、读取和管理测试案例。

特点

✅ Zephyr Scale Data Center支持：与Zephyr Scale一起使用本地部署的JIRA实例
✅ 三种类型的测试脚本：stepu byu step、plainu text和bdd自动转换
✅ 全生命周期管理：创建、读取、更新、删除测试案例、管理测试伤口和文件夹
✅ 资源系统：通过URI访问Zephyr的实时数据（zephyr://testcase/KEY）用作模板
✅ 下载图像：自动从Markdown下载图像并将测试案例集成到步骤中
✅ 智能文件夹搜索：基于测试案例描述自动提供合适的文件夹
✅ 将 Markdown 转换为 HTML自动Markdown标记转换以正确显示Zephyr scale

安装和配置

通过NPX使用（推荐）

将MCP客户端配置为：

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

本地安装

克隆存储库：

git clone <your-repo-url>
cd zephyr-scale-mcp-server

建立依赖关系：

npm install

收集项目：

npm run build

配置环境变量：

export ZEPHYR_BASE_URL="https://your-jira-server.com"
export ZEPHYR_API_KEY="your-api-token"

启动服务器：

npm start

相容性

服务器已测试并运行以下版本：

Jira数据中心: 9.12.14
Zephyr天平：11.7.1-吉拉9

备注：服务器设计用于Zephyr Scale Data Center。无法保证与其他版本的兼容性。

认证

此服务器仅与Zephyr Scale Data Center一起工作。身份验证需要：

ZEPHYR_BASE_URL：您的JIRA服务器的URL（例如， https://jira.skyeng.link)
ZEPHYR_API_KEY：来自JIRA配置文件设置的API令牌

获取令牌API

进入Jira
转到 账户设置 → 安全 → API令牌
创建新令牌
在环境变量中使用它 ZEPHYR_API_KEY

基本概念

测试脚本类型

服务器支持三种类型的测试脚本：

STEP_BY_STEP

使用时：

需要一个清晰的结构，每个步骤都有单独的字段
需要说明 试验数据 （测试数据与描述分开）
需要链接到其他测试案例 testCaseKey
步骤简单，不需要复杂的格式

结构：

{
  "type": "STEP_BY_STEP",
  "steps": [
    {
      "description": "Описание действия",
      "testData": "Конкретные данные для теста (URL, параметры, значения)",
      "expectedResult": "Ожидаемый результат",
      "testCaseKey": "PROJ-T123" // опционально, ссылка на другой тест-кейс
    }
  ]
}

特点：

每一步都是一个具有清晰结构的独立对象
支持字段 testData 输入数据
支持 testCaseKey 链接到其他测试案例
所有字段都独立处理

PLAIN_TEXT

使用时：

测试箱包含许多带有标记的文本（标题、列表、图像）
需要灵活地格式化步骤描述
不需要单独的字段 testData （描述中的所有数据）
步骤由简单的分隔符分开

结构：

Шаг 1: Описание первого действия
Может содержать markdown: **жирный текст**, списки, заголовки
**Ожидаемый результат:** Результат первого шага

---

Шаг 2: Описание второго действия
![Изображение](url)
**Ожидаемый результат:** Результат второго шага

---

Шаг 3: Описание третьего действия
**Ожидаемый результат:** Результат третьего шага

特点：

分离器： --- 或 *** 单行
自动转换为服务器上的step_by_step
从文本中检索“预期结果” **Ожидаемый результат:**)
不支持 独立场 testData -所有数据必须在描述中
如果没有分隔符，整个文本将成为一个步骤
支持Markdown标记（标题、列表、图像）

与stepu byu step的主要区别：

plain_text→自动转换，无 testData，带有分隔符的纯文本
step_by_step→结构化JSON有 testData清晰的领域

行为驱动开发

使用时：

测试描述系统行为（given/when/then）
需要Gherkin格式的Acceptance Criteria
英文名：Behavior Driven Development

结构：

Feature: Описание фичи

Scenario: Описание сценария
  Given начальное условие
  When выполняется действие
  Then ожидается результат

特点：

自动将Markdown BDD风格转换为Gherkin
支持关键字：given，when，then，and

比较表

Критерий	步骤_步骤	明文
数据格式 ≫结构化JSON≫纯文本≫文本≫Gherkin≫
根据测试数据	✅ 支持→❌ 不支持→❌ 不支持→
链接到其他测试	✅ testCaseKey	❌ 不支持→❌ 不支持→
Markdown 标签	✅ 有限的。✅ 全力支持→✅ 有限的。
步骤分隔符不需要（数组） `---` 或 `***` 我不需要。
自动转换没有✅ 在step_by_step✅ 在Gherkin
何时使用 –简单结构化步骤–复杂的格式、大量文本、行为测试›

LLM推荐：

选择 STEP_BY_STEP如果需要单独的字段 testData 或其他测试的链接
选择 PLAIN_TEXT，如果步骤描述包含许多标记（标题、列表、图像），并且不需要 testData
选择 行为驱动开发，如果测试以given/when/then格式描述系统行为

资源系统

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

zephyr://testcase/YOUR-TEST-CASE-KEY：从Zephyr获取真实的测试案例数据用作模板
file:///absolute/path/to/your/file.json：读取用户文件

工具手册

测试案例管理

get_test_case：获取测试案例的详细信息
create_test_case：创建支持stepu byu step、plainu text或bdd的测试案例
delete_test_case：删除测试箱
update_test_case_bdd：更新现有BDD内容测试箱
update_test_case_step：更新stepu byu step test case中的特定步骤

测试伤口管理

create_test_run：创建新的测试伤口
get_test_run：获取测试伤口信息
get_test_run_cases：获取测试伤口中的测试案例列表
add_test_cases_to_run：将测试案例添加到现有测试伤口中
get_test_execution：获取测试执行的详细信息

文件夹管理

create_folder：在Zephyr Scale中创建新文件夹
delete_folder：删除文件夹ID（使用 get_folder_tree 或 get_folder_full_structure 获取文件夹ID）
get_folder_tree：获取项目文件夹的完整结构
get_folder_full_structure：获取特定根文件夹的完整子文件夹结构
suggest_folder_for_test_case：根据测试案例描述提供合适的文件夹

项目管理

get_project_info：获取项目信息，包括ProjectID
get_all_projects：获取所有项目列表

搜索

search_test_cases_by_folder：在特定文件夹中搜索测试案例

下载图像

upload_image：将图像加载到Zephyr Scale并获得HTML标记以嵌入到测试案例的步骤中

使用示例

创建Stepu Byu Step测试案例

当需要测试数据的单独字段时，请使用：

{
  "project_key": "PROJ",
  "name": "User Login Test",
  "test_script": {
    "type": "STEP_BY_STEP",
    "steps": [
      {
        "description": "Открыть страницу входа",
        "testData": "URL: https://example.com/login",
        "expectedResult": "Страница входа отображается"
      },
      {
        "description": "Ввести учетные данные",
        "testData": "Username: testuser@example.com\nPassword: password123",
        "expectedResult": "Поля заполнены корректно"
      },
      {
        "description": "Нажать кнопку входа",
        "testData": "",
        "expectedResult": "Пользователь авторизован, выполнен переход на главную страницу"
      }
    ]
  }
}

优点： 明确区分描述、测试数据和预期结果。

创建纯文本测试案例

当需要使用Markdown进行复杂格式时，请使用：

{
  "project_key": "PROJ",
  "name": "Complex Test with Markdown",
  "test_script": {
    "type": "PLAIN_TEXT",
    "text": "# Шаг 1: Настройка окружения\n\nВыполнить следующие действия:\n- Проверить доступность сервера\n- Установить необходимые зависимости\n- Настроить переменные окружения\n\n**Ожидаемый результат:** Окружение готово к тестированию\n\n---\n\n# Шаг 2: Выполнение основного действия\n\nОткрыть приложение и выполнить основную операцию.\n\n![Screenshot](https://example.com/screenshot.png)\n\n**Ожидаемый результат:** Операция выполнена успешно, отображается результат\n\n---\n\n# Шаг 3: Проверка результатов\n\nПроверить:\n1. Корректность данных\n2. Отображение в интерфейсе\n3. Запись в базе данных\n\n**Ожидаемый результат:** Все проверки пройдены"
  }
}

优点： 灵活的格式，支持Markdown，自动转换为Stepu Byu Step。

创建BDD测试案例

{
  "project_key": "PROJ",
  "name": "User Authentication",
  "test_script": {
    "type": "BDD",
    "text": "Feature: User Login\n\nScenario: Valid user login\n  Given a user with valid credentials\n  When the user attempts to log in\n  Then the user should be authenticated successfully"
  }
}

备注：服务器自动将Markdown BDD样式转换为正确的Gherkin格式。

使用现有的测试案例作为模板

获取现有的测试案例： zephyr://testcase/PROJ-T123
复制它的结构（特别是 customFields 和 folder)
使用相同的项目配置创建新的测试案例

创建带有图像的测试案例

Markdown格式的图像会自动下载和嵌入：

{
  "project_key": "PROJ",
  "name": "Test with Screenshot",
  "test_script": {
    "type": "STEP_BY_STEP",
    "steps": [
      {
        "description": "# Шаг 1: Открыть страницу\n\nПереход на главную страницу\n\n![Screenshot](https://example.com/screenshot.png)",
        "testData": "URL: https://example.com",
        "expectedResult": "Страница загружена успешно"
      }
    ]
  }
}

创建测试伤口

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

寻找合适的文件夹

{
  "project_key": "PROJ",
  "test_case_description": "Авторизация пользователя через API"
}

服务器将根据描述自动找到最合适的文件夹。

转换 Markdown

服务器自动将Markdown标记转换为HTML，以便在Zephyr Scale中正确显示：

标题（#, ##, ###）→HTML标题
粗体文字 → <strong>
斜体 → <em>
Код → <code>
列表HTML列表
图像 ![alt](url) →自动加载和嵌入

重要：带下划线的技术术语（例如 english_adult_not_native_speaker_course_it）防止转换为斜体字。

许可证

麻省理工学院

使用说明

Zephyr Scale MCP服务器

特点

安装和配置

通过NPX使用（推荐）

本地安装

相容性

认证

获取令牌API

基本概念

测试脚本类型

STEP_BY_STEP

PLAIN_TEXT

行为驱动开发

比较表

资源系统

工具手册

测试案例管理

测试伤口管理

文件夹管理

项目管理

搜索

下载图像

使用示例

创建Stepu Byu Step测试案例

创建纯文本测试案例

创建BDD测试案例

使用现有的测试案例作为模板

创建带有图像的测试案例

创建测试伤口

寻找合适的文件夹

转换 Markdown

许可证

相关 MCP

Jira集成服务

GitHub-Jira集成服务

Jira API集成工具

Jira项目管理服务器

Jira集成服务器

工程智能报告工具