tools/list 不带参数,无法按目标设备过滤工具列表。60 个工具里有 33 个只在 Windows 客户端上有实现,模型无从得知,只能下发命令后白等超时。 DispatchSingleHostTool 开头按 kToolPlatforms 表核对目标主机平台,不匹配立刻 返回 -32005;批量路径经由同一函数自动覆盖。主机不存在或离线时放行,把 -32002 留给工具自己报,避免同一个问题出现两种错误码。 支持面是刻意设计的阶梯:win 60/60、lnx 27、mac 16、apk 10。60 个工具全部含 win,所以 Windows 客户端永远不会被这道门禁拒绝,行为与改动前完全一致。 平台表按服务端实际放行来标,不按客户端能力标。两处会分叉的地方: - exec_command / terminal_* / kill_process:macOS 客户端有实现(main.mm:753 的 ShellworkingThread、SystemManager 的 KILLPROCESS),但服务端刻意拦着 (McpServer.cpp:3652「macOS 本轮不开放」、6870),故标 win+lnx。 - list_windows:Linux/macOS 的 SystemManager 都有 COMMAND_WSLIST 分支,但 BuildListWindows 把命令发在主连接上,而这两个平台的主循环只处理 COMMAND_SYSTEM (起子连接),WSLIST 只在子连接里才被处理,走不到。实测 Linux 上直接超时 -32001。那两个 case 是给 SystemDlg 用的,故标 win。 copy_files_c2c 是唯一的非对称工具(源端必须 Windows,目标端可 win/lnx/mac, 反向不支持),用 roles 按参数名分别声明,C++ 侧 CollectTargetReqs 对应处理。 配套 mcp/tools.json(60 个工具,version 2)与 tools/mcp_tools/ 下的抓取、生成、 比对、校验脚本。check_platform_table.py 校验 C++ 表、tools.json、instructions 三方一致,并把「Windows 全量」做成不变式。 已在 A6(Windows 11)与 Ubuntu24(Linux)上实测:Windows 侧 14/14 通过且无误拒, Linux 侧 11 项拒绝全部命中门禁,copy_files_c2c win->lnx 成功、lnx->win 被拒。 开关 McpPlatformGuard(默认 1),关闭只失去提前拦截,不影响任何执行路径。
321 lines
14 KiB
Python
321 lines
14 KiB
Python
"""从 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.json> <mcp/tools.json>")
|
||
|
||
SRC = sys.argv[1]
|
||
DST = sys.argv[2]
|
||
|
||
# gate: 该工具要求哪个服务端开关为开(null = 无条件出现)
|
||
# write: 需要 !McpReadonly
|
||
# manage: 额外需要 McpManage(仅 McpMachine 族的两处用到)
|
||
GATE = {
|
||
# ---- McpServer.cpp:BuildToolsListResult 无条件段 ----
|
||
"list_online_hosts": (None, False, False),
|
||
"search_hosts": (None, False, False),
|
||
"list_all_hosts": (None, False, False),
|
||
"get_host_detail": (None, False, False),
|
||
"list_processes": (None, False, False),
|
||
"list_windows": (None, False, False),
|
||
"get_activity_history": (None, False, False),
|
||
"get_screenshot": (None, False, False),
|
||
"list_files": (None, False, False),
|
||
"list_services": (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),
|
||
|
||
# ---- 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_block_input": ("remote_control", True, False),
|
||
|
||
# ---- file_transfer ----
|
||
"download_file": ("file_transfer", True, False),
|
||
"upload_file": ("file_transfer", True, False),
|
||
"copy_files_c2c": ("file_transfer", True, False),
|
||
|
||
# ---- manage(McpServer 侧的危险操作)----
|
||
"kill_process": ("manage", True, False),
|
||
"operate_window": ("manage", True, False),
|
||
"control_service": ("manage", True, False),
|
||
"power_action": ("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),
|
||
"host_list_processes": ("machine", False, False),
|
||
"host_list_windows": ("machine", False, False),
|
||
"host_list_network_state": ("machine", False, False),
|
||
"host_list_software": ("machine", False, False),
|
||
"host_list_browser_history": ("machine", False, False),
|
||
"host_list_favorites": ("machine", False, False),
|
||
"host_list_win32_services": ("machine", False, False),
|
||
"host_list_driver_services": ("machine", False, False),
|
||
"host_list_scheduled_tasks": ("machine", False, False),
|
||
"host_get_hosts_file": ("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。
|
||
#
|
||
# 分组依据(全部经代码核对):
|
||
# 全平台 —— 只读写服务端本地数据,与客户端平台无关
|
||
# win/lnx/mac —— client/、linux/、macos/ 都有该命令的处理分支,且服务端不拦
|
||
# win/lnx —— 远程控制只实现于 Windows/Linux(McpServer.cpp:2728);
|
||
# 以及 macOS 客户端有实现但服务端未开放的 exec_command / terminal_* / kill_process
|
||
# 仅 win —— 服务/注册表/键日志/活动历史/文件写/块输入/host_* /chat_* /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:534-540 明确
|
||
# 标注 not implemented,且客户端未声明 SCREEN_PREVIEW,故除服务端本地类外几乎全不支持。
|
||
_APK = ["win", "lnx", "mac", "apk"]
|
||
_TRIO = ["win", "lnx", "mac"]
|
||
_WL = ["win", "lnx"]
|
||
_WIN = ["win"]
|
||
|
||
PLATFORMS = {
|
||
# 服务端本地数据,与客户端平台无关
|
||
"list_online_hosts": _APK,
|
||
"search_hosts": _APK,
|
||
"list_all_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:三个桌面平台都实现了
|
||
"list_processes": _TRIO,
|
||
"list_files": _TRIO,
|
||
"get_client_log": _TRIO,
|
||
|
||
# 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 本轮不开放」),故实际不可用。
|
||
"terminal_open": _WL,
|
||
"terminal_exec": _WL,
|
||
"terminal_close": _WL,
|
||
"exec_command": _WL,
|
||
|
||
# macOS 客户端有 COMMAND_KILLPROCESS 分支,但服务端同样拦着(McpServer.cpp:6870)
|
||
"kill_process": _WL,
|
||
|
||
# 需要 CLIENT_CAP_V2;三个桌面平台的 DefaultCaps() 都含 V2
|
||
"download_file": _TRIO,
|
||
"upload_file": _TRIO,
|
||
|
||
# 远程控制:注释明确只实现于 Windows / Linux
|
||
"remote_open": _WL,
|
||
"remote_close": _WL,
|
||
"remote_keyboard": _WL,
|
||
"remote_mouse": _WL,
|
||
"remote_clipboard": _WL,
|
||
|
||
# 需要 CLIENT_CAP_SCREEN_PREVIEW:Windows 恒有,Linux 仅在探测到 X11 桌面时声明
|
||
"get_screenshot": _WL,
|
||
|
||
# ---- 仅 Windows ----
|
||
"list_services": _WIN,
|
||
"control_service": _WIN,
|
||
"list_registry": _WIN,
|
||
"get_keylog": _WIN,
|
||
"get_activity_history": _WIN,
|
||
"search_file": _WIN,
|
||
"delete_path": _WIN,
|
||
"move_path": _WIN,
|
||
"create_folder": _WIN,
|
||
"copy_files_c2c": _TRIO, # 两端并集:源端仅 win,目标端 win/lnx/mac,见 ROLES
|
||
"remote_block_input": _WIN,
|
||
"operate_window": _WIN, # WSLIST 能列窗口,但窗口操作仅 Windows 实现
|
||
"power_action": _WIN, # 实际走 TOKEN_MACHINE_MANAGE
|
||
|
||
# McpMachine 族(COMMAND_MACHINE_MANAGE 仅 Windows 实现)
|
||
"list_network_connections": _WIN,
|
||
"kill_network_connection": _WIN,
|
||
"host_list_processes": _WIN,
|
||
"host_list_windows": _WIN,
|
||
"host_list_network_state": _WIN,
|
||
"host_list_software": _WIN,
|
||
"host_list_browser_history": _WIN,
|
||
"host_list_favorites": _WIN,
|
||
"host_list_win32_services": _WIN,
|
||
"host_list_driver_services": _WIN,
|
||
"host_list_scheduled_tasks": _WIN,
|
||
"host_get_hosts_file": _WIN,
|
||
"host_control_process": _WIN,
|
||
"host_control_window": _WIN,
|
||
"host_control_service": _WIN,
|
||
"host_control_task": _WIN,
|
||
|
||
# McpChat 族(COMMAND_TALK 仅 Windows,代码里另有 requireWindows_ 硬校验)
|
||
"chat_open": _WIN,
|
||
"chat_send": _WIN,
|
||
"chat_wait": _WIN,
|
||
"chat_close": _WIN,
|
||
}
|
||
|
||
# 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_in = raw["result"]["tools"]
|
||
|
||
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 条件解析而来,运行时不可见。",
|
||
"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}")
|