QTM4J MCP Server

MCP-сервер с 42 инструментами для QMetry Test Management for Jira (QTM4J). Ищите и управляйте тест-кейсами, циклами, выполнениями, планами, папками, правилами автоматизации и метаданными проекта из Claude Desktop, Claude Code, VS Code Copilot, Cursor или любого другого MCP-совместимого клиента.

Распространение:

• npm: qtm4j-mcp-server

• Реестр MCP: io.github.salehrifai42/qtm4j-mcp-server

• GitHub: salehrifai42/qmetrymcp

Быстрый старт (клонирование не требуется)

Вам понадобится API-ключ QMetry (QMetry → API Keys) и Node.js 18+.

Claude Desktop

Отредактируйте файл конфигурации и перезапустите Claude:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "qtm4j": {
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add qtm4j -e QTM4J_API_KEY=your-api-key-here -e QTM4J_REGION=US -- npx -y qtm4j-mcp-server@^0.1

VS Code (режим агента GitHub Copilot)

Создайте .vscode/mcp.json в вашей рабочей области:

{
  "servers": {
    "qtm4j": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": {
        "QTM4J_API_KEY": "${env:QTM4J_API_KEY}",
        "QTM4J_REGION": "US"
      }
    }
  }
}

Переключите Copilot Chat в режим Agent, и инструменты qtm4j_* появятся автоматически.

Cursor

Добавьте в ~/.cursor/mcp.json (или <project>/.cursor/mcp.json для уровня проекта):

{
  "mcpServers": {
    "qtm4j": {
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": { "QTM4J_API_KEY": "your-api-key-here" }
    }
  }
}

В примерах конфигурации выше пакет зафиксирован на версии ^0.1, чтобы будущие критические обновления не привели к автоматическому обновлению. Удалите суффикс @^0.1, если предпочитаете всегда использовать последнюю версию.

Глобальная установка (быстрый запуск)

npx переустанавливает пакет при каждом запуске, что добавляет несколько секунд задержки. Если вы часто используете сервер, установите его глобально и укажите клиенту путь к бинарному файлу напрямую:

npm install -g qtm4j-mcp-server

Затем в конфигурации клиента замените команду npx:

{
  "mcpServers": {
    "qtm4j": {
      "command": "qtm4j-mcp-server",
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

Компромисс: мгновенный запуск и работа в офлайне, но вам нужно будет выполнять npm update -g qtm4j-mcp-server для получения новых версий.

Related MCP server: qtm4j-mcp-server

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

💡 Установите QTM4J_REGION=AU, если ваш экземпляр QMetry находится в кластере Сиднея.

Инструменты

Все инструменты имеют префикс qtm4j_ во избежание конфликтов с другими MCP-серверами.

См. docs/TOOLS.md для полного справочника и docs/COOKBOOK.md для примеров промптов, которые коллеги могут вставить в любой MCP-клиент.

Каждый инструмент поставляется с аннотациями (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), чтобы клиенты могли решить, нужно ли запрашивать подтверждение. Инструменты чтения принимают параметр response_format (по умолчанию json или markdown для человекочитаемого вывода). Большие ответы автоматически обрезаются на 25 000 символов с подсказкой сузить запрос.

Все инструменты проверяют входные данные с помощью Zod, поддерживают пагинацию через startAt/maxResults и автоматически повторяют запросы при ограничении частоты (HTTP 429) с экспоненциальной задержкой (до 3 попыток).

Проверка в работе

После подключения попросите своего помощника о чем-то вроде:

Найди в проекте QMetry <ваш ID проекта> тест-кейсы со статусом "To Do" и покажи мне первые 5.

Клиент вызовет qtm4j_search_test_cases и отобразит ответ.

Получи все выполнения в цикле тестирования FS-TR-747 и отметь все невыполненные как Pass.

Примеры вызовов инструментов

Замените 10011 ниже на ваш числовой ID проекта Jira. Его можно найти в URL проекта: …?projectId=10011&projectKey=FS.

// Search test cases
{
  "name": "qtm4j_search_test_cases",
  "arguments": {
    "projectId": 10011,
    "status": ["Approved"],
    "maxResults": 20,
    "response_format": "markdown"
  }
}

// Update an execution result
// (executionResultId: 239444=Pass, 239441=Fail, 239443=Not Executed)
{
  "name": "qtm4j_update_test_execution",
  "arguments": {
    "cycleId": "gxMbioKJsyEr3E",
    "testCaseExecutionId": 287595809,
    "executionResultId": 239444,
    "comment": "Verified on staging"
  }
}

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

• Инструменты не появляются в клиенте. Перезапустите клиент после редактирования конфигурации. Проверьте claude mcp list (Claude Code) или панель MCP в VS Code для проверки статуса подключения. При первом запуске npx -y qtm4j-mcp-server может потребоваться несколько секунд для загрузки пакета.

• 401 Unauthorized. Ваш QTM4J_API_KEY недействителен или истек. Создайте новый в QMetry → API Keys.

• 404 на эндпоинтах выполнения или поиска. Многие эндпоинты требуют внутренний числовой id, а не человекочитаемый ключ, такой как FS-TR-747. Сначала вызовите qtm4j_get_test_cycle, чтобы перевести ключ во внутренний ID.

• Пустой или слишком большой ответ папки. Передайте folderId в qtm4j_list_folders для ограничения области поиска поддеревом — полные деревья проектов в крупных проектах могут превысить лимит размера ответа.

• projectId отклонен. Используйте числовой ID проекта Jira (например, 10011), а не ключ проекта ("FS"). Его можно найти в URL проекта Jira: …?projectId=10011&projectKey=FS.

Примечания

• Эндпоинты поиска используют POST /…/search — фильтры помещаются в тело запроса под ключом filter, пагинация/сортировка — в строке запроса. Обработчики инструментов делают это за вас.

• Ответы 204 No Content разрешаются как { message: "…" }.

• Спецификация Swagger в настоящее время не документирует эндпоинт импорта результатов автоматизации в стиле фреймворков (например, JUnit/TestNG/Cucumber); инструменты автоматизации покрывают потоки запуска правил и связывания правил, описанные в спецификации.

Разработка

Локальная настройка, если вы хотите изменить сервер:

git clone https://github.com/salehrifai42/qmetrymcp.git
cd qmetrymcp
npm install
npm run build
QTM4J_API_KEY=your-key npm start

Протестируйте изменения с помощью MCP Inspector:

QTM4J_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

Ошибки и вклад

Нашли ошибку или хотите предложить функцию? Откройте issue на https://github.com/salehrifai42/qmetrymcp/issues. PR приветствуются.

Лицензия

MIT