Testomatio MCP Server

Testomat.io MCP 服务

Model Context Protocol（MCP）服务，支持 AI 助手（Claude、Cursor、OpenCode 等）与 Testomat.io Public API v2 交互。

功能

• 每个实体提供一个 CLI 风格工具 - tests、suites、runs、testruns、plans、rungroups、steps、snippets、labels、requirements、branches、tags、milestones、issues；每个工具都接受一个 command 参数（list、get、create、update、delete，以及适用时的作用域内 issues_*/attachments_*/share 命令）和扁平的命令参数
• 项目信息 - 获取项目配置、元数据、功能和 CI 配置文件
• 问题关联 - 将问题关联到任意资源，或解除关联（每个实体上的 issues_* 命令，以及全局 issues 工具）
• 附件 - tests、suites 和 testruns 上的 attachments_* 命令；上传时将本地文件路径作为 multipart 字段 files 发送
• 需求 - 支持从本地文件路径上传文件
• API 兼容性 - 自动处理负载格式差异（扁平格式与封装格式）
• 自动 API 会话 - 使用 API 会话在 Testomat.io 历史记录中对 MCP 变更进行分组
• 运行管理 - 通过 status_event 参数进行状态转换
• 仅使用 TQL 搜索 - tests/runs 的 command: "list" 使用 tql 作为唯一搜索/筛选输入
• 内置 TQL 参考 - TQL 参数包含精确的字段白名单和示例；tql_help 可按需提供语法详情
• 工具范围配置 - 通过 --tools full|core|read（默认值为 full）仅开放会话所需的工具；降低长时间 Agent 会话中每次调用的架构开销

快速开始

安装

npm install -g @testomatio/mcp@latest

需要企业分析工具？请改为安装 @testomatio/mcp-enterprise@latest。详情请参阅下文的 Enterprise Analytics 部分。

配置

必需凭据：

• TESTOMATIO_PROJECT_TOKEN - 项目 API 令牌
• TESTOMATIO_PROJECT_ID - 项目 ID

运行服务：

npx testomatio-mcp --token <PROJECT_TOKEN> --project <PROJECT_ID>

或使用环境变量：

export TESTOMATIO_PROJECT_TOKEN=<PROJECT_TOKEN>
export TESTOMATIO_PROJECT_ID=<PROJECT_ID>
npx testomatio-mcp

仅提供主机名时，会自动扩展为 https://<host>。如需完全控制，请使用 --base-url / TESTOMATIO_BASE_URL，其优先级高于主机选项

可选：工具范围配置

默认情况下，服务会开放所有工具。对于较长且对令牌用量敏感的会话，可使用 --tools 开放较少的工具：

npx testomatio-mcp --token <PROJECT_TOKEN> --project <PROJECT_ID> --tools core

配置	开放内容
full（默认值）	全部
core	核心实体的所有命令（不包括 steps、snippets、labels、rungroups 工具）
read	核心实体的只读命令（list、get、search、issues_list、attachments_list）

值不区分大小写；若值未知，服务将无法启动。启动时可通过标志或 TESTOMATIO_TOOLS 环境变量设置配置——会话开始后无法更改。两者同时设置时，CLI 标志优先。

与 AI 助手配合使用

Cursor IDE

将此配置添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json 以全局使用：

{
  "mcpServers": {
    "testomatio": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@testomatio/mcp@latest",
        "--token",
        "<TOKEN>",
        "--project",
        "<PROJECT_ID>"
      ],
      "env": {
        "TESTOMATIO_BASE_URL": "https://app.testomat.io"
      }
    }
  }
}

Claude Desktop

将此配置添加到：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "testomatio": {
      "command": "npx",
      "args": [
        "-y",
        "@testomatio/mcp@latest",
        "--token",
        "<TOKEN>",
        "--project",
        "<PROJECT_ID>"
      ],
      "env": {
        "TESTOMATIO_BASE_URL": "https://app.testomat.io"
      }
    }
  }
}

OpenCode

将此配置添加到项目根目录中的 opencode.json，或添加到 ~/.config/opencode/opencode.json 以全局使用：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "testomat": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@testomatio/mcp@latest",
        "--token",
        "<TOKEN>",
        "--project",
        "<PROJECT_ID>"
      ],
      "enabled": true,
      "environment": {
        "TESTOMATIO_BASE_URL": "https://app.testomat.io"
      }
    }
  }
}

HTTP 传输

除标准输入/输出（stdio）外，服务器还会通过 Testomat.io 托管在 Cloudflare Worker 上的 Streamable HTTP 运行。项目名称包含在 URL 中，因此所有工具签名保持不变：

https://mcp.testomat.io/mcp/<project_id>

使用项目令牌，将 MCP 客户端指向该 URL：

{
  "mcpServers": {
    "testomatio": {
      "url": "https://mcp.testomat.io/mcp/<PROJECT_ID>",
      "headers": {
        "Authorization": "Bearer <PROJECT_TOKEN>"
      }
    }
  }
}

claude.ai 等 Web 连接器无法提供静态令牌，因此会针对同一 URL 使用带 PKCE 的 OAuth 2.1 和动态客户端注册。以 testomat_ 或 tstmt_ 开头的令牌始终会绕过 OAuth，直接传递，因此 IDE 客户端和 CI 仍可正常工作。

端点仅支持 POST；GET 会返回 405，因为服务器不会主动发起流量。使用 curl 测试时，Accept 中必须包含这两种媒体类型：

curl -sS https://mcp.testomat.io/mcp/<PROJECT_ID> \
  -H "Authorization: Bearer <PROJECT_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

可自托管的安装仍使用标准输入/输出（stdio）。

快速示例

每个实体工具的工作方式都像命令行工具：传入 command 以及该命令所需的参数。工具架构中的每条参数说明都会列出其适用的命令。

列出测试：

{
  "name": "tests",
  "arguments": { "command": "list", "page": 1, "per_page": 50, "tql": "priority == 'high'" }
}

创建测试：

{
  "name": "tests",
  "arguments": {
    "command": "create",
    "title": "User login test",
    "suite_id": "123",
    "priority": "high"
  }
}

创建运行：

{
  "name": "runs",
  "arguments": {
    "command": "create",
    "title": "Smoke tests",
    "kind": "automated",
    "env": "production"
  }
}

完成运行：

{
  "name": "runs",
  "arguments": {
    "command": "update",
    "run_id": "456",
    "status_event": "finish"
  }
}

将附件上传到测试：

{
  "name": "tests",
  "arguments": {
    "command": "attachments_upload",
    "test_id": "123",
    "file_path": "/path/to/screenshot.png"
  }
}

从 Markdown 批量创建／更新测试：

{
  "name": "tests",
  "arguments": {
    "command": "bulk_upsert",
    "markdown": "\n# Login Functionality\n\n# Successful Login\n\n# Failed Login"
  }
}

带有 id: @T... 的测试会被更新，不带该字段的测试则会被创建；套件通过 id: @S... 或标题解析，若不存在则会创建。每次调用最多处理 100 项测试。完整语义请参阅 docs/tools.md。

文档

完整工具参考：docs/tools.md

项目结构

src/
|- config/          # Config loading, defaults
|- core/            # Errors, logger
|- api/             # HTTP client, Testomat.io API client
|- mcp/             # MCP server, tools, registry
|  |- definitions/  # Tool definitions by entity
|  |- configs/      # Registry generation configs
|  `- registry/     # Tool handlers
`- cli/             # CLI bootstrap

环境变量

变量	必需	默认值	说明
TESTOMATIO_PROJECT_TOKEN	是*	-	项目令牌（首选）
TESTOMATIO_API_TOKEN	是*	-	备用令牌
TESTOMATIO_PROJECT_ID	是	-	项目 ID
TESTOMATIO_HOST	否	-	API 主机，例如 beta.testomat.io
TESTOMATIO_BASE_URL	否	https://app.testomat.io	API 基础 URL，优先于 TESTOMATIO_HOST
TESTOMATIO_TOOLS	否	full	工具配置：full、core 或 read

*必须设置 TESTOMATIO_PROJECT_TOKEN 或 TESTOMATIO_API_TOKEN

企业 TLS 证书

如果 MCP 服务运行在企业代理或 TLS 检查之后，即使浏览器可以访问同一 URL，Node.js 也可能拒绝 Testomat.io 的 HTTPS 请求。这通常意味着操作系统信任公司的根证书，但 Node.js 不信任。

使用 Node.js 系统 CA 支持：

NODE_OPTIONS=--use-system-ca testomatio-mcp --token <TOKEN> --project <PROJECT_ID>

对于 MCP 客户端，在服务环境中传入 NODE_OPTIONS：

{
  "mcpServers": {
    "testomatio": {
      "command": "testomatio-mcp",
      "args": ["--token", "<TOKEN>", "--project", "<PROJECT_ID>"],
      "env": {
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

如果你的 Node.js 版本不支持 --use-system-ca，请将企业根证书导出为 PEM 文件，并使用 Node.js 额外 CA 支持：

NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem testomatio-mcp --token <TOKEN> --project <PROJECT_ID>

重要说明

• CLI 风格工具 - 每个实体对应一个工具；所有操作都通过 command 参数指定（使用 tests 和 command: "list"，而不是旧的 tests_list）。未知命令会返回错误，并列出有效命令
• 运行状态 - 使用 runs 和 command: "update"，并通过 status_event 进行状态转换（完成、启动、重新运行等）
• 搜索/筛选 - 没有专用的 /search 端点；通过 list 命令进行筛选（tests 和 runs 使用 tql，其他实体使用与 OpenAPI 对齐的筛选条件）
• 精简列表响应 - 列表命令默认请求紧凑的 API 响应，并省略实体中的大型字段和 null 值。传入 verbose: true 可返回完整对象，或传入 fields: ["id", "title", "description"] 仅返回选定字段。这两个选项都会停用后端的 slim=true 请求，以便在需要时保留大型字段。
• TQL - 对于使用 command: "list" 的 tests/runs，使用 tql 作为唯一的搜索/筛选输入
• TQL 语法 - 有关面向用户的语法说明和更多示例，请参阅官方 TQL 文档：https://docs.testomat.io/advanced/tql/
• TQL 范围 - TQL 参数说明中会附带文档所列的字段白名单；如需了解语法详情和更多示例，请调用 tql_help
• 问题关联 - 每个实体都提供范围限定命令：command: "issues_link" / "issues_unlink"
• 附件 - tests、suites 和 testruns 提供范围限定命令：command: "attachments_list" | "attachments_upload" | "attachments_delete"。上传时通过 multipart 字段 files 发送一个本地文件路径。
• 企业版软件包 - 分析工具仅通过 @testomatio/mcp-enterprise 提供，标准 @testomatio/mcp 软件包不包含这些工具
• API 会话 - 服务器会在首次 POST、PUT 或 DELETE 请求前自动启动 Testomat.io 会话，并在后续修改请求中通过 X-Session-Hash 发送返回的会话哈希；MCP 服务关闭时会停止会话。GET 请求不会启动或使用会话。

开发

npm install
npm run start -- --token <TOKEN> --project <PROJECT_ID>
npm test

进行本地 MCP 开发时，请将 Claude Desktop 指向已检出的入口文件：

{
  "mcpServers": {
    "testomatio-local": {
      "command": "node",
      "args": ["/path/to/mcp/index.js", "--token", "<TOKEN>", "--project", "<PROJECT_ID>"]
    }
  }
}

企业版分析

企业版分析仅在单独的 @testomatio/mcp-enterprise 软件包中提供。

安装：

npm install -g @testomatio/mcp-enterprise@latest

运行：

testomatio-mcp-enterprise --token <PROJECT_TOKEN> --project <PROJECT_ID>

包含的工具：

• analytics_tests - GET /api/v2/{project_id}/analytics/tests/{kind}
• analytics_stats - GET /api/v2/{project_id}/analytics/stats/{kind}
• analytics_charts_list - GET /api/v2/{project_id}/analytics/charts
• analytics_charts_get - GET /api/v2/{project_id}/analytics/charts/{id}
• analytics_charts_results - GET /api/v2/{project_id}/analytics/charts/{id}/result

分析端点需要 api_analytics 订阅功能。分析工具使用 q 作为 TQL 筛选参数。

analytics_tests 调用示例：

{
  "name": "analytics_tests",
  "arguments": {
    "kind": "flaky",
    "q": "priority == 'high'",
    "days": 30,
    "page": 1,
    "per_page": 20
  }
}

analytics_stats 调用示例：

{
  "name": "analytics_stats",
  "arguments": {
    "kind": "success-rate-by-date",
    "q": "tag IN ['@smoke']",
    "from": "2026-04-01",
    "to": "2026-04-30"
  }
}

analytics_charts_get 返回包含 TQL 查询的图表定义；analytics_charts_results 返回每个查询的总数，或某个查询匹配的测试/运行（通过其从零开始的 number 指定）。

analytics_charts_results 调用示例：

{
  "name": "analytics_charts_results",
  "arguments": {
    "chart_id": "abc123",
    "number": 2,
    "per_page": 50
  }
}