"""从 tools/list 黄金样本生成 tools.json。 黄金样本来自运行中的 MFC 服务端(全部开关打开,因此是工具全集)。 本脚本只做两件事: 1. 原样保留 name / description / inputSchema / outputSchema(零信息损失) 2. 补充运行时不可见的元信息:gate / write / manage / impl —— 这些是从 C++ 注册点(BuildToolsListResult / McpMachine::AppendTools / McpChat::AppendTools)的 if 条件解析出来的,见 GATE 表。 """ import json import sys if len(sys.argv) < 3: sys.exit("用法: python make_tools_json.py [tools_raw_machine_off.json]") SRC = sys.argv[1] DST = sys.argv[2] # 可选:McpMachine=0 状态下的抓取。开启态的抓取里没有降级工具(P2-2), # 而它们仍是真实工具,必须进清单——所以清单 = 两份抓取的并集。 OFF_SRC = sys.argv[3] if len(sys.argv) > 3 else None # 只在 McpMachine=0 时出现的降级工具(gate = "!machine")。改动这个集合要同步更新 # McpServer.cpp 里 showDegradedLists / showMainControls 两段。 # P2-2:operate_window / control_service 与 host_inspect / host_control_* 之间同样按 # McpMachine 二选一暴露(动作并集,两套名字都可调用)。 MACHINE_OFF_FALLBACKS = {"list_processes", "list_windows", "list_services", "operate_window", "control_service"} # gate: 该工具要求哪个服务端开关为开(null = 无条件出现) # write: 需要 !McpReadonly # manage: 额外需要 McpManage(仅 McpMachine 族的两处用到) GATE = { # ---- McpServer.cpp:BuildToolsListResult 无条件段 ---- # P1-1:list_online_hosts / search_hosts / list_all_hosts 三合一(旧名为别名,不出现在 tools/list) "list_hosts": (None, False, False), "get_host_detail": (None, False, False), # ---- McpMachine=0 时的降级路径(P2-2)---- # 开启主机管理后它们由 host_inspect 的 processes / windows / win32_services 项取代, # 所以只在开关关闭时进 tools/list(名字仍可作为别名调用)。 # 同理,operate_window / control_service(见下方单开关段)在开启后被 # host_control_window / host_control_service 取代。 "list_processes": ("!machine", False, False), "list_windows": ("!machine", False, False), "list_services": ("!machine", False, False), "get_activity_history": (None, False, False), "get_screenshot": (None, False, False), "get_foreground_window": (None, False, False), "list_files": (None, False, False), "get_client_log": (None, False, False), "get_audit_log": (None, False, False), "get_server_status": (None, False, False), "mcp_list_sessions": (None, False, False), "mcp_cancel_session": (None, False, False), "list_registry": (None, False, False), # ---- 单开关 ---- "get_keylog": ("keylog", False, False), # ---- 写操作(无专属开关,只受 readonly 约束)---- "exec_command": (None, True, False), "host_set_remark": (None, True, False), "host_set_watch_level": (None, True, False), "search_file": (None, True, False), # ---- terminal ---- "terminal_open": ("terminal", True, False), "terminal_exec": ("terminal", True, False), "terminal_close": ("terminal", True, False), # http_probe 在主机上跑 shell(Windows PowerShell / Linux curl),与终端族同门控 "http_probe": ("terminal", True, False), # ---- remote_control ---- "remote_open": ("remote_control", True, False), "remote_close": ("remote_control", True, False), "remote_keyboard": ("remote_control", True, False), "remote_mouse": ("remote_control", True, False), "remote_clipboard": ("remote_control", True, False), "remote_lock_screen": ("remote_control", True, False), "remote_block_input": ("remote_control", True, False), # ---- file_transfer ---- "download_file": ("file_transfer", True, False), # read_file 只读远端(不写),因此不受 readonly 约束 "read_file": ("file_transfer", False, False), "upload_file": ("file_transfer", True, False), "copy_files_c2c": ("file_transfer", True, False), # ---- manage(McpServer 侧的危险操作)---- "kill_process": ("manage", True, False), # P2-2:主机管理开启时由 host_control_window / host_control_service 承担 # (后两者也接受 close/show、set_auto/set_manual),所以只在 McpMachine=0 时暴露。 "operate_window": ("!machine", True, True), "control_service": ("!machine", True, True), "power_action": ("manage", True, False), "uninstall_host": ("manage", True, False), # ---- file_write ---- "delete_path": ("file_write", True, False), "move_path": ("file_write", True, False), "create_folder": ("file_write", True, False), # ---- McpMachine 族:总开关 McpMachine ---- "list_network_connections": ("machine", False, False), # P2-1:10 个 host_list_* / host_get_hosts_file 合并(旧名为别名,不出现在 tools/list) "host_inspect": ("machine", False, False), "kill_network_connection": ("machine", True, True), # writable && IsManageEnabled() "host_control_process": ("machine", True, False), # writable "host_control_window": ("machine", True, False), "host_control_service": ("machine", True, False), "host_control_task": ("machine", True, False), # ---- McpChat 族:独立开关 McpChat,与 readonly 无关 ---- "chat_open": ("chat", False, False), "chat_send": ("chat", False, False), "chat_wait": ("chat", False, False), "chat_close": ("chat", False, False), } # platforms: 该工具涉及的任一主机都必须落在此集合内。 # # 判定依据是**服务端实际放行**,不是客户端有没有实现。两者在 macOS 上会分叉: # exec_command / terminal_* / kill_process 的客户端实现是有的,但服务端刻意拦着 # (McpServer.cpp:3652「macOS 本轮不开放」、6870),所以标 win/lnx(终端族另有 apk)。 # Android 同理:COMMAND_SHELL 只有声明 CLIENT_CAP_TERMINAL 的新版 APK 才处理, # 老 APK 由工具内部按能力位返回 -32005。 # # 分组依据(全部经代码核对): # 全平台 —— 只读写服务端本地数据,与客户端平台无关 # win/lnx/mac —— client/、linux/、macos/ 都有该命令的处理分支,且服务端不拦 # win/lnx —— 远程控制只实现于 Windows/Linux(McpServer.cpp:2728); # 以及 macOS 客户端有实现但服务端未开放的 kill_process # 仅 win —— 服务/注册表/键日志/活动历史/文件写/host_* /power_action # (power_action 实际走 TOKEN_MACHINE_MANAGE,不是通用电源命令) # # 支持面是产品定位的阶梯:win 100% > lnx 46% > mac 28% ≈ apk 16%。 # Windows 是唯一全量支持的平台,check_platform_table.py 会把这条做成不变式。 # # apk 现状:COMMAND_SYSTEM 与 COMMAND_SHELL 在 android/.../main.cpp 明确标注 not # implemented,故除服务端本地类之外,只有少量按需补过分支的能力:运行日志 # (COMMAND_QUERY_LOG)、活动历史(COMMAND_QUERY_ACTIVITY)、截屏 # (COMMAND_SCREEN_PREVIEW_REQ,靠无障碍 takeScreenshot,Android 11+ 且开无障碍时 # 登录才声明 SCREEN_PREVIEW 能力位)。 _APK = ["win", "lnx", "mac", "apk"] _TRIO = ["win", "lnx", "mac"] _WL = ["win", "lnx"] _WLA = ["win", "lnx", "apk"] _WIN = ["win"] _WINAPK = ["win", "apk"] _APKONLY = ["apk"] PLATFORMS = { # 服务端本地数据,与客户端平台无关 "list_hosts": _APK, "get_host_detail": _APK, "get_audit_log": _APK, "get_server_status": _APK, "mcp_list_sessions": _APK, "mcp_cancel_session": _APK, "host_set_remark": _APK, "host_set_watch_level": _APK, # SYSTEM / LIST_DRIVE / QUERY_LOG:三个桌面平台都实现了;APK 也实现了 QUERY_LOG # (android/.../main.cpp ClientLogThread → TOKEN_REPORT_LOG) "list_processes": _TRIO, "list_files": _TRIO, "get_client_log": _APK, # list_windows 只有 Windows:服务端把 COMMAND_WSLIST 发在主连接上,Linux/macOS # 主循环只处理 COMMAND_SYSTEM,WSLIST 只在 SystemManager 子连接里处理 —— 走不到, # 实测 Linux 直接超时 -32001。别被 SystemManager 里的 case 骗到,那是 SystemDlg 用的。 "list_windows": _WIN, # macOS 客户端有 PTY 实现(macos/main.mm:753 起 ShellworkingThread),但服务端 # 本轮刻意不开放(McpServer.cpp:3652 注释「macOS 本轮不开放」),故实际不可用。 # Android 新版复用 common/PTYHandler.h,声明 CLIENT_CAP_TERMINAL 后服务端才放行。 "terminal_open": _WLA, "terminal_exec": _WLA, "terminal_close": _WLA, "exec_command": _WLA, # http_probe 走终端通道:macOS 终端未开放;Android 的 toybox 不保证有 curl/base64 "http_probe": _WL, # macOS 客户端有 COMMAND_KILLPROCESS 分支,但服务端同样拦着(McpServer.cpp:6870) "kill_process": _WL, # 需要 CLIENT_CAP_V2;三个桌面平台的 DefaultCaps() 都含 V2 "download_file": _TRIO, "read_file": _TRIO, "upload_file": _TRIO, # 远程控制:Windows / Linux 全功能;Android 只支持整屏目标,输入翻译成触摸与全局动作 # (remote_open/close/keyboard/mouse/clipboard),remote_block_input 另支持新版 Android "remote_open": _WLA, "remote_close": _WLA, "remote_keyboard": _WLA, "remote_mouse": _WLA, "remote_clipboard": _WLA, # COMMAND_SCREEN_CTRL_ALT_DEL:只有 Android 客户端实现(映射为系统锁屏) "remote_lock_screen": _APKONLY, # 需要 CLIENT_CAP_SCREEN_PREVIEW:Windows 恒有,Linux 仅在探测到 X11 桌面时声明, # Android 仅在无障碍服务在跑时声明(takeScreenshot,只支持 mode=screen) "get_screenshot": _WLA, # ---- 仅 Windows ---- "list_services": _WIN, "control_service": _WIN, "list_registry": _WIN, "get_keylog": _WIN, "get_activity_history": _WLA, # Windows 前台窗口;Linux 桌面/无桌面均有实现(linux/main.cpp);APK 复用同一采样机 "get_foreground_window": _WIN, # 窗口信息 RPC:CLIENT_CAP_WINDOW_INFO,仅 Windows 客户端声明 "search_file": _WIN, "delete_path": _WIN, "move_path": _WIN, "create_folder": _WIN, "copy_files_c2c": _TRIO, # 两端并集:源端仅 win,目标端 win/lnx/mac,见 ROLES # Windows 用 BlockInput();Android 新版用无障碍全屏 overlay(CLIENT_CAP_PRIVACY_OVERLAY) "remote_block_input": _WINAPK, "operate_window": _WIN, # WSLIST 能列窗口,但窗口操作仅 Windows 实现 "power_action": _WIN, # 实际走 TOKEN_MACHINE_MANAGE # TOKEN_UNINSTALL:Windows 客户端一直有该分支;Android 新版映射为系统卸载确认框 "uninstall_host": _WINAPK, # McpMachine 族(COMMAND_MACHINE_MANAGE 仅 Windows 实现) "list_network_connections": _WIN, "kill_network_connection": _WIN, # P2-1:10 个 host_list_* / host_get_hosts_file 合并为 host_inspect(仅 Windows) "host_inspect": _WIN, "host_control_process": _WIN, "host_control_window": _WIN, "host_control_service": _WIN, "host_control_task": _WIN, # McpChat 族(Windows 一直支持;新版 Android 声明 CLIENT_CAP_REMOTE_CHAT 后也可用) "chat_open": _WINAPK, "chat_send": _WINAPK, "chat_wait": _WINAPK, "chat_close": _WINAPK, } # roles: 多主机工具的方向性要求。 # platforms 只能表达「任一参与端都必须落在这个集合内」,表达不了「源端必须是 A、 # 目标端可以是 B」。copy_files_c2c 就是这种非对称能力: # src_id —— 只有 Windows 实现了发送逻辑(client/KernelManager.cpp; # McpServer.cpp:6591 对 LNX/MAC 直接返回 -32005) # dst_id —— 只要求 CLIENT_CAP_V2 收包,Windows / Linux / macOS 都行 # (McpServer.cpp:6601-6604 的 posixDst 分支专门处理 LNX/MAC 的路径形态) # 反过来 Linux → Windows 不支持:POSIX 客户端没有 C2C_PATHS 发送实现。 # 必须与 C++ 的 CollectTargetReqs 保持一致,check_platform_table.py 会校验。 ROLES = { "copy_files_c2c": { "src_id": _WIN, "dst_id": _TRIO, }, } raw = json.load(open(SRC, encoding="utf-8")) tools_on = raw["result"]["tools"] # 并集:开启态抓取 + 关闭态抓取里独有的降级工具。关闭态工具的描述/schema 也必须来自 # 活服务端,不能沿用旧清单,否则清单会和二进制悄悄漂移。 if OFF_SRC: tools_off = json.load(open(OFF_SRC, encoding="utf-8"))["result"]["tools"] on_names = {t["name"] for t in tools_on} off_names = {t["name"] for t in tools_off} off_only = [t for t in tools_off if t["name"] not in on_names] bad = [t["name"] for t in off_only if GATE.get(t["name"], (None,))[0] != "!machine"] if bad: print(f"!! 关闭态抓取里有未声明为 !machine 的工具: {bad}", file=sys.stderr) sys.exit(1) absent = sorted(MACHINE_OFF_FALLBACKS - off_names) if absent: print(f"!! 关闭态抓取里缺少降级工具: {absent}", file=sys.stderr) sys.exit(1) leaked = sorted(n for n in MACHINE_OFF_FALLBACKS if n in on_names) if leaked: print(f"!! 开启态抓取里出现了降级工具(应已隐藏): {leaked}", file=sys.stderr) sys.exit(1) tools_on = tools_on + off_only elif MACHINE_OFF_FALLBACKS & {t["name"] for t in tools_on}: print("!! 未提供关闭态抓取,但开启态里有降级工具——清单会丢工具", file=sys.stderr) sys.exit(1) tools_in = tools_on missing = [t["name"] for t in tools_in if t["name"] not in GATE] if missing: print(f"!! GATE 表缺少 {len(missing)} 个工具: {missing}", file=sys.stderr) sys.exit(1) missing_p = [t["name"] for t in tools_in if t["name"] not in PLATFORMS] if missing_p: print(f"!! PLATFORMS 表缺少 {len(missing_p)} 个工具: {missing_p}", file=sys.stderr) sys.exit(1) # 一致性检查:描述里声称「仅 Windows」但 platforms 含非 win 项,说明两者已经漂移。 # 这类矛盾靠人工 review 抓不住(60 个工具、26KB 描述),必须由脚本拦。 import re ONLY_WIN = re.compile(r"仅\s*Windows\s*(客户端)?(支持)?|only\s+Windows", re.I) drift = [] for t in tools_in: name = t["name"] plats = PLATFORMS[name] if ONLY_WIN.search(t.get("description", "")) and any(p != "win" for p in plats): drift.append((name, plats)) if drift: print("!! 描述声称「仅 Windows」但 platforms 含其他平台:", file=sys.stderr) for n, p in drift: print(f" {n}: {p}", file=sys.stderr) sys.exit(1) # roles 是 platforms 的细分,不能超出 platforms 的范围 for name, roles in ROLES.items(): outer = set(PLATFORMS[name]) for arg, plats in roles.items(): extra = set(plats) - outer if extra: print(f"!! {name}.roles.{arg} 含 platforms 之外的值 {sorted(extra)}", file=sys.stderr) sys.exit(1) tools_out = [] for t in tools_in: name = t["name"] gate, write, manage = GATE[name] entry = {"name": name, "description": t.get("description", "")} entry["gate"] = gate if write: entry["write"] = True if manage: entry["manage"] = True entry["platforms"] = PLATFORMS[name] if name in ROLES: entry["roles"] = ROLES[name] entry["impl"] = "mfc" entry["inputSchema"] = t.get("inputSchema", {}) entry["outputSchema"] = t.get("outputSchema", {}) tools_out.append(entry) doc = { "_readme": [ "YAMA MCP 工具清单(单一来源候选)。", "description / inputSchema / outputSchema 与运行中服务端的 tools/list 逐字节一致,", "由 tools/mcp_tools/dump_tools.py 抓取、make_tools_json.py 生成,勿手工编辑。", "gate: 该工具出现的开关条件(null = 无条件);write: 需 !McpReadonly;", "manage: 额外需 McpManage。这三项从 C++ 注册点的 if 条件解析而来,运行时不可见。", "gate 为 \"!machine\" 表示该降级工具只在 McpMachine=0 时出现(开启主机管理后", "由 host_inspect 的对应 aspect 取代,名字仍可作为别名调用);清单是开启态与", "关闭态两份抓取的并集。", "platforms: 该工具涉及的任一主机都必须落在此集合内(win/lnx/mac/apk),依据各平台", "客户端对相应 COMMAND_ 的处理实现。apk 上 COMMAND_SYSTEM 与 COMMAND_SHELL 均为空实现。", "roles: 仅多主机工具才有。按参数名细分平台,表达 platforms 说不清的方向性能力", "(copy_files_c2c:src_id 必须 Windows,dst_id 可 win/lnx/mac,反向不支持)。", "impl: 已实现该工具的服务端(mfc / go / both)。", "version 2 起 platforms 语义为「任一参与端都落在此集合内」,并新增 roles 字段;", "version 1 的 platforms 表示「该工具能在哪些客户端上执行」,两者对单主机工具等价。", ], "version": 2, "protocolVersion": "2025-06-18", "toolCount": len(tools_out), "tools": tools_out, } with open(DST, "w", encoding="utf-8", newline="\n") as f: json.dump(doc, f, ensure_ascii=False, indent=2) f.write("\n") import collections dist = collections.Counter(tuple(t["platforms"]) for t in tools_out) print(f"写入 {DST}: {len(tools_out)} 个工具") print(f" 有 gate 的: {sum(1 for t in tools_out if t['gate'])}") print(f" 写操作: {sum(1 for t in tools_out if t.get('write'))}") print(f" 需 manage: {sum(1 for t in tools_out if t.get('manage'))}") print(" 平台分布:") for plats, n in sorted(dist.items(), key=lambda x: -len(x[0])): print(f" {'+'.join(plats):20s} {n}")