MCP 集成

Tapilot 实现了 Model Context Protocol server,任何支持 MCP 的客户端(Claude Code、Cursor、Continue、LibreChat 等)都能直接调 Tapilot 的 43 个工具操作 Android / iOS / Web。

一分钟接入

Claude Code

编辑 ~/.claude/config.json(或项目级 .mcp.json):

{
  "mcpServers": {
    "tapilot": {
      "command": "npx",
      "args": ["-y", "mobai-mcp"]
    }
  }
}

重启 Claude Code → 输入 /mcp 看到 tapilot 已连接即成功。

Cursor

Settings → MCP → Add new MCP server:

{
  "name": "tapilot",
  "command": "npx -y mobai-mcp"
}

其他 MCP 客户端

只要能跑 stdio-based MCP server,配置 command: "npx -y mobai-mcp" 即可。

验证安装

在客户端里让 AI 执行:

帮我列出当前设备

AI 会调 list_devices 工具返回已连接的 Android 和 iOS 设备。

常用工具速查

场景	调哪个 tool
看看屏幕	screenshot(默认降采样,~1000 tokens)
点按钮	tap({ label: "登录" }) 或 tap({ x, y })
输入文字	input_text({ text: "hello" })
读 UI 结构	dump_ui(比 screenshot 省 token,推荐优先)
找元素坐标	find_element({ label: "登录" })
跑 DSL 脚本	run_script({ yaml: "..." })
Web 自动化	web_click / web_navigate / web_execute_js

完整列表见 MCP 工具参考。

省 token 的使用模式

Claude Vision 对每张截图收取 w×h/750 token,1080×2400 Android 屏 ≈ 3500 token,频繁截图会很快撑满 context。

推荐优先级:

1. 先 dump_ui / get_elements — 纯文本 UI 结构,1-5k token 能覆盖大部分情况
2. 需要视觉细节时用 screenshot — 默认 scale=0.5 已降 4x,还可以显式传 scale=0.3(~400 token)
3. 复杂视觉判断用 analyze_screen — 服务器侧 Gemini 读图,Claude 只看 JSON 结果

设备前置条件

Android

• adb 在 PATH 里
• 设备开 USB 调试 + USB 连线连到电脑
• 或者跑 Android Emulator

iOS Simulator

• 安装 Xcode
• 启动一台 Simulator(xcrun simctl boot <UDID>)
• 启动 WebDriverAgent(见 docs/ios-smoke-setup.md),Simulator 可以用 CODE_SIGNING_ALLOWED=NO 跳过签名,10 分钟搞定

Web

• 需要 Chrome/Chromium 在 PATH 里
• 第一次调 web_navigate 或 web_click 会自动启动 Chrome 并监听 CDP

常见问题

Q: 截图消耗 token 太多? → 优先用 dump_ui;必要用 screenshot 时传 scale=0.3;或用 analyze_screen 让 Gemini 在服务器侧读。

Q: iOS 操作报 "WDA not running"? → 启动 WDA:xcodebuild test-without-building -scheme WebDriverAgentRunner -destination 'id=<UDID>'。验证:curl http://localhost:8100/status 应返 ready。

Q: Android adb: command not found? → 确认 Android SDK 在 PATH,或装:brew install android-platform-tools。

Q: 能不能通过 HTTP 而不是 stdio 调? → 可以,用 npx mobai-api 启 HTTP server 听 localhost:3210。见 HTTP REST API。