The ten read-only host-management tools (host_list_processes, windows, network_state, software, browser_history, favorites, win32_services, driver_services, scheduled_tasks, host_get_hosts_file) each carried a name, description and schema for what is one connection to the host, one tab id per aspect and one paged list shape. Ten entries made tools/list hard to scan and took a large share of the description budget. They are now one tool, host_inspect(aspects[], ...), where aspects is a required, deduplicated array of the ten former names. A single aspect returns exactly what the old tool returned (same builder, same code path), so output is byte-identical; several aspects are fetched over separate managed sessions and merged into results.<aspect>, with failures isolated in errors.<aspect> and isError only when every aspect failed. Filters (pid/name/arch/title/url/publisher/folder/status/ start_type/process/protocol/ports/state/max_bytes) are still applied server-side before paging and are ignored by aspects they don't apply to. The old names stay as dispatch aliases so existing callers keep working but no longer appear in tools/list; the platform table, batch read-only list, tool hints, instructions, generator tables and the captured mcp/tools.json move to the new name (63 tools -> 54). The description also notes that win32_services / driver_services need an elevated client: a non-elevated one cannot open SCM and never answers, so the call times out after ~12 s. Co-Authored-By: deepseek-flash
331 lines
15 KiB
Python
331 lines
15 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 无条件段 ----
|
||
# P1-1:list_online_hosts / search_hosts / list_all_hosts 三合一(旧名为别名,不出现在 tools/list)
|
||
"list_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),
|
||
"get_foreground_window": (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),
|
||
# 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),
|
||
"operate_window": ("manage", True, False),
|
||
"control_service": ("manage", True, False),
|
||
"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_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}")
|