diff --git a/mcp/tools.json b/mcp/tools.json index 18cfba5..f264a2a 100644 --- a/mcp/tools.json +++ b/mcp/tools.json @@ -5,6 +5,9 @@ "由 tools/mcp_tools/dump_tools.py 抓取、make_tools_json.py 生成,勿手工编辑。", "gate: 该工具出现的开关条件(null = 无条件);write: 需 !McpReadonly;", "manage: 额外需 McpManage。这三项从 C++ 注册点的 if 条件解析而来,运行时不可见。", + "gate 为 \"!machine\" 表示该降级工具只在 McpMachine=0 时出现(开启主机管理后", + "由 host_inspect 的对应 aspect 取代,名字仍可作为别名调用);清单是开启态与", + "关闭态两份抓取的并集。", "platforms: 该工具涉及的任一主机都必须落在此集合内(win/lnx/mac/apk),依据各平台", "客户端对相应 COMMAND_ 的处理实现。apk 上 COMMAND_SYSTEM 与 COMMAND_SHELL 均为空实现。", "roles: 仅多主机工具才有。按参数名细分平台,表达 platforms 说不清的方向性能力", @@ -358,322 +361,6 @@ "type": "object" } }, - { - "name": "list_processes", - "description": "获取指定在线主机的进程列表(PID、映像名称、架构、程序完整路径)。通过主连接下发命令、子连接回传,一次性返回。可选 name(映像名子串,ASCII 不区分大小写)/ pid(精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。定位是 McpMachine=0(主机管理工具关闭)时的降级路径,字段较少;若 host_inspect 出现在 tools/list 里,一律优先用它的 processes 项。", - "gate": null, - "platforms": [ - "win", - "lnx", - "mac" - ], - "impl": "mfc", - "inputSchema": { - "anyOf": [ - { - "required": [ - "id" - ] - }, - { - "required": [ - "ids" - ] - } - ], - "properties": { - "id": { - "description": "主机 id,取 list_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_inspect 出现在 tools/list 里,一律优先用它的 windows 项。", - "gate": null, - "platforms": [ - "win" - ], - "impl": "mfc", - "inputSchema": { - "anyOf": [ - { - "required": [ - "id" - ] - }, - { - "required": [ - "ids" - ] - } - ], - "properties": { - "id": { - "description": "主机 id,取 list_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": "获取指定在线主机的历史活动记录。Windows 与有桌面的 Linux 客户端返回前台窗口驻留记录,每行一条「[时间] [标题] 时长」;Android 客户端返回前台应用驻留记录(标题为「应用名 (包名)」,需开启无障碍服务);无桌面的 Linux 客户端返回登录记录与 shell 命令历史,每行带「[登录]」或「[命令]」标签(首行为「[来源]」说明)。主连接 RPC。结果按 limit/offset 分页(默认 100 条、上限 1000),新在前:offset=0 就是最近 limit 条,想看更早的再往后翻。total 为本机现有记录总数,hasMore 表示还有更早的记录;窗口后端只保留最近 500 条,所以 total 最多约 501(含进行中的当前窗口)。", @@ -1193,158 +880,6 @@ "type": "object" } }, - { - "name": "list_services", - "description": "获取指定在线 Windows 主机的服务列表(显示名、服务名、可执行文件路径、运行状态、启动类型)。仅 Windows 客户端支持;一次性返回,结果按 limit/offset 分页。不支持服务端过滤。定位是 McpMachine=0(主机管理工具关闭)时的降级路径,字段较少(无描述、登录身份);若 host_inspect 出现在 tools/list 里,一律优先用它的 win32_services 项。", - "gate": null, - "platforms": [ - "win" - ], - "impl": "mfc", - "inputSchema": { - "anyOf": [ - { - "required": [ - "id" - ] - }, - { - "required": [ - "ids" - ] - } - ], - "properties": { - "id": { - "description": "主机 id,取 list_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 行,含时间戳/源文件/行号)。注意:这不是被管业务程序的日志——业务程序自己写的日志在主机磁盘上,读它用 read_file(看尾部用 offset=-N,如 offset=-200)。本工具取的是 YAMA 客户端自身的运行记录,用于排查客户端/连接问题。客户端持续增量上报,本工具取当前时刻的快照后即断开。默认只返回末尾 200 行(故障排查看的是最后发生了什么);可用 limit 调整(上限 2000)、filter 只保留包含某子串的行。返回里的 lines_total / lines_matched / lines_returned / truncated 说明裁剪情况。只读。", @@ -5374,6 +4909,474 @@ ], "type": "object" } + }, + { + "name": "list_processes", + "description": "获取指定在线主机的进程列表(PID、映像名称、架构、程序完整路径)。通过主连接下发命令、子连接回传,一次性返回。可选 name(映像名子串,ASCII 不区分大小写)/ pid(精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。仅在 McpMachine=0(主机管理工具关闭)时出现——那是本服务端唯一能列进程的路径;开启主机管理后改用 host_inspect 的 processes 项(字段更全、支持 arch 过滤)。", + "gate": "!machine", + "platforms": [ + "win", + "lnx", + "mac" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_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_inspect 的 windows 项(字段更全,含窗口矩形与 z 序)。", + "gate": "!machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_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": "list_services", + "description": "获取指定在线 Windows 主机的服务列表(显示名、服务名、可执行文件路径、运行状态、启动类型)。仅 Windows 客户端支持;一次性返回,结果按 limit/offset 分页。不支持服务端过滤。仅在 McpMachine=0(主机管理工具关闭)时出现;开启主机管理后改用 host_inspect 的 win32_services 项(字段更全:描述、登录身份)。注意两者都要求客户端以管理员权限运行,否则拿不到服务列表。", + "gate": "!machine", + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "anyOf": [ + { + "required": [ + "id" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "id": { + "description": "主机 id,取 list_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" + } } ] } diff --git a/server/2015Remote/McpServer.cpp b/server/2015Remote/McpServer.cpp index e3ecddf..2e13132 100644 --- a/server/2015Remote/McpServer.cpp +++ b/server/2015Remote/McpServer.cpp @@ -2122,6 +2122,12 @@ std::string BuildToolsListResult(const Json::Value& id) { Json::Value result(Json::objectValue); Json::Value tools(Json::arrayValue); + // P2-2:主机管理开启时,list_processes / list_windows / list_services 由 host_inspect + // 的 processes / windows / win32_services 项覆盖,不再出现在 tools/list;但名字仍在 + // 分派处可用(见 Call),老调用方不会断。关闭主机管理时它们必须出现——那是这台 + // 服务端唯一能列进程/窗口/服务的路径(McpMachine 默认关)。 + const bool showDegradedLists = !McpServer().IsMachineEnabled(); + // 1) list_hosts(P1-1:合并 list_online_hosts / search_hosts / list_all_hosts; // 旧名作为别名保留在分发处,不出现在 tools/list) { @@ -2145,11 +2151,11 @@ std::string BuildToolsListResult(const Json::Value& id) { tools.append(tool); } - // 4) list_processes(P2b:主连接 RPC,进程列表) - { + // 4) list_processes(P2b:主连接 RPC,进程列表;P2-2:主机管理开启时由 host_inspect 取代) + if (showDegradedLists) { Json::Value tool(Json::objectValue); tool["name"] = "list_processes"; - tool["description"] = u8"获取指定在线主机的进程列表(PID、映像名称、架构、程序完整路径)。通过主连接下发命令、子连接回传,一次性返回。可选 name(映像名子串,ASCII 不区分大小写)/ pid(精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。定位是 McpMachine=0(主机管理工具关闭)时的降级路径,字段较少;若 host_inspect 出现在 tools/list 里,一律优先用它的 processes 项。"; + tool["description"] = u8"获取指定在线主机的进程列表(PID、映像名称、架构、程序完整路径)。通过主连接下发命令、子连接回传,一次性返回。可选 name(映像名子串,ASCII 不区分大小写)/ pid(精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。仅在 McpMachine=0(主机管理工具关闭)时出现——那是本服务端唯一能列进程的路径;开启主机管理后改用 host_inspect 的 processes 项(字段更全、支持 arch 过滤)。"; tool["inputSchema"] = BuildFilteredPagedHostListInputSchema( u8"按映像名子串过滤,ASCII 不区分大小写(如 chrome)", @@ -2159,11 +2165,11 @@ std::string BuildToolsListResult(const Json::Value& id) { tools.append(tool); } - // 5) list_windows(P2b:主连接 RPC,窗口列表) - { + // 5) list_windows(P2b:主连接 RPC,窗口列表;P2-2:主机管理开启时由 host_inspect 取代) + if (showDegradedLists) { Json::Value tool(Json::objectValue); tool["name"] = "list_windows"; - tool["description"] = u8"获取指定在线主机的顶层窗口列表(句柄、窗口标题、窗口状态、所属进程 PID)。一次性返回。可选 name(窗口标题子串,ASCII 不区分大小写)/ pid(所属进程,精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。定位是 McpMachine=0(主机管理工具关闭)时的降级路径;若 host_inspect 出现在 tools/list 里,一律优先用它的 windows 项。"; + tool["description"] = u8"获取指定在线主机的顶层窗口列表(句柄、窗口标题、窗口状态、所属进程 PID)。一次性返回。可选 name(窗口标题子串,ASCII 不区分大小写)/ pid(所属进程,精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。仅在 McpMachine=0(主机管理工具关闭)时出现;开启主机管理后改用 host_inspect 的 windows 项(字段更全,含窗口矩形与 z 序)。"; tool["inputSchema"] = BuildFilteredPagedHostListInputSchema( u8"按窗口标题子串过滤,ASCII 不区分大小写(如 notepad);匹配的是标题不是进程名", @@ -2221,11 +2227,11 @@ std::string BuildToolsListResult(const Json::Value& id) { tools.append(tool); } - // 9) list_services(P3:服务链路,仅 Windows,一次性子链接) - { + // 9) list_services(P3:服务链路,仅 Windows,一次性子链接;P2-2:主机管理开启时由 host_inspect 取代) + if (showDegradedLists) { Json::Value tool(Json::objectValue); tool["name"] = "list_services"; - tool["description"] = u8"获取指定在线 Windows 主机的服务列表(显示名、服务名、可执行文件路径、运行状态、启动类型)。仅 Windows 客户端支持;一次性返回,结果按 limit/offset 分页。不支持服务端过滤。定位是 McpMachine=0(主机管理工具关闭)时的降级路径,字段较少(无描述、登录身份);若 host_inspect 出现在 tools/list 里,一律优先用它的 win32_services 项。"; + tool["description"] = u8"获取指定在线 Windows 主机的服务列表(显示名、服务名、可执行文件路径、运行状态、启动类型)。仅 Windows 客户端支持;一次性返回,结果按 limit/offset 分页。不支持服务端过滤。仅在 McpMachine=0(主机管理工具关闭)时出现;开启主机管理后改用 host_inspect 的 win32_services 项(字段更全:描述、登录身份)。注意两者都要求客户端以管理员权限运行,否则拿不到服务列表。"; tool["inputSchema"] = BuildPagedHostListInputSchema(); tool["outputSchema"] = BuildServiceListOutputSchema(); diff --git a/tools/mcp_tools/make_tools_json.py b/tools/mcp_tools/make_tools_json.py index fba4691..51926df 100644 --- a/tools/mcp_tools/make_tools_json.py +++ b/tools/mcp_tools/make_tools_json.py @@ -11,10 +11,17 @@ import json import sys if len(sys.argv) < 3: - sys.exit("用法: python make_tools_json.py ") + sys.exit("用法: python make_tools_json.py [tools_raw_machine_off.json]") SRC = sys.argv[1] DST = sys.argv[2] +# 可选:McpMachine=0 状态下的抓取。开启态的抓取里没有降级工具(P2-2), +# 而它们仍是真实工具,必须进清单——所以清单 = 两份抓取的并集。 +OFF_SRC = sys.argv[3] if len(sys.argv) > 3 else None + +# 只在 McpMachine=0 时出现的降级工具(gate = "!machine")。改动这个集合要同步更新 +# McpServer.cpp 里 showDegradedLists 那段。 +MACHINE_OFF_FALLBACKS = {"list_processes", "list_windows", "list_services"} # gate: 该工具要求哪个服务端开关为开(null = 无条件出现) # write: 需要 !McpReadonly @@ -24,13 +31,16 @@ GATE = { # P1-1:list_online_hosts / search_hosts / list_all_hosts 三合一(旧名为别名,不出现在 tools/list) "list_hosts": (None, False, False), "get_host_detail": (None, False, False), - "list_processes": (None, False, False), - "list_windows": (None, False, False), + # ---- McpMachine=0 时的降级路径(P2-2)---- + # 开启主机管理后它们由 host_inspect 的 processes / windows / win32_services 项取代, + # 所以只在开关关闭时进 tools/list(名字仍可作为别名调用)。 + "list_processes": ("!machine", False, False), + "list_windows": ("!machine", False, False), + "list_services": ("!machine", False, False), "get_activity_history": (None, False, False), "get_screenshot": (None, False, False), "get_foreground_window": (None, False, False), "list_files": (None, False, False), - "list_services": (None, False, False), "get_client_log": (None, False, False), "get_audit_log": (None, False, False), "get_server_status": (None, False, False), @@ -239,7 +249,33 @@ ROLES = { } raw = json.load(open(SRC, encoding="utf-8")) -tools_in = raw["result"]["tools"] +tools_on = raw["result"]["tools"] + +# 并集:开启态抓取 + 关闭态抓取里独有的降级工具。关闭态工具的描述/schema 也必须来自 +# 活服务端,不能沿用旧清单,否则清单会和二进制悄悄漂移。 +if OFF_SRC: + tools_off = json.load(open(OFF_SRC, encoding="utf-8"))["result"]["tools"] + on_names = {t["name"] for t in tools_on} + off_names = {t["name"] for t in tools_off} + off_only = [t for t in tools_off if t["name"] not in on_names] + bad = [t["name"] for t in off_only if GATE.get(t["name"], (None,))[0] != "!machine"] + if bad: + print(f"!! 关闭态抓取里有未声明为 !machine 的工具: {bad}", file=sys.stderr) + sys.exit(1) + absent = sorted(MACHINE_OFF_FALLBACKS - off_names) + if absent: + print(f"!! 关闭态抓取里缺少降级工具: {absent}", file=sys.stderr) + sys.exit(1) + leaked = sorted(n for n in MACHINE_OFF_FALLBACKS if n in on_names) + if leaked: + print(f"!! 开启态抓取里出现了降级工具(应已隐藏): {leaked}", file=sys.stderr) + sys.exit(1) + tools_on = tools_on + off_only +elif MACHINE_OFF_FALLBACKS & {t["name"] for t in tools_on}: + print("!! 未提供关闭态抓取,但开启态里有降级工具——清单会丢工具", file=sys.stderr) + sys.exit(1) + +tools_in = tools_on missing = [t["name"] for t in tools_in if t["name"] not in GATE] if missing: @@ -301,6 +337,9 @@ doc = { "由 tools/mcp_tools/dump_tools.py 抓取、make_tools_json.py 生成,勿手工编辑。", "gate: 该工具出现的开关条件(null = 无条件);write: 需 !McpReadonly;", "manage: 额外需 McpManage。这三项从 C++ 注册点的 if 条件解析而来,运行时不可见。", + "gate 为 \"!machine\" 表示该降级工具只在 McpMachine=0 时出现(开启主机管理后", + "由 host_inspect 的对应 aspect 取代,名字仍可作为别名调用);清单是开启态与", + "关闭态两份抓取的并集。", "platforms: 该工具涉及的任一主机都必须落在此集合内(win/lnx/mac/apk),依据各平台", "客户端对相应 COMMAND_ 的处理实现。apk 上 COMMAND_SYSTEM 与 COMMAND_SHELL 均为空实现。", "roles: 仅多主机工具才有。按参数名细分平台,表达 platforms 说不清的方向性能力", diff --git a/tools/mcp_tools/verify_tools.py b/tools/mcp_tools/verify_tools.py index a362ec6..9cf3f4d 100644 --- a/tools/mcp_tools/verify_tools.py +++ b/tools/mcp_tools/verify_tools.py @@ -10,7 +10,8 @@ port 省略时自动探测 6545(明文后端)/ 6544(TLS 前端) 比对内容:name / description / inputSchema / outputSchema,逐字段深度比较, -外加工具顺序。gate / write / manage / impl 是 tools.json 独有的元信息,不参与比对。 +外加工具顺序。gate / write / manage / impl 是 tools.json 独有的元信息,不参与比对; +例外是 gate == "!machine" 的降级工具——它们只在 McpMachine=0 时出现,不进本次比对。 """ import http.client import json @@ -119,14 +120,20 @@ def main(): doc = json.load(open(path, encoding="utf-8")) tools_json = doc["tools"] + # gate == "!machine" 的工具只在 McpMachine=0 时出现,而黄金样本/活服务都是开关 + # 全开的抓取,按约定它们不该在这里出现(tools.json 是两份抓取的并集)。 + off_gated = {t["name"] for t in tools_json if t.get("gate") == "!machine"} + tools_cmp = [t for t in tools_json if t["name"] not in off_gated] print(f"tools.json: {path} ({len(tools_json)} 个工具)") + if off_gated: + print(f" 其中 {len(off_gated)} 个 !machine 降级工具不计入本次比对: {sorted(off_gated)}") print(f"服务端: {len(tools_live)} 个工具") - if len(tools_json) != len(tools_live): - print(f"!! 数量不一致: {len(tools_json)} vs {len(tools_live)}") + if len(tools_cmp) != len(tools_live): + print(f"!! 数量不一致: {len(tools_cmp)} 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} + json_by_name = {t["name"]: t for t in tools_cmp} only_live = sorted(set(live_by_name) - set(json_by_name)) only_json = sorted(set(json_by_name) - set(live_by_name)) @@ -156,7 +163,7 @@ def main(): # 顺序一致性:tools/list 的数组顺序会影响模型的选择倾向 order_live = [t["name"] for t in tools_live] - order_json = [t["name"] for t in tools_json] + order_json = [t["name"] for t in tools_cmp] if order_live != order_json: print("!! 工具顺序不一致") for i, (x, y) in enumerate(zip(order_live, order_json)): @@ -168,7 +175,7 @@ def main(): print("工具顺序: 一致") if diffs == 0 and not only_live and not only_json: - print(f"\nPASS: {len(tools_json)} 个工具完全一致") + print(f"\nPASS: {len(tools_cmp)} 个工具完全一致") return 0 print(f"\nFAIL: {diffs} 处差异") return 1