Xray MCP

🚀 Xray MCP Server

Model Context Protocol (MCP)サーバーで、Xray Cloud APIをClaude Codeやその他のMCPクライアントと統合します。

✨ 主な機能

このMCPサーバーは、公式のGraphQL APIを使用してXray Cloud内のテストケースとテスト実行を管理するツールを提供します。

テストケース (テスト管理)

• create_test_case：新しいテストケースを作成します（GraphQLミューテーション createTest を使用）
• get_test_case：特定のテストケースの詳細を取得します（GraphQLクエリ getTests を使用）
• delete_test_case：テストケースを削除します（GraphQLミューテーション deleteTest を使用）
• search_test_cases：JQL（Jira Query Language）を使用してテストケースを検索します
• get_project_test_cases：プロジェクトのすべてのテストケースを取得します
• update_test_case：⚠️ 直接サポートされていません - 標準フィールドを更新するにはJira REST APIを使用してください

テスト実行 (テスト自動化とCI/CD)

• create_test_execution：テストを実行するための新しいテスト実行を作成します
• get_test_execution：すべてのテストランを含むテスト実行の詳細を取得します
• search_test_executions：JQLを使用してテスト実行を検索します
• get_project_test_executions：プロジェクトのすべてのテスト実行を取得します
• update_test_run_status：テストランのステータス（PASS、FAILなど）を更新します

テストプラン (テストの組織化)

• create_test_plan：テストを組織化するための新しいテストプランを作成します
• get_test_plan：すべてのテストを含む特定のテストプランの詳細を取得します
• search_test_plans：JQLを使用してテストプランを検索します
• get_project_test_plans：プロジェクトのすべてのテストプランを取得します
• add_tests_to_test_plan：既存のテストプランにテストを追加します
• remove_tests_from_test_plan：テストプランからテストを削除します

テストセット (テストのグルーピング)

• create_test_set：テストをグループ化するための新しいテストセットを作成します
• get_test_set：すべてのテストを含む特定のテストセットの詳細を取得します
• search_test_sets：JQLを使用してテストセットを検索します
• get_project_test_sets：プロジェクトのすべてのテストセットを取得します
• add_tests_to_test_set：既存のテストセットにテストを追加します
• remove_tests_from_test_set：テストセットからテストを削除します

📦 インストール

前提条件

• Node.js 18以上
• Xray Cloud APIの認証情報（クライアントIDとクライアントシークレット）

インストール手順

1. このリポジトリをクローンまたはダウンロードします。
2. 依存関係をインストールします。

npm install

3. プロジェクトをビルドします。

npm run build

API認証情報の取得方法

1. https://xray.cloud.getxray.app/ にアクセスします。
2. Settings → API Keys に移動します。
3. Create API Key をクリックします。
4. 生成されたクライアントIDとクライアントシークレットをコピーします。

💻 使用例

テストケース

テストケースの作成

{
  "projectKey": "ABC",
  "summary": "Verify login functionality",
  "description": "Test that users can log in with valid credentials",
  "testType": "Manual",
  "labels": ["login", "authentication"],
  "priority": "High"
}

テストケースの検索

{
  "jql": "project = ABC AND labels = automation",
  "maxResults": 20
}

プロジェクトのテストケースの取得

{
  "projectKey": "ABC",
  "maxResults": 50
}

テスト実行

テスト実行の作成

{
  "projectKey": "ABC",
  "summary": "Sprint 23 Regression Tests",
  "description": "Regression testing for sprint 23",
  "testIssueIds": ["10001", "10002", "10003"],
  "testEnvironments": ["Chrome", "Firefox"]
}

テスト実行の取得

{
  "testExecutionKey": "ABC-456"
}

テストランのステータスの更新

{
  "testRunId": "5acc7ab0a3fe1b6fcdc3c737",
  "status": "PASS"
}

最近のテスト実行の検索

{
  "jql": "project = ABC AND created >= -7d",
  "maxResults": 20
}

📚 ドキュメント

テストに関する詳細なドキュメント

このプロジェクトには包括的なテストが含まれています。

• 単体テスト：モックAPIレスポンスを使用した高速なテスト（認証情報不要）
• 統合テスト：実際のXray Cloud APIを使用したエンドツーエンドのテスト

# 単体テストの実行
npm run test:unit

# 統合テストの実行（認証情報が必要）
npm run test:integration

# すべてのテストの実行
npm test

詳細なテストドキュメントについては、TESTING.md を参照してください。

プロジェクト構造

xray-mcp/
├── src/
│   ├── index.ts           # メインのMCPサーバー
│   └── xray-client.ts     # Xray Cloud APIのクライアント
├── dist/                  # ビルド後に生成されるコンパイル済みファイル
├── .env.example           # 環境変数のテンプレート
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

Xray Cloud API

このサーバーは以下のXray Cloud APIを使用しています。

• 認証：POST /api/v1/authenticate（トークンの有効期限は24時間）
• GraphQLエンドポイント：POST /api/v2/graphql
  • テストクエリ：getTests - JQLを使用してテストを取得
  • テストミューテーション：createTest, deleteTest - テストの作成/削除
  • テスト実行クエリ：getTestExecutions - JQLを使用してテスト実行を取得
  • テスト実行ミューテーション：createTestExecution, updateTestRunStatus - テスト実行と結果の管理
  • テストプランクエリ：getTestPlans - JQLを使用してテストプランを取得
  • テストプランミューテーション：createTestPlan, addTestsToTestPlan, removeTestsFromTestPlan - テストプランの管理
  • テストセットクエリ：getTestSets - JQLを使用してテストセットを取得
  • テストセットミューテーション：createTestSet, addTestsToTestSet, removeTestsFromTestSet - テストセットの管理

完全なAPIドキュメントについては、以下を参照してください。

• GraphQL API: https://docs.getxray.app/display/XRAYCLOUD/GraphQL+API
• GraphQLスキーマ: https://us.xray.cloud.getxray.app/doc/graphql/
• REST API: https://docs.getxray.app/display/XRAYCLOUD/REST+API

使用方法

Claude Codeでの設定

このMCPサーバーをClaude Codeで使用するには、MCP設定ファイル（通常、macOSでは ~/Library/Application Support/Claude/claude_desktop_config.json）に以下の設定を追加します。

{
  "mcpServers": {
    "xray": {
      "command": "node",
      "args": ["/path/to/xray-mcp/dist/index.js"],
      "env": {
        "XRAY_CLIENT_ID": "your_client_id",
        "XRAY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

重要：

• /path/to/xray-mcp をプロジェクトの絶対パス（例：/Users/manuel/repositories/xray-mcp）に置き換えます。
• your_client_id と your_client_secret をあなたのXray Cloud認証情報に置き換えます。

ローカルでのテスト

開発モードでサーバーをテストするには、以下のコマンドを実行します。

# 環境変数の設定
export XRAY_CLIENT_ID="your_client_id"
export XRAY_CLIENT_SECRET="your_client_secret"

# サーバーの起動
npm run dev

ユースケース

CI/CD統合

このMCPサーバーを使用して、以下のことができます。

1. CI/CDパイプラインで自動的にテスト実行を作成する
2. 自動テスト結果に基づいてテストランのステータスを更新する
3. 異なる環境でのテスト実行を追跡する
4. スプリントレビュー用のテスト実行レポートを生成する

テスト管理

このMCPサーバーを使用して、以下のことができます。

1. テストケースを作成して整理する
2. 複雑なJQLクエリを使用してテストを検索する
3. 手動テスト実行を管理する
4. 時間の経過に伴うテストステータスを追跡する

📄 ライセンス

ISC

サポート

Xray Cloud APIに関する問題や質問については、公式ドキュメントを参照してください。

• https://docs.getxray.app/
• https://support.getxray.app/