QTM4J MCP Server

MCP сервер, который предоставляет REST API QMetry Test Management for Jira Cloud (QTM4J) в качестве инструментов, которые может вызывать Claude (или любой другой MCP-совместимый клиент).

Возможности

Инструменты охватывают наиболее распространенные процессы CRUD для основных сущностей QTM4J:

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

Требования

• Node.js 18+ (использует встроенный fetch)

• API-ключ QMetry (из QMetry → API Keys)

Установка

git clone https://github.com/salehrifai42/qmetrymcp.git
cd qmetrymcp
npm install
npm run build

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

Сервер настраивается полностью через переменные окружения:

Запуск

QTM4J_API_KEY=your-key npm start

Сервер работает по протоколу MCP через stdio — обычно вы не запускаете его напрямую; ваш MCP-клиент (Claude Desktop, Claude Code и т.д.) запускает его сам.

Настройка MCP-клиента

Все клиенты запускают сервер напрямую с помощью node. Замените /path/to/qmetrymcp на абсолютный путь к папке, куда вы клонировали репозиторий.

Claude Desktop

Отредактируйте файл ~/Library/Application Support/Claude/claude_desktop_config.json в macOS (или аналогичный файл для вашей платформы) и перезапустите Claude Desktop:

{
  "mcpServers": {
    "qtm4j": {
      "command": "node",
      "args": ["/path/to/qmetrymcp/dist/index.js"],
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

Claude Code (CLI)

Используйте команду claude mcp add:

claude mcp add qtm4j \
  -e QTM4J_API_KEY=your-api-key-here \
  -e QTM4J_REGION=US \
  -- node /path/to/qmetrymcp/dist/index.js

Это запишет конфигурацию в ваш пользовательский файл (~/.claude.json). Чтобы ограничить область действия одним репозиторием, создайте файл .mcp.json в корне проекта с той же структурой mcpServers, что и в примере для Claude Desktop выше — Claude Code подхватит его автоматически.

Проверьте, что сервер зарегистрирован:

claude mcp list

В сессии вы также можете выполнить /mcp, чтобы увидеть подключенные серверы и их инструменты.

GitHub Copilot (VS Code)

Режим агента Copilot поддерживает MCP через файл .vscode/mcp.json в вашем рабочем пространстве (или аналогичный блок в пользовательском settings.json в разделе github.copilot.chat.mcp.servers). Обратите внимание: схема Copilot использует servers (а не mcpServers) и ожидает явное указание type:

// .vscode/mcp.json
{
  "servers": {
    "qtm4j": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/qmetrymcp/dist/index.js"],
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

После сохранения откройте панель Copilot Chat, переключитесь в режим Agent, и инструменты qtm4j появятся в выборе инструментов. Если вы не хотите сохранять свой API-ключ в файле, используйте секретный ввод VS Code:

{
  "inputs": [
    { "id": "qtm4jKey", "type": "promptString", "description": "QTM4J API Key", "password": true }
  ],
  "servers": {
    "qtm4j": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/qmetrymcp/dist/index.js"],
      "env": {
        "QTM4J_API_KEY": "${input:qtm4jKey}",
        "QTM4J_REGION": "US"
      }
    }
  }
}

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

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

Найди в проекте QMetry 10011 тест-кейсы со статусом "Approved" и покажи первые 5.

Клиент вызовет search_test_cases с параметрами { projectId: 10011, status: ["Approved"], maxResults: 5 } и отобразит ответ.

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

// Search test cases in project with numeric ID 10011
{
  "name": "search_test_cases",
  "arguments": {
    "projectId": 10011,
    "status": ["Approved"],
    "maxResults": 20
  }
}

// Update an execution result
{
  "name": "update_test_execution",
  "arguments": {
    "cycleId": 1234,
    "testCaseExecutionId": 56789,
    "executionResultId": 2,
    "comment": "Verified on staging"
  }
}

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

• Ответы, отличные от 2xx, возвращают ошибку инструмента с HTTP-статусом и разобранным телом API.

• Сетевые ошибки возвращают описательное сообщение об ошибке.

• Ответы 429 автоматически повторяются с экспоненциальной задержкой (всего до 3 попыток).

Примечания

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

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

• Эндпоинты "Update", возвращающие 204 No Content, завершаются с простым ответом { message: "…" }.

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