操作手册
核对日期:2026-11-09。适用代码:v2,核对基线 14c3bed。
想让自己的程序打开手机应用、点击按钮、输入文字或获取截图,可以通过这里的 MCP 接口完成。先准备有效 Token 和在线手机,再按功能查找调用方式。
第一次使用,从这里开始
- 打开 开始使用,设置 Token 和服务地址。
- 运行“查看在线手机”,找到目标手机的设备 ID。
- 运行“截图”,把手机画面保存到电脑。
- 确认连接和截图正常,再尝试点击、滑动等动作。
第一个示例只查看设备,不会操作手机。后面的写操作示例会改变手机状态,执行前请确认目标设备和页面。
按你想做的事查找
| 我想做什么 | 查看哪一页 | 常用工具 |
| 查看手机、电量、亮度,点亮屏幕 | 设备与状态 | 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。
电脑需要 Node.js 20 或更新版本,使用内置 fetch,不需要 npm install。
新建一个文件夹,例如 mcp-demo,将本页末尾 JavaScript 标签中的完整代码保存为 mcp_client.mjs。仓库中的同一份示例位于 v2/docs/contracts/mcp/examples/mcp_client.mjs。
后面的示例保存为 .mjs 文件,用 node 执行。它们是电脑或服务端运行的外部 MCP 客户端,不是浏览器直接运行的脚本,也不是平台内置工作流。
导入客户端文件不会连接服务。把后面的示例文件和客户端放在同一个文件夹,再在该文件夹打开终端。
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
新建 list_devices.mjs:
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const devices = client.textJSON(await client.call("list_devices"));
for (const device of devices) {
console.log(device.id, device.name ?? "", device.model ?? "");
}
运行:
node list_devices.mjs
程序会列出设备 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
新建 screenshot.mjs:
import { writeFile } from "node:fs/promises";
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const deviceId = "你的设备ID";
const result = await client.call("screenshot", { device_id: deviceId });
const image = result.content.find(item => item.type === "image");
if (!image || image.mimeType !== "image/jpeg") {
throw new Error("截图格式变化,请按 mimeType 选择文件后缀");
}
await writeFile("screen.jpg", Buffer.from(image.data, "base64"));
console.log("截图已保存为 screen.jpg");
node screenshot.mjs
打开同一文件夹里的 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
保存为 home.mjs:
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("press_key", {
device_id: "你的设备ID",
key: 3,
});
console.log(client.text(result));
node home.mjs
执行后再截图,确认手机回到桌面。接下来查阅 点击与滑动、文字输入 或 页面控件。
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_client.mjs:
// 外部 MCP 文档示例客户端,适用于 Node.js 20+。
// 导入此文件不会连接服务或操作设备;所有副作用都由调用方显式发起。
const resultText = result => (result.content ?? [])
.filter(item => item.type === 'text')
.map(item => item.text ?? '')
.join('\n');
export class ToolError extends Error {
constructor(result) {
super(resultText(result) || 'MCP 工具调用失败');
this.name = 'ToolError';
// 保留原始结果,调用方可读取失败操作的 operation.id 后核对。
this.result = result;
}
}
export class MCPClient {
constructor(url, token, { timeoutMs = 200_000 } = {}) {
if (!token) throw new Error('请设置 AGOV_TOKEN');
this.url = url;
this.token = token;
this.timeoutMs = timeoutMs;
this.protocol = null;
this.sequence = 0;
}
static fromEnv() {
return new MCPClient(
process.env.AGOV_MCP_URL || 'https://frpc.api-y.cn/mcp',
process.env.AGOV_TOKEN,
);
}
async rpc(method, params, { notification = false, timeoutMs = this.timeoutMs } = {}) {
const id = notification ? undefined : ++this.sequence;
const body = { jsonrpc: '2.0', method };
if (!notification) body.id = id;
if (params !== undefined) body.params = params;
const headers = {
Authorization: `Bearer ${this.token}`,
'Content-Type': 'application/json',
Accept: 'application/json, text/event-stream',
};
if (this.protocol) headers['MCP-Protocol-Version'] = this.protocol;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const response = await fetch(this.url, {
method: 'POST', headers, body: JSON.stringify(body), signal: controller.signal,
});
if (!response.ok) {
await response.body?.cancel();
throw new Error(`MCP HTTP ${response.status},请检查认证或服务状态`);
}
if (notification) {
await response.body?.cancel();
return null;
}
const contentType = response.headers.get('content-type') ?? '';
const message = contentType.toLowerCase().includes('text/event-stream')
? await this.readSSE(response, id)
: await response.json();
if (message.id !== id) throw new Error('MCP 响应 id 不匹配');
if (message.error) throw new Error(`MCP 协议错误:${JSON.stringify(message.error)}`);
return message.result;
} catch (error) {
if (controller.signal.aborted) {
throw new Error('MCP 请求超时;写操作可能已执行,请先核对,不要直接重发');
}
throw error;
} finally {
clearTimeout(timer);
}
}
async readSSE(response, id) {
if (!response.body) throw new Error('MCP SSE 响应体为空');
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
let data = [];
try {
while (true) {
const { value, done } = await reader.read();
buffer += decoder.decode(value, { stream: !done });
let boundary;
while ((boundary = buffer.indexOf('\n')) >= 0) {
const line = buffer.slice(0, boundary).replace(/\r$/, '');
buffer = buffer.slice(boundary + 1);
if (line.startsWith('data:')) {
const text = line.slice(5);
data.push(text.startsWith(' ') ? text.slice(1) : text);
} else if (!line && data.length) {
const message = JSON.parse(data.join('\n'));
data = [];
if (message.id === id) return message;
}
}
if (done) break;
}
throw new Error('未收到匹配响应;写操作不可直接重发');
} finally {
// 收到目标结果后关闭流,避免完成的请求继续占用连接。
try { await reader.cancel(); } catch { /* 已关闭或超时的流无需再次处理。 */ }
reader.releaseLock();
}
}
async initialize() {
const result = await this.rpc('initialize', {
protocolVersion: '2025-03-26', capabilities: {},
clientInfo: { name: 'mcp-manual-example-js', version: '1.0.0' },
});
this.protocol = result.protocolVersion;
if (this.protocol !== '2025-03-26') throw new Error('未协商到示例支持的协议版本');
await this.rpc('notifications/initialized', undefined, { notification: true });
return result;
}
async listTools() {
const tools = [];
let params = {};
while (true) {
const result = await this.rpc('tools/list', params);
tools.push(...(result.tools ?? []));
if (!result.nextCursor) return tools;
params = { cursor: result.nextCursor };
}
}
async call(name, args = {}, options = {}) {
// 不自动补设备 ID,也不自动重试副作用。
const result = await this.rpc('tools/call', { name, arguments: args }, options);
if (result.isError) throw new ToolError(result);
return result;
}
text(result) { return resultText(result); }
// 仅对工具页明确说明“文本中的 JSON”的返回值使用。
textJSON(result) { return JSON.parse(resultText(result)); }
}
返回值怎么读
同样一次 MCP 调用,不同工具可能返回文字、JSON 文本或图片。先看工具页的“返回结果”,再选择读取方式。
普通文字
例如 current_app 的设备实现返回普通包名文本:
result = client.call("current_app", {"device_id": device_id})
package = client.text(result).strip()
print(package)
const result = await client.call("current_app", { device_id: deviceId });
const packageName = client.text(result).trim();
console.log(packageName);
示例输出 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"])
const devices = client.textJSON(await client.call("list_devices"));
for (const device of devices) {
console.log(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;没有自动重发。
import { ToolError } from "./mcp_client.mjs";
try {
const result = await client.call("input_text", {
device_id: deviceId,
text: "杭州天气",
});
console.log(client.text(result));
} catch (error) {
if (!(error instanceof ToolError)) throw error;
console.log(error.message);
// 原始内容保存在 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 | 全量,包括通用能力入口 |
core | list_devices、observe、tap_element、screenshot、input_text、press_key、swipe、current_app |
standard | core + app |
agent | sense + act;不是全量,也不包含 list_devices |
core,ui | 核心 + 控件、缩放、多指、输入诊断 |
tools | list_capabilities、invoke_tool、get_operation,不包含直接设备工具 |
也可组合 core/app/vision/ui/device/sense/act/tools 组,重复项合并。全部组名无效时,当前实现回退到全量,不报空集;权限校验仍然有效。
完整参数表见官网 /mcp.html;程序以实际 tools/list.inputSchema 为准。
| 工具 | 重要参数和语义 |
| list_devices | 无参数;文本里是设备数组 JSON,其中 id 才是设备 ID |
| screenshot | device_id;返回 image 内容块,读取 mimeType 和 Base64 data |
| observe / ui_dump | device_id;读取当前页面 |
| tap_element | device_id、i;页面变化后重新 observe,不能复用旧编号 |
| tap | device_id、x、y;坐标为 0..1 比例 |
| swipe | device_id、x、y、x2、y2;可选 dur(毫秒) |
| long_press | device_id、x、y;可选 ms(毫秒) |
| pinch | device_id、x、y、from、to;可选 ms;半径按屏宽归一化 |
| gesture | device_id、frames;见第 7 节 |
| input_info | device_id;查询输入通道和触点状态,属于 ui 组 |
| input_reset | device_id;可选 force;清触点不等于释放任务或解除隔离 |
| launch_app | device_id、name;应用名或包名 |
| current_app | device_id;返回普通包名文本,例如 com.android.settings |
| input_text | device_id、text;先聚焦输入框,设备选择可用输入通道 |
| ime_on / ime_off | device_id;开启和恢复会话输入法,不等于独占整段外部自动化 |
| download_file | device_id、url、path;可选 scan、timeout_sec;用于二进制下载 |
| watch | device_id、templates;templates 是包含 JSON 对象数组的字符串;当前落在 device 组 |
| list_capabilities | 无参数;查询能力定义、目标要求和输入约束 |
| invoke_tool | capability、target_kind、target_id;可选 input、idempotency_key |
| get_operation | operation_id;查询通用能力操作的持久状态 |
直接设备工具使用单个 device_id,不是 deviceIds 数组。list_devices/list_capabilities/invoke_tool/get_operation 不使用顶层 device_id;通用能力的目标按定义填 target_kind/target_id。
4. 返回值的三层检查
- HTTP 非成功状态先按传输或认证错误处理;反向代理可能返回 429、502 等,不能当作工具结果。
- JSON-RPC 顶层
error 是方法或协议错误。
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 无状态传输与设备执行会话是两件事。
同一手机逐条等待动作完成,不并发抢屏。不同设备可分别提交,但没有跨设备事务或同时完成保证。
通用能力对接顺序:
- 用
list_capabilities 获取当前身份可见的定义和目标要求。
- 用
invoke_tool,按定义填写 capability、target_kind、target_id 和 input,不能猜名称或端点。
- 保存返回 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)
const templates = JSON.stringify([{ sha1: "", b64: "模板图片的Base64" }]);
const result = await client.call("watch", {
device_id: deviceId,
templates,
tap: false,
every_ms: 300,
timeout_ms: 10000,
max_hits: 1,
}, { timeoutMs: 30000 });
按工具等待时限设置客户端和代理超时;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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("list_devices", {});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("device_info", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("set_screen", {
"device_id": "你的设备ID",
"on": true
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("set_brightness", {
"device_id": "你的设备ID",
"value": 100
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("set_volume", {
"device_id": "你的设备ID",
"value": 5,
"stream": 3
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("vibrate", {
"device_id": "你的设备ID",
"ms": 300
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("cancel_vibration", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("notifications", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("proc_info", {
"device_id": "你的设备ID",
"name": "com.android.settings"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("cpu_usage", {
"device_id": "你的设备ID",
"pid": 1234
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("reboot_device", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("restart_agent", {
"device_id": "你的设备ID"
});
console.log(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 | 布尔值 | 否 | false | true=列全部已安装包(不带 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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("list_apps", {
"device_id": "你的设备ID",
"filter": "设置",
"limit": 20
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("launch_app", {
"device_id": "你的设备ID",
"name": "com.android.settings"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("current_app", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("app_info", {
"device_id": "你的设备ID",
"package": "com.android.settings"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("open_url", {
"device_id": "你的设备ID",
"url": "https://example.com"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("stop_app", {
"device_id": "你的设备ID",
"package": "com.android.settings"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("install_app", {
"device_id": "你的设备ID",
"path": "/data/local/tmp/demo.apk"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("uninstall_app", {
"device_id": "你的设备ID",
"package": "com.example.demo"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("clear_app", {
"device_id": "你的设备ID",
"package": "com.example.demo"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("set_app_enabled", {
"device_id": "你的设备ID",
"package": "com.example.demo",
"enabled": true
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ignore_batt_opt", {
"device_id": "你的设备ID",
"pkg": "com.example.demo"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("tap", {
"device_id": "你的设备ID",
"x": 0.5,
"y": 0.5
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("long_press", {
"device_id": "你的设备ID",
"x": 0.5,
"y": 0.5,
"ms": 600
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("swipe", {
"device_id": "你的设备ID",
"x": 0.5,
"y": 0.8,
"x2": 0.5,
"y2": 0.3,
"dur": 500
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("press_key", {
"device_id": "你的设备ID",
"key": 3
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("pinch", {
"device_id": "你的设备ID",
"x": 0.5,
"y": 0.5,
"from": 0.08,
"to": 0.18,
"ms": 400
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await 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": []
}
]
});
console.log(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 取得,不是型号或账号。 |
调用示例
展开完整 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 | 布尔值 | 否 | false | false 释放本次输入;true 清除设备全部触点,不是解除任务隔离。 |
调用示例
展开完整 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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("input_text", {
"device_id": "你的设备ID",
"text": "杭州天气"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ime_on", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ime_off", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("get_ime_list", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("set_ime", {
"device_id": "你的设备ID",
"ime_id": "从get_ime_list取得的完整ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("get_clipboard", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("set_clipboard", {
"device_id": "你的设备ID",
"text": "杭州天气"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ui_paste", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("observe", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ui_dump", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("tap_element", {
"device_id": "你的设备ID",
"i": 1
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("long_press_element", {
"device_id": "你的设备ID",
"i": 1,
"ms": 600
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ui_tap", {
"device_id": "你的设备ID",
"by": "text",
"val": "搜索"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ui_long_click", {
"device_id": "你的设备ID",
"by": "text",
"val": "示例项目"
});
console.log(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 | 字符串 | 否 | — | 可选:选择器的值 |
调用示例
展开完整 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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("wait_for", {
"device_id": "你的设备ID",
"by": "textContains",
"val": "搜索",
"timeout_ms": 8000
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ui_expand", {
"device_id": "你的设备ID",
"by": "text",
"val": "更多"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ui_collapse", {
"device_id": "你的设备ID",
"by": "text",
"val": "更多"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ui_set_selection", {
"device_id": "你的设备ID",
"start": 0,
"end": 2
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ui_copy", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ui_cut", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("screenshot", {
"device_id": "你的设备ID"
});
import { writeFile } from "node:fs/promises";
const image = result.content.find(item => item.type === "image");
if (!image || image.mimeType !== "image/jpeg") {
throw new Error("请按实际 MIME 类型选择文件后缀");
}
await writeFile("screen.jpg", Buffer.from(image.data, "base64"));
展开完整 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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("screenshot_region", {
"device_id": "你的设备ID",
"x1": 0.1,
"y1": 0.1,
"x2": 0.9,
"y2": 0.5
});
import { writeFile } from "node:fs/promises";
const image = result.content.find(item => item.type === "image");
if (!image || image.mimeType !== "image/jpeg") {
throw new Error("请按实际 MIME 类型选择文件后缀");
}
await writeFile("screen.jpg", Buffer.from(image.data, "base64"));
展开完整 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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("ocr", {
"device_id": "你的设备ID"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("find_text", {
"device_id": "你的设备ID",
"val": "搜索",
"tap": false
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await 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
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("find_color", {
"device_id": "你的设备ID",
"color": "FF0000",
"sim": 0.9,
"tap": false
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("find_multi_colors", {
"device_id": "你的设备ID",
"color": "FF0000,10,0,00FF00",
"sim": 0.9,
"tap": false
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("cmp_color", {
"device_id": "你的设备ID",
"x": 0.5,
"y": 0.5,
"color": "FF0000",
"sim": 0.9
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("pixel", {
"device_id": "你的设备ID",
"x": 0.5,
"y": 0.5
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("color_count", {
"device_id": "你的设备ID",
"color": "FF0000",
"sim": 0.9,
"x1": 0.1,
"y1": 0.1,
"x2": 0.9,
"y2": 0.5
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("yolo", {
"device_id": "你的设备ID",
"thresh": 0.25
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("tap_by_vision", {
"device_id": "你的设备ID",
"target": "屏幕顶部的搜索按钮",
"tap": false
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("watch", {
"device_id": "你的设备ID",
"templates": "[{\"sha1\": \"\", \"b64\": \"替换为模板图片Base64\"}]",
"tap": false,
"every_ms": 300,
"timeout_ms": 10000,
"max_hits": 1
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("read_file", {
"device_id": "你的设备ID",
"path": "/sdcard/Download/mcp-demo.txt"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("write_file", {
"device_id": "你的设备ID",
"path": "/sdcard/Download/mcp-demo.txt",
"content": "示例文字\n"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("append_file", {
"device_id": "你的设备ID",
"path": "/sdcard/Download/mcp-demo.txt",
"content": "追加一行\n"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("list_dir", {
"device_id": "你的设备ID",
"path": "/sdcard/Download"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("file_info", {
"device_id": "你的设备ID",
"path": "/sdcard/Download/mcp-demo.txt"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("copy_file", {
"device_id": "你的设备ID",
"from": "/sdcard/Download/mcp-demo.txt",
"to": "/sdcard/Download/mcp-copy.txt"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("move_file", {
"device_id": "你的设备ID",
"from": "/sdcard/Download/mcp-demo.txt",
"to": "/sdcard/Download/mcp-moved.txt"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("delete_file", {
"device_id": "你的设备ID",
"path": "/sdcard/Download/mcp-demo.txt"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("download_file", {
"device_id": "你的设备ID",
"url": "https://example.com/demo.jpg",
"path": "/sdcard/Pictures/mcp-demo.jpg",
"scan": true,
"timeout_sec": 30
});
console.log(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 | 字符串 | 是 | — | 媒体文件绝对路径 |
调用示例
展开完整 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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("view_file", {
"device_id": "你的设备ID",
"path": "/sdcard/Pictures/mcp-demo.jpg",
"mime": "image/jpeg"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("http_get", {
"device_id": "你的设备ID",
"url": "https://example.com",
"timeout_sec": 15
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("http_post", {
"device_id": "你的设备ID",
"url": "https://example.com/your-api",
"body": "message=hello",
"timeout_sec": 15
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("kv_put", {
"device_id": "你的设备ID",
"table": "mcp-demo",
"key": "progress",
"value": "done"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("kv_get", {
"device_id": "你的设备ID",
"table": "mcp-demo",
"key": "progress"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("kv_list", {
"device_id": "你的设备ID",
"table": "mcp-demo"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("kv_delete", {
"device_id": "你的设备ID",
"table": "mcp-demo",
"key": "progress"
});
console.log(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))
import { MCPClient } from "./mcp_client.mjs";
const client = MCPClient.fromEnv();
await client.initialize();
const result = await client.call("kv_clear", {
"device_id": "你的设备ID",
"table": "mcp-demo"
});
console.log(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 为空。
常见问题
会删除整张表中的数据,不是只删一个键。