The MCP remote-control family (remote_open / remote_close / remote_mouse / remote_keyboard / remote_clipboard) previously stopped at Windows and Linux, even though the Android client already translated injected events into touch gestures and global actions. This wires up the missing piece and opens the five tools to APK hosts. Client side, the screen sub-connection now handles COMMAND_SCREEN_SET_CLIPBOARD: the native handler forwards the raw GBK bytes to CaptureService.onClipboardText, which decodes them, strips the trailing NUL that the human clipboard-sync senders append, and writes the system clipboard from a background app (allowed on Android 10+, only reads are restricted). Pasting cannot be a Ctrl+V combo, so VK_V is mapped to ACTION_PASTE on the focused node, falling back to the accessibility focus and then to the first editable node, since WebView and self-drawn inputs often do not flag FOCUS_INPUT or isEditable. A new capability bit CLIENT_CAP_SCREEN_CLIPBOARD (0x0800) tells the server the APK understands both paths, so builds without the handler get an explicit -32005 instead of a package that is silently dropped. action=type is rejected outright for APK hosts - physical key events would only turn 'v' into a paste - and the error points at remote_clipboard + key=V. The platform table, server instructions and the five tool descriptions now describe Android support, which keys actually act as global actions (ESC, HOME, APPS, PRINTSCREEN), and that injection needs the accessibility service while capture needs an authorized MediaProjection session, both without receipts. Verified on the API 35 emulator against a Debug server: ASCII and GBK Chinese text round-tripped through the clipboard into a focused Settings search field, type / expect_hwnd / window_hwnd returned -32005, and PRINTSCREEN produced a saved screenshot. check_platform_table.py and verify_tools.py --offline pass. Co-Authored-By: deepseek-flash
MCP 工具清单维护
mcp/tools.json 是 MCP 全部 61 个工具的单一来源候选:工具名、描述、
inputSchema、outputSchema,以及运行时不可见的开关元信息(gate / write / manage)。
它的用途不限于给 Go 服务端复用。当前 26KB 的工具描述埋在 11k 行 C++ 里, 没有人能整体 review 一遍;抽成一份 JSON 后可以 diff、可以搜索、可以一眼看出 哪些工具描述含糊或功能重叠。
文件
| 路径 | 作用 |
|---|---|
mcp/tools.json |
工具清单本体(生成产物,勿手工编辑) |
tools/mcp_tools/dump_tools.py |
从运行中的服务端抓 tools/list |
tools/mcp_tools/make_tools_json.py |
把抓取结果转成 tools.json(含 gate / platforms 表) |
tools/mcp_tools/verify_tools.py |
校验 tools.json 与服务端是否一致 |
tools/mcp_tools/check_platform_table.py |
校验 tools.json 的 platforms 与 C++ kToolPlatforms 一致 |
更新流程
改动 C++ 里的工具定义(McpServer.cpp / McpMachine.cpp / McpChat.cpp)之后:
# 0. 先重编并启动主控端,确保服务端跑的是新代码
cd C:/github/YAMA
# 1. 抓取(token 自动从注册表读;端口自动探测 6545/6544)
python tools/mcp_tools/dump_tools.py "" /tmp/tools_raw.json
# 2. 生成
python tools/mcp_tools/make_tools_json.py /tmp/tools_raw.json mcp/tools.json
# 3. 校验
python tools/mcp_tools/verify_tools.py --live mcp/tools.json
第 3 步输出 PASS: 61 个工具完全一致 才算成功。
如果工具数量变了
make_tools_json.py 里的 GATE 和 PLATFORMS 两张表是手工维护的,新增工具会直接报错退出:
!! GATE 表缺少 1 个工具: ['new_tool']
!! PLATFORMS 表缺少 1 个工具: ['new_tool']
这是有意为之——gate / write / manage 三项在运行时不可见,只能从 C++
注册点的 if 条件读出来,必须人工确认。补表时对照:
McpServer.cpp:BuildToolsListResult—— 内联的 41 个McpMachine.cpp:AppendTools—— 16 个(总开关IsMachineEnabled用 early return)McpChat.cpp:AppendTools—— 4 个(总开关IsChatEnabled用 early return)
PLATFORMS 还要额外核对各平台客户端有没有实现对应命令,见下节。
字段说明
| 字段 | 含义 |
|---|---|
gate |
该工具出现所需的开关(null = 无条件)。取值:machine / chat / terminal / remote_control / file_transfer / file_write / keylog / manage |
write |
需要 !McpReadonly |
manage |
额外需要 McpManage(仅 kill_network_connection 用到) |
platforms |
该工具涉及的任一主机都必须落在此集合内:win / lnx / mac / apk |
roles |
仅多主机工具才有。按参数名细分平台,表达 platforms 说不清的方向性能力 |
impl |
已实现该工具的服务端:mfc / go / both |
gate / write / manage 只描述可见性,不描述行为。像
「McpMachine 开启时 host_list_processes 优先、关闭时退回 list_processes」
这类互斥/降级关系属于逻辑,仍然留在代码里。
platforms 怎么判定
只看各平台客户端有没有实现对应命令,不能看「是否引用了 COMMAND_ 常量」。 两个真实的反例:
android/.../main.cpp里COMMAND_SYSTEM和COMMAND_SHELL都有case分支, 但内容是LOGI("... (not implemented)")—— 引用 ≠ 实现。macos/能处理COMMAND_SEND_FILE_V2,但DefaultCaps()在 macOS 上只给V2|UTF8,没有SCREEN_PREVIEW,所以get_screenshot在 macOS 上仍不可用。
判定时要同时看命令实现和能力位:
| 依据 | 位置 |
|---|---|
| 命令分支 | client/、linux/main.cpp、macos/main.mm、android/app/src/main/cpp/main.cpp |
| 能力位 | common/commands.h 的 LOGIN_INFOR::DefaultCaps();Linux 另在 linux/main.cpp:RefreshLoginCaps 追加 SCREEN_PREVIEW |
当前分布(61 个工具):
| platforms | 数量 | 典型工具 |
|---|---|---|
win+lnx+mac+apk |
10 | 只读写服务端本地数据:list_online_hosts / get_audit_log / mcp_* |
win+lnx+mac |
6 | 进程列表、文件列取、日志、V2 文件传输、copy_files_c2c |
win+lnx |
12 | remote_* 全族、get_screenshot、get_activity_history、exec_command / terminal_* / kill_process |
win |
33 | 服务 / 注册表 / 键日志 / 文件写 / list_windows / get_foreground_window / host_* / chat_* / power_action |
注意 exec_command / terminal_* / kill_process 不在 win+lnx+mac 组:
macOS 客户端其实有对应实现(macos/main.mm:753 的 ShellworkingThread 跑 PTY,
SystemManager.mm 有 COMMAND_KILLPROCESS 分支),但服务端刻意拦着
(McpServer.cpp:3652 注释「macOS 本轮不开放」、6870)。平台表按实际行为标,
不按客户端能力标。
list_windows 只有 Windows 可用,这个坑很隐蔽:Linux 的
SystemManager.h:38 和 macOS 的 SystemManager.mm:39 都有 COMMAND_WSLIST
的 case 分支,看起来是支持的。但 BuildListWindows 把命令发在主连接上
(McpServer.cpp:2931),而这两个平台的主循环只处理 COMMAND_SYSTEM
(起 SystemManager 子连接),WSLIST 在子连接里才被处理——走不到。实测 Linux
上直接超时 -32001。那两个 case 是给 SystemDlg 窗口管理用的,不是 MCP 这条路径。
Windows 是在主循环里处理的(client/KernelManager.cpp:1491),所以正常。
平台优先级(产品定位)
支持面是刻意设计的阶梯,不是历史遗留:
| 平台 | 覆盖 | 定位 |
|---|---|---|
| win | 60 / 60 (100%) | 唯一全量支持的平台,所有工具都以它为准 |
| lnx | 27 / 60 (45%) | 第二梯队,桌面场景基本可用 |
| mac | 16 / 60 (27%) | 第三梯队 |
| apk | 10 / 60 (17%) | 第三梯队,仅服务端本地类工具 |
check_platform_table.py 把「Windows 全量」做成了不变式:任何工具缺 win
直接报错,同时检查 win >= lnx >= mac/apk 的阶梯不倒挂。新增工具时若只标了
lnx,脚本会拦下。
判断平台归属时以 Windows 为基线:先确认它在 Windows 上成立,再逐级确认
Linux、macOS、Android。反过来做(从 Android 往上推)容易把「客户端有实现」
误当成「服务端放行」——exec_command 在 macOS 上就是这种情况。
注意 exec_command / terminal_* / kill_process 不在 win+lnx+mac 组:
macOS 客户端其实有对应实现(macos/main.mm:753 的 ShellworkingThread 跑 PTY,
SystemManager.mm 有 COMMAND_KILLPROCESS 分支),但服务端刻意拦着
(McpServer.cpp:3652 注释「macOS 本轮不开放」、6870)。平台表按实际行为标,
不按客户端能力标——将来开放这几项时,要同时改表、roles 无关、和 instructions。
make_tools_json.py 会做一致性检查:描述里声称「仅 Windows」但 platforms 含
其他平台时直接报错,防止描述与事实再次漂移。
方向性能力(roles)
platforms 是无序集合,只能表达「任一参与端都落在这个集合内」。
copy_files_c2c 两端的要求不同,单靠它表达不了:
"platforms": ["win", "lnx", "mac"],
"roles": {
"src_id": ["win"],
"dst_id": ["win", "lnx", "mac"]
}
依据是 McpServer.cpp:6591-6609:
- 源端只有 Windows 实现了 C2C 发送逻辑(
client/KernelManager.cpp), 代码对LNX/MAC直接返回-32005 - 目标端只需
CLIENT_CAP_V2收包,posixDst分支专门处理 LNX/MAC 的路径形态 (接收端把\归一化成/后按绝对路径落盘)
Linux / macOS 只能当接收方,不能当发送方。 这是当前唯一的非对称工具。
新增同类工具时,platforms 填两端并集,方向性写进 roles,并在 C++ 的
CollectTargetReqs 里同步一份 AddIdReq —— check_platform_table.py 会校验
tools.json / C++ / 脚本三方一致。
与 instructions 的对应
server/2015Remote/McpServer.cpp 的 kServerInstructions 第 5 节(客户端平台差异)
是这份矩阵的面向模型的摘要。改 PLATFORMS 时同步改那一节,否则模型看到的
说明会和数据不一致。
运行时门禁
platforms 不只是文档,它还被编进 McpServer.cpp 的 kToolPlatforms 表,
由 DispatchSingleHostTool 开头的 CheckToolPlatform 执行硬校验:
平台不匹配时直接返回 -32005,不会下发命令也不会白等超时。
批量调用走 BuildBatchCall → DispatchSingleHostTool,自动被覆盖。
门禁需要从入参里拿到目标主机 id 才能判断平台。绝大多数工具用 id,
copy_files_c2c 用 src_id / dst_id(两端都查)——这是目前唯一的例外,
由 C++ 的 CollectTargetIds 处理。新增受限平台的工具时,如果入参里没有 id,
必须在 CollectTargetIds 和 check_platform_table.py 的 ID_ALIASES 两处同时登记,
否则门禁会静默放行。check_platform_table.py 会检查这件事。
总开关:McpPlatformGuard(默认 1),关掉后 CheckToolPlatform 直接返回放行。
python tools/mcp_tools/check_platform_table.py
# PASS: 61 个工具的 platforms 两边完全一致,且门禁都能拿到主机 id
与 Go 服务端的关系
impl 字段就是给 Go 端裁剪用的:标 mfc 的工具表示 Go 端还没有对应能力。
Go 端补齐某个工具的底层命令后,把它改成 both。
注意 Go 端目前只有 5 类客户端命令(SCREEN_SPY / NEXT / SCREEN_CONTROL /
BYE / SHELL),所以短期内 impl: both 的工具不会多。
前置条件
- 服务端在运行(
McpEnabled=1) - Release 版读注册表
HKCU\Software\YAMA\settings,Debug 版读<exe目录>\settings.ini—— 抓不到工具时先确认跑的是哪个构建 - 抓取时所有开关都应为开,否则拿到的是子集而非全集