QTM4J MCP 서버

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

기능

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

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

Related MCP server: qtm4j-mcp-server

요구 사항

• Node.js 18+ (네이티브 fetch 사용)

• QMetry API 키 (QMetry → API Keys에서 확인)

설정 (모든 클라이언트에서 동일)

1. 복제, 설치, 빌드:

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

2. API 키 추가 — 예시를 복사하여 키를 입력하세요:

cp .env.example .env

그런 다음 .env를 편집하세요:

QTM4J_API_KEY=your-api-key-here
QTM4J_REGION=US

.env는 git-ignored 처리되어 커밋되지 않습니다.

3. 저장소 디렉토리에서 에디터/IDE를 엽니다. 서버는 시작 시 .env를 자동으로 로드하므로 추가 설정이 필요 없습니다:

• Claude Code — 이 디렉토리에서 claude를 실행하세요. .mcp.json이 미리 구성되어 있으며 qtm4j 서버가 자동으로 연결됩니다.

• GitHub Copilot (VS Code) — VS Code에서 폴더를 열고 Copilot Chat을 Agent 모드로 전환하세요. .vscode/mcp.json이 미리 구성되어 있으며 qtm4j 도구가 자동으로 나타납니다.

구성

서버는 두 가지 환경 변수를 읽습니다:

로컬 구성 참조

일반적인 필드 값(프로젝트 ID, 상태, 우선순위, 실행 결과 ID, 폴더 ID 등)이 포함된 config.template.json이 제공됩니다. 로컬 참조를 위해 복사하세요:

cp config.template.json config.json

config.json은 git-ignored 처리됩니다. MCP 서버는 환경 변수에서만 읽습니다.

수동 실행

QTM4J_API_KEY=your-key npm start

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

MCP 클라이언트 구성

Claude Code (CLI)

.mcp.json은 이 저장소와 함께 제공되며 프로젝트 디렉토리에서 Claude Code를 열면 자동으로 감지됩니다. 확인 방법:

claude mcp list

세션 내에서 /mcp를 실행하여 연결된 서버와 해당 도구를 확인하세요.

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"
      }
    }
  }
}

GitHub Copilot (VS Code)

.vscode/mcp.json은 이 저장소와 함께 제공되며 VS Code에서 폴더를 열면 자동으로 감지됩니다. Copilot Chat을 Agent 모드로 전환하면 qtm4j 도구가 자동으로 나타납니다.

사용해 보기

연결되면 어시스턴트에게 다음과 같이 질문해 보세요:

QMetry 프로젝트 10011에서 상태가 "To Do"인 테스트 케이스를 검색해서 처음 5개만 보여줘.

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

테스트 주기 FS-TR-747의 모든 실행을 가져와서 실행되지 않은 항목은 Pass로 표시해.

도구 호출 예시

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

// Update an execution result (executionResultId: 239444=Pass, 239441=Fail, 239443=Not Executed)
{
  "name": "update_test_execution",
  "arguments": {
    "cycleId": "gxMbioKJsyEr3E",
    "testCaseExecutionId": 287595809,
    "executionResultId": 239444,
    "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를 반환하는 "업데이트" 엔드포인트는 간단한 { message: "…" } 페이로드로 해결됩니다.

• Swagger 사양에는 현재 프레임워크 스타일의 자동화 가져오기 결과 엔드포인트(예: JUnit/TestNG/Cucumber 수집)가 문서화되어 있지 않습니다. 여기의 자동화 도구는 사양에 노출된 규칙 실행 및 규칙 연결 흐름을 다룹니다.