TestOptim

TestOptim MCP 服务

将 Claude Code、Cursor、VS Code 和其他 MCP 客户端连接到 TestOptim，让你的 AI 助手能够在 Web 应用上运行 QA 测试，并查看发现的问题。

“在我的项目上运行 QA 测试套件，并显示关键问题。”

TestOptim 托管此服务；无需安装或运行任何内容。此仓库包含设置说明、可直接复制的客户端配置，以及用于在 MCP 注册表中列出该服务的 server.json。

• 端点： https://api.testoptim.com/api/mcp
• 传输方式： Streamable HTTP（无状态；仅支持 POST）
• 身份验证： TestOptim API 密钥，通过 Authorization: Bearer topt_... 发送

目录

• 开始之前
• 创建 API 密钥
• 连接客户端
• 工具
• 提示词示例
• 安全性
• 限制与错误
• 故障排除

开始之前

• 拥有一个 TestOptim 账户，且至少有一个项目已生成测试用例。请参阅生成测试用例。
• 在组织中拥有 Owner 或 Admin 角色，以便创建 API 密钥。
• 通过 MCP 启动的运行会使用你套餐中的测试执行次数，与在应用中启动的运行相同。运行会归属于创建密钥的人员。

创建 API 密钥

1. 在 TestOptim 中打开 Settings，然后选择 API keys，再点击 New token。
2. 为密钥命名，使用容易辨认的名称，例如 Claude Code - laptop。
3. 在 Project access 下，选择 All projects 或单个项目。选择单个项目可限制密钥泄露后能够访问的范围。
4. 仅保留所需的权限（请参阅工具，了解各工具所需的权限）。
5. 复制令牌。令牌以 topt_ 开头，且只显示一次。

然后在客户端启动时使用的 shell 中导出该密钥，以免将其写入配置文件：

export TESTOPTIM_TOKEN="topt_..."

包含截图的完整指南请参阅使用 API 密钥从 CI 运行 TestOptim 测试。

若要改为通过 GitHub Actions 工作流运行测试，请使用 TestOptim Run Tests。

连接客户端

每个配置片段也可在 examples/ 中找到。

Claude Code

claude mcp add --transport http testoptim https://api.testoptim.com/api/mcp \
  --header "Authorization: Bearer ${TESTOPTIM_TOKEN}"

这会将令牌保存在本地 Claude Code 配置中。添加 --scope user 可在所有项目中使用该令牌。

若要与团队共享服务但不共享令牌，请提交项目级 .mcp.json 文件。Claude Code 会从每个人的环境变量中展开 ${TESTOPTIM_TOKEN}（examples/claude-code.mcp.json）：

{
  "mcpServers": {
    "testoptim": {
      "type": "http",
      "url": "https://api.testoptim.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${TESTOPTIM_TOKEN}"
      }
    }
  }
}

Cursor

将配置添加到 ~/.cursor/mcp.json，或项目中的 .cursor/mcp.json（examples/cursor.mcp.json）：

{
  "mcpServers": {
    "testoptim": {
      "url": "https://api.testoptim.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TESTOPTIM_TOKEN}"
      }
    }
  }
}

Cursor 会从 shell 或系统环境中读取 TESTOPTIM_TOKEN；远程服务不支持 envFile。

VS Code

将配置添加到工作区中的 .vscode/mcp.json，或运行 MCP: Open User Configuration 以供所有工作区使用（examples/vscode.mcp.json）。服务首次启动时，VS Code 会提示你输入密钥并将其安全存储：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "testoptim-token",
      "description": "TestOptim API key (starts with topt_)",
      "password": true
    }
  ],
  "servers": {
    "testoptim": {
      "type": "http",
      "url": "https://api.testoptim.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:testoptim-token}"
      }
    }
  }
}

Windsurf

将配置添加到 MCP 配置文件中（从 Cascade 的 MCP 设置中打开该文件）。远程服务使用 serverUrl（examples/windsurf.mcp_config.json）：

{
  "mcpServers": {
    "testoptim": {
      "serverUrl": "https://api.testoptim.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TESTOPTIM_TOKEN}"
      }
    }
  }
}

Claude（claude.ai 和 Claude Desktop）

将 TestOptim 添加为自定义连接器：

1. 打开 Customize > Connectors，选择 + Add，然后选择 Add custom connector。
2. 将其命名为 TestOptim，并输入 https://api.testoptim.com/api/mcp 作为服务 URL。
3. 在 Authentication 下，选择 No sign in。
4. 在 Request headers 下，添加 Authorization，值为 Bearer topt_...（你的密钥）。
5. 选择 Add。

在 Team 和 Enterprise 计划中，Owner 可在 Organization settings > Connectors 下添加连接器，所有使用该连接器的人共用同一个密钥。请使用仅限一个项目的密钥；除非每位成员都应能启动测试运行，否则不要授予 tests:run 权限。Claude 的 Research 模式无需事先询问即可调用连接器工具，因此共享密钥不启用写入权限也是一个重要原因。之后若要更改密钥，请移除连接器并重新添加。

其他客户端

任何支持带自定义标头的 Streamable HTTP 的客户端都可使用。将其指向 https://api.testoptim.com/api/mcp，并在每个请求中发送 Authorization: Bearer <your key>。该服务是无状态的：不会发放会话 ID，并且对 GET 和 DELETE 请求返回 405。

工具

服务只会列出你的密钥权限允许使用的工具，因此只读密钥永远看不到 start_test_run。

工具	权限	功能	参数
list_projects	projects:read	列出密钥可访问的项目，以便找到其他工具所需的项目 ID。	无
start_test_run	tests:run	启动测试运行并返回运行 ID。传入 changedAreas 可仅重新测试你刚修改的页面或流程；不传则测试整个套件。运行需要几分钟。	projectId、changedAreas（例如 ["/checkout", "/cart"]；可选）
get_test_run	tests:read	显示运行状态（pending、running、completed、failed）、进度、当前步骤以及按严重程度分类的问题数量。	testRunId
stop_test_run	tests:run	停止正在运行的测试，避免执行并计费后续测试用例。停止的运行会报告为 failed。	testRunId
list_issues	issues:read	以摘要形式列出项目的问题：ID、标题、严重程度、类别和状态。传入 testRunId 可仅查看某次运行发现的问题。	projectId、severity（critical、high、medium 或 low；可选）、testRunId（可选）、limit（1-100，默认值为 20）
get_issue	issues:read	获取单个问题的完整信息：描述、复现步骤、预期和实际行为、页面 URL 及屏幕截图。	issueId
start_exploration	knowledge:explore	探索项目应用，让 TestOptim 学习新增或变更的页面和流程。此操作会消耗计划中的页面额度，并替换已在运行的探索。返回探索 ID。	projectId
get_exploration	projects:read	显示探索的状态和进度；探索结束后，还会显示记录的页面、流程和实体数量。waiting_otp_ready 或 waiting_otp 表示登录需要在 TestOptim 应用中输入一次性验证码。	explorationId

结果以 JSON 文本返回，字段名称与 TestOptim API 相同。

示例提示词

• “我可以访问哪些 TestOptim 项目？”
• “在 checkout 项目上运行 QA 套件，完成后告诉我。”
• “列出我项目中严重和高严重程度的问题，然后展示第一个问题的复现步骤。”
• “我刚修改了注册表单。运行测试；如果有任何测试失败，请打开问题并修复代码。”
• “我修改了 /checkout。用 TestOptim 仅重新测试该页面，并修复任何严重问题。”
• “我添加了一个设置页面。重新探索应用，让 TestOptim 发现这个页面。”
• “停止你启动的测试运行；项目选错了。”

安全

• 最小权限。 为每个客户端和每台机器分别创建一个密钥，并将其限制为一个项目及其所需的权限。没有 tests:run 权限的密钥无法启动或停止运行。
• 项目范围的密钥会被拒绝用于任何其他项目，工具也绝不会显示其他组织的数据。
• 不要将密钥放入要提交的文件中。 使用上文所述的环境变量或输入提示形式。密钥以 topt_ 开头，因此很容易在日志和代码仓库中搜索。
• 如果密钥泄露或设备丢失，请在 Settings > API keys 下撤销密钥。撤销后密钥会立即失效。
• 使用 tests:run 权限连接的助手可以启动运行，并消耗套餐中的测试执行次数。大多数客户端会在调用工具前询问；请保持此确认功能开启。

限制和错误

• 每个客户端 IP 地址每分钟最多 120 个请求，与 TestOptim REST API 共用限额。
• 每个项目一次只能运行一个作业。如果同一项目上已有作业正在进行，此时启动运行会被拒绝；请等待作业完成后重试。
• 与应用中的 Run all 一样，运行会根据剩余测试执行次数进行裁剪。如果需要查看完整测试套件，请检查运行中的 totalCases。

故障排除

现象	原因
401 Missing API token	Authorization 标头未能传入。请检查启动客户端的 shell 中是否已设置环境变量，然后重启客户端。
401 Invalid API token	密钥错误、已撤销或已过期。请创建新密钥。
缺少预期的工具	密钥没有该工具所需的权限。请创建包含该权限的密钥。
This token is restricted to a different project	密钥限定于一个项目；请使用该项目的 ID，或使用适用于所有项目的密钥。
405 Method not allowed	有内容发送了 GET 或 DELETE 请求。服务仅接受 POST；请使用支持 Streamable HTTP 的客户端。

贡献

发现客户端配置已过时，或想为其他客户端添加配置？请参阅 CONTRIBUTING.md。如果遇到账号或 TestOptim 服务本身的问题，请联系 TestOptim 支持。

许可证

MIT