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 请求

Related MCP server: Http-tools Universal MCP Server

默认目标

默认会连到：

• 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

• 更细的资源级权限控制