testclaw-mcp

给 TestClaw 提供远程 HTTP MCP 工具层。

当前仓库的 AI 主架构已经调整为 API + CLI + SKILL。testclaw-mcp 继续保留，但定位改为：

• 面向外部 MCP 客户端的兼容层
• 远程 HTTP MCP 暴露层
• 无法直接运行 testclaw-cli 时的替代接入方式

如果当前运行环境可直接安装并执行 testclaw-cli，业务主路径应优先走 testclaw-cli，而不是继续把 testclaw-mcp 当作唯一执行面。

OAuth 登录主路径已经收敛到 sonic-server。testclaw-mcp 仅保留自身兼容 OAuth/HTTP 接入能力，用于已有 MCP 客户端接入；业务主路径仍优先走 testclaw-cli。

能力

• OAuth 登录 Sonic MCP
• 无鉴权 GET /healthz
• 获取当前用户
• 查询项目 / 模块 / 用例 / 元素 / 步骤 / 安装包 / Agent / 设备 / 测试结果 / 测试套件
• 创建模块 / 测试用例 / 步骤 / 测试套件
• 连接 Agent websocket 查询已安装应用
• 远程安装 / 打开 / 关闭 / 卸载应用
• 运行 / 停止测试套件
• 通用 Sonic API 请求

默认目标

默认会连到：

• SONIC_BASE_URL=http://192.168.31.121:3001
• SONIC_API_PREFIX=/api/controller

也可以通过环境变量覆盖。

环境变量

• SONIC_BASE_URL：Sonic 站点地址，例如 http://192.168.31.121:3001
• SONIC_API_PREFIX：API 前缀，默认 /api/controller
• SONIC_MCP_HOST：MCP 对外可访问的主机名或 IP，默认 127.0.0.1
• SONIC_MCP_PORT：HTTP MCP 监听端口，默认 39040
• SONIC_MCP_DATA_DIR：SQLite 数据目录，默认 ./.data
• MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL：允许 http:// issuer，仅测试/内网使用

安装依赖

cd testclaw-mcp
npm install

要求 Node >=22.5.0。

本地运行

SONIC_BASE_URL=http://192.168.31.121:3001 \
SONIC_MCP_HOST=127.0.0.1 \
SONIC_MCP_PORT=39040 \
MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true \
node index.js

注意：

• OAuth 地址会直接由 SONIC_MCP_HOST 和 SONIC_MCP_PORT 推导
• 服务端本地监听固定绑定 0.0.0.0
• SONIC_MCP_HOST 必须填写客户端可访问的真实地址，例如 127.0.0.1 或 192.168.31.121
• 若要使用 http://，必须显式开启 MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true
• 部署端不再需要写死 SONIC_USERNAME / SONIC_PASSWORD

服务器部署示例：

SONIC_BASE_URL=http://127.0.0.1:3001 \
SONIC_MCP_HOST=192.168.31.121 \
SONIC_MCP_PORT=39040 \
MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true \
node index.js

在 MCP 客户端中接入

当前版本只提供 HTTP /mcp 接入，不再支持 stdio。

示例（Codex）：

[mcp_servers.sonic]
url = "http://127.0.0.1:39040/mcp"

首次登录：

codex mcp login sonic

如果你把 testclaw-mcp 部署到服务器上，再把地址改成服务器 URL，例如：

[mcp_servers.sonic]
url = "http://192.168.31.121:39040/mcp"

通用 MCP 客户端示例：

{
  "mcpServers": {
    "sonic": {
      "url": "http://127.0.0.1:39040/mcp"
    }
  }
}

登录方式

当前版本的登录方式是：

1. Codex 连接 /mcp
2. 用户执行 codex mcp login sonic
3. 浏览器打开 testclaw-mcp 的 /authorize
4. 用户输入 Sonic 用户名密码
5. testclaw-mcp 向 Sonic 换取 SonicToken
6. 后续 MCP 工具调用自动附带当前登录用户对应的 SonicToken

部署端不保存 Sonic 明文账号密码。

第一版工具

• sonic_login
• sonic_get_current_user
• sonic_list_projects
• sonic_list_modules
• sonic_get_module
• sonic_create_module
• sonic_list_test_cases
• sonic_get_test_case
• sonic_create_test_case
• sonic_list_elements
• sonic_get_element
• sonic_list_steps
• sonic_get_step
• sonic_create_step
• sonic_list_packages
• sonic_create_package
• sonic_upload_package
• sonic_list_agents
• sonic_list_installed_apps
• sonic_get_agent
• sonic_list_devices
• sonic_get_device
• sonic_prepare_android_debug
• sonic_release_device
• sonic_install_package
• sonic_open_app
• sonic_kill_app
• sonic_uninstall_app
• sonic_list_results
• sonic_get_result
• sonic_list_suites
• sonic_get_suite
• sonic_create_suite
• sonic_run_suite
• sonic_force_stop_suite
• sonic_api_request

AI Agent 全自动流程

当前 testclaw-mcp 已经可以覆盖一条完整的 AI Agent 自动化链路：

1. sonic_list_projects
2. sonic_list_modules / sonic_create_module
3. sonic_list_test_cases / sonic_create_test_case
4. sonic_list_elements / sonic_create_step
5. sonic_create_suite
6. sonic_prepare_android_debug
7. sonic_install_package / sonic_open_app / sonic_kill_app / sonic_uninstall_app
8. sonic_run_suite
9. sonic_get_result / sonic_force_stop_suite
10. sonic_release_device

也就是说，AI Agent 现在可以：

• 自动创建测试模块、测试用例、步骤和测试套件
• 自动占用 Android 设备并获取 adb / uiautomator2 调试地址
• 自动在本地 adb 模式下安装应用、启动应用、停止应用、卸载应用
• 自动触发 Sonic 测试套件执行并轮询结果
• 在流程结束后自动释放设备

推荐编排顺序：

1. 先通过 sonic_prepare_android_debug 绑定设备
2. 再通过 sonic_create_* 系列工具生成测试资产
3. 如需直接做设备前置动作，优先走默认 executionMode=local
4. 再调用 sonic_run_suite
5. 最后无论成功失败都执行 sonic_release_device

当前默认设计适合：

• Codex/Claude Desktop/Cursor -> testclaw-mcp -> Sonic Server
• 如果 testclaw-mcp 跑在 AI Agent 本机，则设备应用操作默认走本机 adb

健康检查

可直接用无鉴权接口做部署探活：

curl http://127.0.0.1:39040/healthz

返回会包含：

• status
• version
• time
• checks.sqlite
• checks.sonic

设备选择

以下设备操作工具现在都支持 3 种设备选择方式：

• deviceId
• udId
• adbAddress

适用工具：

• sonic_prepare_android_debug
• sonic_release_device
• sonic_list_installed_apps
• sonic_install_package
• sonic_open_app
• sonic_kill_app
• sonic_uninstall_app

其中 adbAddress 支持直接传页面上展示的字符串，例如：

adb connect 192.168.31.52:52892

当前解析规则是：

• 先按 adbAddress 的 host 找到对应 Agent
• 再查找该 Agent 下当前登录用户唯一一台 DEBUGGING 状态的 Android 设备
• 若匹配到多台或 0 台，会直接报错，要求改传 deviceId 或 udId

设备执行模式

设备相关工具现在支持两种执行模式：

• 默认 executionMode=local
• 可选 executionMode=server

默认 local 的含义是：

• testclaw-mcp 仍然通过 Sonic Server 占用设备并获取调试端口
• 但真正的 adb 操作在 运行 testclaw-mcp 的这台机器本地执行
• 因此如果你希望 Codex -> 本机 adb -> Sonic 设备调试端口，就应该把 testclaw-mcp 跑在 Codex 本机

兼容模式 server 的含义是：

• 继续沿用旧逻辑
• 由 testclaw-mcp 通过 Agent WebSocket 在服务端侧执行应用安装、启动、停止、卸载与应用列表查询

支持 executionMode 的工具：

• sonic_list_installed_apps
• sonic_install_package
• sonic_open_app
• sonic_kill_app
• sonic_uninstall_app

sonic_prepare_android_debug 的默认行为：

• 支持 deviceId 或 udId
• 默认给 Android 设备分配一组确定性的调试端口：
  • sasRemotePort = 45000 + (deviceId % 1000) * 2
  • uia2RemotePort = sasRemotePort + 1
• 返回结果里会额外带上：
  • resolvedDevice
  • adbAddress
  • localCommands.connectAdb
  • localCommands.uia2ServerUrl

本地运行示例

如果你要让 Codex 本地直连设备，请在 Codex 本机运行 testclaw-mcp：

SONIC_BASE_URL=http://192.168.31.121:3001 \
SONIC_MCP_HOST=127.0.0.1 \
SONIC_MCP_PORT=39040 \
SONIC_MCP_ADB_BIN=adb \
node index.js

可选环境变量：

• SONIC_MCP_ADB_BIN
  • 指定本地 adb 可执行文件路径，默认 adb
• SONIC_MCP_ADB_ENV_JSON
  • 以 JSON 形式附加本地执行 adb 时需要的环境变量

安全说明

• 推荐生产环境给 SONIC_MCP_HOST 配置可访问的 HTTPS 域名
• HTTP 模式属于显式不安全模式，仅建议内网或测试环境使用
• SQLite 会保存 OAuth client、授权码、access token / refresh token 以及 Sonic session token
• 不会长期保存 Sonic 明文密码

说明

返回结果尽量保留 Sonic 原始响应结构（code / message / data），方便后续扩展。后面如果你要，我可以继续补：

• 测试用例 tools
• 模块 / 公共步骤 tools
• 设备占用 / 释放 tools
• 更细的资源级权限控制