操作手册

核对日期:2026-11-09。适用代码:v2,核对基线 14c3bed。

想让自己的程序打开手机应用、点击按钮、输入文字或获取截图,可以通过这里的 MCP 接口完成。先准备有效 Token 和在线手机,再按功能查找调用方式。

第一次使用,从这里开始

  1. 打开 开始使用,设置 Token 和服务地址。
  2. 运行“查看在线手机”,找到目标手机的设备 ID。
  3. 运行“截图”,把手机画面保存到电脑。
  4. 确认连接和截图正常,再尝试点击、滑动等动作。

第一个示例只查看设备,不会操作手机。后面的写操作示例会改变手机状态,执行前请确认目标设备和页面。

按你想做的事查找

我想做什么查看哪一页常用工具
查看手机、电量、亮度,点亮屏幕设备与状态list_devices、device_info、set_screen
打开应用、查包名、安装测试 APK设备上的应用launch_app、list_apps、current_app
点击、长按、翻页、缩放点击与滑动tap、swipe、pinch、gesture
输入中文、切输入法、粘贴文字输入input_text、ime_on、set_clipboard
按文字点击、等页面加载页面控件observe、ui_tap、wait_for
截屏、截取页面局部截图screenshot、screenshot_region
找文字、图标、颜色和物体图像与文字识别ocr、find_text、find_image、watch
下载图片到相册、读写文件文件与媒体download_file、scan_media、read_file
让手机请求某个 HTTP 接口手机网络请求http_get、http_post
在手机上保存少量进度数据手机本地存储kv_put、kv_get
调用已注册的第三方接口或内部函数扩展工具调用list_capabilities、invoke_tool

本手册覆盖当前代码中的 86 个 MCP 工具。每项都给出用途、参数、完整请求、Python / JavaScript 示例、返回说明和核对方法。网页点击语言标签即可切换,并记住选择。JavaScript 示例适用于 Node.js 20+;页面中的代码只展示,不会直接执行。返回值是格式示例,不是真机执行记录;目标部署和设备是否支持,以实际 tools/list 和回执为准。

先理解这三个小规则

设备 ID 就是要操作哪台手机。 用 list_devices 取得 id,后续传 device_id;不要填账号、手机型号或列表序号。

点击坐标是屏幕比例。 左上角约为 (0,0),中央是 (0.5,0.5),右下角约为 (1,1)。例如从 (0.5,0.8) 滑到 (0.5,0.3),表示在屏幕中央从下向上滑。

动作完成还要看效果。 点击工具返回成功,只说明这次动作取得了成功回执;是否进入目标页面,需要截图或页面控件确认。

常见操作顺序

  • 打开应用:list_apps 查应用 → launch_app 打开 → current_app 核对前台 → screenshot 看页面。
  • 输入并搜索:ui_tap 聚焦输入框 → input_text 输入 → 核对文字 → press_key 按回车。
  • 等待并点击:wait_for 等目标出现 → 检查 found → ui_tap 点击目标。
  • 下载到相册:download_file 下载且 scan=true → file_info 查文件 → 到相册核对。

这些是调用顺序示例,不代表原始 MCP 多次调用会自动形成一个独占任务。对同一手机要逐条等待结果,避免并发争用屏幕。

遇到问题

文档维护

手册依据 v2/adapters/mcp 注册参数和设备命令实现编写,参考 AutoGo 按模块解释参数和示例的组织方式,没有照搬其 Go API 或坐标单位。

网页由 server/site/gen_mcp_doc.py 生成,中文用途和示例在 mcp/reference.json 维护,工具参数保存在同一文件的 inputSchema。更新工具时同时核对说明与参数,执行生成器即可同步分类 Markdown 和官网页面,不需要修改服务端入口。

开始使用

这一页只做两件事:找到你的手机,把手机截图保存到电脑。可以在 Python 和 JavaScript 标签之间切换;同一页和其他工具页会沿用所选语言。

1. 准备三样东西

要准备的东西从哪里取得
服务地址例如 https://frpc.api-y.cn/mcp,也可以是你自己的部署域名
Token当前平台签发的有效卡密,或有权限的有效登录会话凭证
在线手机在控制台确认手机已连接,并且当前身份有权访问

Token 是访问接口的凭证,不是账号密码或设备 ID。不要把真实值写入脚本仓库。账号密码登录的程序可保留登录响应的 Cookie;接口不会在登录 JSON 中返回 token 字段,认证细节见 进阶参考。

2. 准备示例客户端

电脑需要 Python 3,只使用标准库,不需要安装额外 Python 包。

新建一个文件夹,例如 mcp-demo,将本页末尾 Python 标签中的完整代码保存为 mcp_client.py。仓库中的同一份示例位于 v2/docs/contracts/mcp/examples/mcp_client.py。

导入客户端文件不会连接服务。把后面的示例文件和客户端放在同一个文件夹,再在该文件夹打开终端。

3. 设置服务地址和 Token

两种语言使用相同的环境变量。

Windows PowerShell:

$env:AGOV_MCP_URL = "https://frpc.api-y.cn/mcp"
$env:AGOV_TOKEN = "替换为你的有效Token"

Linux / macOS:

export AGOV_MCP_URL='https://frpc.api-y.cn/mcp'
export AGOV_TOKEN='替换为你的有效Token'

这些变量只对当前终端及其启动的程序生效。所有示例先使用全量 /mcp,熟悉后再按进阶说明选择精简工具组。

4. 找到你的手机

新建 list_devices.py:

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
devices = client.text_json(client.call("list_devices"))

for device in devices:
    print(device["id"], device.get("name", ""), device.get("model", ""))

运行:

python list_devices.py

程序会列出设备 ID、名称和型号。复制目标手机的 ID,后续不要填整行文字或账号。

列表为空怎么办? 先确认控制台中手机在线,再确认 Token 对应身份有权访问。接口只列出当前身份可见的在线设备。

5. 截图保存到电脑

把代码中的“你的设备ID”替换为上一步选定的 ID:

新建 screenshot.py:

import base64
from pathlib import Path
from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
device_id = "你的设备ID"
result = client.call("screenshot", {"device_id": device_id})

image = next(item for item in result["content"] if item.get("type") == "image")
if image["mimeType"] != "image/jpeg":
    raise RuntimeError("截图格式变化,请按 mimeType 选择文件后缀")
Path("screen.jpg").write_bytes(base64.b64decode(image["data"], validate=True))
print("截图已保存为 screen.jpg")
python screenshot.py

打开同一文件夹里的 screen.jpg。看到当前手机画面,说明认证、设备选择和截图链路已连通。

6. 再试一个明确的动作

确认当前页面可以返回桌面,再执行 HOME 示例。它会改变手机前台页面。

保存为 home.py:

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call("press_key", {"device_id": "你的设备ID", "key": 3})
print(client.text(result))
python home.py

执行后再截图,确认手机回到桌面。接下来查阅 点击与滑动、文字输入 或 页面控件。

7. 手册示例怎么使用

每个工具都提供可切换的 Python / JavaScript 调用示例,同时保留完整 JSON-RPC 请求。JavaScript 示例使用 Node.js 和 await;同一台手机的动作逐条等待,不用 Promise.all 并发抢屏。

含“替换为”“你的设备ID”等文字的是占位符,必须替换。example.com 只表达参数格式,不保证那里有图片、APK 或业务接口。

客户端只处理认证、协议和结果解析,不自动重试。设备结果未知或客户端超时时,先按 常见问题 核对,不要重复发起同一个副作用。

示例客户端完整代码

选择需要的语言,只保存对应文件即可。

保存为 mcp_client.py:

"""外部 MCP 文档示例客户端;导入不会连接服务或操作设备。"""
import itertools
import json
import os
import urllib.error
import urllib.request


class ToolError(RuntimeError):
    """保留原始工具结果,便于读取失败操作的 operation.id 并核对。"""
    def __init__(self, result):
        self.result = result
        super().__init__(MCPClient.text(result) or "MCP 工具调用失败")


class MCPClient:
    def __init__(self, url, token, timeout=200):
        self.url, self.token, self.timeout = url, token, timeout
        self.protocol = None
        self.ids = itertools.count(1)

    @classmethod
    def from_env(cls):
        return cls(
            os.environ.get("AGOV_MCP_URL", "https://frpc.api-y.cn/mcp"),
            os.environ["AGOV_TOKEN"],
        )

    def rpc(self, method, params=None, *, notification=False, timeout=None):
        rid = None if notification else next(self.ids)
        body = {"jsonrpc": "2.0", "method": method}
        if not notification:
            body["id"] = rid
        if params is not None:
            body["params"] = params
        headers = {
            "Authorization": "Bearer " + self.token,
            "Content-Type": "application/json",
            "Accept": "application/json, text/event-stream",
        }
        if self.protocol:
            headers["MCP-Protocol-Version"] = self.protocol
        request = urllib.request.Request(
            self.url, data=json.dumps(body).encode("utf-8"),
            headers=headers, method="POST",
        )
        try:
            with urllib.request.urlopen(request, timeout=timeout or self.timeout) as response:
                if notification:
                    return None
                if response.headers.get_content_type() == "text/event-stream":
                    data, message = [], None
                    for raw_line in response:
                        line = raw_line.decode("utf-8").rstrip("\r\n")
                        if line.startswith("data:"):
                            value = line[5:]
                            data.append(value[1:] if value.startswith(" ") else value)
                        elif not line and data:
                            event = json.loads("\n".join(data))
                            data = []
                            if event.get("id") == rid:
                                message = event
                                break
                    if message is None:
                        raise RuntimeError("未收到匹配响应;写操作不可直接重发")
                else:
                    message = json.load(response)
        except urllib.error.HTTPError as error:
            raise RuntimeError(f"MCP HTTP {error.code},请检查认证或服务状态") from None
        if message.get("id") != rid:
            raise RuntimeError("MCP 响应 id 不匹配")
        if "error" in message:
            raise RuntimeError("MCP 协议错误:" + json.dumps(message["error"], ensure_ascii=False))
        return message["result"]

    def initialize(self):
        result = self.rpc("initialize", {
            "protocolVersion": "2025-03-26", "capabilities": {},
            "clientInfo": {"name": "mcp-manual-example", "version": "1.0.0"},
        })
        self.protocol = result["protocolVersion"]
        if self.protocol != "2025-03-26":
            raise RuntimeError("未协商到示例支持的协议版本")
        self.rpc("notifications/initialized", notification=True)
        return result

    def list_tools(self):
        tools, params = [], {}
        while True:
            result = self.rpc("tools/list", params)
            tools.extend(result.get("tools", []))
            cursor = result.get("nextCursor")
            if not cursor:
                return tools
            params = {"cursor": cursor}

    def call(self, name, arguments=None, *, timeout=None):
        # 不自动添加设备 ID,不自动重试,避免给通用工具误传参数或重复副作用。
        result = self.rpc("tools/call", {
            "name": name, "arguments": arguments or {},
        }, timeout=timeout)
        if result.get("isError"):
            raise ToolError(result)
        return result

    @staticmethod
    def text(result):
        return "\n".join(
            item.get("text", "") for item in result.get("content", [])
            if item.get("type") == "text"
        )

    @staticmethod
    def text_json(result):
        # 仅对文档明确说明“文本中的 JSON”的结果使用。
        return json.loads(MCPClient.text(result))

返回值怎么读

同样一次 MCP 调用,不同工具可能返回文字、JSON 文本或图片。先看工具页的“返回结果”,再选择读取方式。

普通文字

例如 current_app 的设备实现返回普通包名文本:

result = client.call("current_app", {"device_id": device_id})
package = client.text(result).strip()
print(package)

示例输出 com.android.settings。不要对它调用 json.loads,也不要读取不存在的 package 属性。

文本里的 JSON

设备列表、文件信息等把 JSON 放在 text 内容里:

{
  "content": [
    {"type": "text", "text": "[{\"id\":\"你的设备ID\"}]"}
  ]
}

先取文本,再解析 JSON。示例客户端已经提供 text_json:

devices = client.text_json(client.call("list_devices"))
for device in devices:
    print(device["id"])

observe 和 list_apps 在某些情况下会附加说明文字。此时先用 client.text 查看完整内容,不能把“JSON + 说明”整段直接解析。

图片

截图返回的是图片内容块:

{
  "content": [
    {"type": "text", "text": "当前屏幕"},
    {"type": "image", "mimeType": "image/jpeg", "data": "图片Base64"}
  ]
}

遍历 content 找 type=image,解码 data。不要假设第一个内容块一定是图片,也不要把整段 JSON 当作 Base64。

调用出错

需要检查三层:HTTP 状态、JSON-RPC 顶层 error、工具结果 isError。HTTP 200 不等于手机操作成功。示例客户端会分别抛出异常;工具错误保留原始 result:

from mcp_client import ToolError

try:
    result = client.call("input_text", {
        "device_id": device_id,
        "text": "杭州天气",
    })
except ToolError as error:
    print(str(error))
    # 原始内容保存在 error.result;没有自动重发。

某些找图或找字工具未找到时返回 isError=true,某些返回 found=false。应先判断工具错误,再按该工具的返回说明读取 found 或 hit。

动作返回成功,但页面没变化

动作回执不是业务验收。例如点击成功不保证按钮响应、应用加载完成或发布成功。调用 screenshot、current_app、wait_for 等检查真实效果,再决定下一步。

通用能力的 operation.id

invoke_tool 的 JSON 文本中含 operation.id,用于 get_operation;JSON-RPC id 只用于匹配请求响应。两者不能互换。

get_operation 返回持久状态,不代表所有直接设备工具都产生可查询的 operation.id。直接 tap、swipe 后不能拿请求 id 查询它们。

常见问题

找不到手机

先在控制台查看设备是否在线,再调用 list_devices。只列当前身份有权访问的在线设备。型号、名称和设备 ID 是不同字段,操作参数必须填 id。

返回 HTTP 401

检查当前终端是否设置 AGOV_TOKEN,凭证是否有效。重新开一个终端不会自动保留之前进程中的环境变量。用户名和密码不能直接当 Bearer Token 使用。

显示 tool not found

用同一个 MCP 地址执行 tools/list。地址带 ?tools=standard 时,可能没有 gesture、watch 等工具;先换全量 /mcp 核对。文档有工具不等于线上服务或当前设备已升级。

输入没有进去

先截图确认目标输入框存在,再用 ui_tap 或 tap 聚焦。input_text 不负责寻找输入框,也不自动提交搜索。需要输入法会话时用 ime_on,结束后 ime_off 恢复;文字落入后还需读取控件或截图确认。

设备正在被其他控制会话使用

先查看是否有人工操作、AI 或其他任务占用同一手机。直接 MCP 写工具会等待约 5 秒取得控制权,超出后可能返回占用,原始 MCP 多次调用不会自动形成一个完整排队任务。

有权限时可读取 GET /api/control-sessions 辅助排查,这是 HTTP 诊断接口,不是 MCP 工具。先确认占用者与运行状态,不要反复强制解锁仍在执行的任务。

写入凭据准备失败或超时

这说明命令写入前的准备没有完成,可能与控制权、隔离、租约或存储访问有关。查看具体错误、运行记录和服务端日志,不能只凭这句判断手机已执行,也不能把所有情况都当成“网络卡”。

execution_unknown 或客户端超时

设备可能已经做了动作,只是结果没有成功返回。先核对页面与执行记录;invoke_tool 已返回持久操作 ID 时可用 get_operation 查询。不要生成新幂等键或换一个请求 ID,就自动再发同一个副作用。

input_reset 只清触点,不解除任务占用或未知结果隔离。释放控制权和确认业务结果也不是同一件事。

JSON 解析失败

先打印 client.text 查看工具实际返回。current_app 是普通文字包名;截图是图片内容块;observe/list_apps 某些情况下可能附带说明。按 返回值怎么读 选择解析方法。

文件下载了,相册看不到

先用 file_info 确认文件存在,再确认下载使用 scan=true 或调用 scan_media。下载成功与媒体库扫描成功是两步,目标应用的相册也可能需要刷新。

一个接口能操作多台手机吗

直接 tap 等工具一次使用一个 device_id。不同手机可以分别提交,同一手机逐条等待结果;多台手机没有统一事务、同时开始或同时完成保证。具有批量能力的扩展工具,应按其自身能力定义调用。

示例运行会操作手机吗

会。截图、读设备列表等示例用于查看;点击、输入、写文件、安装、卸载等会产生实际影响。文档生成和语法检查不会执行这些示例,文档里的结果也不是本次真机测试记录。

进阶参考

核对日期:2026-11-09。适用代码:v2,核对基线 71fa208。

本文只说明外部客户端接入 MCP,不涉及内置 JS 模板或工作流编写。官网入口为 /mcp.html。线上可用能力以该部署的 tools/list 为准,不能仅凭文档判断服务已经升级。

1. 连接和认证

项目当前实现
地址https://<服务域名>/mcp,例如 https://frpc.api-y.cn/mcp
传输MCP Streamable HTTP,JSON-RPC 2.0;不是 WebSocket 或旧版独立 /sse 端点
方法请求和通知通过 POST 发送
认证Authorization: Bearer <Token>
内容类型Content-Type: application/json
接收类型Accept: application/json, text/event-stream
工具范围URL 的 ?tools= 选择工具集,不授予额外权限
传输会话当前为无状态模式 WithStateLess(true),不要求持有 Mcp-Session-Id

Token 可使用平台签发的有效卡密,也接受有效的用户登录会话 ID。浏览器登录使用 autogov_session Cookie;POST /api/login 的 JSON 只返回 ok、username,不返回 token 字段。程序通过用户名密码登录时,应保留响应设置的 Cookie,而不是读取不存在的 JSON Token。

每个请求都需认证。身份决定租户、角色和设备分组,不能通过参数切换租户。Token 放环境变量,不写入源码或 URL;虽然服务端支持 ?token=,外部 HTTP 对接应使用 Bearer 头。本地匿名仅限显式启用且来自环回地址的请求,不是公网免认证入口。

2. 初始化、发现和调用

下面使用 Bash/curl;Windows PowerShell 请使用 curl.exe 并按 PowerShell 语法传递 JSON,或使用第 5 节 Python 示例。调用方自行设置环境变量 AGOV_TOKEN。

MCP_URL='https://frpc.api-y.cn/mcp?tools=standard'

curl -sS "$MCP_URL" \
  -H "Authorization: Bearer $AGOV_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data-binary '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'

读取返回的 result.protocolVersion,后续请求用协商值设置 MCP-Protocol-Version。下面假设返回 2025-03-26;服务端返回其他版本时不能照抄此值。JSON-RPC id 是响应关联标识,不是幂等键,也不是设备会话 ID。

# 通知不带 id;成功可能返回 202 和空响应体。
curl -sS "$MCP_URL" \
  -H "Authorization: Bearer $AGOV_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-03-26' \
  --data-binary '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 获取工具定义;有 nextCursor 时继续翻页。
curl -sS "$MCP_URL" \
  -H "Authorization: Bearer $AGOV_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-03-26' \
  --data-binary '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 列出当前身份可访问的在线设备。
curl -sS "$MCP_URL" \
  -H "Authorization: Bearer $AGOV_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-03-26' \
  --data-binary '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_devices","arguments":{}}}'

同一次连接流程使用同一个工具集 URL。响应可能是普通 JSON,也可能是 SSE:解析 SSE 的 data: 消息,并匹配响应 id,不能直接取第一个事件。

3. 工具集

当前代码注册 86 个 MCP 工具,不代表线上已部署同版本。新增工具通常也需要设备实现对应命令。

URL 参数内容
不传 / full全量,包括通用能力入口
corelist_devices、observe、tap_element、screenshot、input_text、press_key、swipe、current_app
standardcore + app
agentsense + act;不是全量,也不包含 list_devices
core,ui核心 + 控件、缩放、多指、输入诊断
toolslist_capabilities、invoke_tool、get_operation,不包含直接设备工具

也可组合 core/app/vision/ui/device/sense/act/tools 组,重复项合并。全部组名无效时,当前实现回退到全量,不报空集;权限校验仍然有效。

完整参数表见官网 /mcp.html;程序以实际 tools/list.inputSchema 为准。

工具重要参数和语义
list_devices无参数;文本里是设备数组 JSON,其中 id 才是设备 ID
screenshotdevice_id;返回 image 内容块,读取 mimeType 和 Base64 data
observe / ui_dumpdevice_id;读取当前页面
tap_elementdevice_id、i;页面变化后重新 observe,不能复用旧编号
tapdevice_id、x、y;坐标为 0..1 比例
swipedevice_id、x、y、x2、y2;可选 dur(毫秒)
long_pressdevice_id、x、y;可选 ms(毫秒)
pinchdevice_id、x、y、from、to;可选 ms;半径按屏宽归一化
gesturedevice_id、frames;见第 7 节
input_infodevice_id;查询输入通道和触点状态,属于 ui 组
input_resetdevice_id;可选 force;清触点不等于释放任务或解除隔离
launch_appdevice_id、name;应用名或包名
current_appdevice_id;返回普通包名文本,例如 com.android.settings
input_textdevice_id、text;先聚焦输入框,设备选择可用输入通道
ime_on / ime_offdevice_id;开启和恢复会话输入法,不等于独占整段外部自动化
download_filedevice_id、url、path;可选 scan、timeout_sec;用于二进制下载
watchdevice_id、templates;templates 是包含 JSON 对象数组的字符串;当前落在 device 组
list_capabilities无参数;查询能力定义、目标要求和输入约束
invoke_toolcapability、target_kind、target_id;可选 input、idempotency_key
get_operationoperation_id;查询通用能力操作的持久状态

直接设备工具使用单个 device_id,不是 deviceIds 数组。list_devices/list_capabilities/invoke_tool/get_operation 不使用顶层 device_id;通用能力的目标按定义填 target_kind/target_id。

4. 返回值的三层检查

  1. HTTP 非成功状态先按传输或认证错误处理;反向代理可能返回 429、502 等,不能当作工具结果。
  2. JSON-RPC 顶层 error 是方法或协议错误。
  3. result.isError=true 是工具执行错误。成功结果的 content 可包含多项文本、图片等内容。

设备列表的结果示例:

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"[{\"id\":\"你的设备ID\"}]"}]}}

要对文本再解析一次 JSON,得到设备数组,再读取每项 id。不能把整段文本当设备 ID。生产对接应明确指定设备,不默认选第一台。

截图返回 {"type":"image","mimeType":"image/jpeg","data":"...Base64..."},解码 data,不要把文本说明当图片。

5. Python / JavaScript 示例客户端

开始使用 已提供两种语言的完整示例客户端和运行步骤,官网可以直接切换。Python 使用 mcp_client.py;JavaScript 使用 Node.js 20+ 和 mcp_client.mjs。两者都支持 JSON / SSE 响应、初始化、工具错误解析;默认不重试副作用。

6. 设备会话、并发和幂等

直接动作示例:

{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"tap","arguments":{"device_id":"你的设备ID","x":0.5,"y":0.5}}}

同一设备的写入由服务端控制会话协调。直接 MCP 写工具当前等待控制权约 5 秒,忙时可能返回占用或准备失败;多次原始 MCP 调用不会自动合并成一个排队任务,也不保证整段操作独占。MCP 无状态传输与设备执行会话是两件事。

同一手机逐条等待动作完成,不并发抢屏。不同设备可分别提交,但没有跨设备事务或同时完成保证。

通用能力对接顺序:

  1. 用 list_capabilities 获取当前身份可见的定义和目标要求。
  2. 用 invoke_tool,按定义填写 capability、target_kind、target_id 和 input,不能猜名称或端点。
  3. 保存返回 JSON 中的 operation.id,用 get_operation(operation_id) 查询。

例如,先在能力列表确认当前身份可调用 device.tap,再提交以下请求。这里是实际点击示例,不是只读查询:

{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"invoke_tool","arguments":{"capability":"device.tap","target_kind":"device","target_id":"你的设备ID","input":{"x":0.5,"y":0.5},"idempotency_key":"业务任务ID:步骤01"}}}

解析该工具的 JSON 文本,保存其中 operation.id,而不是响应的 JSON-RPC id=11。查询请求:

{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"get_operation","arguments":{"operation_id":"上一步operation.id的值"}}}

invoke_tool.idempotency_key 最长 96 字符。同一业务重试复用原键与参数,改参数是新提交;它不是直接 tap/swipe 的通用参数,也不保证第三方端到端恰好执行一次。

通用操作状态为 queued/running/succeeded/failed/unknown。能力只返回“已入队”时,提交成功不代表后续业务完成。直接 tap 等工具不承诺返回可用于 get_operation 的操作 ID,不能把 JSON-RPC id 当 operation_id。

7. 多指轨迹和输入诊断

gesture/input_info/input_reset 属于 ui 组,使用 /mcp?tools=core,ui 或 full;standard、agent 不包含这三个工具。

{
  "jsonrpc": "2.0", "id": 20, "method": "tools/call",
  "params": {
    "name": "gesture",
    "arguments": {
      "device_id": "你的设备ID",
      "frames": [
        {"atMs": 0, "contacts": [{"id": 0, "x": 0.45, "y": 0.5}, {"id": 1, "x": 0.55, "y": 0.5}]},
        {"atMs": 300, "contacts": [{"id": 0, "x": 0.3, "y": 0.5}, {"id": 1, "x": 0.7, "y": 0.5}]},
        {"atMs": 320, "contacts": []}
      ]
    }
  }
}
  • 1~2048 帧,首帧从 0 毫秒开始且至少一个触点;时间不得倒退,最大 120000 毫秒。
  • contacts 是该时刻全部活动触点,不是增量事件;空数组全部抬起,示例显式用末帧释放。
  • 同帧最多 10 个不同触点,ID 为 0..9,实际数量受设备能力限制。
  • x/y 和可选轴 pressure、touchMajor、touchMinor、widthMajor、widthMinor、orientation 都为 0..1 有限数;可选轴能否生效取决于驱动。
  • gesture 当前 Schema 顶层只标 frames 必填,但处理器仍要求 device_id,调用必须传入。

input_info 查询输入通道、节点、协议及触点占用。C/Java 通道由设备选择,接口没有客户端强制通道参数;支持某通道不代表上一动作必然走该通道,实际路径结合设备执行日志核对。

input_reset(force=false) 释放本次输入;force=true 清设备全部触点,仅在确认现场后使用。它不释放任务控制权、不核对业务结果、不解除未知结果隔离。

8. 错误处理

现象处理
HTTP 401检查认证头、Token 或登录会话
当前角色无权 / 设备不存在或无权访问检查租户、角色、分组,不靠改设备 ID 绕过
tool not found查同一 URL 的 tools/list、工具组和部署版本
设备不在线 / 连接归属失效重新列设备并等待连接恢复
其他控制会话占用确认占用者和运行状态,不反复强制解锁仍执行的任务
写入凭据准备失败 / 超时尚未完成准备,结合会话、隔离和服务日志区分占用、租约、存储故障
execution_unknown / 客户端超时或断线命令可能执行,停止自动重发副作用,核对现场和执行记录
工具失败 / execution_failed查看具体原因和阶段,失败不代表之前动作回滚
动作成功但业务未完成用页面、业务状态或外部结果另行核验

占用诊断可读取授权范围内的 GET /api/control-sessions,这是辅助 HTTP API,不是 MCP 工具。get_operation 仅适用于已有持久操作 ID 的调用;其他调用结合设备执行日志和现场核对。

找图/OCR 等可能带 tap=true,watch 也可点击,不能按名字判断只读。watch 的正确参数示例:

import json

templates = json.dumps([{"sha1": "", "b64": "模板图片的Base64"}])
result = client.call("watch", {
    "device_id": device_id,
    "templates": templates,
    "tap": False,
    "every_ms": 300,
    "timeout_ms": 10000,
    "max_hits": 1,
}, timeout=30)

按工具等待时限设置客户端和代理超时;watch 最长等待 600000 毫秒。客户端超时不是设备停止的证据。本文不承诺固定耗时、服务端统一限流额度或自动重试安全性。

9. 维护依据

  • 注册和参数:v2/adapters/mcp/{tools,integration,vision}.go。
  • 分组:v2/adapters/mcp/toolsets.go。
  • 认证和权限:v2/server/internal/app/main.go。
  • 控制与回执:v2/adapters/mcp/control.go、v2/adapters/agentws/query.go。
  • 轨迹契约:v2/capability/definitions/device.go、v2/core/gesture/gesture.go。
  • 通用操作:v2/core/operation/service.go、v2/server/internal/app/operations.go。

本页保留协议与运维细节;操作入门和按功能手册请先阅读上一级 MCP 文档。官网生成器:server/site/gen_mcp_doc.py。输入支持 tools/list JSON-RPC 响应或工具数组,默认输出 v2 静态目录,也可用 --output 指定既有官网目录。更新时从目标部署的全量端点导出,不能拿精简工具集冒充全量;分页结果应先合并完整。

本次按本地代码和既有工具快照更新;没有操作真实设备、编译服务或验证线上部署。

设备与状态

查手机、电量、屏幕、音量和设备运行情况。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

查看在线手机 list_devices

开始操作前查看自己能访问的在线手机,找到对应的设备 ID。

参数

无参数。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "list_devices",
    {}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_devices",
    "arguments": {}
  }
}

返回结果

一项文本内容,文本内部是设备数组 JSON;空数组表示当前没有可访问的在线设备。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "[{\"id\": \"你的设备ID\", \"name\": \"示例手机\", \"model\": \"示例型号\", \"w\": 1080, \"h\": 2400, \"online\": true, \"battery\": 80, \"fgApp\": \"com.android.settings\"}]"
    }
  ]
}

怎么确认成功

读取每个对象的 id、name、model,明确选定一台,后续沿用它的 id。

常见问题

列表为空时先检查手机连接和当前账号授权,不要填手机型号代替设备 ID。

查看手机详细状态 device_info

查看当前亮度、电量、屏幕是否点亮以及前台应用,操作前后都可读取。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "device_info",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "device_info",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

文本中的 JSON 对象,包含 width、height、battery、brightness、screenOn、unlocked、foreground 等,字段采集结果随机型变化。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"model\": \"示例手机\", \"width\": 1080, \"height\": 2400, \"battery\": 80, \"brightness\": 100, \"screenOn\": true, \"unlocked\": true, \"foreground\": \"com.android.settings\"}"
    }
  ]
}

怎么确认成功

例如设置亮度后再次读取 brightness,确认值已变化。

常见问题

部分系统限制敏感信息读取,字段为空不能直接当作整次查询失败。

点亮或熄灭屏幕 set_screen

操作前点亮手机,或结束后熄屏。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
on布尔值是—true=点亮,false=熄屏

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "set_screen",
    {'device_id': '你的设备ID', 'on': True}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_screen",
    "arguments": {
      "device_id": "你的设备ID",
      "on": true
    }
  }
}

返回结果

普通文字:已点亮屏幕或已熄屏。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已点亮屏幕"
    }
  ]
}

怎么确认成功

读取 device_info.screenOn,或查看真实设备。

常见问题

点亮屏幕不保证通过 PIN、图案或生物识别锁屏。

设置屏幕亮度 set_brightness

调整屏幕亮度,数值范围 0~255。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
value数字是—亮度 0~255

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "set_brightness",
    {'device_id': '你的设备ID', 'value': 100}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_brightness",
    "arguments": {
      "device_id": "你的设备ID",
      "value": 100
    }
  }
}

返回结果

普通文字,表示设置亮度的回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已设亮度 100"
    }
  ]
}

怎么确认成功

读取 device_info.brightness,核对目标值。

常见问题

会先关闭自动亮度;0 可能非常暗,初次示例使用 100。

设置音量 set_volume

调整媒体、通知、闹钟或铃声音量。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
value数字是—目标音量值
stream数字否3音量流:3=媒体 5=通知 4=闹钟 2=铃声,默认 3

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "set_volume",
    {'device_id': '你的设备ID', 'value': 5, 'stream': 3}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_volume",
    "arguments": {
      "device_id": "你的设备ID",
      "value": 5,
      "stream": 3
    }
  }
}

返回结果

普通文字音量设置回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已设音量 5"
    }
  ]
}

怎么确认成功

媒体音量可用 device_info 中 volumeMedia、volumeMax 核对。

常见问题

设备音量最大档位不同;参数校验允许 0~100 不代表手机有 100 档。

让手机震动 vibrate

让设备短暂震动,检查反馈能力。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
ms数字否300震动时长毫秒,默认 300

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "vibrate",
    {'device_id': '你的设备ID', 'ms': 300}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vibrate",
    "arguments": {
      "device_id": "你的设备ID",
      "ms": 300
    }
  }
}

返回结果

普通文字震动回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已下发震动 300ms"
    }
  ]
}

怎么确认成功

以真实设备震动为准。

常见问题

震动能力、静音设置和系统权限可能影响效果。

停止震动 cancel_vibration

结束正在进行的震动。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "cancel_vibration",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "cancel_vibration",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

普通文字:已取消震动。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已取消震动"
    }
  ]
}

怎么确认成功

确认手机停止震动。

常见问题

只取消震动,不会取消正在执行的任务。

读取通知栏消息 notifications

读取手机当前可获取的通知,用于查看任务相关的通知内容。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "notifications",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "notifications",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

设备回传的通知数据;内容与系统开放程度有关。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

核对通知来源应用与时间,不把历史通知当本次任务结果。

常见问题

部分 ROM 可能不返回通知;不应在日志中公开敏感通知。

查询应用进程 proc_info

查看指定应用或进程当前是否运行、PID 和内存。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
name字符串是—包名或进程名

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "proc_info",
    {'device_id': '你的设备ID', 'name': 'com.android.settings'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "proc_info",
    "arguments": {
      "device_id": "你的设备ID",
      "name": "com.android.settings"
    }
  }
}

返回结果

文本中的 JSON,常见字段 name、pid、memKB、running。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"name\": \"com.android.settings\", \"pid\": 1234, \"memKB\": 65536, \"running\": true}"
    }
  ]
}

怎么确认成功

只有取得当前有效 PID 后,再调用 cpu_usage。

常见问题

进程重启后 PID 会变,不要长期复用旧 PID。

查看进程 CPU 和内存 cpu_usage

排查某个手机进程是否占用过高;先从 proc_info 取得 PID。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
pid数字是—进程 PID

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "cpu_usage",
    {'device_id': '你的设备ID', 'pid': 1234}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "cpu_usage",
    "arguments": {
      "device_id": "你的设备ID",
      "pid": 1234
    }
  }
}

返回结果

文本中的 JSON,字段 pid、cpu、memKB。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"pid\": 1234, \"cpu\": 2.5, \"memKB\": 65536}"
    }
  ]
}

怎么确认成功

连续少量采样观察趋势,不能凭一次读数判断长期负载。

常见问题

1234 只是示例 PID,必须替换为当前手机真实进程 PID。

重启手机 reboot_device

在维护时重启整台手机。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "reboot_device",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "reboot_device",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

重启命令回执;随后设备连接可能中断。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

等待 list_devices 再次出现该设备。

常见问题

会中断当前手机任务,需要设备具有重启权限。

重启手机内核进程 restart_agent

重启设备端 Agent,手机系统本身不重启。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "restart_agent",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "restart_agent",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

普通文字重启回执,连接随后短暂中断。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

等待同一设备重新连接,确认内核恢复。

常见问题

需要有看护进程重新拉起 Agent;不要把此操作当作手机系统重启。

设备上的应用

查应用、打开应用,维护测试应用的安装与数据。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

查找手机安装的应用 list_apps

不知道应用包名时,先根据名称或包名查询。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
filter字符串否—按中文名或包名模糊匹配,如 微信 / tencent
limit数字否40最多返回多少条,默认 40。超出会提示用 filter 缩小范围
include_system布尔值否falsetrue=列全部已安装包(不带 label);默认 false=只列能打开的应用

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "list_apps",
    {'device_id': '你的设备ID', 'filter': '设置', 'limit': 20}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_apps",
    "arguments": {
      "device_id": "你的设备ID",
      "filter": "设置",
      "limit": 20
    }
  }
}

返回结果

文本内是应用列表 JSON,常见字段 pkg、label、version;达到 limit 时可能附加缩小搜索范围的说明。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "[{\"pkg\": \"com.android.settings\", \"label\": \"设置\"}]"
    }
  ]
}

怎么确认成功

从列表取 pkg,再用于 app_info、stop_app 等按包名操作的工具。

常见问题

默认查询可启动应用,不是所有系统包;要查询全部包显式设 include_system=true。

打开应用 launch_app

打开已安装应用,可传应用名或完整包名。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
name字符串是—App 显示名或包名,如 微信 / com.tencent.mm

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "launch_app",
    {'device_id': '你的设备ID', 'name': 'com.android.settings'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "launch_app",
    "arguments": {
      "device_id": "你的设备ID",
      "name": "com.android.settings"
    }
  }
}

返回结果

设备拉起回执;成功也应结合 current_app 和截图确认具体页面。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

调用 current_app,应返回目标包名;再截图确认页面。

常见问题

找不到应用时先用 list_apps,不要反复猜名称;前台停在安全中心可能是系统拦截。

查看当前打开的应用 current_app

在打开应用后确认前台包名,或判断是否被系统弹窗带离目标页面。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "current_app",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "current_app",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

普通包名文本,不是包含 package 字段的 JSON 对象。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "com.android.settings"
    }
  ]
}

怎么确认成功

使用 client.text(result).strip() 读取包名;需要页面级判断时继续截图。

常见问题

安全中心或权限页成为前台时会返回它们的包名,不代表目标应用一定没有安装。

查看应用信息 app_info

查询指定包名对应的安装和版本信息。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
package字符串是—应用包名

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "app_info",
    {'device_id': '你的设备ID', 'package': 'com.android.settings'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "app_info",
    "arguments": {
      "device_id": "你的设备ID",
      "package": "com.android.settings"
    }
  }
}

返回结果

设备返回的应用信息,以设备实际字段为准;外层为 MCP text 内容块。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

核对包名与设备上安装的应用一致。

常见问题

参数名是 package,不是 launch_app 使用的 name。

打开网页或应用链接 open_url

通过手机默认浏览器或已注册的应用打开链接。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
url字符串是—要打开的 URL 或深链

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "open_url",
    {'device_id': '你的设备ID', 'url': 'https://example.com'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "open_url",
    "arguments": {
      "device_id": "你的设备ID",
      "url": "https://example.com"
    }
  }
}

返回结果

普通文字说明已打开 URL。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已打开 https://example.com"
    }
  ]
}

怎么确认成功

截图查看打开后的实际页面,网络或登录可能影响加载。

常见问题

地址在手机上打开;电脑能访问不表示手机网络也能访问。

停止应用 stop_app

结束指定应用进程,例如准备重新打开。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
package字符串是—应用包名

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "stop_app",
    {'device_id': '你的设备ID', 'package': 'com.android.settings'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "stop_app",
    "arguments": {
      "device_id": "你的设备ID",
      "package": "com.android.settings"
    }
  }
}

返回结果

普通文字,表示强制停止命令已完成回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已下发强停 com.android.settings"
    }
  ]
}

怎么确认成功

用 proc_info 或再次查看前台,确认目标进程状态。

常见问题

停止应用会中断该应用正在处理的操作。

安装手机上的 APK install_app

安装已经放到手机上的 APK 文件。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
path字符串是—设备上的 APK 路径

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "install_app",
    {'device_id': '你的设备ID', 'path': '/data/local/tmp/demo.apk'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "install_app",
    "arguments": {
      "device_id": "你的设备ID",
      "path": "/data/local/tmp/demo.apk"
    }
  }
}

返回结果

普通文字安装回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

用 list_apps 或 app_info 确认新应用。

常见问题

path 是手机路径,不是电脑路径;没有文件时先下载或传输。

卸载应用 uninstall_app

移除指定应用;示例包名需要换成你确认要卸载的测试应用。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
package字符串是—要卸载的应用包名

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "uninstall_app",
    {'device_id': '你的设备ID', 'package': 'com.example.demo'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "uninstall_app",
    "arguments": {
      "device_id": "你的设备ID",
      "package": "com.example.demo"
    }
  }
}

返回结果

普通文字卸载回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

重新查询 app_info 或应用列表。

常见问题

卸载可能删除应用数据;先确认包名,系统应用还可能受权限限制。

清空应用数据 clear_app

把应用数据恢复到初始状态,通常也会清除登录状态。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
package字符串是—应用包名

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "clear_app",
    {'device_id': '你的设备ID', 'package': 'com.example.demo'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "clear_app",
    "arguments": {
      "device_id": "你的设备ID",
      "package": "com.example.demo"
    }
  }
}

返回结果

普通文字清数据回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

重新打开应用确认初始化或登录页。

常见问题

这是清数据,不是只清缓存;不要对需要保留账号状态的应用使用。

启用或禁用应用 set_app_enabled

恢复被禁用的应用,或明确禁用某个测试应用。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
package字符串是—应用包名
enabled布尔值是—true=启用,false=禁用

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "set_app_enabled",
    {'device_id': '你的设备ID', 'package': 'com.example.demo', 'enabled': True}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_app_enabled",
    "arguments": {
      "device_id": "你的设备ID",
      "package": "com.example.demo",
      "enabled": true
    }
  }
}

返回结果

普通文字启用或禁用回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

用 list_apps 和实际启动结果核对。

常见问题

enabled=false 可能使图标消失且无法启动,恢复时使用同一包名和 true。

加入电池优化白名单 ignore_batt_opt

允许指定应用较少受到系统电池优化限制。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
pkg字符串是—应用包名

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ignore_batt_opt",
    {'device_id': '你的设备ID', 'pkg': 'com.example.demo'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ignore_batt_opt",
    "arguments": {
      "device_id": "你的设备ID",
      "pkg": "com.example.demo"
    }
  }
}

返回结果

文本中的 JSON,out 为系统命令输出。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"out\": \"系统命令输出(示意)\"}"
    }
  ]
}

怎么确认成功

到系统电池设置核对,白名单不等于所有 ROM 都保证后台常驻。

常见问题

这里参数名是 pkg;部分系统需要 shell/root 权限。

点击与滑动

点击、长按、翻页、按键、缩放和多指操作。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

点击屏幕 tap

点击屏幕中央;x 从左向右,y 从上向下,都是 0~1 的比例。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
x数字是—横向 0..1
y数字是—纵向 0..1

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "tap",
    {'device_id': '你的设备ID', 'x': 0.5, 'y': 0.5}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tap",
    "arguments": {
      "device_id": "你的设备ID",
      "x": 0.5,
      "y": 0.5
    }
  }
}

返回结果

普通文字,动作收到设备回执后返回坐标。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已点击 (0.500, 0.500)"
    }
  ]
}

怎么确认成功

随后 screenshot,检查按钮或页面是否发生预期变化。

常见问题

页面变化后旧坐标可能点到其他位置;有文本控件时优先使用 ui_tap。

长按屏幕 long_press

在指定位置按住一段时间,例如打开菜单。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
x数字是—横向 0..1
y数字是—纵向 0..1
ms数字否600时长毫秒,默认 600

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "long_press",
    {'device_id': '你的设备ID', 'x': 0.5, 'y': 0.5, 'ms': 600}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "long_press",
    "arguments": {
      "device_id": "你的设备ID",
      "x": 0.5,
      "y": 0.5,
      "ms": 600
    }
  }
}

返回结果

普通文字长按回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已长按 (0.500,0.500)"
    }
  ]
}

怎么确认成功

截图确认菜单或选择状态出现。

常见问题

ms 是毫秒,不是秒;页面必须支持长按。

滑动翻页 swipe

从屏幕下方滑向上方,查看下方内容。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
x数字是—起点横向 0..1
y数字是—起点纵向 0..1
x2数字是—终点横向 0..1
y2数字是—终点纵向 0..1
dur数字否300时长毫秒,默认 300

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "swipe",
    {'device_id': '你的设备ID',
     'x': 0.5,
     'y': 0.8,
     'x2': 0.5,
     'y2': 0.3,
     'dur': 500}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "swipe",
    "arguments": {
      "device_id": "你的设备ID",
      "x": 0.5,
      "y": 0.8,
      "x2": 0.5,
      "y2": 0.3,
      "dur": 500
    }
  }
}

返回结果

普通文字,包含滑动的起点和终点。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已滑动 (0.50,0.80)→(0.50,0.30)"
    }
  ]
}

怎么确认成功

对比滑动前后的截图或页面元素,确认内容真的滚动。

常见问题

起点和终点相同会被拒绝;不要让轨迹起于系统边缘手势区。

按下系统按键 press_key

按 Android HOME 键返回桌面;4 返回,66 回车,187 最近任务。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
key数字是—Android keycode

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "press_key",
    {'device_id': '你的设备ID', 'key': 3}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "press_key",
    "arguments": {
      "device_id": "你的设备ID",
      "key": 3
    }
  }
}

返回结果

普通文字按键回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

截图确认返回桌面;回车是否提交由当前输入框决定。

常见问题

26 是电源切换键,多次重复会反复开关屏幕;明确亮灭需求请用 set_screen。

双指放大或缩小 pinch

在图片或地图中,双指从中心向外展开;to 小于 from 时缩小。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
x数字是—中心横向 0..1
y数字是—中心纵向 0..1
from数字是—起始半径 0..1
to数字是—结束半径 0..1
ms数字否300时长毫秒,默认 300

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "pinch",
    {'device_id': '你的设备ID',
     'x': 0.5,
     'y': 0.5,
     'from': 0.08,
     'to': 0.18,
     'ms': 400}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pinch",
    "arguments": {
      "device_id": "你的设备ID",
      "x": 0.5,
      "y": 0.5,
      "from": 0.08,
      "to": 0.18,
      "ms": 400
    }
  }
}

返回结果

普通文字,包含中心点和起止半径。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

查看图片或地图缩放比例变化。

常见问题

半径按屏宽计算;横向边缘附近使用较大半径可能超出屏幕。

执行多指轨迹 gesture

把一组多指按下、移动和抬起轨迹作为一次有界动作提交。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
frames数组是—完整多指轨迹,详见下方嵌套参数;每帧是全部活动触点。
展开嵌套参数 Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "frames"
  ],
  "properties": {
    "device_id": {
      "type": "string",
      "description": "目标设备 id(使用 list_devices 返回的 id)"
    },
    "frames": {
      "type": "array",
      "minItems": 1,
      "maxItems": 2048,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "atMs",
          "contacts"
        ],
        "properties": {
          "atMs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 120000
          },
          "contacts": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "x",
                "y"
              ],
              "properties": {
                "x": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "y": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "pressure": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "touchMajor": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "touchMinor": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "widthMajor": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "widthMinor": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "orientation": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "id": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9
                }
              }
            }
          }
        }
      }
    }
  }
}

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "gesture",
    {'device_id': '你的设备ID',
     'frames': [{'atMs': 0,
                 'contacts': [{'id': 0, 'x': 0.45, 'y': 0.5},
                              {'id': 1, 'x': 0.55, 'y': 0.5}]},
                {'atMs': 300,
                 'contacts': [{'id': 0, 'x': 0.3, 'y': 0.5},
                              {'id': 1, 'x': 0.7, 'y': 0.5}]},
                {'atMs': 320, 'contacts': []}]}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "gesture",
    "arguments": {
      "device_id": "你的设备ID",
      "frames": [
        {
          "atMs": 0,
          "contacts": [
            {
              "id": 0,
              "x": 0.45,
              "y": 0.5
            },
            {
              "id": 1,
              "x": 0.55,
              "y": 0.5
            }
          ]
        },
        {
          "atMs": 300,
          "contacts": [
            {
              "id": 0,
              "x": 0.3,
              "y": 0.5
            },
            {
              "id": 1,
              "x": 0.7,
              "y": 0.5
            }
          ]
        },
        {
          "atMs": 320,
          "contacts": []
        }
      ]
    }
  }
}

返回结果

普通文字设备动作回执,不能据此直接认定业务目标完成。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "动作函数已返回,效果待验证"
    }
  ]
}

怎么确认成功

截图核对效果,必要时 input_info 确认没有残留触点。

常见问题

首帧必须 atMs=0 且有触点;1~2048 帧,时间不倒退且不超过 120000ms;每帧最多 10 个 ID 为 0~9 的触点。

  • 每帧 contacts 是全部活动触点快照,不是增量事件;最后一个空数组显式抬起全部触点。
  • x/y 及可选 pressure、touchMajor、touchMinor、widthMajor、widthMinor、orientation 均为 0~1;实际可用轴和触点数量受设备限制。
  • 当前 Schema 只将 frames 标记为必填,但处理器仍要求 device_id;此手册按实际执行要求标注。

查看输入通道与触点状态 input_info

排查当前手机是否具备 C 输入通道、可用触点数及触点占用。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "input_info",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "input_info",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

文本中的 JSON,包含 policy、cAvailable、rotation、maxContacts、activeGesture 等,驱动信息按设备提供。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"policy\": \"设备配置值\", \"cAvailable\": true, \"rotation\": 0, \"maxContacts\": 10, \"activeGesture\": false}"
    }
  ]
}

怎么确认成功

结合实际动作日志确认本次走了哪条通道。

常见问题

cAvailable=true 是能力信息,不是上一条动作一定走 C 通道的证据。

释放残留触点 input_reset

结束本次输入残留;force=true 会清除设备全部触点。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
force布尔值否falsefalse 释放本次输入;true 清除设备全部触点,不是解除任务隔离。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "input_reset",
    {'device_id': '你的设备ID', 'force': False}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "input_reset",
    "arguments": {
      "device_id": "你的设备ID",
      "force": false
    }
  }
}

返回结果

普通文字设备动作回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "动作函数已返回,效果待验证"
    }
  ]
}

怎么确认成功

用 input_info 检查触点状态,或观察手机是否恢复正常触摸。

常见问题

这不是任务解锁按钮;不释放任务控制权,也不核对未知执行结果。

文字输入

聚焦输入框后输入文字,管理输入法与剪贴板。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

输入文字 input_text

在已经聚焦的输入框中填入中文或其他文字。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
text字符串是—要输入的文本

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "input_text",
    {'device_id': '你的设备ID', 'text': '杭州天气'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "input_text",
    "arguments": {
      "device_id": "你的设备ID",
      "text": "杭州天气"
    }
  }
}

返回结果

普通文字,成功时可包含实际输入通道,如已输入(通道名称)。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

用 ui_dump 或截图核对输入框中的文字。

常见问题

先点输入框;input_text 不会替你查找输入框,也不自动按回车。

  • 整框替换语义由设备端输入实现负责;不要假定每次调用都是追加文本。

开启自动化输入法会话 ime_on

在一段输入操作开始前切到 ADBKeyBoard 并记住原输入法。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ime_on",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ime_on",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

普通文字:IME 会话已开启(ADBKeyBoard)。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "IME 会话已开启(ADBKeyBoard)"
    }
  ]
}

怎么确认成功

随后聚焦输入框并 input_text。

常见问题

需要设备安装对应输入法;结束时调用 ime_off 恢复。

恢复原输入法 ime_off

输入完成后切回 ime_on 之前记住的输入法。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ime_off",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ime_off",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

普通文字:IME 会话已结束(切回原输入法)。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "IME 会话已结束(切回原输入法)"
    }
  ]
}

怎么确认成功

手机应恢复正常键盘使用。

常见问题

异常或取消也应安排清理;会话已被占用时不能假定清理一定执行成功。

列出已安装输入法 get_ime_list

查找 set_ime 需要的输入法完整 ID。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "get_ime_list",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_ime_list",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

文本中的 JSON,imes 是设备返回的输入法 ID 列表。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"imes\": [\"com.example.keyboard/.InputService\"]}"
    }
  ]
}

怎么确认成功

从 imes 中取实际值,不手写猜测输入法服务名。

常见问题

输入法名称不等于完整 ID。

切换指定输入法 set_ime

明确切换到某个已安装输入法。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
ime_id字符串是—输入法 id,如 com.x/.InputService

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "set_ime",
    {'device_id': '你的设备ID', 'ime_id': '从get_ime_list取得的完整ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_ime",
    "arguments": {
      "device_id": "你的设备ID",
      "ime_id": "从get_ime_list取得的完整ID"
    }
  }
}

返回结果

普通文字输入法切换回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

检查手机键盘和实际输入效果。

常见问题

该示例的 ime_id 是占位符,必须替换为真实值。

读取剪贴板 get_clipboard

读取手机剪贴板内容,不是电脑剪贴板。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "get_clipboard",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_clipboard",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

文本内 JSON 的 text 字段是剪贴板文本。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"text\": \"示例文字\"}"
    }
  ]
}

怎么确认成功

读取 text,与预期内容比较。

常见问题

系统或桥限制可能拒绝读取,空文本也可能表示剪贴板本来为空。

设置剪贴板 set_clipboard

把文字写入手机剪贴板,供后续 ui_paste 使用。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
text字符串是—要写入剪贴板的文本

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "set_clipboard",
    {'device_id': '你的设备ID', 'text': '杭州天气'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_clipboard",
    "arguments": {
      "device_id": "你的设备ID",
      "text": "杭州天气"
    }
  }
}

返回结果

普通文字:剪贴板已设置。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "剪贴板已设置"
    }
  ]
}

怎么确认成功

调用 get_clipboard 核对;输入框中不会因此自动出现文字。

常见问题

写剪贴板和粘贴是两步。

粘贴到输入框 ui_paste

把手机剪贴板粘贴到当前已经聚焦的输入框。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ui_paste",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ui_paste",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

普通文字控件动作回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

读取输入框或截图确认内容。

常见问题

部分 WebView 不支持粘贴,可改用 input_text;先确认焦点和剪贴板。

页面控件

读取页面结构、按文字定位、等待页面并操作控件。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

查看可操作元素编号 observe

把当前页面可操作元素列成编号,随后按编号点按。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "observe",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "observe",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

文本中的元素数组,含 i、t、x、y、k;空列表时可能附带说明文字。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "[{\"i\": 1, \"t\": \"搜索\", \"x\": 0.5, \"y\": 0.12, \"k\": \"btn\"}]"
    }
  ]
}

怎么确认成功

选择当前屏幕目标的 i,再用 tap_element。

常见问题

页面变化后要重新 observe;带附加说明的文本不能直接 json.loads 整段。

读取完整页面控件 ui_dump

查看页面控件的文字、描述、ID、位置,选择稳定的定位条件。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ui_dump",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ui_dump",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

文本中是设备回传的控件树 JSON;具体字段以当前设备实现为准。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

找到目标文字或 desc,再用于 ui_tap、wait_for。

常见问题

纯图片页面或某些应用读不到控件,可改用截图、OCR 或找图。

按编号点击元素 tap_element

点击刚刚 observe 返回的第 1 个元素。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
i数字是—元素清单里的编号

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "tap_element",
    {'device_id': '你的设备ID', 'i': 1}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tap_element",
    "arguments": {
      "device_id": "你的设备ID",
      "i": 1
    }
  }
}

返回结果

普通文字,包含点击元素编号和文字。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

截图确认目标页面打开。

常见问题

编号不是固定控件 ID,不能把其他页面或上次运行的编号拿来用。

按编号长按元素 long_press_element

长按刚刚 observe 返回的目标元素。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
i数字是—元素清单里的编号
ms数字否600时长毫秒,默认 600

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "long_press_element",
    {'device_id': '你的设备ID', 'i': 1, 'ms': 600}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "long_press_element",
    "arguments": {
      "device_id": "你的设备ID",
      "i": 1,
      "ms": 600
    }
  }
}

返回结果

普通文字长按回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

检查菜单或选中状态。

常见问题

先重新 observe,确保编号仍对应当前页面。

按文字或控件条件点击 ui_tap

点击文字恰好为“搜索”的控件,不用自己计算坐标。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
by字符串是—选择器类型(单条件):文本 text|textContains|textStartsWith|textEndsWith|textMatches;描述 desc|descContains|descEndsWith|descMatches;i…
val字符串是—选择器的值

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ui_tap",
    {'device_id': '你的设备ID', 'by': 'text', 'val': '搜索'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ui_tap",
    "arguments": {
      "device_id": "你的设备ID",
      "by": "text",
      "val": "搜索"
    }
  }
}

返回结果

普通文字控件点击回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

检查目标页面变化。

常见问题

text 是精确匹配;需要包含匹配时用 textContains;重复文字需换更明确条件。

按控件条件长按 ui_long_click

找到指定文字控件并长按。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
by字符串是—选择器类型(单条件):文本 text|textContains|textStartsWith|textEndsWith|textMatches;描述 desc|descContains|descEndsWith|descMatches;i…
val字符串是—选择器的值

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ui_long_click",
    {'device_id': '你的设备ID', 'by': 'text', 'val': '示例项目'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ui_long_click",
    "arguments": {
      "device_id": "你的设备ID",
      "by": "text",
      "val": "示例项目"
    }
  }
}

返回结果

普通文字控件动作回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

检查是否出现菜单或选择状态。

常见问题

控件存在不代表支持长按,先确认页面。

滚动可滚动控件 ui_scroll

让页面列表向下翻,查看下方内容。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
direction字符串否"down"down=下翻(默认)/up=上翻
by字符串否—可选:限定滚动容器的选择器类型,同 ui_tap
val字符串否—可选:选择器的值

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ui_scroll",
    {'device_id': '你的设备ID', 'direction': 'down'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ui_scroll",
    "arguments": {
      "device_id": "你的设备ID",
      "direction": "down"
    }
  }
}

返回结果

普通文字滚动动作回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

比较页面内容是否改变。

常见问题

可选 by、val 用来指定容器;未指定时选择页面首个可滚动区域,嵌套列表可能选错。

等待页面控件出现 wait_for

等待页面准备好再操作,替代固定等待几秒后盲点。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
by字符串是—选择器类型(单条件):文本 text|textContains|textStartsWith|textEndsWith|textMatches;描述 desc|descContains|descEndsWith|descMatches;i…
val字符串是—选择器的值
timeout_ms数字否5000超时毫秒,默认 5000

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "wait_for",
    {'device_id': '你的设备ID',
     'by': 'textContains',
     'val': '搜索',
     'timeout_ms': 8000}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wait_for",
    "arguments": {
      "device_id": "你的设备ID",
      "by": "textContains",
      "val": "搜索",
      "timeout_ms": 8000
    }
  }
}

返回结果

文本内 JSON,found 表示是否出现,找到时含 cx、cy、text、desc、id。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"found\": true, \"cx\": 0.5, \"cy\": 0.12, \"text\": \"搜索\", \"desc\": \"\", \"id\": \"示例控件ID\"}"
    }
  ]
}

怎么确认成功

先检查 found,再决定下一步;found=false 不应继续按成功路径点按。

常见问题

客户端超时应大于 timeout_ms 加额外查询开销。

展开折叠控件 ui_expand

对支持展开动作的控件执行展开。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
by字符串是—选择器类型(单条件):文本 text|textContains|textStartsWith|textEndsWith|textMatches;描述 desc|descContains|descEndsWith|descMatches;i…
val字符串是—选择器的值

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ui_expand",
    {'device_id': '你的设备ID', 'by': 'text', 'val': '更多'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ui_expand",
    "arguments": {
      "device_id": "你的设备ID",
      "by": "text",
      "val": "更多"
    }
  }
}

返回结果

普通文字控件动作回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

检查子项或隐藏内容是否出现。

常见问题

只适用于支持 ACTION_EXPAND 的控件;普通“更多”按钮可能需要 ui_tap。

折叠控件 ui_collapse

对支持折叠动作的控件收起内容。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
by字符串是—选择器类型(单条件):文本 text|textContains|textStartsWith|textEndsWith|textMatches;描述 desc|descContains|descEndsWith|descMatches;i…
val字符串是—选择器的值

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ui_collapse",
    {'device_id': '你的设备ID', 'by': 'text', 'val': '更多'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ui_collapse",
    "arguments": {
      "device_id": "你的设备ID",
      "by": "text",
      "val": "更多"
    }
  }
}

返回结果

普通文字控件动作回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

检查展开的子项是否收起。

常见问题

控件不支持 ACTION_COLLAPSE 时会失败,不能当作任意关闭弹窗工具。

设置文字选区 ui_set_selection

选中当前输入框前两个字符,便于复制、剪切等操作。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
start数字是—选区起始字符下标
end数字是—选区结束字符下标
by字符串否—可选:选择器类型,同 ui_tap(留空=焦点框)
val字符串否—可选:选择器的值

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ui_set_selection",
    {'device_id': '你的设备ID', 'start': 0, 'end': 2}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ui_set_selection",
    "arguments": {
      "device_id": "你的设备ID",
      "start": 0,
      "end": 2
    }
  }
}

返回结果

普通文字:已下发设选区。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "已下发设选区"
    }
  ]
}

怎么确认成功

继续 get_clipboard 或截图核对后续复制结果。

常见问题

start/end 是字符下标;可选 by/val 指定输入框,留空作用于当前焦点。

复制输入框选区 ui_copy

把当前输入框已选中的文本复制到手机剪贴板。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ui_copy",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ui_copy",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

普通文字复制动作回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

调用 get_clipboard 读取结果。

常见问题

先用 ui_set_selection 选中内容;没有选区时可能没有可复制文字。

剪切输入框选区 ui_cut

剪切当前输入框选中的文字并放入剪贴板。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ui_cut",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ui_cut",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

普通文字剪切动作回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

核对输入框文字被移除、剪贴板包含选中文字。

常见问题

会修改输入框内容;先确认选区正确。

截图

获取整屏或局部图片,并保存到电脑。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

截取手机屏幕 screenshot

获取当前手机画面,检查页面和操作结果。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "screenshot",
    {'device_id': '你的设备ID'}
)

import base64
from pathlib import Path
image = next(item for item in result["content"] if item.get("type") == "image")
if image["mimeType"] != "image/jpeg":
    raise RuntimeError("请按实际 MIME 类型选择文件后缀")
Path("screen.jpg").write_bytes(base64.b64decode(image["data"], validate=True))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "screenshot",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

content 中包含 type=image、mimeType=image/jpeg 和 Base64 data;同时可能有文字说明。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "截图说明(示意)"
    },
    {
      "type": "image",
      "mimeType": "image/jpeg",
      "data": "图片Base64(非真实数据)"
    }
  ]
}

怎么确认成功

解码 image.data 保存为 JPEG,或交给支持图片的客户端展示。

常见问题

不要把整个 result 或 text 当成 Base64。

截取屏幕局部 screenshot_region

只截取屏幕上方中间区域,例如聚焦表单或弹窗。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
x1数字是—左上 x,0..1
y1数字是—左上 y,0..1
x2数字是—右下 x,0..1
y2数字是—右下 y,0..1

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "screenshot_region",
    {'device_id': '你的设备ID', 'x1': 0.1, 'y1': 0.1, 'x2': 0.9, 'y2': 0.5}
)

import base64
from pathlib import Path
image = next(item for item in result["content"] if item.get("type") == "image")
if image["mimeType"] != "image/jpeg":
    raise RuntimeError("请按实际 MIME 类型选择文件后缀")
Path("screen.jpg").write_bytes(base64.b64decode(image["data"], validate=True))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "screenshot_region",
    "arguments": {
      "device_id": "你的设备ID",
      "x1": 0.1,
      "y1": 0.1,
      "x2": 0.9,
      "y2": 0.5
    }
  }
}

返回结果

与 screenshot 一样返回 JPEG 图片内容块。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "截图说明(示意)"
    },
    {
      "type": "image",
      "mimeType": "image/jpeg",
      "data": "图片Base64(非真实数据)"
    }
  ]
}

怎么确认成功

检查截图是否只包含指定区域。

常见问题

左上角必须小于右下角,坐标都是 0~1,不是像素。

图像与文字识别

通过文字、图片、颜色或视觉模型寻找目标。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

读取屏幕文字 ocr

识别截图中的文字,不要求应用提供可访问的控件树。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "ocr",
    {'device_id': '你的设备ID'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ocr",
    "arguments": {
      "device_id": "你的设备ID"
    }
  }
}

返回结果

文本内文字块数组,含 text、score、cx、cy、x、y、w、h。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "[{\"text\": \"搜索\", \"score\": 0.98, \"cx\": 0.5, \"cy\": 0.12, \"x\": 0.4, \"y\": 0.1, \"w\": 0.2, \"h\": 0.04}]"
    }
  ]
}

怎么确认成功

根据文字和置信度筛选目标,cx/cy 可用于点击。

常见问题

OCR 会受字号、遮挡和图片清晰度影响,读到文字不代表业务完成。

查找屏幕上的文字 find_text

只定位屏幕上的“搜索”;确认目标后可显式改 tap=true 点击。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
val字符串是—要找的文字
tap布尔值否true命中是否点击,默认 true

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "find_text",
    {'device_id': '你的设备ID', 'val': '搜索', 'tap': False}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_text",
    "arguments": {
      "device_id": "你的设备ID",
      "val": "搜索",
      "tap": false
    }
  }
}

返回结果

找到时文本内 JSON 含 found、cx、cy、text;未找到可能作为工具错误返回。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"found\": true, \"cx\": 0.5, \"cy\": 0.12, \"text\": \"搜索\"}"
    }
  ]
}

怎么确认成功

先看 isError,再看 found,不要假定所有未找到都以成功返回 false。

常见问题

默认 tap=true,单纯查询务必显式传 false。

按模板图片找图 find_image

在指定屏幕区域定位图标,例如没有文字的按钮。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
template字符串是—模板图片 base64(PNG/JPEG/GIF 都可)
thresh数字否0.7置信阈值 0..1,默认 0.7
tap布尔值否false命中是否点击,默认 false
x1数字否—区域左边界 0..1
y1数字否—区域上边界 0..1
x2数字否—区域右边界 0..1
y2数字否—区域下边界 0..1

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "find_image",
    {'device_id': '你的设备ID',
     'template': '替换为模板图片Base64',
     'thresh': 0.8,
     'tap': False,
     'x1': 0.1,
     'y1': 0.1,
     'x2': 0.9,
     'y2': 0.5}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_image",
    "arguments": {
      "device_id": "你的设备ID",
      "template": "替换为模板图片Base64",
      "thresh": 0.8,
      "tap": false,
      "x1": 0.1,
      "y1": 0.1,
      "x2": 0.9,
      "y2": 0.5
    }
  }
}

返回结果

文本内 JSON 含 found、cx、cy、score。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"found\": true, \"cx\": 0.5, \"cy\": 0.2, \"score\": 0.91}"
    }
  ]
}

怎么确认成功

检查 found 和 score,再决定是否点击。

常见问题

Base64 是模板图片内容,不是文件路径;模板应裁到目标本体。

查找某种颜色 find_color

在当前画面中寻找符合条件的颜色位置。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
color字符串是—颜色串,如 FF0000 或 FF0000-101010
sim数字否0.9相似度 0.1..1,默认 0.9
tap布尔值否false命中是否点击,默认 false
dir数字否0查找方向 0-3
x1数字否—区域左上 x 归一化 0..1(默认 0=全屏)
x2数字否—区域右下 x 0..1(0=到边)
y1数字否—区域左上 y 0..1
y2数字否—区域右下 y 0..1(0=到边)

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "find_color",
    {'device_id': '你的设备ID', 'color': 'FF0000', 'sim': 0.9, 'tap': False}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_color",
    "arguments": {
      "device_id": "你的设备ID",
      "color": "FF0000",
      "sim": 0.9,
      "tap": false
    }
  }
}

返回结果

文本内 JSON 含 found、cx、cy。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"found\": true, \"cx\": 0.5, \"cy\": 0.5}"
    }
  ]
}

怎么确认成功

结合截图核对找到的位置是否属于目标元素。

常见问题

相同颜色可能出现很多处,使用 x1/y1/x2/y2 缩小范围。

按相对多点颜色找图案 find_multi_colors

寻找一个红色锚点及其右侧相对位置的绿色点,用于简单颜色图案定位。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
color字符串是—锚色,dx,dy,色,…
sim数字否0.9颜色相似度,通常 0.1~1。
tap布尔值否false是否命中后点击。查找文字和 watch 默认可能为 true,纯查询请明确传 false。
dir数字否0找色搜索方向,0~3。
x1数字否—区域左上 x 归一化 0..1(默认 0=全屏)
x2数字否—区域右下 x 0..1(0=到边)
y1数字否—区域左上 y 0..1
y2数字否—区域右下 y 0..1(0=到边)

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "find_multi_colors",
    {'device_id': '你的设备ID',
     'color': 'FF0000,10,0,00FF00',
     'sim': 0.9,
     'tap': False}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_multi_colors",
    "arguments": {
      "device_id": "你的设备ID",
      "color": "FF0000,10,0,00FF00",
      "sim": 0.9,
      "tap": false
    }
  }
}

返回结果

文本内 JSON 含 found、cx、cy。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"found\": true, \"cx\": 0.5, \"cy\": 0.5}"
    }
  ]
}

怎么确认成功

检查锚点实际落在预期图案上。

常见问题

字符串中的 dx/dy 是相对像素偏移,不是屏幕比例;页面缩放可能使图案条件失效。

判断指定点颜色 cmp_color

判断屏幕中央是否接近目标颜色。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
x数字是—横向 0..1
y数字是—纵向 0..1
color字符串是—颜色串
sim数字否0.9相似度,默认 0.9

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "cmp_color",
    {'device_id': '你的设备ID', 'x': 0.5, 'y': 0.5, 'color': 'FF0000', 'sim': 0.9}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "cmp_color",
    "arguments": {
      "device_id": "你的设备ID",
      "x": 0.5,
      "y": 0.5,
      "color": "FF0000",
      "sim": 0.9
    }
  }
}

返回结果

文本内 JSON 的 match 为布尔值。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"match\": true}"
    }
  ]
}

怎么确认成功

根据 match 分支处理,必要时再截图。

常见问题

坐标必须明确传入;颜色相似不证明这是目标页面。

读取指定点像素颜色 pixel

查询某个位置的实际颜色,用于辅助配置找色。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
x数字是—横向 0..1
y数字是—纵向 0..1

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "pixel",
    {'device_id': '你的设备ID', 'x': 0.5, 'y': 0.5}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pixel",
    "arguments": {
      "device_id": "你的设备ID",
      "x": 0.5,
      "y": 0.5
    }
  }
}

返回结果

文本内 JSON 包含 color、x、y;返回 x/y 是实际截图像素坐标。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"color\": \"FF0000\", \"x\": 540, \"y\": 1200}"
    }
  ]
}

怎么确认成功

读取 color 字符串;不要把返回的像素 x/y 原样当 tap 的比例坐标。

常见问题

传入 x/y 是比例,返回 x/y 是像素,单位不同。

统计区域颜色像素 color_count

统计区域内匹配颜色的像素,用于观察进度条等。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
color字符串是—颜色串
sim数字否0.9相似度,默认 0.9
x1数字否—区域左上 x 归一化 0..1(默认 0=全屏)
y1数字否—区域左上 y 0..1
x2数字否—区域右下 x 0..1(0=到边)
y2数字否—区域右下 y 0..1(0=到边)

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "color_count",
    {'device_id': '你的设备ID',
     'color': 'FF0000',
     'sim': 0.9,
     'x1': 0.1,
     'y1': 0.1,
     'x2': 0.9,
     'y2': 0.5}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "color_count",
    "arguments": {
      "device_id": "你的设备ID",
      "color": "FF0000",
      "sim": 0.9,
      "x1": 0.1,
      "y1": 0.1,
      "x2": 0.9,
      "y2": 0.5
    }
  }
}

返回结果

文本内 JSON 的 count 是命中像素数。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"count\": 120}"
    }
  ]
}

怎么确认成功

比较同一区域前后 count 的变化。

常见问题

count 是像素数量,不是百分比或目标控件数量。

识别画面中的物体 yolo

使用设备端目标检测模型查找可识别物体。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
thresh数字否0.25置信阈值,默认 0.25

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "yolo",
    {'device_id': '你的设备ID', 'thresh': 0.25}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "yolo",
    "arguments": {
      "device_id": "你的设备ID",
      "thresh": 0.25
    }
  }
}

返回结果

文本内检测框数组,含 label、score 和归一化位置。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

筛选模型实际支持的类别并检查置信度。

常见问题

默认模型不是任意应用控件检测模型,不能保证识别某个 App 图标。

按描述视觉定位 tap_by_vision

控件树和固定识别都不方便时,由已配置的视觉模型定位目标。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
target字符串是—要点击的目标描述,如:右上角的搜索图标 / 底部的“我的”标签
tap布尔值否true命中后是否点击,默认 true;false 则只返回坐标不点

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "tap_by_vision",
    {'device_id': '你的设备ID', 'target': '屏幕顶部的搜索按钮', 'tap': False}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tap_by_vision",
    "arguments": {
      "device_id": "你的设备ID",
      "target": "屏幕顶部的搜索按钮",
      "tap": false
    }
  }
}

返回结果

普通文字:可能已定位、已定位并点击,或未找到;不是固定坐标 JSON。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

先以 tap=false 检查定位描述,确需点击时才设 true 并截图核对。

常见问题

会调用当前身份配置的视觉模型,产生模型请求;描述要具体。

等待图标出现 watch

让手机自己循环找图,避免客户端反复传截图。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
templates字符串是—模板数组 JSON,如 [{"sha1":"","b64":"iVBOR..."},{"sha1":"a1b2..."}]
tap布尔值否true命中是否点击,默认 true
every_ms数字否200每轮间隔毫秒,默认 200
timeout_ms数字否300000最长盯多久毫秒,默认 300000(5 分钟),上限 600000
max_hits数字否1命中几次后返回,默认 1
cooldown_ms数字否3000命中后冷却毫秒,默认 3000
report_every_ms数字否0进度心跳间隔毫秒,0=不回,默认 0
thresh数字否0.68置信阈值 0..1,默认 0.68
x1数字否—区域左边界 0..1
x2数字否—区域右边界 0..1
y1数字否—区域上边界 0..1
y2数字否—区域下边界 0..1

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "watch",
    {'device_id': '你的设备ID',
     'templates': '[{"sha1": "", "b64": "替换为模板图片Base64"}]',
     'tap': False,
     'every_ms': 300,
     'timeout_ms': 10000,
     'max_hits': 1}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "watch",
    "arguments": {
      "device_id": "你的设备ID",
      "templates": "[{\"sha1\": \"\", \"b64\": \"替换为模板图片Base64\"}]",
      "tap": false,
      "every_ms": 300,
      "timeout_ms": 10000,
      "max_hits": 1
    }
  }
}

返回结果

文本内 JSON 含 hit、坐标、匹配得分和尝试次数;超时未命中通常是正常 hit=false。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"hit\": false, \"tries\": 20, \"best\": 0.4}"
    }
  ]
}

怎么确认成功

先检查 hit;tap=false 只观察,tap=true 命中后会点击。

常见问题

templates 必须是包含对象数组的 JSON 字符串;默认 tap=true;客户端超时要覆盖设备等待时长。

  • 工具属于 URL 的 device 组;本手册把它放在“识别”分类仅为方便查找。
  • 最长设备等待 600000ms;MCP 等待还包含缓冲,不要用默认短 HTTP 超时。

文件与媒体

读写手机文件、下载媒体、加入相册或打开文件。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

读取手机文本文件 read_file

读取手机上的 UTF-8 等文本文件,不能用来读取图片二进制。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
path字符串是—设备上的绝对路径

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "read_file",
    {'device_id': '你的设备ID', 'path': '/sdcard/Download/mcp-demo.txt'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "device_id": "你的设备ID",
      "path": "/sdcard/Download/mcp-demo.txt"
    }
  }
}

返回结果

文本内 JSON 含 path、content、size;size 为内容字节数。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"path\": \"/sdcard/Download/mcp-demo.txt\", \"content\": \"示例文字\", \"size\": 12}"
    }
  ]
}

怎么确认成功

从 content 取文本。

常见问题

路径在手机上且执行身份必须有权限,不是电脑文件路径。

写入手机文本文件 write_file

将文本保存到手机文件;已有文件内容会被覆盖。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
path字符串是—设备上的绝对路径
content字符串是—要写入的文本

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "write_file",
    {'device_id': '你的设备ID',
     'path': '/sdcard/Download/mcp-demo.txt',
     'content': '示例文字\n'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "write_file",
    "arguments": {
      "device_id": "你的设备ID",
      "path": "/sdcard/Download/mcp-demo.txt",
      "content": "示例文字\n"
    }
  }
}

返回结果

普通文字写入回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

用 read_file 读回并比较内容。

常见问题

会覆盖原内容;先用专用测试文件,不要填系统或应用私有配置路径。

追加手机文本文件 append_file

把文字追加到已有文件末尾。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
path字符串是—设备上的绝对路径
content字符串是—要追加的文本

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "append_file",
    {'device_id': '你的设备ID',
     'path': '/sdcard/Download/mcp-demo.txt',
     'content': '追加一行\n'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "append_file",
    "arguments": {
      "device_id": "你的设备ID",
      "path": "/sdcard/Download/mcp-demo.txt",
      "content": "追加一行\n"
    }
  }
}

返回结果

普通文字追加回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

read_file 查看末尾新增内容。

常见问题

换行要自行写入 content;重发可能追加两次。

列出手机目录 list_dir

查看某个手机目录下有哪些文件和子目录。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
path字符串是—设备上的绝对路径

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "list_dir",
    {'device_id': '你的设备ID', 'path': '/sdcard/Download'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_dir",
    "arguments": {
      "device_id": "你的设备ID",
      "path": "/sdcard/Download"
    }
  }
}

返回结果

文本内 JSON 含 path、entries。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"path\": \"/sdcard/Download\", \"entries\": []}"
    }
  ]
}

怎么确认成功

根据 entries 中的实际名称拼接路径。

常见问题

目录无权限或不存在会失败,不是空列表的同义词。

查看文件是否存在 file_info

查询存在性、文件类型及可用的摘要。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
path字符串是—设备上的绝对路径

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "file_info",
    {'device_id': '你的设备ID', 'path': '/sdcard/Download/mcp-demo.txt'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_info",
    "arguments": {
      "device_id": "你的设备ID",
      "path": "/sdcard/Download/mcp-demo.txt"
    }
  }
}

返回结果

文本内 JSON 含 exists;不存在仍可正常返回 exists=false,其他字段随存在性变化。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"path\": \"/sdcard/Download/mcp-demo.txt\", \"exists\": false}"
    }
  ]
}

怎么确认成功

先检查 exists,再使用 name、isFile、isDir、md5。

常见问题

不存在不是接口异常;md5 未取得时也可能为空。

复制手机文件 copy_file

把手机文件复制到手机上的另一路径。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
from字符串是—源路径
to字符串是—目标路径

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "copy_file",
    {'device_id': '你的设备ID',
     'from': '/sdcard/Download/mcp-demo.txt',
     'to': '/sdcard/Download/mcp-copy.txt'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "copy_file",
    "arguments": {
      "device_id": "你的设备ID",
      "from": "/sdcard/Download/mcp-demo.txt",
      "to": "/sdcard/Download/mcp-copy.txt"
    }
  }
}

返回结果

普通文字复制回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

检查源、目标 file_info 或 read_file 内容。

常见问题

from/to 都是手机路径;目标已存在时可能被覆盖。

移动手机文件 move_file

移动或重命名手机文件。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
from字符串是—源路径
to字符串是—目标路径

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "move_file",
    {'device_id': '你的设备ID',
     'from': '/sdcard/Download/mcp-demo.txt',
     'to': '/sdcard/Download/mcp-moved.txt'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "move_file",
    "arguments": {
      "device_id": "你的设备ID",
      "from": "/sdcard/Download/mcp-demo.txt",
      "to": "/sdcard/Download/mcp-moved.txt"
    }
  }
}

返回结果

普通文字移动回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

确认旧路径不存在、新路径存在。

常见问题

移动成功后不能继续用旧路径读取,跨目录还可能有权限限制。

删除手机文件 delete_file

删除明确指定的测试文件或目录。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
path字符串是—设备上的绝对路径

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "delete_file",
    {'device_id': '你的设备ID', 'path': '/sdcard/Download/mcp-demo.txt'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_file",
    "arguments": {
      "device_id": "你的设备ID",
      "path": "/sdcard/Download/mcp-demo.txt"
    }
  }
}

返回结果

普通文字删除回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

file_info 检查 exists=false。

常见问题

执行后不能靠再次调用撤销;确认完整路径,不拿目录根路径试用。

下载图片或视频到手机 download_file

让手机直接下载媒体文件,并可加入相册。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
url字符串是—要下载的 URL
path字符串是—设备上的保存路径,如 /sdcard/Pictures/a.jpg
scan布尔值否false下载后是否加入媒体库(图片/视频建议 true)
timeout_sec数字否30超时秒,默认 30

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "download_file",
    {'device_id': '你的设备ID',
     'url': 'https://example.com/demo.jpg',
     'path': '/sdcard/Pictures/mcp-demo.jpg',
     'scan': True,
     'timeout_sec': 30}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "download_file",
    "arguments": {
      "device_id": "你的设备ID",
      "url": "https://example.com/demo.jpg",
      "path": "/sdcard/Pictures/mcp-demo.jpg",
      "scan": true,
      "timeout_sec": 30
    }
  }
}

返回结果

文本内 JSON 含 code、size、path,媒体扫描成功时还可能有 scan。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"code\": 200, \"size\": 1024, \"path\": \"/sdcard/Pictures/mcp-demo.jpg\"}"
    }
  ]
}

怎么确认成功

检查 code、size,再用 file_info 确认文件;需要相册可见时还需确认扫描结果。

常见问题

示例 URL 必须换成真实可下载地址;下载成功不保证媒体扫描成功。

  • 设备下载超时默认 30 秒,但本接口服务端等待目前为 60 秒;不要只提高 timeout_sec 就以为整体可无限等待。

把文件加入手机相册 scan_media

文件已在手机上,但相册暂时看不到时,通知媒体库扫描。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
path字符串是—媒体文件绝对路径

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "scan_media",
    {'device_id': '你的设备ID', 'path': '/sdcard/Pictures/mcp-demo.jpg'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scan_media",
    "arguments": {
      "device_id": "你的设备ID",
      "path": "/sdcard/Pictures/mcp-demo.jpg"
    }
  }
}

返回结果

文本内 JSON 的 out 是系统扫描输出。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"out\": \"系统扫描输出(示意)\"}"
    }
  ]
}

怎么确认成功

在相册查看该文件;应用可能还需要刷新自己的相册缓存。

常见问题

只建立媒体库可见性,不负责下载,也不保证所有应用立刻刷新。

用手机应用打开文件 view_file

用手机默认查看器打开某个已存在的文件。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
path字符串是—设备上的文件绝对路径
mime字符串否—可选 MIME 类型,如 image/png、application/pdf

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "view_file",
    {'device_id': '你的设备ID',
     'path': '/sdcard/Pictures/mcp-demo.jpg',
     'mime': 'image/jpeg'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "view_file",
    "arguments": {
      "device_id": "你的设备ID",
      "path": "/sdcard/Pictures/mcp-demo.jpg",
      "mime": "image/jpeg"
    }
  }
}

返回结果

普通文字文件打开回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

截图确认查看器实际打开了目标文件。

常见问题

路径必须存在且手机有能处理 MIME 类型的应用。

手机网络请求

通过手机自身网络请求文本接口。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

由手机发起 GET 请求 http_get

从手机网络访问一个文本接口,不是由服务器发请求。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
url字符串是—URL
timeout_sec数字否15超时秒,默认 15

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "http_get",
    {'device_id': '你的设备ID', 'url': 'https://example.com', 'timeout_sec': 15}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "http_get",
    "arguments": {
      "device_id": "你的设备ID",
      "url": "https://example.com",
      "timeout_sec": 15
    }
  }
}

返回结果

文本内 JSON 含 code、body、len;HTTP 4xx/5xx 也可能作为正常网络返回。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"code\": 200, \"body\": \"ok\", \"len\": 2}"
    }
  ]
}

怎么确认成功

先检查 code,再按第三方接口约定解析 body。

常见问题

不要用它下载图片或视频;timeout_sec 仅是设备请求时限,服务端默认查询等待可能更短。

由手机发起 POST 请求 http_post

让手机给你有权限的接口发送文本请求。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
url字符串是—URL
body字符串否—请求体(默认表单类型)
timeout_sec数字否15超时秒,默认 15

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "http_post",
    {'device_id': '你的设备ID',
     'url': 'https://example.com/your-api',
     'body': 'message=hello',
     'timeout_sec': 15}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "http_post",
    "arguments": {
      "device_id": "你的设备ID",
      "url": "https://example.com/your-api",
      "body": "message=hello",
      "timeout_sec": 15
    }
  }
}

返回结果

文本内 JSON 含 code、body、len;不能仅凭 MCP 成功认定第三方业务成功。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"code\": 200, \"body\": \"ok\", \"len\": 2}"
    }
  ]
}

怎么确认成功

同时检查 HTTP code 和第三方响应业务状态。

常见问题

当前工具未提供自定义请求头参数,不能假定 body 是 JSON 就自动使用 JSON Content-Type。

手机本地存储

在当前手机保存、读取和清理少量字符串数据。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

保存手机上的键值 kv_put

在手机本地保存一个字符串值。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
table字符串是—表名(命名空间)
key字符串是—键
value字符串是—值

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "kv_put",
    {'device_id': '你的设备ID',
     'table': 'mcp-demo',
     'key': 'progress',
     'value': 'done'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "kv_put",
    "arguments": {
      "device_id": "你的设备ID",
      "table": "mcp-demo",
      "key": "progress",
      "value": "done"
    }
  }
}

返回结果

普通文字保存回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

kv_get 读回并核对。

常见问题

重复使用同一表和键会覆盖旧值;对象需自行 JSON 编码成字符串。

读取手机上的键值 kv_get

读取同一台手机本地保存的小型进度或配置。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
table字符串是—表名(命名空间)
key字符串是—键

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "kv_get",
    {'device_id': '你的设备ID', 'table': 'mcp-demo', 'key': 'progress'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "kv_get",
    "arguments": {
      "device_id": "你的设备ID",
      "table": "mcp-demo",
      "key": "progress"
    }
  }
}

返回结果

文本内 JSON 含 table、key、value;不存在通常为空值。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"table\": \"mcp-demo\", \"key\": \"progress\", \"value\": \"done\"}"
    }
  ]
}

怎么确认成功

读取 value,按自己保存的格式解析。

常见问题

存储在手机上,不是服务器数据库;不同手机不共享。

列出手机上的整张键值表 kv_list

查看某张手机本地表的全部键值。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
table字符串是—表名(命名空间)

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "kv_list",
    {'device_id': '你的设备ID', 'table': 'mcp-demo'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "kv_list",
    "arguments": {
      "device_id": "你的设备ID",
      "table": "mcp-demo"
    }
  }
}

返回结果

文本内 JSON 含 table、all。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"table\": \"mcp-demo\", \"all\": {\"progress\": \"done\"}}"
    }
  ]
}

怎么确认成功

从 all 中查找对应键。

常见问题

不要把私人令牌等敏感内容通过调试输出公开。

删除手机上的一个键 kv_delete

移除指定本地存储键。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
table字符串是—表名(命名空间)
key字符串是—键

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "kv_delete",
    {'device_id': '你的设备ID', 'table': 'mcp-demo', 'key': 'progress'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "kv_delete",
    "arguments": {
      "device_id": "你的设备ID",
      "table": "mcp-demo",
      "key": "progress"
    }
  }
}

返回结果

普通文字删除回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

kv_get 或 kv_list 检查该键不再有值。

常见问题

仅影响该手机指定表中的键,不删除服务器任务记录。

清空手机上的键值表 kv_clear

删除指定表里的所有本地键值。

参数

参数类型必填默认说明
device_id字符串是—目标手机 ID,从 list_devices 取得,不是型号或账号。
table字符串是—表名(命名空间)

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "kv_clear",
    {'device_id': '你的设备ID', 'table': 'mcp-demo'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "kv_clear",
    "arguments": {
      "device_id": "你的设备ID",
      "table": "mcp-demo"
    }
  }
}

返回结果

普通文字清空回执。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

kv_list 检查 all 为空。

常见问题

会删除整张表中的数据,不是只删一个键。

扩展工具调用

发现已注册能力、执行能力并查询持久状态。 可切换 Python / JavaScript(Node.js),客户端代码见“开始使用”。请先替换设备、文件或接口占位符。

查看可调用的扩展能力 list_capabilities

查看当前账号能使用的内部函数、已配置 HTTP API 或外部 MCP 能力。

参数

无参数。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "list_capabilities",
    {}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_capabilities",
    "arguments": {}
  }
}

返回结果

文本中的能力定义 JSON,包含名称、目标约束和输入规则;具体清单随配置变化。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "这里是设备返回的成功说明,具体文字以实际回执为准"
    }
  ]
}

怎么确认成功

读取实际 capability、targetKind、targetID 及输入 Schema,再调用 invoke_tool。

常见问题

没有配置不代表接口坏了;不能照搬别人租户的能力名称和目标。

调用已注册能力 invoke_tool

把已发现的能力交给统一操作入口;这个示例会点击设备中央。

参数

参数类型必填默认说明
capability字符串是—已注册能力名称,先用 list_capabilities 查询。
target_kind字符串是—能力定义要求的目标种类,例如 device;不能自行猜测。
target_id字符串是—具体目标 ID;设备能力使用设备 ID,其他目标按能力定义。
input对象否—能力输入对象,字段按 list_capabilities 返回的输入 Schema 填写。
idempotency_key字符串否—同一业务提交重试复用的键,最长 96 字符;改变参数不要复用。
展开嵌套参数 Schema
{
  "type": "object",
  "properties": {
    "capability": {
      "type": "string",
      "description": ""
    },
    "target_id": {
      "type": "string",
      "description": ""
    },
    "target_kind": {
      "type": "string",
      "description": ""
    },
    "idempotency_key": {
      "type": "string",
      "description": ""
    },
    "input": {
      "type": "object",
      "description": ""
    }
  },
  "required": [
    "capability",
    "target_id",
    "target_kind"
  ]
}

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "invoke_tool",
    {'capability': 'device.tap',
     'target_kind': 'device',
     'target_id': '你的设备ID',
     'input': {'x': 0.5, 'y': 0.5},
     'idempotency_key': '你的业务任务ID:step-01'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "invoke_tool",
    "arguments": {
      "capability": "device.tap",
      "target_kind": "device",
      "target_id": "你的设备ID",
      "input": {
        "x": 0.5,
        "y": 0.5
      },
      "idempotency_key": "你的业务任务ID:step-01"
    }
  }
}

返回结果

文本内 JSON 含 operation、output、replayed;保存 operation.id,检查 operation.state。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"operation\": {\"id\": \"操作ID\", \"capability\": \"device.tap\", \"state\": \"succeeded\"}, \"replayed\": false}"
    }
  ]
}

怎么确认成功

用 get_operation 查询持久状态,业务效果另按能力核验。

常见问题

先确认 list_capabilities 中存在此能力;同一次业务重试沿用原幂等键和参数,未知结果不创建新操作。

  • device.tap 仅作为当前代码中一个具体能力示例,不表示所有租户都具有授权。
  • JSON-RPC id 是请求关联标识,不能填作 operation_id。

查询一次能力调用的状态 get_operation

查询通用能力调用的持久记录,不重复执行业务。

参数

参数类型必填默认说明
operation_id字符串是—invoke_tool 返回 JSON 中的 operation.id,不是 JSON-RPC id。

调用示例

from mcp_client import MCPClient

client = MCPClient.from_env()
client.initialize()
result = client.call(
    "get_operation",
    {'operation_id': '从invoke_tool返回中取得的operation.id'}
)
print(client.text(result))
展开完整 MCP 请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_operation",
    "arguments": {
      "operation_id": "从invoke_tool返回中取得的operation.id"
    }
  }
}

返回结果

文本内 JSON 是操作记录,包含 id、state 等;不是完整 invoke_tool 的 output。

以下仅为 result 的格式示例,可能只列部分字段,不是真机执行记录。

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\": \"操作ID\", \"capability\": \"device.tap\", \"state\": \"succeeded\", \"version\": 1}"
    }
  ]
}

怎么确认成功

按 queued、running、succeeded、failed、unknown 分支处理。

常见问题

直接 tap 等工具不承诺返回持久 operation.id;不能把 JSON-RPC id 当操作 ID。