QTM4J MCPサーバー

QMetry Test Management for Jira Cloud (QTM4J) REST APIを、Claude（またはその他のMCP互換クライアント）から呼び出せるツールとして公開するMCPサーバーです。

機能

主要なQTM4Jエンティティ全体で、最も一般的なCRUDフローをカバーするツールを提供します。

すべてのツールはZodで入力を検証し、startAt / maxResults を介してリストエンドポイントをページネーションします。また、レート制限（HTTP 429）が発生した応答に対しては、最大3回まで指数バックオフによる自動再試行を行います。

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 ツールが自動的に表示されます。

設定

サーバーは2つの環境変数を読み取ります:

ローカル設定リファレンス

一般的なフィールド値（プロジェクト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 は数値のJiraプロジェクトID (例: 10011) である必要があり、プロジェクトキー (例: "FS") ではありません。JiraプロジェクトのURLから確認できます: …?projectId=10011&projectKey=FS。

• 検索エンドポイントは POST /…/search を使用します。フィルターはボディの filter に、ページネーション/ソートはクエリ文字列に記述します。MCPハンドラーがこれを自動的にラップします。

• 204 No Content を返す「更新」エンドポイントは、単純な { message: "…" } ペイロードで解決されます。

• Swagger仕様には、現在フレームワーク形式の自動化インポート結果エンドポイント（例: JUnit/TestNG/Cucumberの取り込み）は記載されていません。ここでの自動化ツールは、仕様で公開されているルール実行およびルールリンクフローをカバーしています。