MCP

🚀 Testomat.io MCP Server

Testomat.io MCP Server 是一個用於將 Testomat.io API 與 Cursor 等 AI 助手集成的模型上下文協議（MCP）服務器，為開發者提供便捷的測試管理和查詢功能。

🚀 快速開始

本服務器為 Testomat.io API 與 AI 助手（如 Cursor）的集成提供了支持。你可以按照以下步驟安裝並使用它。

📦 安裝指南

前提條件

• Node.js 18 或更高版本（需支持內置的 fetch 功能）
• npm 或 yarn 包管理器
• 擁有具備 API 訪問權限的 Testomat.io 賬戶

通過 npm 安裝

npm install -g @testomatio/mcp

或者使用 npx 直接運行

npx @testomatio/mcp --token <your-token> --project <project-id>

💻 使用示例

命令行選項

MCP 服務器可以通過命令行參數或環境變量啟動：

使用命令行參數

# 使用短標誌
npx @testomatio/mcp -t testomat_YOUR_TOKEN_HERE -p your-project-id

# 使用長標誌
npx @testomatio/mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id

# 如果全局安裝
testomatio-mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id

# 使用自定義基礎 URL
npx @testomatio/mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id --base-url https://your-instance.testomat.io

使用環境變量

# 設置環境變量
export TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE
export TESTOMATIO_BASE_URL=https://app.testomat.io  # 可選，默認為 https://app.testomat.io

# 使用項目 ID 運行
npx @testomatio/mcp --project your-project-id

# 或者直接使用環境變量運行
TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE npx @testomatio/mcp --project your-project-id

獲取 API 令牌

1. 訪問 Testomat.io
2. 導航至用戶令牌頁面 https://app.testomat.io/account/access_tokens
3. 創建並複製 通用 API 令牌（以 testomat_ 開頭）

獲取項目 ID

在查看項目時，項目 ID 可以在 URL 中找到：

https://app.testomat.io/projects/YOUR_PROJECT_ID

與 Cursor 集成

要在 Cursor 中使用此 MCP 服務器，請將以下配置添加到 Cursor 設置中：

選項 1：使用 npx（推薦）

將以下內容添加到你的 Cursor MCP 設置（cursor-settings.json 或通過 Cursor 設置界面）：

{
  "mcpServers": {
    "testomatio": {
      "command": "npx",
      "args": ["@testomatio/mcp", "--token", "testomat_YOUR_TOKEN_HERE", "--project", "YOUR_PROJECT_ID"]
    }
  }
}

選項 2：使用環境變量

首先，在你的 shell 配置文件（如 .bashrc, .zshrc 等）中設置環境變量：

export TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE

然後將以下內容添加到你的 Cursor MCP 設置中：

{
  "mcpServers": {
    "testomatio": {
      "command": "npx",
      "args": ["@testomatio/mcp", "--project", "YOUR_PROJECT_ID"],
      "env": {
        "TESTOMATIO_API_TOKEN": "testomat_YOUR_TOKEN_HERE"
      }
    }
  }
}

選項 3：全局安裝

如果你已經全局安裝了該包：

{
  "mcpServers": {
    "testomatio": {
      "command": "testomatio-mcp",
      "args": ["--token", "testomat_YOUR_TOKEN_HERE", "--project", "YOUR_PROJECT_ID"]
    }
  }
}

✨ 主要特性

工具

測試

• get_tests – 獲取所有測試（參數：plan, query, state, suite_id, tag, labels） — API：GET /tests
• search_tests – 搜索測試（參數：query, tql, labels, state, priority, filter, page） — API：GET /tests

測試套件

• search_suites – 搜索套件（參數：query, labels, state, priority, page） — API：GET /suites
• get_root_suites – 列出根級套件（無參數） — API：GET /suites
• get_suite – 獲取一個套件（參數：suite_id） — API：GET /suites/{suite_id}

測試運行

• get_runs – 列出所有運行（無參數） — API：GET /runs
• get_run – 獲取一次運行（參數：run_id, tree） — API：GET /runs/{run_id}
• get_testruns – 某個測試的運行記錄（參數：test_id, finished_at_date_range） — API：GET /testruns

測試計劃

• get_plans – 列出所有計劃（參數：detail, labels, page） — API：GET /plans
• get_plan – 獲取一個計劃（參數：plan_id） — API：GET /plans/{plan_id}

💻 使用示例

基礎用法

配置完成後，你可以向 AI 助手提出以下問題：

• "Show me all the tests in the project"（顯示項目中的所有測試）
• "Get the test runs for test ID abc123"（獲取測試 ID 為 abc123 的測試運行記錄）
• "What are the root suites in this project?"（該項目中的根套件有哪些？）
• "Show me details for test run xyz789"（顯示測試運行 xyz789 的詳細信息）
• "List all automated tests with the @smoke tag"（列出所有帶有 @smoke 標籤的自動化測試）
• "Get all test plans for this project"（獲取該項目的所有測試計劃）

🔍 查詢模式

基本信息查詢

這些查詢用於檢索通用信息，無需特定過濾：

• "Show me all the tests in the project" → get_tests 工具
• "What are the root suites in this project?" → get_root_suites 工具
• "Get all test runs" → get_runs 工具
• "Get all test plans for this project" → get_plans 工具

特定項目查詢

這些查詢通過 ID 定位特定實體：

• "Get test runs for test ID abc123" → get_testruns 工具，test_id: "abc123"
• "Show me details for test run xyz789" → get_run 工具，run_id: "xyz789"
• "Get suite details for suite-456" → get_suite 工具，suite_id: "suite-456"

搜索和過濾查詢

這些查詢使用高級過濾功能：

• "List all automated tests with the @smoke tag" → search_tests 工具，query: "@smoke"，state: "automated"
• "Find tests with priority high" → search_tests 工具，priority: "high"
• "Search for tests containing 'login'" → search_tests 工具，query: "login"
• "List tests tagged @critical or labelled 'ux' with high priority" → search_tests 工具，tql: "tag == 'critical' or label == 'ux' and priority == 'high'"
• "Find tests linked to JIRA-123" → search_tests 工具，tql: jira == 'BDCP-2'

高級查詢語法

測試查詢語言（TQL）

search_tests 工具支持使用 TQL 進行復雜過濾：

"tag == 'smoke' and state == 'manual'"
"priority == 'high' or label == 'ux'"

基於標籤的搜索

可以使用 @ 前綴搜索標籤：

@smoke        # 帶有 'smoke' 標籤的測試
@regression   # 帶有 'regression' 標籤的測試
@critical     # 帶有 'critical' 標籤的測試

Jira 集成

可以使用問題鍵查找與 Jira 問題關聯的測試：

JIRA-123      # 與 JIRA-123 關聯的測試
PROJ-456      # 與 PROJ-456 關聯的測試

🛠️ 故障排除

常見問題

1. "API token is required" 錯誤

   • 確保你的令牌以 testomat_ 開頭
   • 驗證令牌在你的 Testomat.io 項目設置中是否正確

2. "Project ID is required" 錯誤

   • 檢查你傳遞的項目 ID 是否正確
   • 驗證項目 ID 是否存在，並且你有權限訪問

3. 連接錯誤

   • 確保你有互聯網連接
   • 檢查防火牆是否允許連接到 app.testomat.io
   • 驗證你的 API 令牌是否具有必要的權限

4. MCP 服務器在 Cursor 中無法啟動

   • 檢查 Cursor 的 MCP 日誌以獲取錯誤信息
   • 確保已安裝並可訪問 Node.js 18+
   • 嘗試先手動運行命令進行測試

調試模式

運行服務器時查看詳細日誌：

DEBUG=* npx @testomatio/mcp --token <token> --project <project-id>

📚 詳細文檔

有關底層 Testomat.io API 的詳細信息，請參考 Testomat.io API 文檔。

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

🎈 支持

如需支持，請：

1. 查看 Testomat.io 文檔
2. 在 GitHub 上提交問題
3. 聯繫 Testomat.io 支持團隊

📝 變更日誌

v1.0.0

• 初始版本發佈
• 支持所有主要的 Testomat.io API 端點
• 兼容 MCP 的工具接口
• 為大語言模型（LLM）處理提供語義 XML 格式化