Xray MCP

🚀 Xray MCP 服務器

Xray MCP 服務器用於將 Xray Cloud API 與 Claude Code 及其他 MCP 客戶端集成，藉助官方 GraphQL API 管理 Xray Cloud 中的測試用例和測試執行。

✨ 主要特性

此 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 查詢語言）搜索測試用例
• 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：更新測試運行的狀態（通過、失敗等）

測試計劃（測試組織）

• 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. 導航至 設置 → API 密鑰
3. 點擊 創建 API 密鑰
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
}

在 Claude Code 中配置

要在 Claude Code 中使用此 MCP 服務器，請在 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

📚 詳細文檔

項目結構

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

使用場景

CI/CD 集成

使用此 MCP 服務器可以：

1. 在 CI/CD 管道中自動創建測試執行
2. 根據自動化測試結果更新測試運行狀態
3. 跟蹤不同環境中的測試執行
4. 生成用於 sprint 評審的測試執行報告

測試管理

使用此 MCP 服務器可以：

1. 創建和組織測試用例
2. 使用複雜的 JQL 查詢搜索測試
3. 管理手動測試執行
4. 隨時間跟蹤測試狀態

📄 許可證

ISC

支持

有關 Xray Cloud API 的問題或疑問，請查閱官方文檔：

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