想给自家 App 接 mobile-mcp?三步把工具暴露给 Agent
想给自家 App 接 mobile-mcp?三步把工具暴露给 Agent
当 Agent 开始接管"打开 App、点按钮、填表单、截图比对"这类原本必须由人肉完成的移动端操作时,最大的门槛往往不是 AI 能力,而是你的应用能力如何被模型"看见"。这正是 mobile-mcp 这类项目存在的理由:它把一台 iPhone、一部 Android 真机、一个模拟器,抽象成一组以 mobile_ 前缀命名的 MCP 工具,让 Claude Code、Codex、Gemini CLI 等任意 MCP 兼容客户端可以直接调用。读完本文,你会理解它的工具暴露模型、服务封装方式与注册流程,并掌握一套可复制的"三步走"套路——无论你想接的是现有 App,还是自己从零写一个 MCP Server。
第一步:理解 MCP 工具暴露模型
工具 = 名称 + 描述 + JSON Schema + 副作用标注
MCP(Model Context Protocol)工具暴露的本质,是让 Server 侧把"一段可执行逻辑"翻译成模型能理解的结构化声明。打开 mobile-mcp 的核心实现 src/server.ts,会发现它用一个内部 tool() 辅助函数统一封装了所有工具注册:
const tool = (name, title, description, paramsSchema, annotations, cb) => {
toolCallbacks.set(name, { callback: cb, paramsSchema });
server.registerTool(name, {
title,
description,
inputSchema: z.object(paramsSchema),
annotations,
}, async (args, _extra) => { ... });
};
拆开看,一个工具被"暴露"给 Agent 的关键就四件事:
- name:全局唯一标识,调用时通过
tools/call传入。mobile-mcp 全部使用mobile_前缀,一眼能看出归属与命名空间。 - description:这是写给模型看的"接口文档"。它决定了模型何时选择这个工具、参数怎么填。例如
mobile_click_on_screen_at_coordinates的描述明确写着"prefer ref when the element is listed",这就是在引导模型优先使用元素引用而非裸坐标。 - inputSchema:用 zod 声明参数结构,SDK 自动转换成 JSON Schema 下发。注意项目里大量使用
z.coerce.number()与z.enum([...]),把参数类型收窄到模型几乎不会填错的程度。 - annotations:
readOnlyHint、destructiveHint、openWorldHint三个副作用提示。例如mobile_uninstall_app标记为 destructive,mobile_open_url标记为 openWorld(影响现实世界),mobile_list_available_devices标记为 readOnly。模型会据此判断一个动作是否"危险"、是否需要先向用户确认。
除了逐个注册,createMcpServer() 还通过 McpServer 构造参数注入了 instructions,相当于给整个 Server 下发一份"使用手册"——先选设备、优先用无障碍树而非截图、把连续操作合并成批量调用。这些系统级提示同样属于"工具暴露"的一部分:暴露的不只是函数签名,还有使用策略。
一个机器人背后的分层:Robot 接口才是真正的"自家 App 适配层"
把视线放远一层。mobile-mcp 暴露的 33 个工具,内部几乎全部收敛到 Robot 接口 上:
export interface Robot {
getScreenSize(): Promise<ScreenSize>;
tap(x: number, y: number): Promise<void>;
tapByRef?(ref: string): Promise<void>;
launchApp(packageName: string, locale?: string): Promise<void>;
sendKeys(text: string): Promise<void>;
getElementsOnScreen(): Promise<ScreenElement[]>;
// ...
}
Android、iOS、模拟器、真机分别由不同实现承载(MobileDevice 通过 mobilecli 二进制下发命令,AndroidRobot、IosRobot 是 legacy 通道),但在 MCP 层看来它们是无差别的。这一设计对"给自家 App 接 MCP"有直接借鉴意义:工具层保持薄,把平台差异全部塞进 Robot 实现。你的 App 接 MCP 时,不需要为每个 UI 操作写一套 XCUITest/Espresso 胶水,只要实现一个 Robot,工具层天然共享。
第二步:用官方 SDK 包一层服务
双传输:stdio 是默认,Streamable HTTP 是远程形态
工具注册完成后,剩下的是"把工具递到 Agent 手上"的传输问题。mobile-mcp 的选择值得参考:默认走 stdio(进程间管道),需要远程/容器部署时用 --listen 起 Streamable HTTP 服务。入口 src/index.ts 里,两种模式共用同一个 createMcpServer() 工厂:
// stdio 模式:Agent 本地拉起进程,通过标准输入输出通信
serveStdio(() => createMcpServer(), { onerror: logMcpError });
// HTTP 模式:绑定 [host:]port,POST /mcp 承载 Streamable HTTP
const handler = createMcpHandler(() => createMcpServer(), { onerror: logMcpError });
const node = toNodeHandler(handler, { onerror: logMcpError });
app.post("/mcp", (req, res) => { void node(req, res, req.body); });
注意依赖声明:package.json 里的 @modelcontextprotocol/express、@modelcontextprotocol/node、@modelcontextprotocol/server 都是 v2.0.0。官方 SDK 拆分成了"服务端核心 + 传输层适配"多个包,createMcpHandler 负责协议处理,toNodeHandler 负责 HTTP 适配,serveStdio 负责管道适配——三层各司其职。自己包服务时照这个结构抄作业即可:核心工厂只产出工具,传输层随便换。
HTTP 模式还有一个值得抄的细节:app.all("/sse", ...) 对旧 SSE 端点返回 410 + 迁移提示,app.get/delete("/mcp") 返回 405。对外暴露工具时,把"已废弃的入口"显式死掉,比静默 404 对客户端友好得多。
鉴权与安全:暴露工具必须同时暴露边界
工具一旦走 HTTP 暴露,就不再是"本机可信进程"了。mobile-mcp 用三层边界守住:
- Bearer Token:设置
MOBILEMCP_AUTH后,所有请求必须携带Authorization: Bearer <token>,否则 401;未设置时启动即打印警告(src/index.ts)。 - URL 白名单:
mobile_open_url默认只放行http:///https://,app 深链需显式设置MOBILEMCP_ALLOW_UNSAFE_URLS=1。 - 路径与扩展名校验:
mobile_save_screenshot、mobile_install_app等涉及写文件的工具,统一走 validateOutputPath 和扩展名白名单(.png/.jpg/.jpeg/.mp4/.apk/.ipa...),从源头堵住路径穿越——这条在 CHANGELOG.md 里能看到 0.0.49 版本正是为修复路径穿越而加的。
接自家 App 时,"工具越界"的审计尤其重要:哪些工具是只读的、哪些会动设备状态、哪些会把请求发到外网,应该像 API 权限一样被逐条标注。
第三步:注册进 Agent 客户端
一份 JSON 通吃所有客户端
工具服务就绪后,"暴露"的最后一公里是注册。mobile-mcp 把这一过程压缩成一段所有客户端通用的配置(见 README.md):
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
command + args 即"怎么启动这个服务",mcpServers 键名即 Agent 看到的 Server 名。README 还给出了各客户端的等效 CLI 一行命令:Claude Code 用 claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest,Codex 用 codex mcp add ...,Gemini CLI 用 gemini mcp add ...。仓库根目录的 mcp.json 与 server.json 则分别服务于插件系统与 MCP 注册表:前者声明了这个 Server 的默认传输与启动参数,后者登记了 npm 包名、版本与 stdio 传输类型,供客户端自动发现。
如果你的 App 要发布成"人人可一键接入"的服务,这四件套(标准 mcpServers 配置 + CLI 命令 + 插件清单 + 注册表声明)缺一不可。
从终端到屏幕:插件让"工具"长出交互界面
纯工具调用是命令行式的,mobile-mcp 还示范了更进一步的形态:1.0.8 版本把它打包成了 Claude Code 插件(plugin.json),通过 plugin/hooks/register.tsx 注册了 /mobile-mirror 命令——在终端侧栏实时镜像设备屏幕,点击画面即触发 mobile_click_on_screen_at_coordinates,键入文字即调用 mobile_type_keys,Home/Back/URL 按钮对应 mobile_press_button 与 mobile_open_url。整个交互面板没有引入任何新工具,只是把已有 MCP 工具映射成了 UI 事件:
const tap = e.data as TapMessage;
const x = Math.round(tap.x * device.screenWidth);
const y = Math.round(tap.y * device.screenHeight);
await runAction($, "Tap", "mobile_click_on_screen_at_coordinates", { device: device.id, x, y });
这给"给自家 App 接 Agent"提供了一个高性价比思路:不一定要把功能拆成 UI 插件,先把核心操作暴露成 MCP 工具,交互层可以后续慢慢长出来。
联调与验收:怎么证明"工具真的被 Agent 用起来了"
冒烟三步:连上、列出、动手
README 给出的验收标准非常朴素:配置完成后,让 Agent 执行 "list available devices",能返回设备列表即接线成功。仓库里还提供了更工程化的验证手段——scripts/verify-streamable-http.mjs 会真实拉起服务、用官方 StreamableHTTPClientTransport 完成 initialize + tools/list,并断言 mobile_list_available_devices 在工具清单里。把它当成你的"验收脚本"模板:不是人肉点一遍,而是让客户端程序化地握手并核对工具清单。
协议层还有一个易踩的坑:MCP 正在经历协议版本演进。mobile-mcp 同时兼容两代协议——携带 server/discover(revision 2026-07-28)的请求走新结果词汇,传统 initialize 握手继续服务 2025 时代协议(测试见 test/server-discover.test.ts)。你自己接的服务如果被老客户端调用失败,先看是不是协议时代不匹配。
让 Agent 少犯错:描述、坐标映射与批量
验收不只是"能调用",还包括"调用得准"。三个来自源码的细节值得抄:
- 截图坐标映射。
mobile_take_screenshot返回的截图通常是缩小过的,src/coordinate-mapping.ts 会在结果里附带一句自然语言换算指令:"要将截图中的位置换算成屏幕坐标,x 乘以 1.333,y 乘以 1.5"。这比让模型自己猜坐标可靠得多,也是 mobile-mcp 在 issue #29 之后补上的关键修复。 - 元素引用(ref)优先于坐标。
mobile_list_elements_on_screen输出每行一个元素及@e5这类引用,点击时传 ref 而非 x/y——布局在不同设备间有差异时,ref 点击依然成立。 - 批量合并往返。
mobile_batch_commands支持在一个调用里串行执行 click → type → click,并可选在结尾重新列出屏幕元素(src/server.ts)。移动设备交互的每次工具调用都是一次设备往返,批量是把"模型思考"与"设备动作"解耦的实用优化。
最后是运维侧验收:服务启动时打印 SDK 与 Server 版本;遥测可通过 MOBILEMCP_DISABLE_TELEMETRY=1 关闭;真机远程场景还有 mobile_list_remote_devices / mobile_allocate_remote_device 一整套云端设备生命周期管理。把这几项列入上线检查单,一个"可被 Agent 稳定使用"的工具服务才算真正交付。
结语
回看 mobile-mcp 的整个链路,"把自家 App 接进 Agent"其实只有三件事:把能力注册成有描述、有 Schema、有副作用标注的 MCP 工具;用官方 SDK 包一层可切换 stdio/HTTP 的服务;再把服务注册进客户端并跑通验收。难点不在协议本身,而在工具描述的颗粒度、设备抽象的收敛、以及安全边界的划定。照着这套模式做,你的 App 离"被 Agent 直接操作"只差一个 mcpServers 配置的距离。
