Files
SimpleRemoter/tools/mcp_tools
yuanyuanxianganddeepseek-flash d4f10db1f2 Feature(Go): verify_tools --subset and MCP deployment docs
Add a third mode to verify_tools.py that validates the Go server end to
end: it fetches /mcp tools/list and requires the name set to equal the
nine implemented tools exactly (seven in readonly mode), compares
description / inputSchema / outputSchema field by field against
mcp/tools.json, and also checks the published order. Unlike --live,
extra or missing tools are failures, not notes.

The field-comparison loop is factored into report_field_diffs so
--offline / --live and --subset share one comparison, diff printer and
FIELDS tuple.

Document and deploy the endpoint: the systemd env example gains
YAMA_MCP_TOKEN / READONLY / TERM_IDLE / MAX_CONCURRENCY / READ_MAX,
the design doc moves to implemented and its section 10 now matches the
code (embedded tools_minimal.json, the three packet dispatch groups).
The tools README explains gen_go_tools.py --check and --subset.

Verified against a freshly built debug Go server on 16543/18090:
read-write mode passes with 9 tools, YAMA_MCP_READONLY=1 passes with 7,
and both mismatch directions (extra tools, missing tools) fail with
exit 1. gen_go_tools.py --check stays clean; no Go code changed.

Co-Authored-By: deepseek-flash
2026-11-12 23:09:33 +01:00
..

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 与服务端是否一致(含 Go 端 --subset)
tools/mcp_tools/gen_go_tools.py 从 tools.json 抽取 Go 端 9 个工具,生成 server/go/mcp/tools_minimal.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 服务端的关系

Go 最小服务端(server/go,设计见 docs/Mcp_Go_Minimal_Design.md)实现 9 个工具。 它的 tools/list 不是手写的:gen_go_tools.py 从 tools.json 原样抽取这 9 个工具 生成 server/go/mcp/tools_minimal.json,再由 //go:embed 编进二进制。

改完 tools.json 之后:

# 重新生成嵌入副本(--check 只检查是否为最新,CI 友好)
python tools/mcp_tools/gen_go_tools.py
python tools/mcp_tools/gen_go_tools.py --check

# 抓 Go 端线上 tools/list,与 tools.json 逐字段比对
# 读写模式恰好 9 个;YAMA_MCP_READONLY=1 时恰好 7 个(隐藏 terminal_*)
python tools/mcp_tools/verify_tools.py --subset mcp/tools.json <token> <port>
python tools/mcp_tools/verify_tools.py --subset mcp/tools.json <token> <port> --readonly

--subset 与 --live 的差别:前者名字集合必须恰好等于 9(或 7),多一个少一个 都失败;后者只报双方差异。impl 字段的 mfc / go / both 目前仍是人工维护的 元信息,脚本不据此推断。

前置条件

  • 服务端在运行(McpEnabled=1)
  • Release 版读注册表 HKCU\Software\YAMA\settings,Debug 版读 <exe目录>\settings.ini —— 抓不到工具时先确认跑的是哪个构建
  • 抓取时所有开关都应为开,否则拿到的是子集而非全集