rtm-mcp

С открытым исходным кодом MCP-сервер (Model Context Protocol) для REST API v2 Requirements and Test Management for Jira. Предоставляет требования, тест-кейсы, тест-планы, тестовые выполнения, выполнения тест-кейсов, дефекты, структуру дерева и автоматизацию в виде MCP-инструментов, чтобы любой MCP-совместимый клиент (Claude Desktop, расширения IDE, пользовательские агенты) мог напрямую управлять RTM.

Запустите его с помощью NPX — без установки и клонирования:

npx rtm-mcp

Ссылки

• 📦 npm-пакет: https://www.npmjs.com/package/rtm-mcp

• 🐙 Репозиторий GitHub: https://github.com/ngocdd/rtm-mcp

• 🐛 Трекер задач: https://github.com/ngocdd/rtm-mcp/issues

• 📚 Документация RTM API: https://deviniti.com/support/addon/cloud/requirements-test-management/latest/rest-api/

Возможности

• 32 MCP-инструмента, охватывающих CRUD, управление связями, вложения и импорт результатов CI для каждого ресурса RTM.

• Аутентификация по Bearer-токену через RTM_API_TOKEN. Сгенерируйте токен в Jira: Apps → Requirements and Test Management → ⋯ → Rest API authentication → Generate Token.

• Регионы US + EU — переключение через RTM_BASE_URL.

• Повторные попытки + таймауты + джиттер встроены в HTTP-клиент (обрабатывает 429/5xx/сетевые ошибки).

• Типизированные ошибки, преобразуемые в понятные сообщения об ошибках MCP — никогда не утекают стектрейсы.

• Загрузка вложений принимает base64-данные (безопасно для изолированных MCP-клиентов).

• Логирование только в stderr — stdout остаётся чистым для JSON-RPC.

Related MCP server: Jira QMetry MCP Server

Быстрый старт

1. Сгенерируйте RTM API-токен

1. Откройте Jira.

2. Перейдите в Apps → Requirements and Test Management.

3. Нажмите на меню из трёх точек (⋯) → Rest API authentication.

4. Нажмите Generate Token, выберите пользователя, добавьте метку, нажмите Generate.

5. Скопируйте токен сразу — RTM больше его не покажет.

2. Запустите сервер

RTM_API_TOKEN=your-token-here npx rtm-mcp

Сервер общается по MCP через stdio — укажите на него вашему MCP-клиенту.

Настройка Claude Desktop

Добавьте в claude_desktop_config.json:

US / Global (URL по умолчанию):

{
  "mcpServers": {
    "rtm": {
      "command": "npx",
      "args": ["-y", "rtm-mcp"],
      "env": {
        "RTM_API_TOKEN": "<your-token-here>",
        "RTM_BASE_URL": "https://rtm-us.deviniti.com/api"
      }
    }
  }
}

Регион EU:

{
  "mcpServers": {
    "rtm": {
      "command": "npx",
      "args": ["-y", "rtm-mcp"],
      "env": {
        "RTM_API_TOKEN": "<your-token-here>",
        "RTM_BASE_URL": "https://rtm-eu-api.hexygen.com/api"
      }
    }
  }
}

Настройка Claude Code CLI

Используйте команду claude mcp add, чтобы зарегистрировать сервер в Claude Code.

Пользовательская область (рекомендуется — доступно во всех ваших проектах)

claude mcp add --scope user --transport stdio rtm \
  -e RTM_API_TOKEN=<your-token-here> \
  -e RTM_BASE_URL=https://rtm-us.deviniti.com/api \
  -- npx -y rtm-mcp

Регион EU:

claude mcp add --scope user --transport stdio rtm \
  -e RTM_API_TOKEN=<your-token-here> \
  -e RTM_BASE_URL=https://rtm-eu-api.hexygen.com/api \
  -- npx -y rtm-mcp

--scope user записывает запись в ~/.claude.json, чтобы каждый проект Claude Code на этой машине мог видеть сервер rtm.

Область проекта (только этот проект)

claude mcp add --scope project --transport stdio rtm \
  -e RTM_API_TOKEN=<your-token-here> \
  -e RTM_BASE_URL=https://rtm-us.deviniti.com/api \
  -- npx -y rtm-mcp

Записывает в .mcp.json в текущем каталоге (сохраняется в git).

Проверьте регистрацию

claude mcp list           # see all configured servers
claude mcp get rtm        # inspect the rtm entry

Удалите сервер

claude mcp remove rtm

Конфигурация

Отсутствующий или пустой RTM_API_TOKEN прерывает запуск с понятной подсказкой.

Доступные инструменты

Все инструменты возвращают MCP-text содержимое с красиво отформатированным JSON. Всего 32 инструмента, сгруппированных по ресурсам RTM ниже. Используйте команду списка инструментов MCP-хоста, чтобы перечислить их во время выполнения.

Требования (REQUIREMENTS)

• rtm_get_requirement — получить по requirementKey

• rtm_create_requirement — создать

• rtm_update_requirement — частичное обновление

• rtm_delete_requirement — окончательное удаление

У RTM нет конечной точки списка для требований — используйте rtm_get_tree_structure для их перечисления по проекту.

Тест-кейсы (TEST_CASES)

• rtm_get_test_case — получить по testCaseKey

• rtm_create_test_case — создать (передайте stepGroups для определения шагов)

• rtm_update_test_case — частичное обновление

• rtm_update_test_case_covered_requirements — управление связями покрытых требований. Передайте ровно одно из set / add / remove. Проводной вызов: PUT /api/v2/test-case/{key}/covered-requirements с телом { coveredRequirements: { <op>: [...] } }.

rtm_delete_test_case намеренно не предоставлен — выполняйте удаление через интерфейс Jira. У RTM нет конечной точки списка — используйте rtm_get_tree_structure.

Тест-планы (TEST_PLANS)

Отражает 8 конечных точек, задокументированных в публичном RTM REST API:

• rtm_get_test_plan — GET /api/test-plan/{testKey}

• rtm_create_test_plan — POST /api/test-plan

• rtm_update_test_plan — PUT /api/test-plan/{testKey}

• rtm_delete_test_plan — DELETE /api/test-plan/{testKey}

• rtm_update_test_plan_tc_order — PUT /api/test-plan/{testKey}/tc-order с телом { order: [...] }

• rtm_create_test_plan_folder — POST /api/test-plan/{testKey}/tree/folders

• rtm_add_test_case_to_test_plan — POST /api/test-plan/{testKey}/testcases с телом { testKey: "..." }

• rtm_remove_test_case_from_test_plan — DELETE /api/test-plan/{testKey}/testcases/{tcKey}

У RTM нет конечной точки списка — используйте rtm_get_tree_structure.

Тестовые выполнения (TEST_EXECUTIONS)

• rtm_get_test_execution — получить по testExecutionKey

• rtm_create_test_execution — создать, выполнив тест-план (передайте testPlanTestKey)

• rtm_update_test_execution — частичное обновление (принимает status, summary, description, priority, owner, customFields)

• rtm_delete_test_execution — окончательное удаление

У RTM нет конечной точки списка — используйте rtm_get_tree_structure.

Выполнения тест-кейсов (TCE)

TCE = одна строка в тестовом выполнении, которая фиксирует результат запуска одного тест-кейса.

• rtm_get_test_case_execution — получить один TCE (результат, исполнитель, комментарий, дефекты, шаги)

• rtm_update_test_case_execution — частичное обновление. Передайте result: "Fail" (или "Pass", "Blocked", …), чтобы изменить статус прохождения. Проводной вызов: PUT /api/v2/test-case-execution/{key} с телом { result: { name: "Fail" } }.

• rtm_link_defect_to_test_case_execution — связать дефект со всем TCE

• rtm_link_defect_to_test_case_execution_step — связать дефект с конкретным шагом

• rtm_list_test_case_execution_attachments — список вложений на TCE

• rtm_upload_test_case_execution_attachment (входные данные base64) — загрузить файл в TCE

• rtm_get_test_case_execution_attachment — получить метаданные одного вложения (возвращает URL для скачивания)

• rtm_list_test_case_execution_step_attachments — список вложений на одном шаге

• rtm_upload_test_case_execution_step_attachment (входные данные base64) — загрузить файл на конкретный шаг

Конечные точки DELETE на TCE (unlink defect, delete attachment) намеренно не предоставлены — выполняйте их через интерфейс Jira или вызывайте базовый REST API напрямую. Конечные точки существуют; были удалены только одноразовые MCP-обёртки, потому что разрушительные операции должны быть за подтверждением.

Дефекты

• rtm_get_defect — получить по defectKey

• rtm_create_defect — создать (передайте identifyingTestCases для связи с тест-кейсами)

• rtm_update_defect — частичное обновление

• rtm_delete_defect — окончательное удаление

У RTM нет конечной точки списка — используйте rtm_get_tree_structure или jira_search через Atlassian MCP.

Дерево

• rtm_get_tree_structure — получить дерево папок для проекта. Требует числовой projectId (разрешается из projectKey через Jira REST API) и treeType ∈ REQUIREMENTS / TEST_CASES / TEST_PLANS / TEST_EXECUTIONS.

Автоматизация

• rtm_import_test_results — загрузить ZIP/TAR.GZ архив с отчётами JUnit / NUnit / Cucumber JSON; возвращает taskId

• rtm_get_import_status — опрашивать предыдущий taskId, пока status не выйдет из IMPORTING

Соглашения, используемые для каждого ресурса

Примеры

«Перечислите требования в проекте ACME.»

> // No list endpoint — fetch the tree and walk it.
> rtm_get_tree_structure { projectId: 10000, treeType: "REQUIREMENTS" }

«Создайте тест-кейс с названием "Login with valid credentials" в папке /Smoke и свяжите его с требованием ACME-42.»

> rtm_create_test_case { projectKey: "ACME", summary: "Login with valid credentials", folder: "/Smoke", stepGroups: [...] }
> rtm_update_test_case_covered_requirements { testCaseKey: "<new>", set: ["ACME-42"] }

«Добавьте 3 тест-кейса в план KAN-52, не заменяя существующий набор.»

> rtm_update_test_plan_included_test_cases {
    testPlanKey: "KAN-52",
    add: ["KAN-30", "KAN-31", "KAN-32"]
  }

«Свяжите дефект KAN-100 с выполнением тест-кейса KAN-53-KAN-46 на шаге 8517443.»

> rtm_link_defect_to_test_case_execution_step {
    testCaseExecutionKey: "KAN-53-KAN-46",
    stepId: "8517443",
    defectTestKey: "KAN-100"
  }

«Отметьте TCE KAN-53-KAN-46 как Failed и добавьте комментарий.»

> rtm_update_test_case_execution {
    testCaseExecutionKey: "KAN-53-KAN-46",
    result: "Fail",
    comment: "Login button did not respond after 3 retries"
  }

«Прикрепите скриншот к шагу 2 TCE KAN-53-KAN-46.»

> rtm_upload_test_case_execution_step_attachment {
    testCaseExecutionKey: "KAN-53-KAN-46",
    stepId: "8517444",
    filename: "evidence.png",
    contentBase64: "<base64 bytes>",
    mimeType: "image/png"
  }

«Импортируйте вчерашний JUnit XML.»

> rtm_import_test_results {
    projectKey: "ACME",
    filename: "junit.zip",
    contentBase64: "<base64>",
    reportType: "JUNIT",
    jobUrl: "https://ci/job/123"
  }
> rtm_get_import_status { taskId: "<returned>" }

Устранение неполадок

Разработка

git clone <repo>
cd rtm-mcp
npm install
npm run build         # compile to dist/
npm test              # unit tests
npm run dev           # run from src/ via tsx
npm run typecheck     # tsc --noEmit

Структура проекта

src/
├── index.ts                  # entry point (shebang)
├── server.ts                 # McpServer wiring
├── config/                   # env validation + constants
├── client/
│   ├── http.ts               # fetch wrapper w/ retry + timeout
│   ├── errors.ts             # RTMError hierarchy
│   └── rtm-client.ts         # facade composing all resources
├── resources/                # one file per RTM resource
├── tools/                    # MCP tool registrations
├── schemas/                  # zod input schemas per tool group
└── utils/                    # logger, MCP response helpers
tests/
├── unit/                     # mocked fetch tests
└── integration/              # opt-in live tests (gated by RTM_LIVE=1)

Живые интеграционные тесты

RTM_API_TOKEN=xxx \
RTM_BASE_URL=https://rtm-us.deviniti.com/api \
RTM_LIVE=1 \
RTM_TEST_PROJECT=ACME \
npm run test:integration

Используйте Jira-проект как песочницу. Смоук-тест создаёт Requirement, получает его, перечисляет соседние и очищает.

Публикация

npm login
npm version patch   # or minor / major
npm publish --access public

prepublishOnly автоматически запускает typecheck, test, build.

Вклад в проект

Это проект с открытым исходным кодом — приветствуются issues и PR!

1. Сделайте форк репозитория: https://github.com/ngocdd/rtm-mcp

2. Создайте feature-ветку: git checkout -b feat/my-tool

3. Установите зависимости и запустите тесты локально:

   npm install
   npm run typecheck
   npm test

4. Добавьте тесты для любого нового метода ресурса или инструмента.

5. Откройте Pull Request в main: https://github.com/ngocdd/rtm-mcp/compare

Добавление нового RTM-эндпоинта

1. Добавьте типизированный метод в соответствующий модуль src/resources/<resource>.ts.

2. Добавьте входную схему zod в src/schemas/<resource>.schema.ts.

3. Зарегистрируйте MCP-инструмент в src/tools/<resource>.ts.

4. Добавьте модульный тест в tests/unit/.

5. Запустите npm run typecheck && npm test.

Сообщение об ошибках

Используйте https://github.com/ngocdd/rtm-mcp/issues — укажите тип RTM-ресурса, путь эндпоинта, ожидаемый и фактический ответ, а также (отредактированное) тело запроса.

Лицензия

MIT — см. LICENSE.

Авторские права (c) 2026 участники rtm-mcp. Выпущено под лицензией MIT; вы можете свободно использовать, изменять и распространять этот проект как в открытом, так и в проприетарном ПО, при условии сохранения уведомления об авторских правах.