zephyr-scale-mcp

MCP-сервер (Model Context Protocol) для Zephyr Scale на self-hosted Jira Server / Data Center (бывш. TM4J / Kanoah). Даёт ИИ-агентам (Claude Code, Claude Desktop и другим MCP-клиентам) инструменты для управления тестовой моделью через REST API v1 ({JIRA_BASE_URL}/rest/atm/1.0).

Zephyr Scale Cloud (API v2) и Zephyr Squad — другие API, этим сервером не поддерживаются.

Возможности

Поддерживаются все три формата скриптов тест-кейсов: STEP_BY_STEP, PLAIN_TEXT, BDD (Gherkin), включая шаги Call to Test (steps[].testCaseKey) и параметры (§parameters).

Related MCP server: mcp-zephyr-scale

Требования

• Node.js ≥ 20

• Jira Server / Data Center с установленным плагином Zephyr Scale

• Персональный токен Jira DC (PAT, Jira 8.14+) или логин/пароль

Установка и сборка

git clone <repo-url> zephyr-scale-mcp
cd zephyr-scale-mcp
npm install
npm run build        # → dist/index.js

Конфигурация (переменные окружения)

Секреты (JIRA_PAT, JIRA_PASSWORD) не пишутся в логи и не попадают в ответы инструментов и тексты ошибок.

Подключение к MCP-клиенту

claude_desktop_config.json / .mcp.json:

{
  "mcpServers": {
    "zephyr-scale": {
      "command": "node",
      "args": ["/path/to/zephyr-scale-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.example.com",
        "JIRA_AUTH": "pat",
        "JIRA_PAT": "<personal access token>",
        "ZEPHYR_DEFAULT_PROJECT_KEY": "PROJ"
      }
    }
  }
}

Claude Code:

claude mcp add zephyr-scale \
  --env JIRA_BASE_URL=https://jira.example.com \
  --env JIRA_PAT=<token> \
  --env ZEPHYR_DEFAULT_PROJECT_KEY=PROJ \
  -- node /path/to/zephyr-scale-mcp/dist/index.js

Проверка: попросите агента вызвать health_check — он должен вернуть { ok: true, jiraUser, baseUrl, zephyrPluginReachable }.

Примеры

Создание кейса с шагами:

{
  "tool": "create_test_case",
  "arguments": {
    "projectKey": "PROJ",
    "name": "Успешный вход",
    "folder": "/Регресс/Авторизация",
    "testScript": {
      "type": "STEP_BY_STEP",
      "steps": [
        { "description": "Открыть страницу логина", "testData": "URL: /login", "expectedResult": "Форма логина отображается" },
        { "testCaseKey": "PROJ-T45" },
        { "description": "Ввести валидные креды", "expectedResult": "Открыт дашборд" }
      ]
    }
  }
}

Поиск по TQL: projectKey = "PROJ" AND folder = "/Регресс" AND status = "Approved" (синтаксис строгий: пробелы вокруг операторов, строки в двойных кавычках, только AND).

Цикл с результатами создаётся одним вызовом create_test_run — см. описание инструмента (поле items, в т.ч. scriptResults с пошаговыми статусами).

Ограничения API v1 (важно)

1. Тест-циклы неизменяемы после создания. PUT /testrun/{key} не существует: нельзя переименовать цикл, сменить папку, добавить/убрать кейсы. Состав задаётся только в create_test_run (поле items). Инструменты результатов лишь находят существующий item по testCaseKey.

2. Папки не создаются автоматически при создании кейсов/циклов; публичного листинга папок нет; переименование — только по числовому id (его возвращает create_folder).

3. owner / executedBy / assignedTo — это Jira user key (JIRAUSER10000), не логин и не e-mail; для резолва используйте find_jira_user.

4. TQL строгий — только AND, пробелы вокруг операторов, строки в двойных кавычках; для циклов доступны только поля projectKey и folder.

5. Статусы / приоритеты / окружения регистрозависимы и передаются внутренними (нелокализованными) именами; на инстансе могут быть кастомные наборы.

6. В labels пробелы заменяются API на _.

7. Устаревшие поля API не поддерживаются намеренно: issueKey → issueLinks, executionDate → actualEndDate, userKey → executedBy.

8. Ключи сущностей: PROJ-T1 — кейс, PROJ-P1 — план, PROJ-R1 — цикл.

9. Серверный default maxResults = 200; инструменты по умолчанию запрашивают 50.

10. Шаги STEP_BY_STEP при PUT синхронизируются по id: без id — создать, с id — обновить, отсутствует в списке — удалить. Поэтому update_test_case с testScript.steps требует полный итоговый список; безопасное частичное добавление шагов делает add_test_steps (читает кейс, сливает, записывает).

Если API вашего инстанса ведёт себя иначе (старая версия плагина и т.п.) — зафиксируйте расхождение здесь и сообщите разработчику.

Обработка ошибок

Ошибки API возвращаются в формате Zephyr API error <status> (<METHOD> <path>): <тело до 2 КБ> с подсказкой для типовых причин (несуществующая папка, регистрозависимые статусы, синтаксис TQL, недоступный плагин, права). 429/503 повторяются с учётом Retry-After; сетевые ошибки и 5xx повторяются только для GET (backoff 500ms * 2^n + джиттер).

Разработка

npm run typecheck    # tsc --noEmit
npm test             # unit + contract (vitest + msw), без сети
npm run smoke        # интеграционный сценарий против реального стенда (ZEPHYR_E2E=1)

Smoke-сценарий требует реальных JIRA_BASE_URL/JIRA_PAT и ZEPHYR_DEFAULT_PROJECT_KEY (выделенный тестовый проект!) и оставляет на стенде папки /mcp-smoke-* (API не умеет удалять папки).

Структура

src/
├── index.ts        # bootstrap: конфиг, регистрация инструментов, stdio-транспорт
├── config.ts       # чтение и валидация env
├── http.ts         # zephyrFetch(): auth, таймаут, ретраи, нормализация ошибок
├── schemas.ts      # zod-схемы общих структур (Step, TestScript, поля результатов…)
├── toolkit.ts      # defineTool(): strict-валидация, read-only guard, формат ответов
└── tools/          # testCases, folders, testRuns, testResults, misc
test/               # unit + contract (msw) + smoke.e2e

Фаза 3 (не реализовано, по отдельному запросу)

Вложения, CRUD тест-планов, эндпоинты автоматизации, обход неизменяемости циклов (recreate_test_run_with_items), internal API за флагом — см. §7.6 ТЗ.