ArtyMaximus/zephyr-scale-mcp-server

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 клиент следующим образом:

{
  "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. Клонируйте репозиторий:

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

2. Установите зависимости:

npm install

3. Соберите проект:

npm run build

4. Настройте переменные окружения:

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

5. Запустите сервер:

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 токена

1. Войдите в Jira
2. Перейдите в Account Settings → Security → API Tokens
3. Создайте новый токен
4. Используйте его в переменной окружения ZEPHYR_API_KEY

Основные концепции

Типы тест-скриптов

Сервер поддерживает три типа тест-скриптов:

STEP_BY_STEP

Используйте, когда:

• Нужна четкая структура с отдельными полями для каждого шага
• Требуется указать testData (тестовые данные) отдельно от описания
• Нужны ссылки на другие тест-кейсы через testCaseKey
• Шаги простые и не требуют сложного форматирования

Структура:

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

Особенности:

• Каждый шаг - отдельный объект с четкой структурой
• Поддерживает поле testData для входных данных
• Поддерживает testCaseKey для ссылок на другие тест-кейсы
• Все поля обрабатываются независимо

PLAIN_TEXT

Используйте, когда:

• Тест-кейс содержит много текста с markdown-разметкой (заголовки, списки, изображения)
• Нужна гибкость в форматировании описания шагов
• Не требуется отдельное поле testData (все данные в описании)
• Шаги разделяются простыми разделителями

Структура:

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

---

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

---

Шаг 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

Сравнительная таблица

Рекомендация для 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 тест-кейса

Используйте, когда нужны отдельные поля для тестовых данных:

{
  "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:

{
  "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, автоматическая конвертация в STEP_BY_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.

Использование существующего тест-кейса как шаблона

1. Получите существующий тест-кейс: zephyr://testcase/PROJ-T123
2. Скопируйте его структуру (особенно customFields и folder)
3. Создайте новый тест-кейс, используя ту же конфигурацию проекта

Создание тест-кейса с изображениями

Изображения в 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) защищены от конвертации в курсив.

Лицензия

MIT