From 356aa271080aef90f4cd1770778bd03ad31344f6 Mon Sep 17 00:00:00 2001 From: yuanyuanxiang <962914132@qq.com> Date: Tue, 3 Nov 2026 15:49:34 +0100 Subject: [PATCH] Feature: Reject MCP tool calls the target client cannot handle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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),关闭只失去提前拦截,不影响任何执行路径。 --- .gitignore | 6 + mcp/tools.json | 5845 +++++++++++++++++++++++ server/2015Remote/2015RemoteDlg.cpp | 4 + server/2015Remote/McpServer.cpp | 240 +- server/2015Remote/McpServer.h | 9 + tools/mcp_tools/README.md | 205 + tools/mcp_tools/check_platform_table.py | 206 + tools/mcp_tools/dump_tools.py | 90 + tools/mcp_tools/make_tools_json.py | 320 ++ tools/mcp_tools/verify_tools.py | 161 + 10 files changed, 7085 insertions(+), 1 deletion(-) create mode 100644 mcp/tools.json create mode 100644 tools/mcp_tools/README.md create mode 100644 tools/mcp_tools/check_platform_table.py create mode 100644 tools/mcp_tools/dump_tools.py create mode 100644 tools/mcp_tools/make_tools_json.py create mode 100644 tools/mcp_tools/verify_tools.py diff --git a/.gitignore b/.gitignore index c9683cc..e9d7536 100644 --- a/.gitignore +++ b/.gitignore @@ -97,3 +97,9 @@ server/go/devices.json server/go/build/ server/go/.claude/settings.json android/app/.cxx/ + +# MCP 工具清单的中间产物(dump_tools.py 的默认输出) +tools_raw.json + +# AI 助手的本地工作记忆(含个人上下文,与 .claude/settings.json 同理) +.workbuddy-ai/ diff --git a/mcp/tools.json b/mcp/tools.json new file mode 100644 index 0000000..7175ee2 --- /dev/null +++ b/mcp/tools.json @@ -0,0 +1,5845 @@ +{ + "_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": 60, + "tools": [ + { + "name": "list_online_hosts", + "description": "获取当前所有在线主机的列表,包含计算机名、IP、操作系统、版本、备注、分组、活动窗口、延迟等实时信息。可选 group / os / client_type 三个过滤条件(均可选、AND 组合、子串匹配、ASCII 不区分大小写),过滤在分页之前生效:total 为命中台数,totalAll 为全部在线台数。结果按 limit/offset 分页(默认 100 条,上限 1000),hasMore 表示还有下一页。tls=true 表示该客户端登录时使用了 TLS 加密传输(登录时上报,非实时探测;老客户端恒为 false)。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac", + "apk" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "client_type": { + "description": "按客户端类型过滤(子串,不区分大小写,如 EXE、LNX、MAC)。离线主机没有该字段,不会命中。省略则不过滤。", + "type": "string" + }, + "group": { + "description": "按分组过滤(子串,不区分大小写)。省略则不过滤。", + "type": "string" + }, + "limit": { + "description": "本次最多返回的条数,默认 100,上限 1000。", + "type": "integer" + }, + "offset": { + "description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。", + "type": "integer" + }, + "os": { + "description": "按操作系统过滤(子串,不区分大小写,如 Windows、Linux、Android)。省略则不过滤。", + "type": "string" + } + }, + "required": [], + "type": "object" + }, + "outputSchema": { + "properties": { + "hasMore": { + "type": "boolean" + }, + "hosts": { + "items": { + "properties": { + "activeWindow": { + "type": "string" + }, + "authStatus": { + "type": "string" + }, + "clientType": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "string" + }, + "install_time": { + "type": "string" + }, + "ip": { + "type": "string" + }, + "last_seen": { + "type": "string" + }, + "location": { + "type": "string" + }, + "name": { + "type": "string" + }, + "online": { + "type": "boolean" + }, + "os": { + "type": "string" + }, + "remark": { + "type": "string" + }, + "rtt": { + "type": "string" + }, + "screen": { + "type": "string" + }, + "tls": { + "type": "boolean" + }, + "version": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "totalAll": { + "type": "integer" + } + }, + "required": [ + "hosts" + ], + "type": "object" + } + }, + { + "name": "search_hosts", + "description": "按计算机名/备注、IP、分组、操作系统过滤主机。所有条件均可选、按 AND 组合;子串匹配(ASCII 不区分大小写)。online=true 只返回在线主机,online=false 只返回离线主机(曾连接过、当前未连接),省略时只返回在线主机。离线主机的 group 恒为 default,last_seen 为最后一次登录时间;两类都要请用 list_all_hosts。结果按 limit/offset 分页(默认 100 条,上限 1000),total 为匹配总数。tls=true 表示该客户端登录时使用了 TLS 加密传输(登录时上报,老客户端恒为 false)。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac", + "apk" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "group": { + "type": "string" + }, + "ip": { + "type": "string" + }, + "limit": { + "description": "本次最多返回的条数,默认 100,上限 1000。", + "type": "integer" + }, + "name": { + "type": "string" + }, + "offset": { + "description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。", + "type": "integer" + }, + "online": { + "type": "boolean" + }, + "os": { + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "properties": { + "hasMore": { + "type": "boolean" + }, + "hosts": { + "items": { + "properties": { + "activeWindow": { + "type": "string" + }, + "authStatus": { + "type": "string" + }, + "clientType": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "string" + }, + "install_time": { + "type": "string" + }, + "ip": { + "type": "string" + }, + "last_seen": { + "type": "string" + }, + "location": { + "type": "string" + }, + "name": { + "type": "string" + }, + "online": { + "type": "boolean" + }, + "os": { + "type": "string" + }, + "remark": { + "type": "string" + }, + "rtt": { + "type": "string" + }, + "screen": { + "type": "string" + }, + "tls": { + "type": "boolean" + }, + "version": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "totalAll": { + "type": "integer" + } + }, + "required": [ + "hosts" + ], + "type": "object" + } + }, + { + "name": "list_all_hosts", + "description": "列出服务端已知的全部主机:在线主机(实时信息)与离线主机(历史连接过、当前未连接,来自主机列表记录)。在线主机字段同 list_online_hosts;离线主机另有 last_seen(最后一次登录时间)、install_time 字段,但没有 rtt/version/activeWindow 等实时字段,也没有 clientType。authStatus 为主机授权状态(unauthorized/authorized_by_super/authorized_by_admin/forbidden)。默认两类都返回;可选 group / os / client_type 过滤(AND 组合、子串匹配、ASCII 不区分大小写),过滤在分页之前生效:total 为命中台数,totalAll 为主机库总数。结果按 limit/offset 分页(默认 100 条,上限 1000)。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac", + "apk" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "client_type": { + "description": "按客户端类型过滤(子串,不区分大小写,如 EXE、LNX、MAC)。离线主机没有该字段,不会命中。省略则不过滤。", + "type": "string" + }, + "group": { + "description": "按分组过滤(子串,不区分大小写)。省略则不过滤。", + "type": "string" + }, + "limit": { + "description": "本次最多返回的条数,默认 100,上限 1000。", + "type": "integer" + }, + "offline": { + "description": "是否包含离线主机(历史连接过、当前未连接的),默认 true", + "type": "boolean" + }, + "offset": { + "description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。", + "type": "integer" + }, + "online": { + "description": "是否包含在线主机,默认 true", + "type": "boolean" + }, + "os": { + "description": "按操作系统过滤(子串,不区分大小写,如 Windows、Linux、Android)。省略则不过滤。", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "properties": { + "hasMore": { + "type": "boolean" + }, + "hosts": { + "items": { + "properties": { + "activeWindow": { + "type": "string" + }, + "authStatus": { + "type": "string" + }, + "clientType": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "string" + }, + "install_time": { + "type": "string" + }, + "ip": { + "type": "string" + }, + "last_seen": { + "type": "string" + }, + "location": { + "type": "string" + }, + "name": { + "type": "string" + }, + "online": { + "type": "boolean" + }, + "os": { + "type": "string" + }, + "remark": { + "type": "string" + }, + "rtt": { + "type": "string" + }, + "screen": { + "type": "string" + }, + "tls": { + "type": "boolean" + }, + "version": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "totalAll": { + "type": "integer" + } + }, + "required": [ + "hosts" + ], + "type": "object" + } + }, + { + "name": "get_host_detail", + "description": "获取单台在线主机的详细信息(id、计算机名、IP、操作系统、备注、分组、活动窗口、屏幕分辨率、客户端类型等)。tls=true 表示该客户端登录时使用了 TLS 加密传输(登录时上报,老客户端恒为 false)。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac", + "apk" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段;与 ids 二选一", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "host": { + "properties": { + "activeWindow": { + "type": "string" + }, + "authStatus": { + "type": "string" + }, + "capabilities": { + "properties": { + "c2cPaths": { + "description": "能否按路径清单接收另一台主机的文件(copy_files_c2c 源端的前提)", + "type": "boolean" + }, + "fileTransferV2": { + "description": "是否支持 V2 文件传输(download_file / upload_file 的前提)", + "type": "boolean" + }, + "platform": { + "description": "客户端形态:EXE/DLL/MEXE/SC/MDLL(Windows)、LNX(Linux)、MAC、APK", + "type": "string" + }, + "registry": { + "description": "是否有 Windows 注册表可查(list_registry);仅 Windows 客户端为 true", + "type": "boolean" + }, + "remoteControl": { + "description": "能否建立远程控制会话(remote_open/remote_mouse/remote_keyboard 的前提);还要求服务端 Web 远程服务已启动(WebSvrPort>0)", + "type": "boolean" + }, + "screenPreview": { + "description": "能否截屏(get_screenshot 的前提)", + "type": "boolean" + } + }, + "type": "object" + }, + "clientType": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "string" + }, + "install_time": { + "type": "string" + }, + "ip": { + "type": "string" + }, + "last_seen": { + "type": "string" + }, + "location": { + "type": "string" + }, + "name": { + "type": "string" + }, + "online": { + "type": "boolean" + }, + "os": { + "type": "string" + }, + "remark": { + "type": "string" + }, + "rtt": { + "type": "string" + }, + "screen": { + "type": "string" + }, + "tls": { + "type": "boolean" + }, + "version": { + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "host" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "list_processes", + "description": "获取指定在线主机的进程列表(PID、映像名称、架构、程序完整路径)。通过主连接下发命令、子连接回传,一次性返回。可选 name(映像名子串,ASCII 不区分大小写)/ pid(精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。定位是 McpMachine=0(主机管理工具关闭)时的降级路径,字段较少;若 host_list_processes 出现在 tools/list 里,一律优先用它。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段;与 ids 二选一", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回的条数,默认 100,上限 1000。", + "type": "integer" + }, + "name": { + "description": "按映像名子串过滤,ASCII 不区分大小写(如 chrome)", + "type": "string" + }, + "offset": { + "description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。", + "type": "integer" + }, + "pid": { + "description": "按 PID 精确过滤", + "type": "integer" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "processes": { + "items": { + "properties": { + "arch": { + "type": "string" + }, + "name": { + "type": "string" + }, + "path": { + "type": "string" + }, + "pid": { + "type": "integer" + } + }, + "type": "object" + }, + "type": "array" + }, + "total": { + "type": "integer" + }, + "totalAll": { + "type": "integer" + } + }, + "required": [ + "processes" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "list_windows", + "description": "获取指定在线主机的顶层窗口列表(句柄、窗口标题、窗口状态、所属进程 PID)。一次性返回。可选 name(窗口标题子串,ASCII 不区分大小写)/ pid(所属进程,精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。定位是 McpMachine=0(主机管理工具关闭)时的降级路径;若 host_list_windows 出现在 tools/list 里,一律优先用它。", + "gate": null, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段;与 ids 二选一", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回的条数,默认 100,上限 1000。", + "type": "integer" + }, + "name": { + "description": "按窗口标题子串过滤,ASCII 不区分大小写(如 notepad);匹配的是标题不是进程名", + "type": "string" + }, + "offset": { + "description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。", + "type": "integer" + }, + "pid": { + "description": "按窗口所属进程的 PID 精确过滤", + "type": "integer" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "totalAll": { + "type": "integer" + }, + "windows": { + "items": { + "properties": { + "hwnd": { + "type": "integer" + }, + "pid": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "title": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "windows" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "get_activity_history", + "description": "获取指定在线主机的历史活动记录(前台窗口驻留时长,每行一条「[时间] [标题] 时长」)。主连接 RPC。结果按 limit/offset 分页(默认 100 条、上限 1000),新在前:offset=0 就是最近 limit 条,想看更早的再往后翻。total 为本机现有记录总数,hasMore 表示还有更早的记录;客户端只保留最近 500 条,所以 total 最多约 501(含进行中的当前窗口)。", + "gate": null, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段;与 ids 二选一", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回的条数,默认 100,上限 1000。", + "type": "integer" + }, + "offset": { + "description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。", + "type": "integer" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "activityHistory": { + "description": "与 records 同源的纯文本(records 按行拼接),窗口外的记录不包含。", + "type": "string" + }, + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "records": { + "description": "本次窗口内的记录,每条一行「[时间] [标题] 时长」。新在前。", + "items": { + "type": "string" + }, + "type": "array" + }, + "total": { + "type": "integer" + }, + "totalAll": { + "type": "integer" + }, + "truncated": { + "description": "因 64 KB 字节预算而比 limit 少返回了条目(此时 hasMore 也为 true)。", + "type": "boolean" + } + }, + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "get_screenshot", + "description": "截取指定在线主机的一帧屏幕,返回 base64 编码的 JPEG 图片(image 对象含 mimeType/data/width/height)。支持 Windows 与带 X11 桌面的 Linux 客户端(能力位 CLIENT_CAP_SCREEN_PREVIEW),主连接 RPC、一次性返回。", + "gate": null, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "max_width": { + "description": "期望图片最大宽度(像素,钳制到 64~1920)。省略或传 0 时沿用 RTT 自适应缩略图档位(最大 1024);传 1920 可拿到接近原分辨率(1080p 源屏即原分辨率,4K 源屏最多 1920),供 AI 视觉/OCR 场景提升清晰度。", + "type": "integer" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "image": { + "properties": { + "bytes": { + "type": "integer" + }, + "height": { + "type": "integer" + }, + "mimeType": { + "type": "string" + }, + "width": { + "type": "integer" + } + }, + "type": "object" + } + }, + "required": [ + "image" + ], + "type": "object" + } + }, + { + "name": "list_files", + "description": "列举指定在线主机的目录。省略或空 path 返回驱动器列表(drives);给定 path 返回该目录一层内的文件/子目录(files,最多 500 条,含 name/isDir/size/mtime)。只读。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回的条数,默认 100,上限 1000。", + "type": "integer" + }, + "offset": { + "description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。", + "type": "integer" + }, + "path": { + "description": "要列举的目录路径(如 C:\\Windows);省略或传空则返回驱动器列表", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "drives": { + "items": { + "properties": { + "drive": { + "type": "string" + }, + "fileSystem": { + "type": "string" + }, + "freeMB": { + "type": "integer" + }, + "totalMB": { + "type": "integer" + }, + "type": { + "type": "integer" + }, + "typeName": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "files": { + "items": { + "properties": { + "isDir": { + "type": "boolean" + }, + "mtime": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "size": { + "type": "integer" + } + }, + "type": "object" + }, + "type": "array" + }, + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "totalAll": { + "type": "integer" + } + }, + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "list_services", + "description": "获取指定在线 Windows 主机的服务列表(显示名、服务名、可执行文件路径、运行状态、启动类型)。仅 Windows 客户端支持;一次性返回,结果按 limit/offset 分页。不支持服务端过滤。定位是 McpMachine=0(主机管理工具关闭)时的降级路径,字段较少(无描述、登录身份);若 host_list_win32_services 出现在 tools/list 里,一律优先用它。", + "gate": null, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段;与 ids 二选一", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回的条数,默认 100,上限 1000。", + "type": "integer" + }, + "offset": { + "description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。", + "type": "integer" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "services": { + "items": { + "properties": { + "binary_path": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "service_name": { + "type": "string" + }, + "start_type": { + "type": "string" + }, + "status": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "total": { + "type": "integer" + }, + "totalAll": { + "type": "integer" + } + }, + "required": [ + "services" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "get_client_log", + "description": "获取指定在线主机 YAMA 客户端的内存运行日志(客户端 ring buffer,最多 1000 行,含时间戳/源文件/行号)。客户端持续增量上报,本工具取当前时刻的快照后即断开。默认只返回末尾 200 行(故障排查看的是最后发生了什么);可用 limit 调整(上限 2000)、filter 只保留包含某子串的行。返回里的 lines_total / lines_matched / lines_returned / truncated 说明裁剪情况。只读。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "filter": { + "description": "只看包含该子串的行(ASCII 不区分大小写,如 error / TIMEOUT);过滤后再取末尾 limit 行", + "type": "string" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段;与 ids 二选一", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "最多返回末尾多少行,默认 200,上限 2000;返回的是最近的日志,不是开头的", + "type": "integer" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "lines_matched": { + "description": "filter 命中后的行数(无 filter 时等于 lines_total)", + "type": "integer" + }, + "lines_returned": { + "description": "本次实际返回的行数", + "type": "integer" + }, + "lines_total": { + "description": "客户端快照的总行数", + "type": "integer" + }, + "log": { + "description": "日志文本(按行,\\n 分隔);已按 limit/filter 裁剪", + "type": "string" + }, + "truncated": { + "description": "true 表示命中行数多于本次返回,log 只是末尾一段", + "type": "boolean" + } + }, + "required": [ + "log" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "get_keylog", + "description": "读取指定在线 Windows 主机的键盘记录(客户端既有键盘记录功能的输出,按行返回)。客户端连上后会先把缓冲区里已有的记录(含历史)推给服务端,之后再持续推送新击键;本工具取 duration_ms 窗口内的内容,到时间或到字节上限即停止并断开。默认只读;可选的 clear / set_offline 是写动作(需 McpReadonly=0),在下发采集窗口之前送到客户端。响应里的 offlineRecord 是客户端自报的常驻记录开关。需服务端开启 McpKeylog。", + "gate": "keylog", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "clear": { + "description": "写操作(需 McpReadonly=0):下发前清空客户端的键盘缓冲区与落盘文件,不可撤销。客户端没有回执;且它可能在收到该命令前已把缓冲区推上来,所以本次响应的 lines 不保证只含清除之后的击键。", + "type": "boolean" + }, + "duration_ms": { + "description": "采集窗口(毫秒),默认 4000,范围 1000-15000。窗口越长越可能捕捉到用户输入,但请求耗时也越长。", + "type": "integer" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "max_bytes": { + "description": "最多返回的字节数,默认 65536,范围 1024-262144;超出部分丢弃并置 truncated=true。", + "type": "integer" + }, + "set_offline": { + "description": "写操作(需 McpReadonly=0):把客户端『无人在线时是否继续落盘记录』的常驻开关设为 true/false(客户端写入 kbrecord 并长期生效)。不影响本次响应已取到的历史。无回执,可再调用一次本工具看 offlineRecord 确认。", + "type": "boolean" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "bytes": { + "type": "integer" + }, + "duration_ms": { + "type": "integer" + }, + "id": { + "type": "string" + }, + "lineCount": { + "type": "integer" + }, + "lines": { + "items": { + "type": "string" + }, + "type": "array" + }, + "offlineRecord": { + "description": "采集开始时客户端自报的离线常驻记录开关(就绪包 byte 1)。缺省表示客户端没有上报。为 false 时缓冲区里的历史只覆盖本进程启动后的在线时段。", + "type": "boolean" + }, + "truncated": { + "type": "boolean" + } + }, + "type": "object" + } + }, + { + "name": "get_audit_log", + "description": "获取 YAMA 服务端主界面的消息/审计日志(主机上线/下线、操作结果、告警等),按 limit/offset 分页(新在前,服务端只保留最近 1000 条)。可选 type 按类型列做不区分大小写的子串过滤(如 MCP、主机),keyword 按正文字串过滤;过滤在分页之前生效,total 为命中条数、totalAll 为镜像里的全部条数。只读、纯内存。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac", + "apk" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "keyword": { + "description": "正文子串过滤,不区分大小写(如 445、timeout)。省略则不过滤。", + "type": "string" + }, + "limit": { + "description": "本次最多返回的条数,默认 100,上限 1000。", + "type": "integer" + }, + "offset": { + "description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。", + "type": "integer" + }, + "type": { + "description": "类型列的子串过滤,不区分大小写(如 MCP、主机上线)。省略则不过滤。", + "type": "string" + } + }, + "required": [], + "type": "object" + }, + "outputSchema": { + "properties": { + "entries": { + "items": { + "properties": { + "msg": { + "type": "string" + }, + "time": { + "type": "string" + }, + "type": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "totalAll": { + "type": "integer" + } + }, + "required": [ + "entries" + ], + "type": "object" + } + }, + { + "name": "get_server_status", + "description": "获取 YAMA 服务端自身的状态:程序版本与 exe 构建时间、进程已运行秒数、MCP 监听地址与端口、各功能开关(只读/终端/远程控制/文件传输/管理/主机管理/高风险操作/键盘记录/远程交谈)、在线与离线主机数、各类在飞会话数、当前被封禁的来源 IP 数。只读、纯内存,不返回 token。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac", + "apk" + ], + "impl": "mfc", + "inputSchema": { + "properties": {}, + "required": [], + "type": "object" + }, + "outputSchema": { + "properties": { + "app_name": { + "type": "string" + }, + "bind": { + "type": "string" + }, + "blocked_auth_ips": { + "type": "integer" + }, + "exe_build_time": { + "type": "string" + }, + "hosts": { + "type": "object" + }, + "port": { + "type": "integer" + }, + "sessions": { + "type": "object" + }, + "switches": { + "type": "object" + }, + "uptime_sec": { + "type": "integer" + }, + "version": { + "type": "string" + } + }, + "required": [], + "type": "object" + } + }, + { + "name": "mcp_list_sessions", + "description": "列出服务端当前的会话:在飞 tools/call(kind=call,含 JSON-RPC request_id)、挂起中的一次性请求(pending)、持久终端、远程控制、文件传输、远程交谈。每项给出 host_id、tool、session_id/request_id、busy、已持续 elapsed_ms,长连接会话还给出距最后一次活动的 idle_ms。主机报 -32003「忙」时用它查是谁占着;要放开占用用 mcp_cancel_session。只读、纯内存。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac", + "apk" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "kind": { + "description": "只列某一类会话;省略则全部列出。", + "enum": [ + "call", + "pending", + "terminal", + "remote_control", + "file_transfer", + "chat" + ], + "type": "string" + } + }, + "required": [], + "type": "object" + }, + "outputSchema": { + "properties": { + "count": { + "type": "integer" + }, + "sessions": { + "description": "会话列表,每项含 host_id/kind/tool/session_id/request_id/busy/elapsed_ms/idle_ms", + "type": "array" + } + }, + "type": "object" + } + }, + { + "name": "mcp_cancel_session", + "description": "取消在飞请求并尽快释放主机占用。给 request_id(tools/call 的 JSON-RPC id,类型要与调用时一致)精确取消一次调用,或按 id(主机)与 session_id 取消匹配的调用(两个都给则必须同时匹配)。工具层的等待在 ≤500ms 内退出并走既有清理路径;本工具最多等 2s,返回 cancelled(取消个数)、released(是否已释放占用)、waited_ms 与 matched(匹配到的会话)。被取消的请求以 -32800 结束。等价于对 SSE 流发 notifications/cancelled。", + "gate": null, + "platforms": [ + "win", + "lnx", + "mac", + "apk" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id:取消该主机上所有在飞请求", + "type": "string" + }, + "request_id": { + "description": "要取消的那次 tools/call 的 JSON-RPC id(字符串或整数,类型必须与调用时一致)", + "type": [ + "string", + "integer" + ] + }, + "session_id": { + "description": "会话 id(terminal/remote_control/chat 的 session_id):只取消该会话上的在飞请求", + "type": "string" + } + }, + "required": [], + "type": "object" + }, + "outputSchema": { + "properties": { + "cancelled": { + "description": "被取消的在飞调用个数", + "type": "integer" + }, + "matched": { + "description": "取消前匹配到的会话快照(同 mcp_list_sessions 的字段)", + "type": "array" + }, + "released": { + "description": "2s 内匹配的会话是否已从服务端表中消失(主机已松开)", + "type": "boolean" + }, + "waited_ms": { + "type": "integer" + } + }, + "type": "object" + } + }, + { + "name": "list_registry", + "description": "查询指定在线 Windows 主机的注册表。省略或空 path 返回 5 个根键;给定 path(如 HKEY_LOCAL_MACHINE\\Software)返回该键一层内的子键(keys)与值(values,含 name/type/data)。只读。", + "gate": null, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段;与 ids 二选一", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "path": { + "description": "注册表键路径(如 HKEY_LOCAL_MACHINE\\Software);省略或传空则返回 5 个根键", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "keys": { + "items": { + "type": "string" + }, + "type": "array" + }, + "path": { + "type": "string" + }, + "values": { + "description": "该键下的值;path 为空(列根键)时不返回本字段", + "items": { + "properties": { + "data": { + "type": "string" + }, + "name": { + "type": "string" + }, + "type": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "keys" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "exec_command", + "description": "在指定在线 Windows 或 Linux 主机上执行一条命令并返回 stdout 与退出码(受只读模式与命令白名单约束,默认仅允许只读命令前缀,见 McpReadonly / McpCmdWhitelist;Linux 有独立的 POSIX 默认白名单,禁用 ; 反引号 $( ${ ! 等串联/子命令字符)。", + "gate": null, + "write": true, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "command": { + "description": "要执行的命令(受只读模式与命令白名单约束,仅允许只读命令前缀;Windows 与 Linux 使用各自的内置默认白名单)", + "type": "string" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "timeout_ms": { + "description": "等待输出完成的超时毫秒数(可选,默认 20000,上限 600000)", + "type": "integer" + } + }, + "required": [ + "id", + "command" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "exit_code": { + "description": "退出码:PTY 客户端(Windows ConPTY / Linux PTY)为命令的真实退出码;老客户端(非 PTY)仅区分 0/非 0;-1=未知(进程异常退出)", + "type": "integer" + }, + "stdout": { + "description": "命令输出(已剥哨兵与 ANSI 转义)", + "type": "string" + } + }, + "required": [ + "stdout", + "exit_code" + ], + "type": "object" + } + }, + { + "name": "terminal_open", + "description": "在指定在线 Windows 或 Linux 主机上打开一个持久 shell 会话并返回 session_id 与终端模式。后续 terminal_exec 复用该会话(cwd/环境变量跨命令保持),用毕须 terminal_close。Linux 使用 POSIX PTY(UTF-8,is_pty=true)。", + "gate": "terminal", + "write": true, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "timeout_ms": { + "description": "等待 shell 启动的超时毫秒数(可选,默认 20000,上限 600000)", + "type": "integer" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "is_pty": { + "description": "true=PTY(UTF-8)(Windows ConPTY / Linux PTY);false=老 cmd 管道(GBK)", + "type": "boolean" + }, + "session_id": { + "description": "持久会话 token,后续 terminal_exec / terminal_close 用", + "type": "string" + } + }, + "required": [ + "session_id", + "is_pty" + ], + "type": "object" + } + }, + { + "name": "terminal_exec", + "description": "在已打开的持久会话中执行一条命令并返回 stdout 与退出码。命令不受白名单约束,但不能含 & 或 |(会破坏输出哨兵捕获),请拆成多条调用;Windows 下重定向 > < 与转义 ^ 允许,Linux 下可用 ; 串联(退出码取最后一条)。", + "gate": "terminal", + "write": true, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "command": { + "description": "要执行的命令(完整 shell,不受白名单约束;但不能含 & 或 |,请拆成多条调用)。Linux 下通过 POSIX shell 执行,可用 ; 串联且退出码取最后一条命令", + "type": "string" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "session_id": { + "description": "terminal_open 返回的 session_id", + "type": "string" + }, + "timeout_ms": { + "description": "等待输出完成的超时毫秒数(可选,默认 20000,上限 600000)", + "type": "integer" + } + }, + "required": [ + "id", + "session_id", + "command" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "exit_code": { + "description": "退出码:PTY 客户端(Windows ConPTY / Linux PTY)为命令的真实退出码;老客户端(非 PTY)仅区分 0/非 0;-1=未知(进程异常退出)", + "type": "integer" + }, + "stdout": { + "description": "命令输出(已剥哨兵与 ANSI 转义)", + "type": "string" + } + }, + "required": [ + "stdout", + "exit_code" + ], + "type": "object" + } + }, + { + "name": "terminal_close", + "description": "关闭并释放指定持久会话(幂等:会话已不存在也返回成功)。", + "gate": "terminal", + "write": true, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "session_id": { + "description": "terminal_open 返回的 session_id", + "type": "string" + } + }, + "required": [ + "id", + "session_id" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "closed": { + "description": "恒为 true(关闭幂等)", + "type": "boolean" + } + }, + "required": [ + "closed" + ], + "type": "object" + } + }, + { + "name": "remote_open", + "description": "在指定在线 Windows 或 Linux 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id 与物理屏幕分辨率(screen_w/screen_h)。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入;多显示器暂不支持。", + "gate": "remote_control", + "write": true, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "timeout_ms": { + "description": "等待屏幕子连接建立 + 分辨率到达的超时毫秒数(可选,默认 20000,上限 600000)", + "type": "integer" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "screen_h": { + "description": "物理屏幕高度(虚拟桌面像素)", + "type": "integer" + }, + "screen_w": { + "description": "物理屏幕宽度(虚拟桌面像素),用于把归一化坐标 0..1 映射为像素", + "type": "integer" + }, + "session_id": { + "description": "控制会话 token,后续 remote_mouse / remote_keyboard / remote_close 用", + "type": "string" + } + }, + "required": [ + "session_id", + "screen_w", + "screen_h" + ], + "type": "object" + } + }, + { + "name": "remote_close", + "description": "关闭并释放指定远程控制会话(幂等:会话已不存在也返回成功)。", + "gate": "remote_control", + "write": true, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "session_id": { + "description": "remote_open 返回的 session_id", + "type": "string" + } + }, + "required": [ + "id", + "session_id" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "closed": { + "description": "恒为 true(幂等)", + "type": "boolean" + } + }, + "required": [ + "closed" + ], + "type": "object" + } + }, + { + "name": "remote_keyboard", + "description": "向已建立的远程控制会话注入键盘事件。action 可选 key_down / key_up / key_press / type:前三种需 key(虚拟键名,如 ENTER/TAB/F5/LEFT/CTRL/ALT/SHIFT/WIN,Linux 侧映射为 X11 keysym),type 需 text(仅 ASCII 文本;非 ASCII 请用 remote_clipboard + Ctrl+V)。modifiers 可选(CTRL/ALT/SHIFT/WIN)。", + "gate": "remote_control", + "write": true, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "action": { + "description": "动作:key_down / key_up / key_press / type", + "type": "string" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "key": { + "description": "按键(key_down/key_up/key_press 用):Windows 虚拟键名(如 ENTER/TAB/F5/LEFT/CTRL/ALT/SHIFT/WIN)或单个字母/数字", + "type": "string" + }, + "modifiers": { + "description": "修饰键(可选):CTRL/ALT/SHIFT/WIN", + "items": { + "type": "string" + }, + "type": "array" + }, + "session_id": { + "description": "remote_open 返回的 session_id", + "type": "string" + }, + "text": { + "description": "文本(type 用,仅 ASCII;非 ASCII 请走 remote_clipboard + Ctrl+V)", + "type": "string" + } + }, + "required": [ + "id", + "session_id", + "action" + ], + "type": "object" + }, + "outputSchema": { + "properties": {}, + "type": "object" + } + }, + { + "name": "remote_mouse", + "description": "向已建立的远程控制会话注入鼠标事件。action 可选 move / down / up / click / right_click / middle_click / drag / scroll;坐标 x/y(及 drag 的 x2/y2)为归一化 0..1 浮点。button 可选 left/middle/right(默认 left);click 的 clicks 可选 1/2/3(默认 1);scroll 的 delta 正=向下滚、负=向上滚。", + "gate": "remote_control", + "write": true, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "action": { + "description": "动作:move / down / up / click / right_click / middle_click / drag / scroll", + "enum": [ + "move", + "down", + "up", + "click", + "right_click", + "middle_click", + "drag", + "scroll" + ], + "type": "string" + }, + "button": { + "description": "按键:left / middle / right(默认 left)", + "enum": [ + "left", + "middle", + "right" + ], + "type": "string" + }, + "clicks": { + "description": "点击次数 1/2/3(仅 click,默认 1)", + "type": "integer" + }, + "delta": { + "description": "滚动量(仅 scroll;正=向下滚,负=向上滚,与 Web 控制台一致;仅垂直滚轮,忽略 button)", + "type": "integer" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "session_id": { + "description": "remote_open 返回的 session_id", + "type": "string" + }, + "x": { + "description": "归一化 X 坐标(0=屏幕最左,1=最右)", + "type": "number" + }, + "x2": { + "description": "拖拽终点 X(仅 drag)", + "type": "number" + }, + "y": { + "description": "归一化 Y 坐标(0=屏幕最上,1=最下)", + "type": "number" + }, + "y2": { + "description": "拖拽终点 Y(仅 drag)", + "type": "number" + } + }, + "required": [ + "id", + "session_id", + "action", + "x", + "y" + ], + "type": "object" + }, + "outputSchema": { + "properties": {}, + "type": "object" + } + }, + { + "name": "remote_clipboard", + "description": "把文本写入远程主机的剪贴板(服务端按 GBK/ANSI 下发,Linux 客户端自动转回 UTF-8;非 GBK 字符如 emoji 会丢失)。仅设置剪贴板,粘贴需随后用 remote_keyboard 注入 Ctrl+V;Linux 需要 X11 桌面与 xclip/xsel。", + "gate": "remote_control", + "write": true, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "session_id": { + "description": "remote_open 返回的 session_id", + "type": "string" + }, + "text": { + "description": "要写入剪贴板的文本(UTF-8;非 GBK 字符如 emoji 会丢失)", + "type": "string" + } + }, + "required": [ + "id", + "session_id", + "text" + ], + "type": "object" + }, + "outputSchema": { + "properties": {}, + "type": "object" + } + }, + { + "name": "remote_block_input", + "description": "锁定或解除目标 Windows 主机的本机键鼠。做 GUI 自动化时先 block=true,真人碰一下鼠标就不会打断流程。必须带期限:max_block_ms(默认 300000 毫秒)到期由服务端自动解除,并在下一次调用结果的 auto_unblocked 里上报;remote_close 或会话闲置回收时服务端也会强制解除。两个限制:1) Windows 只在调用进程具备管理员权限(或 UIAccess)时才允许 BlockInput,普通权限的客户端会静默失败且不上报结果,所以本工具的成功只代表命令已送达、不保证真的锁住了——不要凭它断言对端已被锁;2) 若屏幕子连接因目标机断网被拆,服务端也再没有下发通道,只能等客户端进程退出(BlockInput 随调用线程结束自动释放)。仅 Windows 支持(Linux 客户端不处理该报文,直接报 -32005)。", + "gate": "remote_control", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "block": { + "description": "true=锁定对端键鼠,false=解除。必填(没有默认值,避免误锁)", + "type": "boolean" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "max_block_ms": { + "description": "锁定自动解除期限(毫秒),仅 block=true 时有效;默认 300000,范围 1000..3600000。到期由服务端强制解除并记入下一次结果的 auto_unblocked", + "type": "integer" + }, + "session_id": { + "description": "remote_open 返回的 session_id", + "type": "string" + } + }, + "required": [ + "id", + "session_id", + "block" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "auto_unblocked": { + "description": "上一次锁定是否因超过 max_block_ms 被服务端自动解除(本次调用取走该通知)", + "type": "boolean" + }, + "blocked": { + "description": "本次调用后的锁定状态", + "type": "boolean" + }, + "max_block_ms": { + "description": "本次锁定的自动解除期限(毫秒);blocked=false 时为 0(无待解除的锁定)", + "type": "integer" + } + }, + "required": [ + "blocked", + "max_block_ms", + "auto_unblocked" + ], + "type": "object" + } + }, + { + "name": "download_file", + "description": "从指定在线主机下载文件或目录到主控本机(V2 协议,逐文件 SHA-256 校验)。支持 Windows 与 Linux/macOS 主机;remote_path 为远程绝对路径(文件或目录,目录递归下载),Windows 用 D:\\data\\a.txt 这类盘符路径,Linux/macOS 用 /home/user/a.txt 这类绝对 POSIX 路径;local_dir 为本机保存目录;overwrite=false 时跳过已存在文件。返回 files[{path,size,sha256}] 与 total_bytes/skipped。", + "gate": "file_transfer", + "write": true, + "platforms": [ + "win", + "lnx", + "mac" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "local_dir": { + "description": "主控本机保存目录(不存在则自动创建),如 C:\\Downloads", + "type": "string" + }, + "overwrite": { + "description": "是否覆盖已存在的同名文件;默认 false(跳过并计入 skipped)", + "type": "boolean" + }, + "remote_path": { + "description": "远程绝对路径(文件或目录;目录递归下载)。Windows 主机用 C:\\Users\\foo\\Pictures,Linux/macOS 主机用 /home/user/data 这类绝对 POSIX 路径", + "type": "string" + }, + "timeout_ms": { + "description": "超时毫秒(默认 600000=10 分钟,上限 3600000=1 小时)", + "type": "integer" + } + }, + "required": [ + "id", + "remote_path", + "local_dir" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "files": { + "items": { + "properties": { + "path": { + "type": "string" + }, + "sha256": { + "type": "string" + }, + "size": { + "type": "integer" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "type": "integer" + }, + "total_bytes": { + "type": "integer" + } + }, + "type": "object" + } + }, + { + "name": "upload_file", + "description": "把主控本机文件或目录上传到指定在线主机的目录(V2 协议,主连接发送)。支持 Windows 与 Linux/macOS 主机;local_path 为主控本机绝对路径(文件或目录,目录递归上传);remote_dir 为远程保存目录(不存在自动创建),Windows 用 C:\\uploads 这类盘符路径,Linux/macOS 用 /home/user/uploads 这类绝对 POSIX 路径;overwrite=false 时跳过 remote_dir 下已存在的同名顶层项。返回 files[{path,size,sha256}] 与 total_bytes/skipped/receiver_ack;sha256 恒为空(发送端不计算)。receiver_ack=true 表示目标端已确认写入(Linux 客户端回执),false 表示目标端没有回执(Windows 目标、老客户端或 macOS),此时需要确证请用 list_files 复核。", + "gate": "file_transfer", + "write": true, + "platforms": [ + "win", + "lnx", + "mac" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "local_path": { + "description": "主控本机文件或目录的绝对路径(目录递归上传),如 C:\\Users\\foo\\Pictures", + "type": "string" + }, + "overwrite": { + "description": "是否覆盖 remote_dir 下已存在的同名顶层文件/目录;默认 false(跳过并计入 skipped)", + "type": "boolean" + }, + "remote_dir": { + "description": "远程主机的保存目录(不存在则自动创建)。Windows 主机如 C:\\uploads,Linux/macOS 主机用 /home/user/uploads 这类绝对 POSIX 路径", + "type": "string" + }, + "timeout_ms": { + "description": "超时毫秒(默认 600000=10 分钟,上限 3600000=1 小时)", + "type": "integer" + } + }, + "required": [ + "id", + "local_path", + "remote_dir" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "files": { + "items": { + "properties": { + "path": { + "type": "string" + }, + "sha256": { + "type": "string" + }, + "size": { + "type": "integer" + } + }, + "type": "object" + }, + "type": "array" + }, + "receiver_ack": { + "type": "boolean" + }, + "skipped": { + "type": "integer" + }, + "total_bytes": { + "type": "integer" + } + }, + "type": "object" + } + }, + { + "name": "copy_files_c2c", + "description": "在两个在线主机之间直接拷贝文件(V2 C2C:源主机自己发、目标主机自己收,服务端只中继,不在主控落盘)。源主机必须是 Windows;目标主机可以是 Windows 或 Linux/macOS。paths 为源主机绝对路径(文件或目录,目录递归、保留相对目录结构);dst_dir 为目标主机保存目录(不存在自动创建),Windows 目标用 D:\\Incoming 这类绝对路径,Linux/macOS 目标用 /home/user/incoming 这类绝对 POSIX 路径。overwrite 默认 false:目标目录已存在同名顶层项时跳过并计入 skipped(目标端是无条件覆盖写,不跳过就会每次全量重发);预检本身失败(目标主机忙/超时/拒绝访问)不报错,退回全发并置 skip_check_failed=true。返回 transfer_id/file_count/total_bytes/skipped/skip_check_failed/receiver_ack:receiver_ack=true 表示目标端已确认写入(Linux 客户端回执),false 表示目标端没有回执(Windows 目标、老客户端或 macOS),此时需要确证请用 list_files 复核。", + "gate": "file_transfer", + "write": true, + "platforms": [ + "win", + "lnx", + "mac" + ], + "roles": { + "src_id": [ + "win" + ], + "dst_id": [ + "win", + "lnx", + "mac" + ] + }, + "impl": "mfc", + "inputSchema": { + "properties": { + "dst_dir": { + "description": "目标主机保存目录(绝对路径,不存在自动创建):Windows 目标如 D:\\Incoming,Linux/macOS 目标如 /home/user/incoming", + "type": "string" + }, + "dst_id": { + "description": "目标主机 id(文件落在这里),同上", + "type": "string" + }, + "overwrite": { + "description": "目标目录已存在同名顶层项时是否覆盖重传。默认 false:跳过并计入 skipped(不发起传输)。目标端收包是无条件覆盖写,所以默认 false 才能避免重复调用时全量重发。", + "type": "boolean" + }, + "paths": { + "description": "源主机上的绝对路径列表(文件或目录;目录递归发送,保留相对目录结构)", + "items": { + "type": "string" + }, + "type": "array" + }, + "src_id": { + "description": "源主机 id(文件从这里发出),取 list_online_hosts / search_hosts 返回的 id", + "type": "string" + }, + "timeout_ms": { + "description": "超时毫秒(默认 600000=10 分钟,上限 3600000=1 小时);超时不代表传输失败", + "type": "integer" + } + }, + "required": [ + "src_id", + "dst_id", + "paths", + "dst_dir" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "dst_dir": { + "type": "string" + }, + "dst_id": { + "type": "string" + }, + "file_count": { + "type": "integer" + }, + "receiver_ack": { + "type": "boolean" + }, + "skip_check_failed": { + "type": "boolean" + }, + "skipped": { + "type": "integer" + }, + "src_id": { + "type": "string" + }, + "total_bytes": { + "type": "integer" + }, + "transfer_id": { + "type": "string" + } + }, + "type": "object" + } + }, + { + "name": "kill_process", + "description": "终止指定在线 Windows 或 Linux 主机上的一个或多个进程(Windows 用 TerminateProcess,Linux 用 SIGKILL 强制结束,不保存进程状态,可能造成数据丢失;Linux 会忽略 pid<=1)。返回 remaining(杀完后仍在运行的 PID)。不可撤销,请谨慎确认 PID。dry_run=true 只取一次进程列表校验 PID 是否存在,返回将被影响的进程(targets)与已不存在的 PID(missing),不发送终止命令——执行前可先用它把清单交给用户确认。", + "gate": "manage", + "write": true, + "platforms": [ + "win", + "lnx" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "dry_run": { + "description": "true 时只校验 PID 是否还存在并返回将被影响的对象,不发送任何终止命令(默认 false)", + "type": "boolean" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "pids": { + "description": "要终止的进程 PID 列表(至少 1 个)", + "items": { + "type": "integer" + }, + "type": "array" + } + }, + "required": [ + "id", + "pids" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "dry_run": { + "description": "true 表示本次只是试运行(dry_run),没有发送终止命令", + "type": "boolean" + }, + "missing": { + "description": "dry_run 时已不存在的 PID", + "type": "array" + }, + "remaining": { + "description": "杀完后仍在运行的 PID(含权限不足未能终止的)", + "items": { + "type": "integer" + }, + "type": "array" + }, + "targets": { + "description": "dry_run 时将被终止的进程(pid/name/path)", + "type": "array" + } + }, + "type": "object" + } + }, + { + "name": "operate_window", + "description": "对指定在线 Windows 主机的窗口执行操作:close(关闭)/show(显示)/hide(隐藏)/minimize(最小化)/maximize(最大化)/restore(还原)。hwnd 取 list_windows 或 host_list_windows 返回的 hwnd。ok 仅表示已下发(窗口句柄可能已失效)。关闭窗口只有本工具能做,host_control_window 不提供 close,且它会重新枚举可见窗口复核结果。dry_run=true 只校验 hwnd 是否还在可见窗口列表里并返回该窗口信息,不发送任何命令。", + "gate": "manage", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "action": { + "description": "操作:close(关闭) | show(显示) | hide(隐藏) | minimize(最小化) | maximize(最大化) | restore(还原)", + "type": "string" + }, + "dry_run": { + "description": "true 时只校验窗口是否还存在并返回将被影响的对象,不发送任何窗口命令(默认 false)", + "type": "boolean" + }, + "hwnd": { + "description": "窗口句柄,取 list_windows 返回的 hwnd 字段", + "type": "integer" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + } + }, + "required": [ + "id", + "hwnd", + "action" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "action": { + "type": "string" + }, + "dry_run": { + "description": "true 表示本次只是试运行(dry_run),没有发送窗口命令", + "type": "boolean" + }, + "ok": { + "description": "命令已下发(不代表窗口已按预期变化)", + "type": "boolean" + }, + "window": { + "description": "dry_run 时的目标窗口(hwnd/title/status/pid)", + "type": "object" + } + }, + "type": "object" + } + }, + { + "name": "control_service", + "description": "控制指定在线 Windows 主机的服务:start(启动)/stop(停止)/set_auto(设为自动)/set_manual(设为手动)。service_name 取 list_services 返回的 service_name。ok 仅表示已下发(成功与否需再查 list_services 核对状态)。", + "gate": "manage", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "action": { + "description": "操作:start(启动) | stop(停止) | set_auto(设为自动) | set_manual(设为手动)", + "type": "string" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "service_name": { + "description": "服务名,取 list_services 返回的 service_name 字段", + "type": "string" + } + }, + "required": [ + "id", + "service_name", + "action" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "ok": { + "type": "boolean" + } + }, + "type": "object" + } + }, + { + "name": "power_action", + "description": "对指定在线 Windows 主机执行电源操作:logout(注销)/shutdown(关机)/reboot(重启)。不可撤销,主机将立即下线;需客户端管理员权限。ok/sent 只代表命令已送达,不代表真的关了机:要验证就给 wait=true,工具会等主机从在线列表消失(went_offline)、再等它重新上线(came_back),并返回 elapsed_ms;每个阶段最多等 wait_ms(默认 60000),等不到不算失败。注销后客户端一般不会自动回线。", + "gate": "manage", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "action": { + "description": "操作:logout(注销) | shutdown(关机) | reboot(重启)", + "type": "string" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "wait": { + "description": "true 时先等主机下线、再等它重新上线(默认 false,发完即返回)。超时不算失败,看返回的 went_offline / came_back。", + "type": "boolean" + }, + "wait_ms": { + "description": "等离线与等回线各自的时限(毫秒,默认 60000);一次调用最长约为 2×wait_ms", + "maximum": 600000, + "minimum": 1000, + "type": "integer" + } + }, + "required": [ + "id", + "action" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "came_back": { + "description": "主机下线后是否重新上线(logout 一般不会自动回来)", + "type": "boolean" + }, + "elapsed_ms": { + "description": "本次等待实际耗时(毫秒)", + "type": "integer" + }, + "ok": { + "description": "命令已下发(不代表已经关机/重启)", + "type": "boolean" + }, + "sent": { + "description": "命令已送达主机", + "type": "boolean" + }, + "went_offline": { + "description": "主机是否真的下线了(wait=true 时观察到的;wait=false 恒为 false)", + "type": "boolean" + } + }, + "type": "object" + } + }, + { + "name": "host_set_remark", + "description": "给主机设置备注(在线或离线历史记录都可)。只写入服务端本地主机库,不向客户端下发任何命令;remark 传空字符串表示清除备注,GBK 编码后最长 63 字节。", + "gate": null, + "write": true, + "platforms": [ + "win", + "lnx", + "mac", + "apk" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id(list_online_hosts / list_all_hosts 返回的十进制字符串)。", + "type": "string" + }, + "remark": { + "description": "备注文本(UTF-8);空字符串表示清除备注;GBK 编码后最长 63 字节。", + "type": "string" + } + }, + "required": [ + "id", + "remark" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "id": { + "type": "string" + }, + "remark": { + "type": "string" + } + }, + "type": "object" + } + }, + { + "name": "host_set_watch_level", + "description": "设置主机在服务端在线列表里的关注等级:0=无、1=蓝字、2=红字、3=红底。只影响主控端本机显示,重复设置同一等级幂等。", + "gate": null, + "write": true, + "platforms": [ + "win", + "lnx", + "mac", + "apk" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id(在线或离线历史记录均可)。", + "type": "string" + }, + "level": { + "description": "关注等级:0=无、1=蓝字、2=红字、3=红底(服务端在线列表现色)。", + "maximum": 3, + "minimum": 0, + "type": "integer" + } + }, + "required": [ + "id", + "level" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "id": { + "type": "string" + }, + "level": { + "type": "integer" + } + }, + "type": "object" + } + }, + { + "name": "search_file", + "description": "在指定主机(仅 Windows)的某个目录下按文件名搜索文件(不区分大小写;pattern 不含通配符时按子串匹配,含 * / ? 时按通配符匹配)。客户端始终递归子目录(深度 32、最多 10000 条,跳过隐藏+系统目录与符号链接),结果边搜边收集、按 limit/offset 分页;finished=false 表示到达 timeout_ms 时限、返回的是部分结果(服务端已通知客户端停止搜索)。单次最多收集 5000 条 / 4 MB,超出时 truncated=true。可选 min_size / max_size(字节)与 modified_after(YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS)在服务端做结果侧过滤,name_only=true 只返回 path 与 name;这些过滤不减少客户端搜索耗时,total 为命中数、totalAll 为过滤前条数。注意:客户端用 char[MAX_PATH] 缓冲拼路径,超过 260 字节的路径会被静默跳过(既不记录也不继续向下递归),所以从盘符根扫描会漏掉深层结果、也更容易先撞上 10000 条上限;请尽量指定具体的中浅层目录(服务端已把 path/pattern 限在 200 字节 GBK 内,给客户端留出余量)。", + "gate": null, + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id(Windows 客户端)。", + "type": "string" + }, + "limit": { + "description": "本次最多返回的条数,默认 100,上限 1000。", + "type": "integer" + }, + "max_size": { + "description": "只保留不大于该字节数的条目。与 min_size 同时给出时区间取交集。", + "type": "integer" + }, + "min_size": { + "description": "只保留大小不小于该字节数的条目。目录项也会参与比较(客户端上报的目录 size 恒为 0),只想看文件时用 min_size=1。", + "type": "integer" + }, + "modified_after": { + "description": "只保留修改时间晚于该时刻的条目,格式 YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS(主机本地时间)。只给日期时按「该日 00:00:00 之后」理解。", + "type": "string" + }, + "name_only": { + "description": "true 时每条只返回 path 与 name,省略 dir/size/modified,用于结果集很大时省流量。默认 false。", + "type": "boolean" + }, + "offset": { + "description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。", + "type": "integer" + }, + "path": { + "description": "搜索的根目录,例如 C:\\Users 或 D:\\Data(必须是完整路径)。", + "type": "string" + }, + "pattern": { + "description": "文件名匹配串(不区分大小写),例如 report、.log、setup.exe;不含通配符时按子串匹配,含 * 或 ? 时按通配符匹配(如 *.log)。", + "type": "string" + }, + "recursive": { + "description": "是否包含子目录,默认 true。客户端只支持递归搜索,传 false 时由服务端过滤出根目录下的直接子项(搜索耗时不变)。", + "type": "boolean" + }, + "timeout_ms": { + "description": "搜索时限(毫秒),默认 20000,范围 1000-120000。到时限会通知客户端停止搜索,返回已收到的部分结果(finished=false)。", + "type": "integer" + } + }, + "required": [ + "id", + "path", + "pattern" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "files": { + "items": { + "type": "object" + }, + "type": "array" + }, + "finished": { + "type": "boolean" + }, + "truncated": { + "type": "boolean" + } + }, + "type": "object" + } + }, + { + "name": "delete_path", + "description": "删除指定主机(仅 Windows)上的文件或目录。recursive=false(默认)删除单个文件;recursive=true 递归删除整个目录及其全部内容——没有回收站,不可恢复。path 必须是绝对路径(C:\\... 或 \\\\server\\share\\...),不接受相对路径,也不接受含 %VAR% 环境变量的路径(客户端会展开,服务端无法校验真实目标)。服务端一律拒绝盘符/共享根,以及系统目录(Windows、Program Files、Program Files (x86)、ProgramData、$Recycle.Bin、System Volume Information)及其子树——需要清理这些位置请改用 exec_command 或逐项确认。客户端对删除命令无条件回完成包(根本不看 DeleteFile 的返回值),所以 ok 只代表命令已送达;真正的结果看 verified:true=复核确认目标已不在,false=复核确认目标还在(只读文件会静默失败,被占用/权限不足同理),null=复核没做成(列目录超时或断线),此时请自己用 list_files 再确认。注意目标本来就不存在时客户端同样回完成包、复核也只能看到「现在没有这个名字」,所以会表现为 verified=true——动手前最好先 list_files 确认目标确实存在。", + "gate": "file_write", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id(Windows 客户端)。", + "type": "string" + }, + "path": { + "description": "要删除的绝对路径(文件或目录),例如 C:\\Temp\\old.log;不能含 %VAR%,不能是盘符根。", + "type": "string" + }, + "recursive": { + "description": "true=按目录递归删除(COMMAND_DELETE_DIRECTORY,连同子目录内容一起删);默认 false=按单个文件删除。目标其实是目录却传 false 时,客户端 DeleteFile 会失败(复核会返回 verified=false)。", + "type": "boolean" + } + }, + "required": [ + "id", + "path" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "ok": { + "description": "命令已送达客户端并收到完成回包。客户端的完成包是无条件回包,不代表操作成功。", + "type": "boolean" + }, + "verified": { + "description": "复核结果:true=确认已生效,false=确认未生效,null=复核没做成(结果未知)。", + "type": [ + "boolean", + "null" + ] + } + }, + "type": "object" + } + }, + { + "name": "move_path", + "description": "重命名或移动指定主机(仅 Windows)上的文件或目录:把 from 改成 to,to 必须是完整的新路径(含新名字)。客户端用 ::MoveFile,只能在同一卷内移动;跨盘请改用 download_file + upload_file。目录也支持(同一卷内整体移动)。from 不能是盘符/共享根或系统目录(Windows、Program Files、ProgramData 等),to 只拒绝根路径;from 与 to 都必须是不含 %VAR% 的绝对路径。ok 只代表命令已送达(客户端无条件回完成包),verified=true 表示复核确认 to 已出现在父目录里,false 表示没出现(目标已存在、跨卷、只读或被占用),null 表示复核没做成。", + "gate": "file_write", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "from": { + "description": "原来的绝对路径(文件或目录),例如 C:\\Temp\\a.txt。", + "type": "string" + }, + "id": { + "description": "主机 id(Windows 客户端)。", + "type": "string" + }, + "to": { + "description": "新的完整路径(含新名字),例如 C:\\Temp\\b.txt;必须在同一卷内。", + "type": "string" + } + }, + "required": [ + "id", + "from", + "to" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "ok": { + "description": "命令已送达客户端并收到完成回包。客户端的完成包是无条件回包,不代表操作成功。", + "type": "boolean" + }, + "verified": { + "description": "复核结果:true=确认已生效,false=确认未生效,null=复核没做成(结果未知)。", + "type": [ + "boolean", + "null" + ] + } + }, + "type": "object" + } + }, + { + "name": "create_folder", + "description": "在指定主机(仅 Windows)上创建目录。客户端用 MakeSureDirectoryPathExists,会连同缺失的中间层一起建(C:\\a\\b\\c 会把 a、b 也建出来),目录已存在时同样算成功。path 若误带上了文件名,就会建出一个同名目录——本工具不会创建文件,也不会覆盖同名文件(那种情况 verified=false)。path 必须是绝对路径,不能含 %VAR%,不能是盘符/共享根。ok 只代表命令已送达,verified=true 表示复核确认该目录已存在且确实是目录,false 表示复核时没看到它(权限不足、被同名文件占用等),null 表示复核没做成。", + "gate": "file_write", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id(Windows 客户端)。", + "type": "string" + }, + "path": { + "description": "要创建的目录绝对路径,例如 C:\\Temp\\report\\2026;缺失的中间层会一并创建。", + "type": "string" + } + }, + "required": [ + "id", + "path" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "ok": { + "description": "命令已送达客户端并收到完成回包。客户端的完成包是无条件回包,不代表操作成功。", + "type": "boolean" + }, + "verified": { + "description": "复核结果:true=确认已生效,false=确认未生效,null=复核没做成(结果未知)。", + "type": [ + "boolean", + "null" + ] + } + }, + "type": "object" + } + }, + { + "name": "list_network_connections", + "description": "列出指定在线 Windows 主机的 TCP/UDP 连接(相当于「连接管理」对话框)。返回四元组、所属进程与 TCP 状态;killable=true 表示该连接可被 kill_network_connection 断开。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "family": { + "description": "地址族过滤,默认 all", + "enum": [ + "ipv4", + "ipv6", + "all" + ], + "type": "string" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回条数,默认 100,上限 1000", + "type": "integer" + }, + "local_port": { + "type": "integer" + }, + "offset": { + "description": "分页起点,默认 0", + "type": "integer" + }, + "pid": { + "description": "按进程 PID 过滤", + "type": "integer" + }, + "process": { + "description": "按进程名子串过滤(不区分大小写)", + "type": "string" + }, + "protocol": { + "description": "协议过滤,默认 all", + "enum": [ + "tcp", + "udp", + "all" + ], + "type": "string" + }, + "remote_address": { + "description": "按远端地址子串过滤", + "type": "string" + }, + "remote_port": { + "type": "integer" + }, + "state": { + "description": "按状态过滤:数字(MIB_TCP_STATE_*)或状态名子串,如 ESTABLISHED", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "connections": { + "items": { + "properties": { + "family": { + "description": "ipv4 / ipv6", + "type": "string" + }, + "killable": { + "description": "是否可被 kill_network_connection 强制断开(仅 IPv4 TCP)", + "type": "boolean" + }, + "localAddress": { + "type": "string" + }, + "localPort": { + "type": "integer" + }, + "pid": { + "type": "integer" + }, + "process": { + "type": "string" + }, + "protocol": { + "description": "tcp / udp", + "type": "string" + }, + "remoteAddress": { + "type": "string" + }, + "remotePort": { + "type": "integer" + }, + "state": { + "description": "MIB_TCP_STATE_* 原始值", + "type": "integer" + }, + "stateName": { + "description": "TCP 状态名;UDP 为空", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "description": "过滤后的条目数", + "type": "integer" + }, + "totalAll": { + "description": "未过滤的条目总数", + "type": "integer" + } + }, + "required": [ + "connections" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "kill_network_connection", + "description": "强制断开指定在线 Windows 主机上的一条 IPv4 TCP 连接(客户端调 SetTcpEntry DELETE_TCB)。必须提供完整四元组;目标不存在返回 -32009(请先刷新 list_network_connections)。断开后会用客户端自动刷新回来的列表复核,若连接仍在则 ok=false、reason=still_present(常见原因:客户端无管理员权限)。", + "gate": "machine", + "write": true, + "manage": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "dry_run": { + "description": "true 时只校验目标存在,不发断开命令,默认 false", + "type": "boolean" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "local_address": { + "description": "本地 IPv4 地址,如 192.168.0.55", + "type": "string" + }, + "local_port": { + "description": "本地端口(主机序)", + "type": "integer" + }, + "pid": { + "description": "可选:同时校验所属进程 PID(多行匹配时用于消歧)", + "type": "integer" + }, + "protocol": { + "description": "协议,默认 tcp(仅 IPv4 TCP 可断开)", + "enum": [ + "tcp", + "udp" + ], + "type": "string" + }, + "remote_address": { + "description": "远端 IPv4 地址", + "type": "string" + }, + "remote_port": { + "description": "远端端口(主机序)", + "type": "integer" + } + }, + "required": [ + "id", + "local_address", + "local_port", + "remote_address", + "remote_port" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "action": { + "type": "string" + }, + "changed": { + "description": "是否真的改变了状态(如服务本来就是目标状态时为 false)", + "type": "boolean" + }, + "detail": { + "description": "dry_run 时目标对象的完整字段", + "type": "object" + }, + "dry_run": { + "description": "true 表示只是试运行,没有下发动作", + "type": "boolean" + }, + "message": { + "description": "人类可读的说明", + "type": "string" + }, + "ok": { + "description": "动作是否达到预期(false 表示未生效/无法确认,不会伪报成功)", + "type": "boolean" + }, + "reason": { + "description": "ok=false 时的原因", + "type": "string" + }, + "state": { + "description": "复核时观测到的状态", + "type": "string" + }, + "target": { + "type": "string" + }, + "verified": { + "description": "是否已用动作后的最新快照复核", + "type": "boolean" + } + }, + "required": [ + "ok" + ], + "type": "object" + } + }, + { + "name": "host_list_processes", + "description": "列出在线 Windows 主机的进程(主机管理「进程」标签页)。返回 PID、架构、窗口标题、路径、优先级、线程数、用户、工作集与文件大小。首选:与 list_processes 同源但字段更全,并支持服务端过滤(pid / name / arch),仅在它没有出现在 tools/list 里(McpMachine=0)时退回 list_processes。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "arch": { + "description": "按架构过滤", + "enum": [ + "x86", + "x64" + ], + "type": "string" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回条数,默认 100,上限 1000", + "type": "integer" + }, + "name": { + "description": "按进程名子串过滤", + "type": "string" + }, + "offset": { + "description": "分页起点,默认 0", + "type": "integer" + }, + "pid": { + "description": "按 PID 过滤", + "type": "integer" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "processes": { + "items": { + "properties": { + "arch": { + "description": "x86 / x64", + "type": "string" + }, + "fileSizeKb": { + "type": "integer" + }, + "name": { + "description": "可执行文件名", + "type": "string" + }, + "path": { + "type": "string" + }, + "pid": { + "type": "integer" + }, + "priority": { + "description": "优先级名称", + "type": "string" + }, + "priorityClass": { + "description": "Windows 优先级类原始值", + "type": "integer" + }, + "threads": { + "type": "integer" + }, + "title": { + "description": "进程主窗口标题", + "type": "string" + }, + "user": { + "type": "string" + }, + "workingSetKb": { + "type": "integer" + } + }, + "type": "object" + }, + "type": "array" + }, + "total": { + "description": "过滤后的条目数", + "type": "integer" + }, + "totalAll": { + "description": "未过滤的条目总数", + "type": "integer" + } + }, + "required": [ + "processes" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "host_list_windows", + "description": "列出在线 Windows 主机上当前可见的顶层窗口(主机管理「窗口」标签页)。只包含可见窗口,故隐藏后窗口会从结果中消失。hwnd 可用于 host_control_window 或 operate_window。首选:支持服务端过滤(pid / title),仅在它没有出现在 tools/list 里(McpMachine=0)时退回 list_windows。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回条数,默认 100,上限 1000", + "type": "integer" + }, + "offset": { + "description": "分页起点,默认 0", + "type": "integer" + }, + "pid": { + "description": "按所属进程 PID 过滤", + "type": "integer" + }, + "title": { + "description": "按窗口标题子串过滤", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "description": "过滤后的条目数", + "type": "integer" + }, + "totalAll": { + "description": "未过滤的条目总数", + "type": "integer" + }, + "windows": { + "items": { + "properties": { + "canSee": { + "description": "客户端是否可抓取该窗口画面", + "type": "boolean" + }, + "height": { + "type": "integer" + }, + "hwnd": { + "description": "窗口句柄(十进制)", + "type": "integer" + }, + "pid": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "width": { + "type": "integer" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "windows" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "host_list_network_state", + "description": "列出在线 Windows 主机的网络连接及其所属进程(主机管理「网络状态」标签页)。数据来源与「连接管理」不同(这里是进程视角、含 UDP 的无对端标记);仅支持 IPv4 展示。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回条数,默认 100,上限 1000", + "type": "integer" + }, + "local_port": { + "type": "integer" + }, + "offset": { + "description": "分页起点,默认 0", + "type": "integer" + }, + "pid": { + "type": "integer" + }, + "process": { + "description": "按进程名子串过滤", + "type": "string" + }, + "protocol": { + "description": "协议过滤", + "enum": [ + "tcp", + "udp" + ], + "type": "string" + }, + "remote_port": { + "type": "integer" + }, + "state": { + "description": "按状态子串过滤", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "connections": { + "items": { + "properties": { + "localAddress": { + "type": "string" + }, + "localEndpoint": { + "description": "地址:端口", + "type": "string" + }, + "localPort": { + "type": "integer" + }, + "pid": { + "type": "integer" + }, + "process": { + "type": "string" + }, + "protocol": { + "description": "tcp / udp", + "type": "string" + }, + "remoteAddress": { + "type": "string" + }, + "remoteEndpoint": { + "description": "地址:端口;UDP 无对端时为 *.*.*.*:*", + "type": "string" + }, + "remotePort": { + "type": "integer" + }, + "state": { + "description": "TCP 状态;UDP 为空", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "description": "过滤后的条目数", + "type": "integer" + }, + "totalAll": { + "description": "未过滤的条目总数", + "type": "integer" + } + }, + "required": [ + "connections" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "host_list_software", + "description": "列出在线 Windows 主机已安装的软件(主机管理「软件」标签页,来自注册表 Uninstall 项)。只读;不提供卸载能力。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回条数,默认 100,上限 1000", + "type": "integer" + }, + "name": { + "description": "按软件名子串过滤", + "type": "string" + }, + "offset": { + "description": "分页起点,默认 0", + "type": "integer" + }, + "publisher": { + "description": "按发布者子串过滤", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "software": { + "items": { + "properties": { + "installDate": { + "type": "string" + }, + "name": { + "type": "string" + }, + "publisher": { + "type": "string" + }, + "uninstallString": { + "description": "卸载命令原文(本工具不执行)", + "type": "string" + }, + "version": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "total": { + "description": "过滤后的条目数", + "type": "integer" + }, + "totalAll": { + "description": "未过滤的条目总数", + "type": "integer" + } + }, + "required": [ + "software" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "host_list_browser_history", + "description": "列出在线 Windows 主机的 IE 浏览历史(主机管理「浏览记录」标签页)。隐私数据,仅在显式开启主机管理时可见。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回条数,默认 100,上限 1000", + "type": "integer" + }, + "offset": { + "description": "分页起点,默认 0", + "type": "integer" + }, + "title": { + "description": "按标题子串过滤", + "type": "string" + }, + "url": { + "description": "按 URL 子串过滤", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "hasMore": { + "type": "boolean" + }, + "history": { + "items": { + "properties": { + "time": { + "type": "string" + }, + "title": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "description": "过滤后的条目数", + "type": "integer" + }, + "totalAll": { + "description": "未过滤的条目总数", + "type": "integer" + } + }, + "required": [ + "history" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "host_list_favorites", + "description": "列出在线 Windows 主机的 IE 收藏夹(主机管理「收藏夹」标签页)。隐私数据,仅在显式开启主机管理时可见。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回条数,默认 100,上限 1000", + "type": "integer" + }, + "name": { + "description": "按收藏名子串过滤", + "type": "string" + }, + "offset": { + "description": "分页起点,默认 0", + "type": "integer" + }, + "url": { + "description": "按 URL 子串过滤", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "favorites": { + "items": { + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "description": "过滤后的条目数", + "type": "integer" + }, + "totalAll": { + "description": "未过滤的条目总数", + "type": "integer" + } + }, + "required": [ + "favorites" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "host_list_win32_services", + "description": "列出在线 Windows 主机的 Win32 服务(主机管理「服务」标签页之一)。返回显示名、描述、状态、启动类型、登录身份、服务名与可执行路径;服务名可用于 host_control_service。首选:支持服务端过滤(name / status),仅在它没有出现在 tools/list 里(McpMachine=0)时退回 list_services。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回条数,默认 100,上限 1000", + "type": "integer" + }, + "name": { + "description": "按服务名或显示名子串过滤", + "type": "string" + }, + "offset": { + "description": "分页起点,默认 0", + "type": "integer" + }, + "start_type": { + "description": "按启动类型子串过滤,如 Auto", + "type": "string" + }, + "status": { + "description": "按状态子串过滤,如 Running", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "services": { + "items": { + "properties": { + "binaryPath": { + "type": "string" + }, + "description": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "interactive": { + "type": "boolean" + }, + "login": { + "type": "string" + }, + "name": { + "description": "服务名(host_control_service 的 name 参数)", + "type": "string" + }, + "startType": { + "type": "string" + }, + "state": { + "description": "Running / Stopped / Paused / ...", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "total": { + "description": "过滤后的条目数", + "type": "integer" + }, + "totalAll": { + "description": "未过滤的条目总数", + "type": "integer" + } + }, + "required": [ + "services" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "host_list_driver_services", + "description": "列出在线 Windows 主机的驱动服务(主机管理「服务」标签页之一)。字段同 host_list_win32_services。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回条数,默认 100,上限 1000", + "type": "integer" + }, + "name": { + "description": "按服务名或显示名子串过滤", + "type": "string" + }, + "offset": { + "description": "分页起点,默认 0", + "type": "integer" + }, + "start_type": { + "description": "按启动类型子串过滤", + "type": "string" + }, + "status": { + "description": "按状态子串过滤", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "services": { + "items": { + "properties": { + "binaryPath": { + "type": "string" + }, + "description": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "interactive": { + "type": "boolean" + }, + "login": { + "type": "string" + }, + "name": { + "description": "服务名(host_control_service 的 name 参数)", + "type": "string" + }, + "startType": { + "type": "string" + }, + "state": { + "description": "Running / Stopped / Paused / ...", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "total": { + "description": "过滤后的条目数", + "type": "integer" + }, + "totalAll": { + "description": "未过滤的条目总数", + "type": "integer" + } + }, + "required": [ + "services" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "host_list_scheduled_tasks", + "description": "列出在线 Windows 主机的计划任务(主机管理「计划任务」标签页)。返回任务名、完整路径、所在文件夹、可执行文件、状态与上次/下次运行时间。任务名 + folder 可用于 host_control_task。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "folder": { + "description": "按任务文件夹子串过滤,如 \\Microsoft", + "type": "string" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "limit": { + "description": "本次最多返回条数,默认 100,上限 1000", + "type": "integer" + }, + "name": { + "description": "按任务名子串过滤", + "type": "string" + }, + "offset": { + "description": "分页起点,默认 0", + "type": "integer" + }, + "status": { + "description": "按状态子串过滤,如 Ready / Disabled", + "type": "string" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "hasMore": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "tasks": { + "items": { + "properties": { + "exe": { + "type": "string" + }, + "folder": { + "description": "任务所在文件夹(host_control_task 的 folder 参数)", + "type": "string" + }, + "lastRun": { + "description": "上次运行时间,未知为空", + "type": "string" + }, + "name": { + "type": "string" + }, + "nextRun": { + "description": "下次运行时间,未知为空", + "type": "string" + }, + "path": { + "type": "string" + }, + "status": { + "description": "Ready / Running / Disabled / ...", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "total": { + "description": "过滤后的条目数", + "type": "integer" + }, + "totalAll": { + "description": "未过滤的条目总数", + "type": "integer" + } + }, + "required": [ + "tasks" + ], + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "host_get_hosts_file", + "description": "读取在线 Windows 主机的 hosts 文件(主机管理「HOSTS」标签页),按行返回并自动识别 UTF-8/GBK。只读;不提供写入能力。", + "gate": "machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "ids": { + "description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。", + "items": { + "type": "string" + }, + "type": "array" + }, + "include_content": { + "description": "是否返回按行切分的内容,默认 true", + "type": "boolean" + }, + "max_bytes": { + "description": "最多返回的原始字节数,默认 262144,上限 1048576", + "type": "integer" + } + }, + "type": "object" + }, + "outputSchema": { + "anyOf": [ + { + "properties": { + "bytes": { + "description": "文件原始字节数", + "type": "integer" + }, + "content": { + "description": "未截断时的完整文本", + "type": "string" + }, + "encoding": { + "description": "utf-8 / gbk(自动探测)", + "type": "string" + }, + "lineCount": { + "type": "integer" + }, + "lines": { + "items": { + "type": "string" + }, + "type": "array" + }, + "path": { + "type": "string" + }, + "returnedBytes": { + "type": "integer" + }, + "truncated": { + "type": "boolean" + } + }, + "type": "object" + }, + { + "properties": { + "failed": { + "description": "失败的台数", + "type": "integer" + }, + "results": { + "items": { + "properties": { + "data": { + "description": "该台成功时的单机 structuredContent(字段随工具而定)", + "type": "object" + }, + "error": { + "description": "该台失败时的错误对象(code / message)", + "type": "object" + }, + "id": { + "description": "主机 id", + "type": "string" + }, + "ok": { + "description": "该台是否成功", + "type": "boolean" + }, + "text": { + "description": "该台失败时的错误文字", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "skipped": { + "description": "因整体时限用尽而未下发的台数(不是主机侧错误)", + "type": "integer" + }, + "succeeded": { + "description": "成功的台数", + "type": "integer" + }, + "tool": { + "description": "被批量调用的工具名", + "type": "string" + }, + "total": { + "description": "请求里的 id 台数", + "type": "integer" + } + }, + "required": [ + "results" + ], + "type": "object" + } + ], + "type": "object" + } + }, + { + "name": "host_control_process", + "description": "挂起或恢复在线 Windows 主机上的一个进程(对应主机管理「进程」右键的冻结/解冻)。可能导致目标进程超时或崩溃,故归入危险操作:需要同时开启 McpMachineDangerous。动作没有回执,客户端也不回报结果;工具会在动作后重新拉取进程列表确认目标仍存在。dry_run=true 只核实目标并返回它,不下发动作。", + "gate": "machine", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "action": { + "description": "freeze=挂起进程,thaw=恢复进程", + "enum": [ + "freeze", + "thaw" + ], + "type": "string" + }, + "dry_run": { + "description": "true 时只校验 PID/名称存在并返回目标进程,不冻结/解冻,默认 false", + "type": "boolean" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "name": { + "description": "可选:校验进程名,防止 PID 被系统复用后误操作", + "type": "string" + }, + "pid": { + "description": "目标进程 PID", + "type": "integer" + } + }, + "required": [ + "id", + "action", + "pid" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "action": { + "type": "string" + }, + "changed": { + "description": "是否真的改变了状态(如服务本来就是目标状态时为 false)", + "type": "boolean" + }, + "detail": { + "description": "dry_run 时目标对象的完整字段", + "type": "object" + }, + "dry_run": { + "description": "true 表示只是试运行,没有下发动作", + "type": "boolean" + }, + "message": { + "description": "人类可读的说明", + "type": "string" + }, + "ok": { + "description": "动作是否达到预期(false 表示未生效/无法确认,不会伪报成功)", + "type": "boolean" + }, + "reason": { + "description": "ok=false 时的原因", + "type": "string" + }, + "state": { + "description": "复核时观测到的状态", + "type": "string" + }, + "target": { + "type": "string" + }, + "verified": { + "description": "是否已用动作后的最新快照复核", + "type": "boolean" + } + }, + "required": [ + "ok" + ], + "type": "object" + } + }, + { + "name": "host_control_window", + "description": "对在线 Windows 主机的窗口执行可恢复操作:restore(还原)/hide(隐藏)/maximize(最大化)/minimize(最小化)。hwnd 取 host_list_windows 或 list_windows 返回的 hwnd。动作后重新枚举可见窗口复核:hide 后 hwnd 应消失,其余动作后仍应存在。不提供关闭窗口——需要 close / show 时改用 operate_window。dry_run=true 只核实 hwnd 并返回窗口信息。", + "gate": "machine", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "action": { + "description": "restore/hide/maximize/minimize", + "enum": [ + "restore", + "hide", + "maximize", + "minimize" + ], + "type": "string" + }, + "dry_run": { + "description": "true 时只校验 hwnd 仍在可见窗口列表里并返回该窗口,不下发操作,默认 false", + "type": "boolean" + }, + "hwnd": { + "description": "窗口句柄,取 host_list_windows 的 hwnd;整数或 0x 前缀字符串", + "type": [ + "integer", + "string" + ] + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + } + }, + "required": [ + "id", + "action", + "hwnd" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "action": { + "type": "string" + }, + "changed": { + "description": "是否真的改变了状态(如服务本来就是目标状态时为 false)", + "type": "boolean" + }, + "detail": { + "description": "dry_run 时目标对象的完整字段", + "type": "object" + }, + "dry_run": { + "description": "true 表示只是试运行,没有下发动作", + "type": "boolean" + }, + "message": { + "description": "人类可读的说明", + "type": "string" + }, + "ok": { + "description": "动作是否达到预期(false 表示未生效/无法确认,不会伪报成功)", + "type": "boolean" + }, + "reason": { + "description": "ok=false 时的原因", + "type": "string" + }, + "state": { + "description": "复核时观测到的状态", + "type": "string" + }, + "target": { + "type": "string" + }, + "verified": { + "description": "是否已用动作后的最新快照复核", + "type": "boolean" + } + }, + "required": [ + "ok" + ], + "type": "object" + } + }, + { + "name": "host_control_service", + "description": "控制在线 Windows 主机的服务:start/stop/pause/continue/restart。客户端对每次控制都会自动回一份刷新后的服务列表,工具据此复核状态并如实返回 ok;stop 与 restart 归入危险操作,需要同时开启 McpMachineDangerous。restart 先 stop 再 start。不提供删除服务。dry_run=true 只核实服务并返回当前状态,不下发命令(是否已是目标状态由你按 state 判断)。", + "gate": "machine", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "action": { + "description": "start/stop/pause/continue/restart", + "enum": [ + "start", + "stop", + "pause", + "continue", + "restart" + ], + "type": "string" + }, + "dry_run": { + "description": "true 时只校验服务存在并返回当前状态,不下发控制命令,默认 false", + "type": "boolean" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "name": { + "description": "服务名(ServiceName,不是显示名),取 host_list_*_services 的 name", + "type": "string" + } + }, + "required": [ + "id", + "action", + "name" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "action": { + "type": "string" + }, + "changed": { + "description": "是否真的改变了状态(如服务本来就是目标状态时为 false)", + "type": "boolean" + }, + "detail": { + "description": "dry_run 时目标对象的完整字段", + "type": "object" + }, + "dry_run": { + "description": "true 表示只是试运行,没有下发动作", + "type": "boolean" + }, + "message": { + "description": "人类可读的说明", + "type": "string" + }, + "ok": { + "description": "动作是否达到预期(false 表示未生效/无法确认,不会伪报成功)", + "type": "boolean" + }, + "reason": { + "description": "ok=false 时的原因", + "type": "string" + }, + "state": { + "description": "复核时观测到的状态", + "type": "string" + }, + "target": { + "type": "string" + }, + "verified": { + "description": "是否已用动作后的最新快照复核", + "type": "boolean" + } + }, + "required": [ + "ok" + ], + "type": "object" + } + }, + { + "name": "host_control_task", + "description": "运行或停止在线 Windows 主机的计划任务(主机管理「计划任务」右键)。客户端无回执,工具只复核任务仍存在并报告当前状态,不声称任务一定执行成功。不提供创建/删除任务。dry_run=true 只核实任务并返回当前状态。", + "gate": "machine", + "write": true, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "action": { + "description": "run=立即运行,stop=停止正在运行的任务", + "enum": [ + "run", + "stop" + ], + "type": "string" + }, + "dry_run": { + "description": "true 时只校验任务存在(含同名歧义检查)并返回当前状态,不下发 run/stop,默认 false", + "type": "boolean" + }, + "folder": { + "description": "可选:任务所在文件夹;同名任务存在多个时必填", + "type": "string" + }, + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "name": { + "description": "任务名,取 host_list_scheduled_tasks 的 name", + "type": "string" + } + }, + "required": [ + "id", + "action", + "name" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "action": { + "type": "string" + }, + "changed": { + "description": "是否真的改变了状态(如服务本来就是目标状态时为 false)", + "type": "boolean" + }, + "detail": { + "description": "dry_run 时目标对象的完整字段", + "type": "object" + }, + "dry_run": { + "description": "true 表示只是试运行,没有下发动作", + "type": "boolean" + }, + "message": { + "description": "人类可读的说明", + "type": "string" + }, + "ok": { + "description": "动作是否达到预期(false 表示未生效/无法确认,不会伪报成功)", + "type": "boolean" + }, + "reason": { + "description": "ok=false 时的原因", + "type": "string" + }, + "state": { + "description": "复核时观测到的状态", + "type": "string" + }, + "target": { + "type": "string" + }, + "verified": { + "description": "是否已用动作后的最新快照复核", + "type": "boolean" + } + }, + "required": [ + "ok" + ], + "type": "object" + } + }, + { + "name": "chat_open", + "description": "在指定在线 Windows 主机上弹出「远程交谈」窗口,建立一次多轮文字对话。返回 session_id,后续 chat_send / chat_wait / chat_close 都要带上。客户端使用者会直接看到聊天窗口(无确认框)。同一主机同一时刻只允许一个会话;会话在客户端断开或空闲 10 分钟后自动失效。会话建立后应先用 chat_send 发送问候,再用 chat_wait 等待对方回复。", + "gate": "chat", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "timeout_ms": { + "description": "等待客户端弹出聊天窗口的超时,默认 15000,范围 2000-60000", + "type": "integer" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "message": { + "type": "string" + }, + "session_id": { + "type": "string" + }, + "status": { + "description": "固定为 open", + "type": "string" + } + }, + "required": [ + "session_id", + "status" + ], + "type": "object" + } + }, + { + "name": "chat_send", + "description": "向会话对端发送一条文本。消息以客户端本地代码页(简体中文为 GBK/CP936)显示;客户端不保证非中文系统能正确显示。发送成功只代表已写入子连接,不代表对方已读。请勿在同一条消息里塞入多段对话;需要等待回复时调用 chat_wait。", + "gate": "chat", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "message": { + "description": "要发给客户端使用者的纯文本(UTF-8)。不能为空、不能含换行/控制字符、不能超过 4000 个 GBK 字节(约 2000 个汉字);emoji 等 GBK 无法表示的字符会被拒绝", + "type": "string" + }, + "session_id": { + "description": "chat_open 返回的 session_id(32 位 hex)", + "type": "string" + } + }, + "required": [ + "id", + "session_id", + "message" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "bytes": { + "description": "实际下发的 GBK 字节数", + "type": "integer" + }, + "message": { + "type": "string" + }, + "sent": { + "type": "boolean" + }, + "session_id": { + "type": "string" + } + }, + "required": [ + "session_id", + "sent" + ], + "type": "object" + } + }, + { + "name": "chat_wait", + "description": "等待客户端使用者发来的消息。有消息立即返回;没有消息则阻塞到 timeout_ms 或会话关闭。返回 messages(按时间顺序,text 为 UTF-8)、timed_out、closed、dropped(因缓冲区溢出丢弃的最旧消息数)。timed_out=true 只表示这段时间对方没说话,会话仍然有效;closed=true 表示客户端已断开,需要重新 chat_open。一般回复后立刻调用 chat_wait 形成对话循环。", + "gate": "chat", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "max_messages": { + "description": "单次最多返回条数,默认 20,范围 1-50;其余留到下一次", + "type": "integer" + }, + "session_id": { + "description": "chat_open 返回的 session_id(32 位 hex)", + "type": "string" + }, + "timeout_ms": { + "description": "最长等待时间,默认 30000,范围 0-55000;0 = 立即返回当前已收到的消息", + "type": "integer" + } + }, + "required": [ + "id", + "session_id" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "closed": { + "type": "boolean" + }, + "dropped": { + "type": "integer" + }, + "messages": { + "items": { + "properties": { + "at": { + "description": "服务端收到的 Unix 秒", + "type": "integer" + }, + "id": { + "description": "会话内单调递增序号", + "type": "integer" + }, + "text": { + "description": "UTF-8 文本", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "session_id": { + "type": "string" + }, + "timed_out": { + "type": "boolean" + } + }, + "required": [ + "session_id", + "messages", + "timed_out", + "closed" + ], + "type": "object" + } + }, + { + "name": "chat_close", + "description": "结束会话并关闭客户端上的聊天窗口。主机在线且会话已不存在时按幂等处理为成功;主机已离线时返回 -32002(此时会话已随断线失效)。关闭后旧的 session_id 不能再用;可立即重新 chat_open。", + "gate": "chat", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "properties": { + "id": { + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段", + "type": "string" + }, + "session_id": { + "description": "chat_open 返回的 session_id(32 位 hex)", + "type": "string" + } + }, + "required": [ + "id", + "session_id" + ], + "type": "object" + }, + "outputSchema": { + "properties": { + "closed": { + "type": "boolean" + }, + "message": { + "type": "string" + }, + "session_id": { + "type": "string" + } + }, + "required": [ + "session_id", + "closed" + ], + "type": "object" + } + } + ] +} diff --git a/server/2015Remote/2015RemoteDlg.cpp b/server/2015Remote/2015RemoteDlg.cpp index 1cf005e..f89334c 100644 --- a/server/2015Remote/2015RemoteDlg.cpp +++ b/server/2015Remote/2015RemoteDlg.cpp @@ -2549,6 +2549,10 @@ BOOL CMy2015RemoteDlg::OnInitDialog() McpServer().SetChatEnabled(THIS_CFG.GetInt("settings", "McpChat", 0) != 0); // N3 键盘记录(get_keylog):独立开关默认关,与只读开关无关。 McpServer().SetKeylogEnabled(THIS_CFG.GetInt("settings", "McpKeylog", 0) != 0); + // 平台门禁:默认开。调用前拦掉目标客户端根本没实现的工具(立刻 -32005), + // 否则会照常下发命令然后白等超时。关掉它只影响这道拦截,不改任何工具的执行路径。 + McpServer().SetPlatformGuardEnabled( + THIS_CFG.GetInt("settings", "McpPlatformGuard", 1) != 0); // 工具默认等待超时(ini-only 键,无设置界面):默认 20000ms,clamp 在 SetToolTimeoutMs 内。 McpServer().SetToolTimeoutMs(THIS_CFG.GetInt("settings", "McpToolTimeoutMs", 20000)); // HTTPS(native TLS):McpHttps=1 时对外端口说 TLS,httplib 退到回环内部端口。 diff --git a/server/2015Remote/McpServer.cpp b/server/2015Remote/McpServer.cpp index ad87550..de9b449 100644 --- a/server/2015Remote/McpServer.cpp +++ b/server/2015Remote/McpServer.cpp @@ -325,7 +325,31 @@ const char* kServerInstructions = u8"客户端无管理员权限时 Windows 会让 BlockInput 静默失败,成功只代表命令已送达)。\n" u8"命令执行:exec_command 一次性取输出;需要保持 cd 或环境变量时用 terminal_open + terminal_exec,用毕 terminal_close。\n" u8"\n" - u8"5) 安全约定\n" + u8"5) 客户端平台差异\n" + u8"工具能否执行取决于目标主机的平台,这与服务端开关无关,两者是叠加关系。调用前用 " + u8"list_online_hosts / get_host_detail 的 capabilities.platform 确认,宁可先查一次,不要先试后错。\n" + u8"支持面从宽到窄依次是 win > lnx > mac ≈ apk:Windows 是唯一全量支持的平台,Linux 次之," + u8"macOS 与 Android 只覆盖一部分。拿不准时按这个顺序假设。\n" + u8"win(EXE / DLL / MEXE / SC / MDLL):全部工具可用。\n" + u8"lnx(LNX):不支持服务、注册表、键日志、活动历史、文件搜索/删除/移动/建目录、" + u8"窗口列表(list_windows)、网络连接列表与断开" + u8"(list_network_connections / kill_network_connection)、" + u8"块输入、host_* 全族、chat_* 全族、operate_window、power_action。远程控制与截屏要求目标机" + u8"有 X11/Xorg(或 XWayland)桌面,纯 Wayland 或无桌面的服务器不行。\n" + u8"mac(MAC):在 lnx 的基础上,还不支持远程控制全族(remote_open / remote_close / " + u8"remote_mouse / remote_keyboard / remote_clipboard)、get_screenshot、" + u8"exec_command、terminal_open / terminal_exec / terminal_close" + u8"(客户端有 PTY 实现,但服务端本轮未开放)、kill_process;" + u8"文件传输、进程列表、日志可用。\n" + u8"apk(APK):只支持主机列表(list_online_hosts / list_all_hosts)/ 详情 / 搜索 / " + u8"审计日志 / 服务状态 / 会话管理,以及 " + u8"host_set_remark / host_set_watch_level 这两个只改服务端本地数据的工具。其余一律不支持" + u8"(客户端未实现 SYSTEM 与 SHELL)。\n" + u8"copy_files_c2c 是唯一有方向性的工具:源端 src_id 必须是 win,目标端 dst_id 可以是 " + u8"win / lnx / mac。Linux 和 macOS 只能当接收方,不能当发送方(反向不支持)。\n" + u8"这些不支持的组合会立刻返回 -32005,不会白等超时;反之,遇到超时不要当成平台不支持。\n" + u8"\n" + u8"6) 安全约定\n" u8"写操作前先读一次现状,动作后再用读工具复核;删改类工具的 ok 只表示命令已送达客户端,不代表成功。" u8"涉及删除、重启、结束进程、关机等不可逆操作时,先把目标和影响范围讲给用户,得到确认再执行。" u8"主机上可能有人正在办公,注入输入、截屏、关机都是会被察觉的动作。"; @@ -8765,6 +8789,213 @@ static const long long kBatchDeadlineMs = 50000; // IsBatchReadOnlyTool 定义在 McpInternal.cpp:tools/list 要用它补 outputSchema, // tools/call 要用它做批量入口判定,两处必须共用同一份清单,故不再在此重复定义。 +// ===== 平台门禁:调用前拦掉「该客户端根本没实现」的组合 ===== +// +// 判据来自各平台客户端对相应 COMMAND_ 的处理实现,不能看「是否引用了常量」: +// - android/.../main.cpp:534-540 的 COMMAND_SYSTEM / COMMAND_SHELL 都是空实现 +// - macOS 能处理 SEND_FILE_V2,但 DefaultCaps() 不给 SCREEN_PREVIEW,截屏仍不可用 +// 表内容与 mcp/tools.json 的 platforms 字段一一对应, +// tools/mcp_tools/check_platform_table.py 会校验两边一致。 +// +// 这里只做平台级粗筛。能力位门槛(SCREEN_PREVIEW / V2 / C2C_PATHS)仍留在各工具内部, +// 因为像「Linux 这台机器有没有 X11 桌面」只有运行时才知道。 +enum : uint8_t { + kPlatWin = 1, + kPlatLnx = 2, + kPlatMac = 4, + kPlatApk = 8, +}; + +struct ToolPlatform { + const char* name; + uint8_t mask; +}; + +// mask 为 0 或表里查不到 = 不限制。新增工具忘了登记时按放行处理(宁可漏拦,不可误拒), +// 遗漏由 check_platform_table.py 的工具数比对发现。 +const ToolPlatform kToolPlatforms[] = { + // ---- win+lnx+mac+apk ---- 只读写服务端本地数据,与客户端平台无关 + { "list_online_hosts", kPlatWin|kPlatLnx|kPlatMac|kPlatApk }, + { "search_hosts", kPlatWin|kPlatLnx|kPlatMac|kPlatApk }, + { "list_all_hosts", kPlatWin|kPlatLnx|kPlatMac|kPlatApk }, + { "get_host_detail", kPlatWin|kPlatLnx|kPlatMac|kPlatApk }, + { "get_audit_log", kPlatWin|kPlatLnx|kPlatMac|kPlatApk }, + { "get_server_status", kPlatWin|kPlatLnx|kPlatMac|kPlatApk }, + { "mcp_list_sessions", kPlatWin|kPlatLnx|kPlatMac|kPlatApk }, + { "mcp_cancel_session", kPlatWin|kPlatLnx|kPlatMac|kPlatApk }, + { "host_set_remark", kPlatWin|kPlatLnx|kPlatMac|kPlatApk }, + { "host_set_watch_level", kPlatWin|kPlatLnx|kPlatMac|kPlatApk }, + // ---- win+lnx+mac ---- SYSTEM / LIST_DRIVE / QUERY_LOG / V2 文件传输 + { "list_processes", kPlatWin|kPlatLnx|kPlatMac }, + { "list_files", kPlatWin|kPlatLnx|kPlatMac }, + { "get_client_log", kPlatWin|kPlatLnx|kPlatMac }, + { "download_file", kPlatWin|kPlatLnx|kPlatMac }, + { "upload_file", kPlatWin|kPlatLnx|kPlatMac }, + // ---- win+lnx ---- 远程控制全族 + 需 SCREEN_PREVIEW 的截屏 + macOS 未开放项 + { "get_screenshot", kPlatWin|kPlatLnx }, + { "remote_open", kPlatWin|kPlatLnx }, + { "remote_close", kPlatWin|kPlatLnx }, + { "remote_keyboard", kPlatWin|kPlatLnx }, + { "remote_mouse", kPlatWin|kPlatLnx }, + { "remote_clipboard", kPlatWin|kPlatLnx }, + // macOS 客户端有 PTY 实现(macos/main.mm:753),但服务端刻意不开放 + // (McpServer.cpp:3652「macOS 本轮不开放」),故实际不可用 + { "exec_command", kPlatWin|kPlatLnx }, + { "terminal_open", kPlatWin|kPlatLnx }, + { "terminal_exec", kPlatWin|kPlatLnx }, + { "terminal_close", kPlatWin|kPlatLnx }, + // macOS 客户端有 COMMAND_KILLPROCESS 分支,服务端同样拦着(McpServer.cpp:6870) + { "kill_process", kPlatWin|kPlatLnx }, + // ---- win ---- 服务 / 注册表 / 键日志 / 文件写 / host_* / chat_* / power_action + // list_windows 单列:BuildListWindows 把 COMMAND_WSLIST 发在**主连接**上 + // (McpServer.cpp:2931 的 Send2Client),而 Linux/macOS 主循环只处理 COMMAND_SYSTEM + // (起 SystemManager 子连接),WSLIST 只在子连接里处理 —— 走不到,实测 Linux 上 + // 直接超时 -32001。Windows 是在主循环里处理的(client/KernelManager.cpp:1491)。 + // 注意别被 linux/SystemManager.h:38 和 macos/SystemManager.mm:39 的 case 骗到, + // 那是给 SystemDlg 窗口管理用的,不是 MCP 这条路径。 + { "list_windows", kPlatWin }, + { "get_activity_history", kPlatWin }, + { "list_services", kPlatWin }, + { "get_keylog", kPlatWin }, + { "list_registry", kPlatWin }, + { "remote_block_input", kPlatWin }, + // 两端并集。方向性差异由 CollectTargetReqs 精确处理:源端必须 win,目标端 win/lnx/mac + { "copy_files_c2c", kPlatWin|kPlatLnx|kPlatMac }, + { "operate_window", kPlatWin }, + { "control_service", kPlatWin }, + { "power_action", kPlatWin }, + { "search_file", kPlatWin }, + { "delete_path", kPlatWin }, + { "move_path", kPlatWin }, + { "create_folder", kPlatWin }, + { "list_network_connections", kPlatWin }, + { "kill_network_connection", kPlatWin }, + { "host_list_processes", kPlatWin }, + { "host_list_windows", kPlatWin }, + { "host_list_network_state", kPlatWin }, + { "host_list_software", kPlatWin }, + { "host_list_browser_history", kPlatWin }, + { "host_list_favorites", kPlatWin }, + { "host_list_win32_services", kPlatWin }, + { "host_list_driver_services", kPlatWin }, + { "host_list_scheduled_tasks", kPlatWin }, + { "host_get_hosts_file", kPlatWin }, + { "host_control_process", kPlatWin }, + { "host_control_window", kPlatWin }, + { "host_control_service", kPlatWin }, + { "host_control_task", kPlatWin }, + { "chat_open", kPlatWin }, + { "chat_send", kPlatWin }, + { "chat_wait", kPlatWin }, + { "chat_close", kPlatWin }, +}; + +// 未知的 clientType 一律按 Windows:EXE/DLL/MEXE/SC/MDLL 都走这个分支, +// 将来新增平台在没有明确登记前也不会被误拦。 +uint8_t CurrentClientPlatform(context* ctx) { + CString t = ctx->GetAdditionalData(RES_CLIENT_TYPE); + if (t == "LNX") return kPlatLnx; + if (t == "MAC") return kPlatMac; + if (t == "APK") return kPlatApk; + return kPlatWin; +} + +const char* PlatformName(uint8_t p) { + switch (p) { + case kPlatLnx: return "lnx"; + case kPlatMac: return "mac"; + case kPlatApk: return "apk"; + default: return "win"; + } +} + +std::string PlatformNames(uint8_t mask) { + std::string s; + if (mask & kPlatWin) s += "win "; + if (mask & kPlatLnx) s += "lnx "; + if (mask & kPlatMac) s += "mac "; + if (mask & kPlatApk) s += "apk "; + if (!s.empty()) s.pop_back(); + return s; +} + +// 一台主机 + 它在这个工具里被允许的平台集合。 +struct TargetReq { + uint64_t id; + uint8_t mask; +}; + +bool AddIdReq(const Json::Value& args, const char* key, uint8_t mask, + std::vector& reqs) { + if (!args[key].isString()) return false; + const std::string sid = args[key].asString(); + if (sid.empty() || sid.find_first_not_of("0123456789") != std::string::npos) return false; + reqs.push_back({ strtoull(sid.c_str(), nullptr, 10), mask }); + return true; +} + +// 取出这个工具真正要操作的主机,以及每台主机各自的平台要求。 +// 绝大多数工具只有一个目标、用统一的 defaultMask;copy_files_c2c 是唯一的 +// 非对称工具,源端和目标端的平台要求不同,必须分开查: +// src_id —— 只有 Windows 实现了 C2C 发送逻辑(client/KernelManager.cpp) +// dst_id —— 只需 CLIENT_CAP_V2 收包,Windows / Linux / macOS 都行 +// 反过来 Linux → Windows 不支持:POSIX 客户端没有 C2C_PATHS 发送实现。 +// 返回 false = 这个工具不针对某台主机(服务端本地工具),不需要门禁。 +bool CollectTargetReqs(const std::string& toolName, const Json::Value& args, + uint8_t defaultMask, std::vector& reqs) { + // 多主机工具必须先判断:它的 schema 里没有 "id",但调用方可以多塞一个 id 进来。 + // 若先走 ParseHostIdArg,就只会检查那一台主机,真正的 src_id / dst_id 反而漏过去。 + if (toolName == "copy_files_c2c") { + AddIdReq(args, "src_id", kPlatWin, reqs); + AddIdReq(args, "dst_id", kPlatWin|kPlatLnx|kPlatMac, reqs); + return !reqs.empty(); + } + + uint64_t devId = 0; + std::string err; + if (!ParseHostIdArg(args, devId, err)) return false; // 无 id:服务端本地工具 + reqs.push_back({ devId, defaultMask }); + return true; +} + +// 返回空串 = 放行;非空 = 可直接作为 tools/call 结果返回的错误 JSON。 +// 主机不存在/离线时跳过该 id,把 -32002 留给工具自己报,避免同一问题出现两种错误码。 +std::string CheckToolPlatform(const Json::Value& id, const std::string& toolName, + const Json::Value& args, CMy2015RemoteDlg* parent) { + if (!CMcpServer::Instance().IsPlatformGuardEnabled()) return ""; + + uint8_t mask = 0; + for (const ToolPlatform& e : kToolPlatforms) { + if (toolName == e.name) { mask = e.mask; break; } + } + if (mask == 0) return ""; + + std::vector reqs; + if (!CollectTargetReqs(toolName, args, mask, reqs)) return ""; // 无 id:服务端本地工具 + + for (const TargetReq& req : reqs) { + context* ctx = FindMainContext(parent, req.id); + if (!ctx) continue; + + const uint8_t cur = CurrentClientPlatform(ctx); + if (req.mask & cur) continue; + + CString ct = ctx->GetAdditionalData(RES_CLIENT_TYPE); + std::string msg; + msg += std::string(u8"该主机平台是 "); + msg += PlatformName(cur); + msg += std::string(u8"(clientType="); + msg += std::string((LPCSTR)ct); + msg += std::string(u8"),"); + msg += toolName; + msg += std::string(u8" 在此主机上仅支持 "); + msg += PlatformNames(req.mask); + msg += std::string(u8"。按 instructions 第 5 节换用该平台支持的等价工具。"); + return BuildError(id, -32005, msg); + } + return ""; +} + // 单主机分派:批量路径复用它,保证批量与单机走同一套实现。 std::string DispatchSingleHostTool(const Json::Value& id, const std::string& toolName, const Json::Value& args, CMy2015RemoteDlg* parent); @@ -8933,6 +9164,13 @@ std::string BuildToolsCall(const Json::Value& root, CMy2015RemoteDlg* parent) { std::string DispatchSingleHostTool(const Json::Value& id, const std::string& toolName, const Json::Value& args, CMy2015RemoteDlg* parent) { + // 平台门禁:放在所有分派之前,批量路径也会经过这里(BuildBatchCall 循环调用本函数), + // 所以不需要在批量入口重复一次。主机不存在/离线时放行,让各工具自己报 -32002。 + { + std::string platErr = CheckToolPlatform(id, toolName, args, parent); + if (!platErr.empty()) return platErr; + } + // P8:连接管理 / 主机管理工具族(独立分发;门控在 McpMachine::Call 内复核)。 if (McpMachine::Handles(toolName)) return McpMachine::Call(id, toolName, args, parent); diff --git a/server/2015Remote/McpServer.h b/server/2015Remote/McpServer.h index 8a90c3e..4c025a7 100644 --- a/server/2015Remote/McpServer.h +++ b/server/2015Remote/McpServer.h @@ -605,6 +605,11 @@ public: bool IsReadonly() const { return m_readonly; } const std::string& GetCmdWhitelist() const { return m_cmdWhitelist; } + // 平台门禁开关:默认开。关闭只影响「错误平台上的调用是否被提前拦住」, + // 不影响任何工具的正常执行路径,可作为出问题时的应急回退手段。 + void SetPlatformGuardEnabled(bool enabled) { m_platformGuard = enabled; } + bool IsPlatformGuardEnabled() const { return m_platformGuard; } + // 监听地址/端口(Start 时记录,供 get_server_status 报告)。 const std::string& GetBind() const { return m_bind; } int GetPort() const { return m_port; } @@ -938,6 +943,10 @@ private: bool m_machineEnabled = false; // P8 主机管理族总开关(默认关;16 个 host_* 工具) bool m_machineDangerousEnabled = false; // P8 高风险子集(冻结/解冻进程、停止/重启服务) bool m_keylogEnabled = false; // N3 键盘记录开关(默认关;get_keylog) + // 平台门禁(默认开):调用前拦掉「该客户端根本没实现」的工具,立刻返回 -32005。 + // 关闭后这类调用会照常下发命令,通常表现为白等超时。判据表见 McpServer.cpp 的 + // kToolPlatforms,与 mcp/tools.json 的 platforms 字段对应。 + bool m_platformGuard = true; int m_toolTimeoutMs = 20000; // 工具默认等待超时(McpToolTimeoutMs,见 SetToolTimeoutMs) }; diff --git a/tools/mcp_tools/README.md b/tools/mcp_tools/README.md new file mode 100644 index 0000000..c4935ef --- /dev/null +++ b/tools/mcp_tools/README.md @@ -0,0 +1,205 @@ +# MCP 工具清单维护 + +`mcp/tools.json` 是 MCP 全部 60 个工具的**单一来源候选**:工具名、描述、 +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` 与服务端是否一致 | +| `tools/mcp_tools/check_platform_table.py` | 校验 `tools.json` 的 `platforms` 与 C++ `kToolPlatforms` 一致 | + +## 更新流程 + +改动 C++ 里的工具定义(`McpServer.cpp` / `McpMachine.cpp` / `McpChat.cpp`)之后: + +```bash +# 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: 60 个工具完全一致` 才算成功。 + +### 如果工具数量变了 + +`make_tools_json.py` 里的 `GATE` 和 `PLATFORMS` 两张表是**手工维护**的,新增工具会直接报错退出: + +``` +!! GATE 表缺少 1 个工具: ['new_tool'] +!! PLATFORMS 表缺少 1 个工具: ['new_tool'] +``` + +这是有意为之——`gate` / `write` / `manage` 三项在运行时不可见,只能从 C++ +注册点的 `if` 条件读出来,必须人工确认。补表时对照: + +- `McpServer.cpp:BuildToolsListResult` —— 内联的 40 个 +- `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` | + +当前分布(60 个工具): + +| platforms | 数量 | 典型工具 | +|---|---|---| +| `win+lnx+mac+apk` | 10 | 只读写服务端本地数据:`list_online_hosts` / `get_audit_log` / `mcp_*` | +| `win+lnx+mac` | 6 | 进程列表、文件列取、日志、V2 文件传输、`copy_files_c2c` | +| `win+lnx` | 11 | `remote_*` 全族、`get_screenshot`、`exec_command` / `terminal_*` / `kill_process` | +| `win` | 33 | 服务 / 注册表 / 键日志 / 文件写 / **`list_windows`** / `host_*` / `chat_*` / `power_action` | + +**注意 `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` 在子连接里才被处理——走不到。实测 Linux +上直接超时 `-32001`。那两个 `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` 两端的要求不同,单靠它表达不了: + +```json +"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` 直接返回放行。 + +```bash +python tools/mcp_tools/check_platform_table.py +# PASS: 60 个工具的 platforms 两边完全一致,且门禁都能拿到主机 id +``` + +## 与 Go 服务端的关系 + +`impl` 字段就是给 Go 端裁剪用的:标 `mfc` 的工具表示 Go 端还没有对应能力。 +Go 端补齐某个工具的底层命令后,把它改成 `both`。 + +注意 Go 端目前只有 5 类客户端命令(`SCREEN_SPY` / `NEXT` / `SCREEN_CONTROL` / +`BYE` / `SHELL`),所以短期内 `impl: both` 的工具不会多。 + +## 前置条件 + +- 服务端在运行(`McpEnabled=1`) +- Release 版读注册表 `HKCU\Software\YAMA\settings`,Debug 版读 `\settings.ini` + —— 抓不到工具时先确认跑的是哪个构建 +- 抓取时所有开关都应为开,否则拿到的是子集而非全集 diff --git a/tools/mcp_tools/check_platform_table.py b/tools/mcp_tools/check_platform_table.py new file mode 100644 index 0000000..e9d1299 --- /dev/null +++ b/tools/mcp_tools/check_platform_table.py @@ -0,0 +1,206 @@ +"""校验 C++ 的 kToolPlatforms 表与 mcp/tools.json 的 platforms 字段是否一致。 + +C++ 侧不读 JSON(当前架构如此),两边是双份维护。这个脚本负责让它们不漂移: + - 工具集合必须完全相同(漏登记 / 多登记都报错) + - 每个工具的掩码必须对应同一组平台 + - 受限平台的工具必须让门禁拿得到主机 id(否则 CheckToolPlatform 会静默放行) + +用法: + python check_platform_table.py [mcp/tools.json] [McpServer.cpp] +""" +import json +import re +import sys + +JSON_PATH = sys.argv[1] if len(sys.argv) > 1 else "mcp/tools.json" +CPP_PATH = sys.argv[2] if len(sys.argv) > 2 else "server/2015Remote/McpServer.cpp" + +BIT = {"kPlatWin": "win", "kPlatLnx": "lnx", "kPlatMac": "mac", "kPlatApk": "apk"} +ORDER = ["win", "lnx", "mac", "apk"] + + +def plats_of(expr, where): + out = [] + for token in re.findall(r"kPlat\w+", expr): + if token not in BIT: + sys.exit(f"未知的平台常量 {token}({where})") + out.append(BIT[token]) + # 保持与 tools.json 相同的顺序约定:win, lnx, mac, apk + return [p for p in ORDER if p in out] + + +def parse_cpp(path): + src = open(path, encoding="utf-8", errors="replace").read() + start = src.find("const ToolPlatform kToolPlatforms[]") + if start < 0: + sys.exit("找不到 kToolPlatforms 表") + end = src.find("};", start) + if end < 0: + sys.exit("kToolPlatforms 表没有闭合") + body = src[start:end] + + table = {} + for line in body.splitlines(): + m = re.search(r'\{\s*"([a-z_0-9]+)"\s*,\s*([^}]+)\}', line) + if not m: + continue + table[m.group(1)] = plats_of(m.group(2), f"工具 {m.group(1)}") + return table, src + + +def parse_cpp_roles(src): + """从 CollectTargetReqs 里提取 AddIdReq(args, "", , reqs) 三元组。""" + i = src.find("bool CollectTargetReqs(") + if i < 0: + return None + j = src.find("\n}", i) + fn_body = src[i:j] if j > i else "" + + roles = {} + for m in re.finditer(r'AddIdReq\(\s*args\s*,\s*"(\w+)"\s*,\s*([^,]+),', fn_body): + roles[m.group(1)] = plats_of(m.group(2), f"CollectTargetReqs 的 {m.group(1)}") + return roles + + +def check_coverage(tools, src): + """两件事: + 1. 受限平台的工具若拿不到主机 id,CheckToolPlatform 会直接放行,等于没拦。 + 2. 多主机工具的方向性要求(roles)必须三方一致:tools.json / C++ / 本脚本。 + """ + problems = 0 + cpp_roles = parse_cpp_roles(src) + if cpp_roles is None: + print("!! 找不到 CollectTargetReqs(门禁实现可能被改名或删除)") + return 1 + + for t in tools: + name = t["name"] + props = t["inputSchema"].get("properties", {}) + roles = t.get("roles") + + if roles: + outer = set(t["platforms"]) + for key, plats in roles.items(): + if key not in props: + problems += 1 + print(f"!! {name}.roles.{key}: 不在 inputSchema 里") + extra = set(plats) - outer + if extra: + problems += 1 + print(f"!! {name}.roles.{key}: 超出 platforms 范围 {sorted(extra)}") + got = cpp_roles.get(key) + if got is None: + problems += 1 + print(f"!! {name}.roles.{key}: C++ CollectTargetReqs 未处理") + elif got != list(plats): + problems += 1 + print(f"!! {name}.roles.{key}: tools.json={plats} C++={got}") + continue + + if len(t["platforms"]) >= 4: + continue # 全平台可用,不需要判断主机 + if "id" in props: + continue # 标准路径,ParseHostIdArg 能取到 + + problems += 1 + print(f"!! {name}: platforms={t['platforms']} 但入参无 id,门禁拿不到主机") + return problems + + +def check_win_baseline(tools): + """Windows 是唯一全量支持的平台,这是产品定位,不是数据巧合。 + + 任何工具都不该缺 win:缺了要么是标注出错,要么是这个工具根本不该注册。 + 支持面从宽到窄依次是 win > lnx > mac ≈ apk,这条阶梯也在这里顺带核对, + 倒挂说明某一档标反了。 + """ + problems = 0 + for t in tools: + if "win" not in t["platforms"]: + problems += 1 + print(f"!! {t['name']}: platforms={t['platforms']} 不含 win,但 Windows 应全量支持") + + def covered(p): + return sum(1 for t in tools if p in t["platforms"]) + + win, lnx, mac, apk = covered("win"), covered("lnx"), covered("mac"), covered("apk") + if not (win >= lnx >= mac and win >= apk): + problems += 1 + print(f"!! 支持面阶梯倒挂: win={win} lnx={lnx} mac={mac} apk={apk}" + f"(应为 win >= lnx >= mac/apk)") + print(f"支持面: win={win} lnx={lnx} mac={mac} apk={apk}") + return problems + + +def check_instructions(src, tools): + """instructions 第 5 节是平台矩阵的摘要,模型只读它不读表。 + + mac 段是逐个点名列出 win+lnx 组工具的,漏一个模型就会误以为 macOS 支持它 + (实际发生过:remote_close 漏了)。这里做一次点名核对。 + """ + i = src.find('u8"5) 客户端平台差异') + if i < 0: + print("!! 找不到 instructions 第 5 节(客户端平台差异)") + return 1 + j = src.find('u8"6) 安全约定', i) + if j < 0: + print("!! 找不到 instructions 第 6 节,无法确定第 5 节的边界") + return 1 + + # 把这一节里所有 u8"..." 拼成连续文本,再按平台段落切开 + text = "".join(re.findall(r'u8"((?:[^"\\]|\\.)*)"', src[i:j])) + mac_at, apk_at = text.find("mac(MAC)"), text.find("apk(APK)") + if mac_at < 0 or apk_at < mac_at: + print("!! instructions 第 5 节里找不到 mac / apk 段落") + return 1 + mac_seg = text[mac_at:apk_at] + + problems = 0 + for t in tools: + if t["platforms"] == ["win", "lnx"] and t["name"] not in mac_seg: + problems += 1 + print(f"!! {t['name']} 不支持 mac,但 instructions 的 mac 段没点名") + return problems + + +def main(): + doc = json.load(open(JSON_PATH, encoding="utf-8")) + tools = doc["tools"] + json_table = {t["name"]: list(t["platforms"]) for t in tools} + cpp_table, cpp_src = parse_cpp(CPP_PATH) + + print(f"{JSON_PATH}: {len(json_table)} 个工具") + print(f"{CPP_PATH}: {len(cpp_table)} 项") + + problems = 0 + + only_json = sorted(set(json_table) - set(cpp_table)) + only_cpp = sorted(set(cpp_table) - set(json_table)) + if only_json: + problems += len(only_json) + print(f"!! 只在 tools.json 里(C++ 表漏登记): {only_json}") + if only_cpp: + problems += len(only_cpp) + print(f"!! 只在 C++ 表里(tools.json 已无此工具): {only_cpp}") + + for name in sorted(set(json_table) & set(cpp_table)): + a, b = json_table[name], cpp_table[name] + if a != b: + problems += 1 + print(f"!! {name}: tools.json={a} C++={b}") + + problems += check_coverage(tools, cpp_src) + problems += check_win_baseline(tools) + problems += check_instructions(cpp_src, tools) + + if problems == 0: + print(f"\nPASS: {len(json_table)} 个工具的 platforms 两边完全一致," + f"Windows 全量覆盖,多主机工具的方向性要求三方一致," + f"门禁都能拿到主机 id,instructions 第 5 节无漏项") + return 0 + print(f"\nFAIL: {problems} 处不一致") + return 1 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/mcp_tools/dump_tools.py b/tools/mcp_tools/dump_tools.py new file mode 100644 index 0000000..96ab2e1 --- /dev/null +++ b/tools/mcp_tools/dump_tools.py @@ -0,0 +1,90 @@ +"""抓取运行中 MCP 服务端的 tools/list 原始响应,作为黄金样本。 + +token 来源(按优先级):命令行参数 > 环境变量 YAMA_MCP_TOKEN > 注册表 + HKCU\\Software\\YAMA\\settings 的 McpToken + 注意:Release 版读注册表,Debug 版读 \\settings.ini,两者可能不同。 + +端口自动探测: + 6545 = McpHttps=1 时 httplib 的明文后端(只绑回环,首选) + 6544 = TLS 前端(McpTlsProxy,需跳过证书校验) + +用法: + python dump_tools.py [token] [out.json] +""" +import http.client +import json +import os +import ssl +import sys + + +def resolve_token(argv_token=""): + if argv_token: + return argv_token + env = os.environ.get("YAMA_MCP_TOKEN", "") + if env: + return env + try: + import winreg + key = winreg.OpenKey(winreg.HKEY_CURRENT_USER, r"Software\YAMA\settings") + val, _ = winreg.QueryValueEx(key, "McpToken") + return val + except Exception: + return "" + + +def call(port, token, method="tools/list", use_tls=False): + body = json.dumps({ + "jsonrpc": "2.0", "id": 1, "method": method, "params": {}, + }, ensure_ascii=False).encode("utf-8") + if use_tls: + ctx = ssl.create_default_context() + ctx.check_hostname = False + ctx.verify_mode = ssl.CERT_NONE + conn = http.client.HTTPSConnection("127.0.0.1", port, timeout=30, context=ctx) + else: + conn = http.client.HTTPConnection("127.0.0.1", port, timeout=30) + conn.request("POST", "/mcp", body, { + "Authorization": "Bearer " + token, + "Content-Type": "application/json", + "Accept": "application/json, text/event-stream", + }) + resp = conn.getresponse() + raw = resp.read() + conn.close() + return resp.status, raw + + +def main(): + token = resolve_token(sys.argv[1] if len(sys.argv) > 1 else "") + out = sys.argv[2] if len(sys.argv) > 2 else "tools_raw.json" + if not token: + sys.exit("未找到 McpToken(参数 / YAMA_MCP_TOKEN / 注册表 均无)") + + last = None + raw = None + for port, tls in ((6545, False), (6544, True)): + try: + status, raw = call(port, token, use_tls=tls) + except Exception as e: + last = f"{port}: {e}" + continue + if status == 200: + print(f"连接 127.0.0.1:{port} ({'TLS' if tls else 'plain'}), {len(raw)} bytes") + break + last = f"{port}: HTTP {status} {raw[:200].decode('utf-8', 'replace')}" + else: + sys.exit(f"两个端口都失败 -> {last}") + + doc = json.loads(raw.decode("utf-8")) + tools = doc.get("result", {}).get("tools", []) + print(f"工具数: {len(tools)}") + + with open(out, "w", encoding="utf-8", newline="\n") as f: + json.dump(doc, f, ensure_ascii=False, indent=2) + f.write("\n") + print(f"已写入 {out}") + + +if __name__ == "__main__": + main() diff --git a/tools/mcp_tools/make_tools_json.py b/tools/mcp_tools/make_tools_json.py new file mode 100644 index 0000000..bdbde7e --- /dev/null +++ b/tools/mcp_tools/make_tools_json.py @@ -0,0 +1,320 @@ +"""从 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 ") + +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}") diff --git a/tools/mcp_tools/verify_tools.py b/tools/mcp_tools/verify_tools.py new file mode 100644 index 0000000..7b6feac --- /dev/null +++ b/tools/mcp_tools/verify_tools.py @@ -0,0 +1,161 @@ +"""校验 tools.json 与 MCP 服务端的 tools/list 是否一致。 + +两种模式: + python verify_tools.py --offline mcp/tools.json tools_raw.json + 对比 tools.json 与已保存的黄金样本(不联网) + + python verify_tools.py --live mcp/tools.json [token] [port] + 抓取运行中服务端的 tools/list 再对比(回归测试用) + token 省略时依次取环境变量 YAMA_MCP_TOKEN、注册表 McpToken; + port 省略时自动探测 6545(明文后端)/ 6544(TLS 前端) + +比对内容:name / description / inputSchema / outputSchema,逐字段深度比较, +外加工具顺序。gate / write / manage / impl 是 tools.json 独有的元信息,不参与比对。 +""" +import http.client +import json +import os +import ssl +import sys + + +def normalize(obj): + """规范化:键排序后序列化,消除 JSON object 的键序差异。""" + return json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + + +def resolve_token(argv_token=""): + if argv_token: + return argv_token + env = os.environ.get("YAMA_MCP_TOKEN", "") + if env: + return env + try: + import winreg + key = winreg.OpenKey(winreg.HKEY_CURRENT_USER, r"Software\YAMA\settings") + val, _ = winreg.QueryValueEx(key, "McpToken") + return val + except Exception: + return "" + + +def fetch_live(token, port=None): + body = json.dumps({ + "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}, + }, ensure_ascii=False).encode("utf-8") + + if port is not None: + candidates = [(port, port == 6544)] + else: + candidates = [(6545, False), (6544, True)] + + last = None + for p, tls in candidates: + try: + if tls: + ctx = ssl.create_default_context() + ctx.check_hostname = False + ctx.verify_mode = ssl.CERT_NONE + conn = http.client.HTTPSConnection("127.0.0.1", p, timeout=30, context=ctx) + else: + conn = http.client.HTTPConnection("127.0.0.1", p, timeout=30) + conn.request("POST", "/mcp", body, { + "Authorization": "Bearer " + token, + "Content-Type": "application/json", + "Accept": "application/json, text/event-stream", + }) + resp = conn.getresponse() + raw = resp.read() + conn.close() + if resp.status == 200: + print(f"连接 127.0.0.1:{p} ({'TLS' if tls else 'plain'})") + return json.loads(raw.decode("utf-8"))["result"]["tools"] + last = f"{p}: HTTP {resp.status} {raw[:200].decode('utf-8', 'replace')}" + except Exception as e: + last = f"{p}: {e}" + sys.exit(f"连接失败 -> {last}") + + +def main(): + args = sys.argv[1:] + if not args: + sys.exit(__doc__) + + if args[0] == "--offline": + if len(args) < 3: + sys.exit("用法: python verify_tools.py --offline <黄金样本.json>") + path, sample = args[1], args[2] + tools_live = json.load(open(sample, encoding="utf-8"))["result"]["tools"] + print(f"黄金样本: {sample}") + elif args[0] == "--live": + if len(args) < 2: + sys.exit("用法: python verify_tools.py --live [token] [port]") + path = args[1] + token = resolve_token(args[2] if len(args) > 2 else "") + port = int(args[3]) if len(args) > 3 else None + if not token: + sys.exit("未找到 McpToken(参数 / YAMA_MCP_TOKEN / 注册表 均无)") + tools_live = fetch_live(token, port) + print(f"活服务: 127.0.0.1:{port if port else 'auto'}") + else: + sys.exit(__doc__) + + doc = json.load(open(path, encoding="utf-8")) + tools_json = doc["tools"] + print(f"tools.json: {path} ({len(tools_json)} 个工具)") + print(f"服务端: {len(tools_live)} 个工具") + + if len(tools_json) != len(tools_live): + print(f"!! 数量不一致: {len(tools_json)} vs {len(tools_live)}") + + live_by_name = {t["name"]: t for t in tools_live} + json_by_name = {t["name"]: t for t in tools_json} + + only_live = sorted(set(live_by_name) - set(json_by_name)) + only_json = sorted(set(json_by_name) - set(live_by_name)) + if only_live: + print(f"!! 仅服务端有: {only_live}") + if only_json: + print(f"!! 仅 json 有: {only_json}") + + FIELDS = ("description", "inputSchema", "outputSchema") + diffs = 0 + for name in sorted(set(live_by_name) & set(json_by_name)): + a, b = live_by_name[name], json_by_name[name] + for f in FIELDS: + va, vb = normalize(a.get(f)), normalize(b.get(f)) + if va != vb: + diffs += 1 + print(f"!! {name}.{f} 不一致") + for i, (ca, cb) in enumerate(zip(va, vb)): + if ca != cb: + print(f" @{i}") + print(f" 服务端: ...{va[max(0,i-60):i+80]}...") + print(f" json : ...{vb[max(0,i-60):i+80]}...") + break + else: + print(f" 长度不同: {len(va)} vs {len(vb)}") + break # 一个工具报一次即可 + + # 顺序一致性:tools/list 的数组顺序会影响模型的选择倾向 + order_live = [t["name"] for t in tools_live] + order_json = [t["name"] for t in tools_json] + if order_live != order_json: + print("!! 工具顺序不一致") + for i, (x, y) in enumerate(zip(order_live, order_json)): + if x != y: + print(f" 首个差异 @{i}: 服务端={x} json={y}") + break + diffs += 1 + else: + print("工具顺序: 一致") + + if diffs == 0 and not only_live and not only_json: + print(f"\nPASS: {len(tools_json)} 个工具完全一致") + return 0 + print(f"\nFAIL: {diffs} 处差异") + return 1 + + +if __name__ == "__main__": + sys.exit(main())