{"_id":"@artymaximus/zephyr-scale-mcp-server","name":"@artymaximus/zephyr-scale-mcp-server","dist-tags":{"latest":"0.2.5"},"versions":{"0.2.5":{"name":"@artymaximus/zephyr-scale-mcp-server","version":"0.2.5","description":"Model Context Protocol (MCP) server for Zephyr Scale Data Center test case management with comprehensive STEP_BY_STEP, PLAIN_TEXT, and BDD support","type":"module","main":"./build/index.js","bin":{"zephyr-scale-mcp":"build/index.js"},"scripts":{"build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","prepare":"npm run build","watch":"tsc --watch","start":"node build/index.js","inspector":"npx @modelcontextprotocol/inspector build/index.js","test":"node test/run-tests.cjs","test:unit":"node test/zephyr-server.test.cjs","test:integration":"node test/integration.test.cjs","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","zephyr","zephyr-scale","test-management","test-cases","atlassian","jira","bdd","testing","qa","automation"],"author":{"name":"aza-a"},"license":"MIT","engines":{"node":">=16.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"0.6.0","axios":"^1.10.0"},"devDependencies":{"@types/node":"^20.11.24","typescript":"^5.8.3"},"publishConfig":{"access":"public"},"_id":"@artymaximus/zephyr-scale-mcp-server@0.2.5","gitHead":"bfb9a5d9c5584608cd0bb627c6b19c32e77aca6f","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-OAE7c6FxirM1nne+dFjtbtb0bkwHpesqUYAvUe3ImirrnMEa+1Kboukh1nM4enJS52GzbjQ1dsKjgfM6Lcp+1w==","shasum":"a916a8887e15fe85b054109874a7306ba39165b2","tarball":"https://registry.npmjs.org/@artymaximus/zephyr-scale-mcp-server/-/zephyr-scale-mcp-server-0.2.5.tgz","fileCount":15,"unpackedSize":216288,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAbu7kWFgbNpnohHnRP1CYSGN//STJRTUSRFXAYm8ilMAiB3pp5mvI6lC4tE0fUENthRGUNHKFQxaFeTP0Sk/25AEQ=="}]},"_npmUser":{"name":"artymaximus","email":"aza-artyom@yandex.ru"},"directories":{},"maintainers":[{"name":"artymaximus","email":"aza-artyom@yandex.ru"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zephyr-scale-mcp-server_0.2.5_1762941793062_0.27800337331889"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-12T10:03:12.995Z","0.2.5":"2025-11-12T10:03:13.239Z","modified":"2025-11-12T10:03:13.473Z"},"maintainers":[{"name":"artymaximus","email":"aza-artyom@yandex.ru"}],"description":"Model Context Protocol (MCP) server for Zephyr Scale Data Center test case management with comprehensive STEP_BY_STEP, PLAIN_TEXT, and BDD support","keywords":["mcp","model-context-protocol","zephyr","zephyr-scale","test-management","test-cases","atlassian","jira","bdd","testing","qa","automation"],"author":{"name":"aza-a"},"license":"MIT","readme":"# Zephyr Scale MCP Server\n\nModel Context Protocol (MCP) сервер для управления тест-кейсами в Zephyr Scale Data Center. Создавайте, читайте и управляйте тест-кейсами через Atlassian REST API с поддержкой STEP_BY_STEP, PLAIN_TEXT и BDD форматов.\n\n## Особенности\n\n- ✅ **Поддержка Zephyr Scale Data Center**: Работает с локально развернутыми экземплярами Jira с Zephyr Scale\n- ✅ **Три типа тест-скриптов**: STEP_BY_STEP, PLAIN_TEXT и BDD с автоматической конвертацией\n- ✅ **Управление полным жизненным циклом**: Создание, чтение, обновление, удаление тест-кейсов, управление тест-ранами и папками\n- ✅ **Система ресурсов**: Доступ к живым данным из Zephyr через URI (`zephyr://testcase/KEY`) для использования в качестве шаблонов\n- ✅ **Загрузка изображений**: Автоматическая загрузка изображений из markdown и встраивание в шаги тест-кейсов\n- ✅ **Умный поиск папок**: Автоматическое предложение подходящих папок на основе описания тест-кейса\n- ✅ **Конвертация Markdown в HTML**: Автоматическое преобразование markdown-разметки для корректного отображения в Zephyr Scale\n\n## Установка и настройка\n\n### Использование через npx (рекомендуется)\n\nНастройте ваш MCP клиент следующим образом:\n\n```json\n{\n  \"mcpServers\": {\n    \"zephyr-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"@artymaximus/zephyr-scale-mcp-server@latest\"],\n      \"env\": {\n        \"ZEPHYR_BASE_URL\": \"https://your-jira-server.com\",\n        \"ZEPHYR_API_KEY\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Локальная установка\n\n1. Клонируйте репозиторий:\n```bash\ngit clone <your-repo-url>\ncd zephyr-scale-mcp-server\n```\n\n2. Установите зависимости:\n```bash\nnpm install\n```\n\n3. Соберите проект:\n```bash\nnpm run build\n```\n\n4. Настройте переменные окружения:\n```bash\nexport ZEPHYR_BASE_URL=\"https://your-jira-server.com\"\nexport ZEPHYR_API_KEY=\"your-api-token\"\n```\n\n5. Запустите сервер:\n```bash\nnpm start\n```\n\n## Совместимость\n\nСервер протестирован и работает со следующими версиями:\n\n- **Jira Data Center**: 9.12.14\n- **Zephyr Scale**: 11.7.1-jira9\n\n> **Примечание**: Сервер разработан для работы с Zephyr Scale Data Center. Совместимость с другими версиями не гарантируется.\n\n## Аутентификация\n\nСервер работает только с Zephyr Scale Data Center. Для аутентификации требуется:\n\n- `ZEPHYR_BASE_URL`: URL вашего Jira сервера (например, `https://jira.skyeng.link`)\n- `ZEPHYR_API_KEY`: API токен из настроек профиля Jira\n\n### Получение API токена\n\n1. Войдите в Jira\n2. Перейдите в **Account Settings** → **Security** → **API Tokens**\n3. Создайте новый токен\n4. Используйте его в переменной окружения `ZEPHYR_API_KEY`\n\n## Основные концепции\n\n### Типы тест-скриптов\n\nСервер поддерживает три типа тест-скриптов:\n\n#### STEP_BY_STEP\n\n**Используйте, когда:**\n- Нужна четкая структура с отдельными полями для каждого шага\n- Требуется указать **testData** (тестовые данные) отдельно от описания\n- Нужны ссылки на другие тест-кейсы через `testCaseKey`\n- Шаги простые и не требуют сложного форматирования\n\n**Структура:**\n```json\n{\n  \"type\": \"STEP_BY_STEP\",\n  \"steps\": [\n    {\n      \"description\": \"Описание действия\",\n      \"testData\": \"Конкретные данные для теста (URL, параметры, значения)\",\n      \"expectedResult\": \"Ожидаемый результат\",\n      \"testCaseKey\": \"PROJ-T123\" // опционально, ссылка на другой тест-кейс\n    }\n  ]\n}\n```\n\n**Особенности:**\n- Каждый шаг - отдельный объект с четкой структурой\n- Поддерживает поле `testData` для входных данных\n- Поддерживает `testCaseKey` для ссылок на другие тест-кейсы\n- Все поля обрабатываются независимо\n\n#### PLAIN_TEXT\n\n**Используйте, когда:**\n- Тест-кейс содержит много текста с markdown-разметкой (заголовки, списки, изображения)\n- Нужна гибкость в форматировании описания шагов\n- Не требуется отдельное поле `testData` (все данные в описании)\n- Шаги разделяются простыми разделителями\n\n**Структура:**\n```\nШаг 1: Описание первого действия\nМожет содержать markdown: **жирный текст**, списки, заголовки\n**Ожидаемый результат:** Результат первого шага\n\n---\n\nШаг 2: Описание второго действия\n![Изображение](url)\n**Ожидаемый результат:** Результат второго шага\n\n---\n\nШаг 3: Описание третьего действия\n**Ожидаемый результат:** Результат третьего шага\n```\n\n**Особенности:**\n- Разделители: `---` или `***` на отдельной строке\n- Автоматически конвертируется в STEP_BY_STEP на сервере\n- Извлекает \"Ожидаемый результат:\" из текста (ищет `**Ожидаемый результат:**`)\n- **НЕ поддерживает** отдельное поле `testData` - все данные должны быть в описании\n- Если нет разделителей, весь текст становится одним шагом\n- Поддерживает markdown-разметку (заголовки, списки, изображения)\n\n**Ключевое отличие от STEP_BY_STEP:**\n- PLAIN_TEXT → автоматическая конвертация, нет `testData`, простой текст с разделителями\n- STEP_BY_STEP → структурированный JSON, есть `testData`, четкие поля\n\n#### BDD\n\n**Используйте, когда:**\n- Тест описывает поведение системы (Given/When/Then)\n- Нужны acceptance criteria в формате Gherkin\n- Тест написан в стиле Behavior Driven Development\n\n**Структура:**\n```\nFeature: Описание фичи\n\nScenario: Описание сценария\n  Given начальное условие\n  When выполняется действие\n  Then ожидается результат\n```\n\n**Особенности:**\n- Автоматическая конвертация markdown-стиля BDD в Gherkin\n- Поддерживает ключевые слова: Given, When, Then, And\n\n#### Сравнительная таблица\n\n| Критерий | STEP_BY_STEP | PLAIN_TEXT | BDD |\n|----------|--------------|------------|-----|\n| **Формат данных** | Структурированный JSON | Простой текст | Текст (Gherkin) |\n| **Поле testData** | ✅ Поддерживается | ❌ Не поддерживается | ❌ Не поддерживается |\n| **Ссылки на другие тесты** | ✅ testCaseKey | ❌ Не поддерживается | ❌ Не поддерживается |\n| **Markdown разметка** | ✅ Ограниченная | ✅ Полная поддержка | ✅ Ограниченная |\n| **Разделители шагов** | Не нужны (массив) | `---` или `***` | Не нужны |\n| **Автоконвертация** | Нет | ✅ В STEP_BY_STEP | ✅ В Gherkin |\n| **Когда использовать** | Простые структурированные шаги | Сложное форматирование, много текста | Поведенческие тесты |\n\n**Рекомендация для LLM:**\n- Выбирайте **STEP_BY_STEP**, если нужны отдельные поля `testData` или ссылки на другие тесты\n- Выбирайте **PLAIN_TEXT**, если описание шагов содержит много markdown-разметки (заголовки, списки, изображения) и не требуется `testData`\n- Выбирайте **BDD**, если тест описывает поведение системы в формате Given/When/Then\n\n### Система ресурсов\n\nСервер предоставляет доступ к различным ресурсам через URI схемы:\n\n- `zephyr://testcase/YOUR-TEST-CASE-KEY`: Получить реальные данные тест-кейса из Zephyr для использования в качестве шаблона\n- `file:///absolute/path/to/your/file.json`: Чтение пользовательских файлов\n\n## Справочник инструментов\n\n### Управление тест-кейсами\n\n- `get_test_case`: Получить детальную информацию о тест-кейсе\n- `create_test_case`: Создать тест-кейс с поддержкой STEP_BY_STEP, PLAIN_TEXT или BDD\n- `delete_test_case`: Удалить тест-кейс\n- `update_test_case_bdd`: Обновить существующий тест-кейс с BDD контентом\n- `update_test_case_step`: Обновить конкретный шаг в STEP_BY_STEP тест-кейсе\n\n### Управление тест-ранами\n\n- `create_test_run`: Создать новый тест-ран\n- `get_test_run`: Получить информацию о тест-ране\n- `get_test_run_cases`: Получить список тест-кейсов в тест-ране\n- `add_test_cases_to_run`: Добавить тест-кейсы в существующий тест-ран\n- `get_test_execution`: Получить детальную информацию о выполнении теста\n\n### Управление папками\n\n- `create_folder`: Создать новую папку в Zephyr Scale\n- `delete_folder`: Удалить папку по её ID (используйте `get_folder_tree` или `get_folder_full_structure` для получения ID папки)\n- `get_folder_tree`: Получить полную структуру папок проекта\n- `get_folder_full_structure`: Получить полную структуру вложенных папок для конкретной корневой папки\n- `suggest_folder_for_test_case`: Предложить подходящую папку на основе описания тест-кейса\n\n### Управление проектами\n\n- `get_project_info`: Получить информацию о проекте, включая projectId\n- `get_all_projects`: Получить список всех проектов\n\n### Поиск\n\n- `search_test_cases_by_folder`: Поиск тест-кейсов в конкретной папке\n\n### Загрузка изображений\n\n- `upload_image`: Загрузить изображение в Zephyr Scale и получить HTML тег для встраивания в шаги тест-кейсов\n\n## Примеры использования\n\n### Создание STEP_BY_STEP тест-кейса\n\nИспользуйте, когда нужны отдельные поля для тестовых данных:\n\n```json\n{\n  \"project_key\": \"PROJ\",\n  \"name\": \"User Login Test\",\n  \"test_script\": {\n    \"type\": \"STEP_BY_STEP\",\n    \"steps\": [\n      {\n        \"description\": \"Открыть страницу входа\",\n        \"testData\": \"URL: https://example.com/login\",\n        \"expectedResult\": \"Страница входа отображается\"\n      },\n      {\n        \"description\": \"Ввести учетные данные\",\n        \"testData\": \"Username: testuser@example.com\\nPassword: password123\",\n        \"expectedResult\": \"Поля заполнены корректно\"\n      },\n      {\n        \"description\": \"Нажать кнопку входа\",\n        \"testData\": \"\",\n        \"expectedResult\": \"Пользователь авторизован, выполнен переход на главную страницу\"\n      }\n    ]\n  }\n}\n```\n\n**Преимущества:** Четкое разделение описания, тестовых данных и ожидаемого результата.\n\n### Создание PLAIN_TEXT тест-кейса\n\nИспользуйте, когда нужно сложное форматирование с markdown:\n\n```json\n{\n  \"project_key\": \"PROJ\",\n  \"name\": \"Complex Test with Markdown\",\n  \"test_script\": {\n    \"type\": \"PLAIN_TEXT\",\n    \"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**Ожидаемый результат:** Все проверки пройдены\"\n  }\n}\n```\n\n**Преимущества:** Гибкое форматирование, поддержка markdown, автоматическая конвертация в STEP_BY_STEP.\n\n### Создание BDD тест-кейса\n\n```json\n{\n  \"project_key\": \"PROJ\",\n  \"name\": \"User Authentication\",\n  \"test_script\": {\n    \"type\": \"BDD\",\n    \"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\"\n  }\n}\n```\n\n**Примечание**: Сервер автоматически конвертирует markdown-стиль BDD в правильный формат Gherkin.\n\n### Использование существующего тест-кейса как шаблона\n\n1. Получите существующий тест-кейс: `zephyr://testcase/PROJ-T123`\n2. Скопируйте его структуру (особенно `customFields` и `folder`)\n3. Создайте новый тест-кейс, используя ту же конфигурацию проекта\n\n### Создание тест-кейса с изображениями\n\nИзображения в markdown формате автоматически загружаются и встраиваются:\n\n```json\n{\n  \"project_key\": \"PROJ\",\n  \"name\": \"Test with Screenshot\",\n  \"test_script\": {\n    \"type\": \"STEP_BY_STEP\",\n    \"steps\": [\n      {\n        \"description\": \"# Шаг 1: Открыть страницу\\n\\nПереход на главную страницу\\n\\n![Screenshot](https://example.com/screenshot.png)\",\n        \"testData\": \"URL: https://example.com\",\n        \"expectedResult\": \"Страница загружена успешно\"\n      }\n    ]\n  }\n}\n```\n\n### Создание тест-рана\n\n```json\n{\n  \"project_key\": \"PROJ\",\n  \"name\": \"Sprint 1 Test Run\",\n  \"test_case_keys\": [\"PROJ-T123\", \"PROJ-T124\", \"PROJ-T125\"],\n  \"environment\": \"Production\"\n}\n```\n\n### Поиск подходящей папки\n\n```json\n{\n  \"project_key\": \"PROJ\",\n  \"test_case_description\": \"Авторизация пользователя через API\"\n}\n```\n\nСервер автоматически найдет наиболее подходящую папку на основе описания.\n\n## Конвертация Markdown\n\nСервер автоматически конвертирует markdown-разметку в HTML для корректного отображения в Zephyr Scale:\n\n- Заголовки (`#`, `##`, `###`) → HTML заголовки\n- **Жирный текст** → `<strong>`\n- *Курсив* → `<em>`\n- `Код` → `<code>`\n- Списки → HTML списки\n- Изображения `![alt](url)` → автоматическая загрузка и встраивание\n\n**Важно**: Технические термины с подчеркиваниями (например, `english_adult_not_native_speaker_course_it`) защищены от конвертации в курсив.\n\n## Лицензия\n\nMIT\n","readmeFilename":"README.md","_rev":"1-3c9917b90c507c689840143b9dc8df29"}