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 格式化