QTM4J MCP 서버

QMetry Test Management for Jira Cloud (QTM4J) REST API를 Claude(또는 모든 MCP 호환 클라이언트)가 호출할 수 있는 도구로 노출하는 MCP 서버입니다.

기능

주요 QTM4J 엔티티 전반에 걸쳐 가장 일반적인 CRUD 흐름을 다루는 도구를 제공합니다:

영역	도구
테스트 케이스	`create_test_case`, `get_test_case`, `search_test_cases`, `update_test_case`, `delete_test_case`, `clone_test_cases`, `create_test_steps`, `update_test_steps`
테스트 주기	`create_test_cycle`, `get_test_cycle`, `search_test_cycles`, `update_test_cycle`, `delete_test_cycle`
테스트 실행	`get_test_cycle_executions`, `update_test_execution`, `update_test_step_execution`, `bulk_update_test_executions`
테스트 계획	`create_test_plan`, `get_test_plan`, `search_test_plans`, `update_test_plan`, `delete_test_plan`, `link_test_cycles_to_plan`, `get_linked_test_cycles`, `unlink_test_cycles_from_plan`
폴더	`list_folders`, `create_folder`
자동화	`link_automation_rule`, `unlink_automation_rule`, `run_automation_rules`

모든 도구는 Zod를 사용하여 입력을 검증하고, startAt / maxResults를 통해 목록 엔드포인트의 페이지네이션을 처리하며, 속도 제한(HTTP 429) 응답 시 최대 3회까지 지수 백오프(exponential back-off)를 사용하여 자동으로 재시도합니다.

요구 사항

Node.js 18+ (네이티브 fetch 사용)
QMetry API 키 (QMetry → API Keys에서 확인)

설치

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

구성

서버는 전적으로 환경 변수를 통해 구성됩니다:

변수	필수	기본값	설명
`QTM4J_API_KEY`	예	—	QMetry API 키, 모든 요청 시 `apiKey` 헤더로 전송
`QTM4J_REGION`	아니오	`US`	`US` → `https://qtmcloud.qmetry.com/rest/api/latest`, `AU` → `https://qtmcloud-au.qmetry.com/rest/api/latest`

실행

QTM4J_API_KEY=your-key npm start

서버는 stdio를 통해 MCP와 통신합니다. 일반적으로 직접 실행하지 않으며, MCP 클라이언트(Claude Desktop, Claude Code 등)가 이를 실행합니다.

MCP 클라이언트 구성

모든 클라이언트는 node를 사용하여 서버를 직접 실행합니다. /path/to/qmetrymcp를 저장소를 복제한 절대 경로로 바꾸십시오.

Claude Desktop

macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json을 편집하고(또는 해당 플랫폼의 설정 파일) 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)에 기록합니다. 단일 저장소로 범위를 지정하려면 프로젝트 루트에 위 Claude Desktop 예제와 동일한 mcpServers 형태를 가진 .mcp.json 파일을 두십시오. Claude Code가 자동으로 이를 감지합니다.

등록되었는지 확인하십시오:

claude mcp list

세션 내에서 /mcp를 실행하여 연결된 서버와 해당 도구를 확인할 수도 있습니다.

GitHub Copilot (VS Code)

Copilot의 에이전트 모드는 작업 공간의 .vscode/mcp.json 파일(또는 사용자 settings.json의 github.copilot.chat.mcp.servers 아래 해당 블록)을 통해 MCP를 지원합니다. 참고: 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개만 보여줘.

클라이언트는 { projectId: 10011, status: ["Approved"], maxResults: 5 }와 함께 search_test_cases를 호출하고 응답을 렌더링합니다.

도구 호출 예시

// 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는 프로젝트 키(예: "FS")가 아닌 숫자 형태의 Jira 프로젝트 ID(예: 10011)여야 합니다. Jira 프로젝트 URL에서 확인할 수 있습니다: …?projectId=10011&projectKey=FS.
검색 엔드포인트는 POST /…/search를 사용합니다. 필터는 본문의 filter 아래에 들어가며, 페이지네이션/정렬은 쿼리 문자열에 들어갑니다. MCP 핸들러가 이를 자동으로 처리합니다.
204 No Content를 반환하는 "Update" 엔드포인트는 간단한 { message: "…" } 페이로드로 해결됩니다.
Swagger 사양에는 현재 프레임워크 스타일의 자동화 결과 가져오기 엔드포인트(예: JUnit/TestNG/Cucumber 수집)가 문서화되어 있지 않습니다. 여기의 자동화 도구는 사양에 노출된 규칙 실행 및 규칙 연결 흐름을 다룹니다.

QTM4J MCP Server