Files
SimpleRemoter/tools/mcp_tools
yuanyuanxianganddeepseek-flash d49ebe521d Docs(mcp): correct claims in the server instructions agents rely on
The initialize.instructions text is the only guide a model gets (it cannot
read docs/), and several statements disagreed with the code:

- get_keylog was described as always visible; it is gated by McpKeylog and
  hidden when the switch is off.
- Dangerous machine actions were not mentioned: freeze/thaw and
  stop/restart stay in tools/list but need McpMachineDangerous and return
  -32006 at call time.
- -32006 was described as policy/admin-only; MFC also returns it when an
  old client lacks CLIENT_CAP_V2. The Go server returns -32005 for that
  case, so its own instructions now say so.
- -32001 advice assumed every failure is a timeout; it also covers
  cancellations, http_probe parse failures and unconfirmed writes.
- "Unsupported combos always return -32005 immediately" ignored paths that
  surface as -32001 once a sub-connection is involved.
- Linux matrix listed all host_* as unsupported, but host_set_remark and
  host_set_watch_level only touch server-local data.
- local_dir / local_path are paths on the controller, not the user's box.

Also align the error table and platform distribution in the docs, and note
that hidden fallback aliases remain callable. Debug build green; go test,
check_platform_table and gen_go_tools --check pass.

Co-Authored-By: deepseek-flash
2026-11-13 12:32: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

当前分布(54 个工具):

platforms 数量 典型工具
win+lnx+mac+apk 9 只读写服务端本地数据:list_hosts / get_host_detail / get_client_log / get_audit_log / get_server_status / mcp_* / host_set_remark / host_set_watch_level
win+lnx+apk 11 remote_* 全族、exec_command / terminal_*、get_screenshot、get_activity_history
win+lnx+mac 6 进程列表、文件列取 / V2 文件传输(含 read_file)、copy_files_c2c
win+lnx 2 http_probe、kill_process
win+apk 6 remote_block_input、uninstall_host、chat_* 全族
win 19 服务 / 注册表 / 键日志 / 文件搜索与写入 / list_windows / get_foreground_window / host_inspect / host_control_* / operate_window / 网络连接 / power_action
apk 1 remote_lock_screen

注意 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 在子连接里才被处理——走不到。关掉平台门禁 (McpPlatformGuard=0)时实测 Linux 上直接超时 -32001;默认门禁开启时,这张表 会先拦下并返回 -32005。那两个 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 —— 抓不到工具时先确认跑的是哪个构建
  • 抓取时所有开关都应为开,否则拿到的是子集而非全集