Testingbot Mcp Server

TestingBot MCP 服务

TestingBot 官方的模型上下文协议（MCP）服务实现。此服务可让 AI 助手与 TestingBot 的测试基础设施交互，通过对话界面管理测试、浏览器、设备等。

⚡ 一键安装

Claude Desktop：从发布页面下载 mcp-server.mcpb 并双击。Claude 将自动设置 TestingBot MCP 服务。

安装后，请在 TestingBot 账户设置中设置凭据。

功能

• 📱 App Automate - 直接通过 Agent 在真实设备和模拟器上运行 Maestro、Espresso 和 XCUITest 测试套件
• 🖥️ 实时测试 - 在真实浏览器和设备上启动交互式手动测试会话
• 🌐 浏览器与设备管理 - 查询可用的浏览器和真实设备
• 🧪 测试管理 - 创建、获取、更新和删除测试，并查看详细信息
• 📦 存储管理 - 上传和管理移动应用文件（APK、IPA、ZIP）
• 📸 截图测试 - 获取跨浏览器截图
• 🏗️ 构建管理 - 将测试整理到构建中
• 👤 用户账户 - 查看和更新账户信息
• 👥 团队管理 - 管理团队设置和团队成员
• 🔌 Chrome DevTools Protocol - 创建 CDP 会话以实现高级浏览器自动化
• 🚇 隧道管理 - 管理用于本地测试的 TestingBot 隧道

先决条件

• Node.js >= 20（推荐：22.15.0 或更高版本）
• TestingBot 账户，并拥有 API 凭据
• 兼容 MCP 的客户端（Claude Desktop、搭配 Continue 的 VS Code、Cursor 等）

安装

快速设置

全局安装 MCP 服务：

npm install -g @testingbot/mcp-server

或添加到项目中：

npm install @testingbot/mcp-server

配置

推荐：使用 tb_login 登录（无需复制密钥或密码）

你不必查找并粘贴 API 凭据。安装服务，将凭据留空，然后直接向 Agent 提出请求：

帮我登录 TestingBot。

Agent 会调用 tb_login 工具。它使用 OAuth 风格的浏览器身份验证——密钥绝不会离开浏览器——并会根据你的环境自动选择合适的方式：

• **浏览器（环回连接，桌面环境下的默认方式）：**浏览器会打开 TestingBot 授权页面。根据需要登录，然后点击 Authorize；凭据会通过本地回调捕获，Agent 随后完成登录。无需输入任何内容。（RFC 8252。）

• **设备代码（在 SSH／远程／开发容器／Web 环境下自动回退）：**工具会改为显示一个简短的网址和代码：

  1. 在浏览器中打开该网址（例如 https://testingbot.com/device）。
  2. 输入代码，根据需要登录，然后点击 Authorize。
  3. 告知 Agent 你已授权——它会再次调用 tb_login 完成登录。

  （RFC 8628。）

你可以向 tb_login 传入 mode: "loopback" 或 mode: "device" 来强制选择方式（默认值为 "auto"）。

你的凭据会写入 ~/.testingbot/credentials（权限模式为 0600），并用于之后的每次工具调用——无需重启，也无需编辑 JSON。此方式适用于任何 MCP 客户端（VS Code、Cursor、Cline、Claude Desktop 等）。如需使用其他账户，请设置 TESTINGBOT_PROFILE；如需更改文件位置，请设置 TESTINGBOT_CONFIG_DIR。

环境变量

或者（在 CI 中，环境变量的优先级高于文件），将 TestingBot 凭据设置为环境变量：

export TESTINGBOT_KEY="your-api-key"
export TESTINGBOT_SECRET="your-api-secret"

也可以在项目中创建 .env 文件：

TESTINGBOT_KEY=your-api-key
TESTINGBOT_SECRET=your-api-secret

密钥也接受别名 TB_KEY／TESTINGBOT_USERNAME；密码也接受别名 TB_SECRET／TESTINGBOT_ACCESS_KEY。

凭据的解析方式

凭据按以下顺序解析，优先级从高到低：

1. 环境变量（见上文）——必须同时设置密钥和密码。这样 CI 和每客户端配置就可以覆盖其他所有设置。
2. tb_login 写入的 ~/.testingbot/credentials 文件，适用于当前配置（default 或 TESTINGBOT_PROFILE）。
3. **两者均未设置：**服务会以降级模式启动，除 tb_login 外的每个工具都会提示“运行 tb_login 进行身份验证”——因此首次运行可以自行修复，而不会直接报错。

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%/Claude/claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server"],
      "env": {
        "TESTINGBOT_KEY": "your-api-key",
        "TESTINGBOT_SECRET": "your-api-secret"
      }
    }
  }
}

VS Code（使用 Continue 扩展）

添加到 .continue/config.json：

{
  "mcpServers": [
    {
      "name": "testingbot",
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server"],
      "env": {
        "TESTINGBOT_KEY": "your-api-key",
        "TESTINGBOT_SECRET": "your-api-secret"
      }
    }
  ]
}

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server"],
      "env": {
        "TESTINGBOT_KEY": "your-api-key",
        "TESTINGBOT_SECRET": "your-api-secret"
      }
    }
  }
}

🤖 让 AI Agent 操控远程浏览器或设备

此服务已包含 @testingbot/automation-mcp 提供的自动化工具——安装此软件包后，Agent 就能在 TestingBot 的网格上实际操控远程浏览器或真实移动设备，而不仅仅是管理资源。

只需提出请求：

在 TestingBot 上打开 macOS 中的 Safari 17。访问 example.com，然后点击“More information”链接。

Agent 会调用 tb_openBrowser、tb_navigate、tb_snapshot、tb_click，并提供一个实时查看网址，让你可以实时观看操作。对于真实的 iOS／Android 设备，捆绑的 appium-mcp 子服务会为 Agent 提供完整的 appium_* 工具集（appium_session_management、appium_gesture、appium_set_value、appium_screenshot，以及其他约 30 个工具）——无需单独安装或配置。只需提出请求：“在 TestingBot 上打开搭载 iOS 17 的 iPhone 15 Pro，点击登录按钮，并截屏。” 完整工具列表、注意事项（会按会话计费）和配置选项，请参阅 @testingbot/automation-mcp README。

可用工具

实时测试

startLiveSession

在 TestingBot 上启动交互式实时测试会话。打开真实浏览器或移动设备进行手动测试。

参数：

• platformType："desktop" 或 "mobile"
• desiredURL：要打开的 URL
• desiredOS：操作系统（桌面端为 Windows、Mac、Linux；移动端为 android、ios）
• desiredOSVersion：操作系统版本
• desiredBrowser（仅限桌面端）：浏览器名称（chrome、firefox、safari、edge、ie）
• desiredBrowserVersion（仅限桌面端）：浏览器版本或 "latest"
• desiredDevice（仅限移动端）：设备名称（例如："iPhone 14"、"Galaxy S23"）

示例提示词：

"在 Windows 11 上使用最新版 Chrome，为 https://example.com 启动实时测试会话" "在 iOS 16 上使用 iPhone 14 打开 https://myapp.com 进行手动测试"

startDesktopLiveSession

用于启动桌面浏览器实时测试会话的便捷工具。

参数：

• desiredURL：要打开的 URL
• desiredOS：Windows、Mac 或 Linux
• desiredOSVersion：操作系统版本
• desiredBrowser：chrome、firefox、safari、edge 或 ie
• desiredBrowserVersion（可选）：浏览器版本或 "latest"（默认值：latest）

示例提示词：

"在 Mac Monterey 上使用 Firefox 120，为 https://example.com 启动桌面实时会话"

startMobileLiveSession

用于启动移动设备实时测试会话的便捷工具。

参数：

• desiredURL：要打开的 URL
• desiredOS：android 或 ios
• desiredOSVersion：操作系统版本
• desiredDevice：设备名称

示例提示词：

"在 Android 13 上使用 Galaxy S23，为 https://example.com 启动移动端实时会话"

浏览器和设备管理

getBrowsers

获取可用于测试的浏览器和平台列表。

参数：

• type（可选）：按 "web" 或 "mobile" 筛选

示例提示词：

"显示所有可用的测试浏览器" "有哪些可用的移动浏览器？"

getDevices

获取可用移动设备（真实设备和模拟器）列表。

示例提示词：

"列出所有可用的 iOS 设备" "显示用于测试的 Android 设备"

测试管理

getTests

分页获取近期测试列表。

参数：

• offset（可选）：分页偏移量（默认值：0）
• limit（可选）：要获取的测试数量（默认值：10，最大值：100）

示例提示词：

"显示最近的 20 个测试" "获取近期测试结果"

getTestDetails

获取某个特定测试的详细信息，包括：

• 测试状态、浏览器、平台和时间信息
• 视频录制 URL 和截图 URL
• Selenium、浏览器和 Appium 日志
• 包含命令和时间戳的测试执行步骤
• 网络日志、异常日志和 JS 错误

参数：

• sessionId：测试的会话 ID

示例提示词：

"获取测试会话 abc123 的详细信息" "显示测试 xyz789 的视频和日志" "显示测试 abc123 的执行步骤"

updateTest

更新测试元数据，例如名称、状态或构建版本。

参数：

• sessionId：测试的会话 ID
• name（可选）：测试的新名称
• status（可选）："passed" 或 "failed"
• build（可选）：构建标识符
• extra（可选）：其他元数据（JSON 字符串）

示例提示词：

"将测试 abc123 标记为通过" "将测试 xyz789 的名称更新为 'Login Flow Test'"

deleteTest

根据会话 ID 删除测试。

参数：

• sessionId：要删除的测试的会话 ID

示例提示词：

"删除测试 abc123"

stopTest

根据会话 ID 停止正在运行的测试。

参数：

• sessionId：要停止的测试的会话 ID

示例提示词：

"停止测试 abc123"

构建管理

getBuilds

分页获取构建列表。

参数：

• offset（可选）：分页偏移量（默认值：0）
• limit（可选）：要获取的构建数量（默认值：10，最大值：100）

示例提示词：

"显示最近的构建"

getTestsForBuild

获取与指定构建 ID 关联的所有测试。

参数：

• buildId：构建 ID

提示词示例：

“显示构建 12345 的所有测试”

deleteBuild

删除一个构建及其所有关联测试。

参数：

• buildId：要删除的构建 ID

提示词示例：

“删除构建 12345”

存储管理

uploadFile

将本地文件（APK、IPA 或 ZIP）上传到 TestingBot 存储。

参数：

• localFilePath：要上传的文件路径

提示词示例：

“将 /path/to/app.apk 上传到 TestingBot”

uploadRemoteFile

从远程 URL 将文件上传到 TestingBot 存储。

参数：

• remoteUrl：要上传的文件 URL

提示词示例：

“将 https://example.com/app.ipa 上传到 TestingBot”

getStorageFiles

列出 TestingBot 存储中的所有文件。

参数：

• offset（可选）：分页偏移量（默认值：0）
• limit（可选）：要检索的文件数量（默认值：10，最大值：100）

提示词示例：

“显示所有已上传的应用”

deleteStorageFile

从 TestingBot 存储中删除文件。

参数：

• appUrl：要删除文件的 app_url

提示词示例：

“从存储中删除应用 tb://app123”

App Automate — Maestro

在 TestingBot 真机、模拟器和仿真器上运行 Maestro 工作流。运行是异步的：启动运行、轮询其状态，然后获取结果——设备执行期间不会阻塞 Agent。

uploadMaestroApp

上传待测应用（.apk、.aab、.ipa 或打包为 ZIP 的 .app）。上传内容按校验和去重——使用相同二进制文件重新运行时可立即完成。

参数：

• localFilePath：应用文件的本地路径

返回供其他 Maestro 工具使用的项目 ID。

提示词示例：

“上传 ./build/app.apk 以进行 Maestro 测试”

uploadMaestroFlows

为项目上传 Maestro 工作流 YAML 文件。接受目录（保留目录结构，因此 runFlow 子工作流仍可正常运行）、预先构建的 .zip 文件，或由 Agent 编写的内联 YAML。此操作会替换之前上传的工作流。

参数：

• projectId：来自 uploadMaestroApp 的项目 ID
• flowsPath（可选）：工作流 YAML 文件所在目录或 .zip 文件
• flows（可选）：以内联形式提供的工作流，格式为 [{ fileName, content }]

runMaestroTest

启动 Maestro 运行。立即返回运行 ID——使用 getMaestroRunStatus 轮询状态。

参数：

• projectId：项目 ID
• platformName：“Android” 或 “iOS”
• deviceName（可选）：设备名称，支持通配符/正则表达式（例如 "Pixel 8"、"iPhone 1[4-6]"、"*"）
• version（可选）：操作系统版本
• realDevice（可选）：在实体设备上运行（.ipa 必需）
• name（可选）：仪表板中显示的运行名称
• env（可选）：传递给工作流的环境变量
• includeTags / excludeTags（可选）：按 Maestro 标签筛选工作流
• shardSplit（可选）：在多个并行设备间拆分工作流
• otherApps（可选）：最多 4 个要与应用一起安装的伴随应用 URL

提示词示例：

“在搭载 Android 14 的 Pixel 8 真机上运行我的 Maestro 工作流”

getMaestroRunStatus

轮询运行进度。列出各工作流的状态（WAITING、READY、DONE、FAILED、CANCELLED），失败项优先显示。

getMaestroRunResults

已完成运行的最终结果：各工作流的结果以及 JUnit XML 报告。

getMaestroFlowDetails

深入查看单个工作流：错误消息、步骤级 JUnit 报告，以及视频、屏幕截图和设备日志的链接。这是用于调试的工具——获取失败工作流的详情，修复 YAML，然后重试。

参数： projectId、runId、flowId

cancelMaestroRun / retryMaestroRun

取消正在运行的任务，或重试某次运行——传入 flowId 可仅重试单个失败的工作流。

uploadMaestroCompanionApp

上传要与待测应用一起安装的辅助应用。返回供 runMaestroTest 的 otherApps 使用的 tb:// URL。

listMaestroProjects / listMaestroRuns

发现账户中的现有项目（应用、flows、运行 ID）和运行。listMaestroRuns 接受 buildName，可按名称查找运行，例如：“重新运行昨晚 nightly 构建中失败的所有项目”。

maestroCheatSheet

返回 Maestro YAML 语法参考（命令、选择器、flow 结构和 TestingBot 工作流）。Agent 在编写或修复 flows 前会调用此工具。

示例工作流：

User: "Run the Maestro flows in ./flows against ./app.apk on a real Pixel 8. Fix any failures."
Assistant: [uploadMaestroApp → uploadMaestroFlows → runMaestroTest]
Assistant: [polls getMaestroRunStatus until complete]
Assistant: [getMaestroFlowDetails for the failed flow, reads the error + screenshots]
Assistant: [fixes the flow YAML, uploadMaestroFlows, retryMaestroRun]

App Automate — Espresso 和 XCUITest

在 TestingBot 设备上运行预构建的 Espresso（Android）和 XCUITest（iOS）测试套件。采用相同的异步模式：启动、轮询、获取结果。

uploadAppAutomateApp

上传待测应用：Espresso 使用 .apk / .aab，XCUITest 使用 .ipa。

参数： framework（"espresso" 或 "xcuitest"）、localFilePath

uploadAppAutomateTests

上传测试套件：Espresso 使用经过检测的测试 .apk，XCUITest 使用打包为 zip 的测试运行器包。

参数： framework、projectId、localFilePath

runAppAutomateTest

启动一次运行，并立即返回运行 ID。

参数：

• framework、projectId
• deviceName、version、realDevice、name、build（可选）：设备选择和元数据
• testClasses、skipTestClasses、packages、annotations、testRunner（可选，仅限 Espresso）：测试筛选
• locale、timeZone（可选）

提示词示例：

“在真实的 Galaxy S23 上运行 Espresso 测试套件，只运行 com.example.LoginTest 类”

getAppAutomateRunStatus / getAppAutomateRunResults

轮询运行进度，然后获取每次运行的结果和 JUnit XML 报告。每次运行的 Appium 会话 ID 都会显示，因此 getTestDetails / getFailureLogs 可用于查看日志和视频。

截图测试

takeScreenshot

在多个浏览器和平台上截取 URL 的屏幕截图。

参数：

• url：要截图的 URL
• browsers：浏览器配置数组
  • browserName：浏览器名称（chrome、firefox、safari 等）
  • version（可选）：浏览器版本或 "latest"
  • os：操作系统（WIN11、MAC 等）
• resolution（可选）：屏幕分辨率（默认："1920x1080"）
• waitTime（可选）：截图前等待的秒数（默认：5，最长：60）
• fullPage（可选）：截取整页或视口（默认：false）

提示词示例：

“在 Chrome 和 Firefox 上截取 https://example.com 的屏幕截图” “在移动设备上截取我的主页”

retrieveScreenshots

按截图 ID 获取截图结果。

参数：

• screenshotId：来自 takeScreenshot 的截图 ID

提示词示例：

“获取任务 abc123 的屏幕截图”

getScreenshotList

获取所有截图任务的列表。

参数：

• offset（可选）：分页偏移量（默认：0）
• limit（可选）：要获取的任务数量（默认：10，最大：100）

提示词示例：

“显示我最近的截图任务”

用户管理

getUserInfo

获取当前用户账户信息，包括已使用的分钟数、套餐详情和限额。

提示词示例：

“显示我的账户信息” “我已经用了多少分钟？”

updateUserInfo

更新用户账户信息。

参数：

• firstName（可选）：名字
• lastName（可选）：姓氏
• email（可选）：电子邮件地址

提示词示例：

“将我的电子邮件地址更新为 [email protected]”

团队管理

getTeam

获取团队信息，包括并发限额、允许的并行 VM 数量和移动端并发数。

提示词示例：

“显示我的团队信息” “我的团队并发限额是多少？”

getUsersInTeam

列出团队中的所有用户及其角色和访问级别。

参数：

• offset（可选）：分页偏移量（默认：0）
• limit（可选）：要获取的用户数量（默认：10，最大：100）

提示词示例：

“显示所有团队成员” “列出我团队中的用户”

getUserFromTeam

通过用户 ID 获取特定团队成员的详细信息。

参数：

• userId：要获取的用户 ID

提示词示例：

“显示用户 12345 的详细信息”

Chrome DevTools Protocol (CDP)

createCdpSession

创建 Chrome DevTools Protocol 会话，用于高级浏览器自动化。返回用于连接浏览器的 WebSocket URL。

参数：

• browserName：浏览器名称（chrome、firefox、safari、edge 等）
• browserVersion（可选）：浏览器版本或 "latest"（默认：latest）
• platform：操作系统平台
• screenResolution（可选）：屏幕分辨率（例如，“1920x1080”）
• name（可选）：会话名称
• build（可选）：构建标识符

提示词示例：

“在装有 Windows 11 的 Chrome latest 上创建 CDP 会话” “在 Firefox 120 上启动 CDP 会话以进行自动化”

隧道管理

getTunnelList

获取所有活动 TestingBot 隧道的列表。隧道可用于测试防火墙后的网站或本地计算机上的网站。

提示词示例：

“显示所有活动隧道” “列出我的 TestingBot 隧道”

deleteTunnel

通过 ID 删除活动的 TestingBot 隧道。此操作会终止隧道连接。

参数：

• tunnelId：要删除的隧道 ID

提示词示例：

“删除隧道 12345”

使用示例

示例 1：运行跨浏览器测试

User: "Show me all available browsers for web testing"
Assistant: [Lists all web browsers]

User: "Take a screenshot of https://myapp.com on Chrome latest and Firefox latest on Windows 11"
Assistant: [Creates screenshot job and returns ID]

User: "Get the screenshots for job abc123"
Assistant: [Returns screenshot URLs]

示例 2：管理移动应用测试

User: "Upload my app from https://example.com/app.apk"
Assistant: [Uploads app and returns tb://app123]

User: "Show me all my uploaded apps"
Assistant: [Lists storage files]

User: "Show me the last 10 tests"
Assistant: [Shows recent test results]

示例 3：在真实设备上运行由 Agent 驱动的 Maestro 测试

User: "Write a Maestro flow that logs into my app and run it on a real Pixel 8"
Assistant: [maestroCheatSheet for syntax, writes the flow YAML]
Assistant: [uploadMaestroApp ./app.apk → project 42]
Assistant: [uploadMaestroFlows with the inline flow]
Assistant: [runMaestroTest on Pixel 8 with realDevice: true → run 101]
Assistant: [polls getMaestroRunStatus, then getMaestroRunResults]

User: "The checkout flow failed — figure out why and fix it"
Assistant: [getMaestroFlowDetails → reads error + screenshots + video]
Assistant: [fixes the YAML, uploadMaestroFlows, retryMaestroRun]

示例 4：构建管理

User: "Show me my recent builds"
Assistant: [Lists recent builds]

User: "Show all tests for build 12345"
Assistant: [Lists tests in that build]

User: "Mark test xyz789 as passed with build name 'Release 1.0'"
Assistant: [Updates test]

示例 5：团队与隧道管理

User: "Show me my team information"
Assistant: [Shows team concurrency limits and settings]

User: "List all team members"
Assistant: [Lists all users in the team]

User: "Show me all active tunnels"
Assistant: [Lists active TestingBot tunnels]

示例 6：CDP 自动化

User: "Create a CDP session on Chrome latest with Windows 11"
Assistant: [Creates session and returns WebSocket URL]

User: "Show me test execution steps for session abc123"
Assistant: [Shows detailed command history with timestamps]

开发

设置

# Clone the repository
git clone https://github.com/testingbot/mcp-server.git
cd testingbot-mcp-server

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your credentials

命令

# Build the project (runs lint, format, test, and compile)
npm run build

# Development mode with watch
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

# Build the .mcpb bundle for Claude Desktop (see section below)
npm run mcpb

本地运行

# Development mode
npm run dev

# Production mode
npm start

使用 MCP Inspector 进行测试

使用 MCP Inspector 在开发期间测试工具：

npx @modelcontextprotocol/inspector node dist/index.js

然后在浏览器中打开 http://localhost:5173。

构建 .mcpb 捆绑包（Claude Desktop 发布版）

.mcpb 归档文件是用户双击即可在 Claude Desktop 中安装的文件。安装程序会读取 manifest.json#user_config 并显示凭据提示——无需编辑 JSON 或折腾环境变量。

# Prerequisites: mcpb CLI (one-time)
npm install -g @anthropic-ai/mcpb

# Build the bundle
npm run mcpb

此操作会运行 scripts/build-mcpb.sh，该脚本会：

1. 运行完整的质量检查流程（npm run build → lint → format → test → tsc）。
2. 在临时目录中暂存一份干净的文件树（仅包含 dist/、manifest.json、package.json、LICENSE、README.md，以及存在时的 icon.png）。
3. 在暂存目录中运行 npm ci --omit=dev——开发依赖（typescript、eslint、vitest）不会进入捆绑包。@testingbot/automation-mcp 会从 npm 获取，并使用 package.json 中固定的版本。
4. 验证清单并运行 mcpb pack，遵循 .mcpbignore 规则（排除测试夹具、源映射和依赖项变更日志）。
5. 写入 releases/testingbot-mcp-server-<version>.mcpb，并对其运行 mcpb info。

输出大小约为 160 MB——其中大部分是捆绑的 appium-mcp 移动驱动程序栈（XCUITest、UiAutomator2）。费用只在安装时支付一次，运行时无需付费。

开发期间使用同级仓库

如果要同时开发 @testingbot/mcp-server 和 @testingbot/automation-mcp，并保持同步，请在此仓库中运行 npm run dev:rebuild。该命令会构建两者，然后通过 npm link 将同级仓库链接到此仓库的 node_modules，因此对 ../testingbot-automation-mcp/src/ 的修改会在下次重新构建时生效，无需重新发布。

此链接只需设置一次——设置后，dev:rebuild 会检测到链接已就位并仅执行构建。如果你在此仓库中运行 npm install，链接会被注册表中的副本替换；重新运行 dev:rebuild 即可恢复链接。

发布

发布流程包含两个相互配合的发布步骤：

1. 将 @testingbot/automation-mcp 发布到 npm（在 ../testingbot-automation-mcp 中）：

   npm version patch    # or minor / major
   npm publish          # publishConfig.access is "public" — handles scoped-pkg defaults
   

2. 更新此仓库以使用新版 automation-mcp，然后发布新版本：

   npm install @testingbot/automation-mcp@latest   # updates package-lock.json
   npm version patch                                # also syncs manifest.json + server.json
   git push --follow-tags
   # → Create a GitHub release at the new tag. The Build MCPB workflow
   #   fires on release:published and attaches releases/*.mcpb to it.
   

发布 CI（.github/workflows/build-mcpb.yml）会在 macos-latest 上运行 npm run mcpb，并将捆绑包作为工作流构建产物（保留 30 天）和发布资源上传。手动重新构建：在 Actions 标签页中触发“Build MCPB bundle”→ 输入标签。

选择 macOS 是为了让捆绑的 appium-xcuitest-driver 包含其原生组件。如果目标用户只有 Linux/Windows 用户，可以将运行器切换为 ubuntu-latest，以节省约 10 倍的运行分钟费用，但捆绑移动端路径将不再支持 iOS。浏览器工具（通过 WebDriver）无论如何都能跨平台运行。

无需构建即可验证清单：

npm run mcpb:validate

检查已构建的捆绑包：

mcpb info releases/testingbot-mcp-server-<version>.mcpb
mcpb unpack releases/testingbot-mcp-server-<version>.mcpb /tmp/unpacked  # see what's inside

该捆绑包未签名。要签名后分发，请运行 mcpb sign --self-signed（冒烟测试）或使用真实证书运行 mcpb sign。请参阅 mcpb sign --help。

releases/*.mcpb 已被 gitignore 忽略——构建后，请将构建产物上传到 GitHub 发布页面（或安装 URL 指向的位置）。

项目结构

testingbot-mcp-server/
├── src/
│   ├── index.ts              # Entry point
│   ├── server-factory.ts     # MCP server setup
│   ├── config.ts             # Configuration management
│   ├── lib/
│   │   ├── types.ts          # TypeScript types
│   │   ├── constants.ts      # Constants and enums
│   │   ├── error.ts          # Error classes
│   │   ├── logger.ts         # Logging setup
│   │   ├── utils.ts          # Utility functions
│   │   ├── get-auth.ts       # Authentication helpers
│   │   └── app-automate-client.ts  # REST client for Maestro/Espresso/XCUITest
│   └── tools/
│       ├── maestro.ts        # Maestro run tools (upload, run, poll, diagnose)
│       ├── app-automate.ts   # Espresso & XCUITest run tools
│       ├── browsers.ts       # Browser & device tools
│       ├── tests.ts          # Test management tools
│       ├── builds.ts         # Build management tools
│       ├── storage.ts        # Storage tools
│       ├── screenshots.ts    # Screenshot tools
│       ├── user.ts           # User management tools
│       ├── team.ts           # Team management tools
│       ├── cdp.ts            # Chrome DevTools Protocol tools
│       ├── tunnels.ts        # Tunnel management tools
│       └── live.ts           # Live testing session tools
├── tests/
│   └── tools/                # Unit tests
├── dist/                     # Compiled output
└── package.json

故障排除

身份验证错误

如果看到身份验证错误：

1. 运行 tb_login 工具（只需让 Agent“帮我登录 TestingBot”）——这是最简单的解决方法，无需密钥或密文
2. 或在 https://testingbot.com/members/user/security 验证凭据
3. 确保环境变量设置正确（环境变量会覆盖 tb_login 凭据文件）
4. 检查凭据中是否包含多余空格

连接问题

如果 MCP 服务无法连接：

1. 重启 MCP 客户端（Claude Desktop、VS Code 等）
2. 检查 MCP 客户端日志中的错误
3. 确认 Node.js 版本不低于 20

工具执行错误

如果工具执行失败：

1. 查看服务日志以获取详细错误消息
2. 确认 TestingBot 账户拥有足够的权限和配额
3. 确保已提供所有必需参数

调试日志

要启用调试日志，请设置 LOG_LEVEL 环境变量：

export LOG_LEVEL=debug

或者在 MCP 客户端配置中设置：

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server"],
      "env": {
        "TESTINGBOT_KEY": "your-api-key",
        "TESTINGBOT_SECRET": "your-api-secret",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

• 📧 电子邮件：[email protected]
• 🐛 问题：GitHub Issues
• 📖 文档：TestingBot MCP 文档

相关

• TestingBot API 软件包
• Model Context Protocol
• TestingBot 平台