Zephyr Scale MCP Server
Model Context Protocol (MCP) сервер для управления тест-кейсами в Zephyr Scale Data Center. Создавайте, читайте и управляйте тест-кейсами через Atlassian REST API с поддержкой STEP_BY_STEP, PLAIN_TEXT и BDD форматов.
Особенности
- ✅ Поддержка Zephyr Scale Data Center: Работает с локально развернутыми экземплярами Jira с Zephyr Scale
- ✅ Три типа тест-скриптов: STEP_BY_STEP, PLAIN_TEXT и BDD с автоматической конвертацией
- ✅ Управление полным жизненным циклом: Создание, чтение, обновление, удаление тест-кейсов, управление тест-ранами и папками
- ✅ Система ресурсов: Доступ к живым данным из Zephyr через URI (
zephyr://testcase/KEY) для использования в качестве шаблонов - ✅ Загрузка изображений: Автоматическая загрузка изображений из markdown и встраивание в шаги тест-кейсов
- ✅ Умный поиск папок: Автоматическое предложение подходящих папок на основе описания тест-кейса
- ✅ Конвертация Markdown в HTML: Автоматическое преобразование markdown-разметки для корректного отображения в Zephyr Scale
Установка и настройка
Использование через npx (рекомендуется)
Настройте ваш MCP клиент следующим образом:```json
{
"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"
}
}
}
}
### Локальная установка
1. Клонируйте репозиторий:```bash
git clone <your-repo-url>
cd zephyr-scale-mcp-server
- Установите зависимости:```bash
npm install
3. Соберите проект:```bash
npm run build
- Настройте переменные окружения:```bash
export ZEPHYR_BASE_URL="https://your-jira-server.com"
export ZEPHYR_API_KEY="your-api-token"
5. Запустите сервер:```bash
npm start
Совместимость
Сервер протестирован и работает со следующими версиями:
- Jira Data Center: 9.12.14
- Zephyr Scale: 11.7.1-jira9
> Примечание: Сервер разработан для работы с Zephyr Scale Data Center. Совместимость с другими версиями не гарантируется.
Аутентификация
Сервер работает только с Zephyr Scale Data Center. Для аутентификации требуется:
ZEPHYR_BASE_URL: URL вашего Jira сервера (например,https://jira.skyeng.link)ZEPHYR_API_KEY: API токен из настроек профиля Jira
Получение API токена
- Войдите в Jira
- Перейдите в Account Settings → Security → API Tokens
- Создайте новый токен
- Используйте его в переменной окружения
ZEPHYR_API_KEY
Основные концепции
Типы тест-скриптов
Сервер поддерживает три типа тест-скриптов:
STEP_BY_STEP
Используйте, когда:
- Нужна четкая структура с отдельными полями для каждого шага
- Требуется указать testData (тестовые данные) отдельно от описания
- Нужны ссылки на другие тест-кейсы через testCaseKey
- Шаги простые и не требуют сложного форматирования
Структура:```json
{
"type": "STEP_BY_STEP",
"steps": [
{
"description": "Описание действия",
"testData": "Конкретные данные для теста (URL, параметры, значения)",
"expectedResult": "Ожидаемый результат",
"testCaseKey": "PROJ-T123" // опционально, ссылка на другой тест-кейс
}
]
}
**Особенности:**
- Каждый шаг - отдельный объект с четкой структурой
- Поддерживает поле `testData` для входных данных
- Поддерживает `testCaseKey` для ссылок на другие тест-кейсы
- Все поля обрабатываются независимо
#### PLAIN_TEXT
**Используйте, когда:**
- Тест-кейс содержит много текста с markdown-разметкой (заголовки, списки, изображения)
- Нужна гибкость в форматировании описания шагов
- Не требуется отдельное поле `testData` (все данные в описании)
- Шаги разделяются простыми разделителями
**Структура:**```
Шаг 1: Описание первого действия
Может содержать markdown: **жирный текст**, списки, заголовки
**Ожидаемый результат:** Результат первого шага
---
Шаг 2: Описание второго действия

**Ожидаемый результат:** Результат второго шага
---
Шаг 3: Описание третьего действия
**Ожидаемый результат:** Результат третьего шага
Особенности:
- Разделители: --- или *** на отдельной строке
- Автоматически конвертируется в STEP_BY_STEP на сервере
- Извлекает "Ожидаемый результат:" из текста (ищет **Ожидаемый результат:**)
- НЕ поддерживает отдельное поле testData - все данные должны быть в описании
- Если нет разделителей, весь текст становится одним шагом
- Поддерживает markdown-разметку (заголовки, списки, изображения)
Ключевое отличие от STEP_BY_STEP:
- PLAIN_TEXT → автоматическая конвертация, нет testData, простой текст с разделителями
- STEP_BY_STEP → структурированный JSON, есть testData, четкие поля
BDD
Используйте, когда:
- Тест описывает поведение системы (Given/When/Then)
- Нужны acceptance criteria в формате Gherkin
- Тест написан в стиле Behavior Driven Development
Структура:```
Feature: Описание фичи
Scenario: Описание сценария
Given начальное условие
When выполняется действие
Then ожидается результат
**Особенности:**
- Автоматическая конвертация markdown-стиля BDD в Gherkin
- Поддерживает ключевые слова: Given, When, Then, And
#### Сравнительная таблица
| Критерий | STEP_BY_STEP | PLAIN_TEXT | BDD |
|----------|--------------|------------|-----|
| **Формат данных** | Структурированный JSON | Простой текст | Текст (Gherkin) |
| **Поле testData** | ✅ Поддерживается | ❌ Не поддерживается | ❌ Не поддерживается |
| **Ссылки на другие тесты** | ✅ testCaseKey | ❌ Не поддерживается | ❌ Не поддерживается |
| **Markdown разметка** | ✅ Ограниченная | ✅ Полная поддержка | ✅ Ограниченная |
| **Разделители шагов** | Не нужны (массив) | `---` или `***` | Не нужны |
| **Автоконвертация** | Нет | ✅ В STEP_BY_STEP | ✅ В Gherkin |
| **Когда использовать** | Простые структурированные шаги | Сложное форматирование, много текста | Поведенческие тесты |
**Рекомендация для LLM:**
- Выбирайте **STEP_BY_STEP**, если нужны отдельные поля `testData` или ссылки на другие тесты
- Выбирайте **PLAIN_TEXT**, если описание шагов содержит много markdown-разметки (заголовки, списки, изображения) и не требуется `testData`
- Выбирайте **BDD**, если тест описывает поведение системы в формате Given/When/Then
### Система ресурсов
Сервер предоставляет доступ к различным ресурсам через URI схемы:
- `zephyr://testcase/YOUR-TEST-CASE-KEY`: Получить реальные данные тест-кейса из Zephyr для использования в качестве шаблона
- `file:///absolute/path/to/your/file.json`: Чтение пользовательских файлов
## Справочник инструментов
### Управление тест-кейсами
- `get_test_case`: Получить детальную информацию о тест-кейсе
- `create_test_case`: Создать тест-кейс с поддержкой STEP_BY_STEP, PLAIN_TEXT или BDD
- `delete_test_case`: Удалить тест-кейс
- `update_test_case_bdd`: Обновить существующий тест-кейс с BDD контентом
- `update_test_case_step`: Обновить конкретный шаг в STEP_BY_STEP тест-кейсе
### Управление тест-ранами
- `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 тег для встраивания в шаги тест-кейсов
## Примеры использования
### Создание STEP_BY_STEP тест-кейса
Используйте, когда нужны отдельные поля для тестовых данных:```json
{
"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": "Пользователь авторизован, выполнен переход на главную страницу"
}
]
}
}
Преимущества: Четкое разделение описания, тестовых данных и ожидаемого результата.
Создание PLAIN_TEXT тест-кейса
Используйте, когда нужно сложное форматирование с markdown:```json
{
"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\n\nОжидаемый результат: Операция выполнена успешно, отображается результат\n\n---\n\n# Шаг 3: Проверка результатов\n\nПроверить:\n1. Корректность данных\n2. Отображение в интерфейсе\n3. Запись в базе данных\n\nОжидаемый результат: Все проверки пройдены"
}
}
**Преимущества:** Гибкое форматирование, поддержка markdown, автоматическая конвертация в STEP_BY_STEP.
### Создание BDD тест-кейса```json
{
"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 формате автоматически загружаются и встраиваются:```json
{
"project_key": "PROJ",
"name": "Test with Screenshot",
"test_script": {
"type": "STEP_BY_STEP",
"steps": [
{
"description": "# Шаг 1: Открыть страницу\n\nПереход на главную страницу\n\n",
"testData": "URL: https://example.com",
"expectedResult": "Страница загружена успешно"
}
]
}
}
### Создание тест-рана```json
{
"project_key": "PROJ",
"name": "Sprint 1 Test Run",
"test_case_keys": ["PROJ-T123", "PROJ-T124", "PROJ-T125"],
"environment": "Production"
}
Поиск подходящей папки```json
{
"project_key": "PROJ",
"test_case_description": "Авторизация пользователя через API"
}
```
Сервер автоматически найдет наиболее подходящую папку на основе описания.
Конвертация Markdown
Сервер автоматически конвертирует markdown-разметку в HTML для корректного отображения в Zephyr Scale:
- Заголовки (
#,##,###) → HTML заголовки - Жирный текст → ``
- Курсив → ``
Код→ ``- Списки → HTML списки
- Изображения `` → автоматическая загрузка и встраивание
Важно: Технические термины с подчеркиваниями (например, english_adult_not_native_speaker_course_it) защищены от конвертации в курсив.
Лицензия
MIT
