Files
SimpleRemoter/tools/mcp_tools
yuanyuanxianganddeepseek-flash 7172ab376d Feature: add build_client MCP tool and improve build dialog linkage
Add a service-local MCP tool, build_client, that patches a client template
with this master's connect settings and writes the binary on the server.
It covers ghost/TestRun/ServerDll/TinyRun plus Linux, macOS and Android,
reusing the same byte path as CBuildDlg::OnBnClickedOk (CONNECT_ADDRESS
overwrite, build-date check, embedded TLS anchor before UPX/padding).
ShellCode AES and payload impersonation stay dialog-only.

The tool is gated by a new McpBuild switch (default 0) and McpReadonly=0.
It refuses to overwrite an existing file unless overwrite=true, protects
the server binaries/settings.ini/upx.exe, validates names strictly and
uses a unique UPX temp file so it cannot race the dialog. Results report
the path, size, target, TLS-anchor status and follow-up tips.

In the build dialog, Linux/macOS/Android targets now also grey out the
install-location combo/label and run mode, save and restore the Windows
compress choice, hide payload/download rows, grey the random-name and
run-as-admin menu items, and fix the TLS-anchor label for posix targets.
OnBnClickedOk is untouched; generated output is unchanged for every target.

New UI strings were added to the en_US, zh_TW and de_DE language packs.
McpBuild is off by default and changes require a server restart.
Verified on a Debug x64 instance: MCP generation for Linux is patched
correctly, Android and ghost anchor/error paths behave, and dialog-driven
Linux/TestRun/SC_AES generation still succeeds. mcp/tools.json regenerated
(55 tools); check_platform_table.py passes.

Co-Authored-By: deepseek-flash
2026-11-15 20:43:28 +01:00
..

MCP 工具清单维护

mcp/tools.json 是 MCP 全部 55 个工具的单一来源候选:工具名、描述、 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 / McpBuildClient.cpp)之后:

# 0. 先重编并启动主控端,确保服务端跑的是新代码
cd C:/github/YAMA

# 1. 抓取(token 自动从注册表读;端口自动探测 6545/6544)
#    清单是「McpMachine=1」与「McpMachine=0」两份抓取的并集,需在两次抓取之间
#    改配置并重启服务端(关闭态那份包含 5 个降级工具)。
python tools/mcp_tools/dump_tools.py "" /tmp/tools_raw_on.json
# ...把 McpMachine 改成 0、重启服务端...
python tools/mcp_tools/dump_tools.py "" /tmp/tools_raw_off.json

# 2. 生成(第三参数是关闭主机管理时的抓取)
python tools/mcp_tools/make_tools_json.py /tmp/tools_raw_on.json mcp/tools.json /tmp/tools_raw_off.json

# 3. 校验
python tools/mcp_tools/verify_tools.py --live mcp/tools.json

第 3 步输出 PASS: 55 个工具完全一致 才算成功。

如果工具数量变了

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)
  • McpBuildClient.cpp:AppendTools —— 1 个(开关 McpBuild 用 early return)

PLATFORMS 还要额外核对各平台客户端有没有实现对应命令,见下节。

字段说明

字段 含义
gate 该工具出现所需的开关(null = 无条件)。取值:machine / chat / terminal / remote_control / file_transfer / file_write / keylog / manage / build
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

当前分布(55 个工具):

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: 55 个工具的 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 —— 抓不到工具时先确认跑的是哪个构建
  • 抓取时所有开关都应为开,否则拿到的是子集而非全集