Feature(mcp): merge the ten host_list_* tools into host_inspect

The ten read-only host-management tools (host_list_processes, windows,
network_state, software, browser_history, favorites, win32_services,
driver_services, scheduled_tasks, host_get_hosts_file) each carried a
name, description and schema for what is one connection to the host,
one tab id per aspect and one paged list shape. Ten entries made
tools/list hard to scan and took a large share of the description
budget.

They are now one tool, host_inspect(aspects[], ...), where aspects is a
required, deduplicated array of the ten former names. A single aspect
returns exactly what the old tool returned (same builder, same code
path), so output is byte-identical; several aspects are fetched over
separate managed sessions and merged into results.<aspect>, with
failures isolated in errors.<aspect> and isError only when every aspect
failed. Filters (pid/name/arch/title/url/publisher/folder/status/
start_type/process/protocol/ports/state/max_bytes) are still applied
server-side before paging and are ignored by aspects they don't apply
to.

The old names stay as dispatch aliases so existing callers keep working
but no longer appear in tools/list; the platform table, batch read-only
list, tool hints, instructions, generator tables and the captured
mcp/tools.json move to the new name (63 tools -> 54).

The description also notes that win32_services / driver_services need
an elevated client: a non-elevated one cannot open SCM and never
answers, so the call times out after ~12 s.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-12 17:21:36 +01:00
1 parent cac5adaafc
commit 59f0f16f74
5 files changed
+1034 -1803

No files matched your search

+19 -25
View File
@@ -287,10 +287,10 @@ const char* kServerInstructions =
u8"当前开关状态可查 get_server_status 的 switches。只读模式(readonly=true)会挡掉大部分写工具,"
u8"但只改服务端本地数据的 host_set_remark / host_set_watch_level 仍会列出,调用时才被拒;"
u8"get_keylog 也始终可见,只读模式下只是它的 clear / set_offline 参数被拒,读取不受影响。\n"
u8"同一能力存在两套工具时优先用主机管理族:host_list_processes / host_list_windows / "
u8"host_list_win32_services 字段更全(host_list_windows 支持 pid/title 过滤,"
u8"host_list_win32_services 支持 name/status 过滤),list_processes / list_windows / list_services "
u8"是它们在 McpMachine=0 时的降级路径。关闭窗口只有 operate_window 能做,host_control_window 没有 close。\n"
u8"同一能力存在两套工具时优先用主机管理族:host_inspect(aspects 选 processes / windows / "
u8"win32_services 等,支持 pid/title/status 等服务端过滤,字段更全),list_processes / "
u8"list_windows / list_services 是它在 McpMachine=0 时的降级路径。关闭窗口只有 operate_window 能做,"
u8"host_control_window 没有 close。\n"
u8"\n"
u8"3) 错误码与动作\n"
u8"-32002 主机离线或不存在:先刷新主机列表再选,不要拿旧快照反复重试。\n"
@@ -319,7 +319,7 @@ const char* kServerInstructions =
u8"它们的 ok 同样只代表客户端回了完成包,真实结果看 verified(true=复核确认生效、"
u8"false=复核确认未生效、null=复核没做成);删除不可恢复,recursive 必须显式传 true。"
u8"列表结果按 limit/offset 分页,total 是命中数、totalAll 是过滤前的总数。\n"
u8"进程排查:host_list_processes 或 list_processes 定位,kill_process 结束。这类动作没有真实回执,"
u8"进程排查:host_inspect(aspects=[\"processes\"])或 list_processes 定位,kill_process 结束。这类动作没有真实回执,"
u8"拿到 ok 后应再列一次复核,不要凭 ok 断言已生效。\n"
u8"GUI 自动化:remote_open 取得 session_id 与分辨率(screen_w/screen_h)→ get_screenshot 看画面 → "
u8"get_foreground_window 确认前台窗口(或用 remote_mouse / remote_keyboard 的 expect_hwnd 做前置校验)→ "
@@ -993,7 +993,7 @@ Json::Value BuildHostItemSchema() {
return itemProps;
}
// 列表型 outputSchema 的公共翻页字段,字段名与 McpMachine.cpp 的 host_list_* 保持一致
// 列表型 outputSchema 的公共翻页字段,字段名与 McpMachine.cpp 的 host_inspect 保持一致
void AppendPageOutputProps(Json::Value& props) {
const char* intFields[] = { "total", "totalAll", "offset", "limit" };
for (const char* f : intFields) {
@@ -1059,7 +1059,7 @@ Json::Value BuildHostDetailOutputSchema() {
capProps["c2cPaths"] = boolProp(u8"能否按路径清单接收另一台主机的文件(copy_files_c2c 源端的前提)");
capProps["registry"] = boolProp(u8"是否有 Windows 注册表可查(list_registry);仅 Windows 客户端为 true");
capProps["windowInfo"] = boolProp(
u8"是否支持窗口信息(get_foreground_window、host_list_windows 的坐标/前后台字段、"
u8"是否支持窗口信息(get_foreground_window、host_inspect 的 windows 项坐标/前后台字段、"
u8"operate_window/host_control_window 的 activate);仅声明 CLIENT_CAP_WINDOW_INFO 的新客户端为 true");
Json::Value caps(Json::objectValue);
caps["type"] = "object";
@@ -1906,7 +1906,7 @@ Json::Value BuildGetScreenshotInputSchema() {
hwndTypes.append("integer");
hwndTypes.append("string");
hwndProp["type"] = hwndTypes;
hwndProp["description"] = u8"window 模式必填:窗口句柄(整数或 0x 前缀字符串),取 host_list_windows / get_foreground_window 返回的 hwnd。窗口最小化时无法抓取(返回错误),先 activate/restore。";
hwndProp["description"] = u8"window 模式必填:窗口句柄(整数或 0x 前缀字符串),取 host_inspect 的 windows 项 / get_foreground_window 返回的 hwnd。窗口最小化时无法抓取(返回错误),先 activate/restore。";
props["hwnd"] = hwndProp;
Json::Value monProp(Json::objectValue);
@@ -2149,7 +2149,7 @@ std::string BuildToolsListResult(const Json::Value& id) {
{
Json::Value tool(Json::objectValue);
tool["name"] = "list_processes";
tool["description"] = u8"获取指定在线主机的进程列表(PID、映像名称、架构、程序完整路径)。通过主连接下发命令、子连接回传,一次性返回。可选 name(映像名子串,ASCII 不区分大小写)/ pid(精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。定位是 McpMachine=0(主机管理工具关闭)时的降级路径,字段较少;若 host_list_processes 出现在 tools/list 里,一律优先用它。";
tool["description"] = u8"获取指定在线主机的进程列表(PID、映像名称、架构、程序完整路径)。通过主连接下发命令、子连接回传,一次性返回。可选 name(映像名子串,ASCII 不区分大小写)/ pid(精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。定位是 McpMachine=0(主机管理工具关闭)时的降级路径,字段较少;若 host_inspect 出现在 tools/list 里,一律优先用它的 processes 项。";
tool["inputSchema"] = BuildFilteredPagedHostListInputSchema(
u8"按映像名子串过滤,ASCII 不区分大小写(如 chrome)",
@@ -2163,7 +2163,7 @@ std::string BuildToolsListResult(const Json::Value& id) {
{
Json::Value tool(Json::objectValue);
tool["name"] = "list_windows";
tool["description"] = u8"获取指定在线主机的顶层窗口列表(句柄、窗口标题、窗口状态、所属进程 PID)。一次性返回。可选 name(窗口标题子串,ASCII 不区分大小写)/ pid(所属进程,精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。定位是 McpMachine=0(主机管理工具关闭)时的降级路径;若 host_list_windows 出现在 tools/list 里,一律优先用它。";
tool["description"] = u8"获取指定在线主机的顶层窗口列表(句柄、窗口标题、窗口状态、所属进程 PID)。一次性返回。可选 name(窗口标题子串,ASCII 不区分大小写)/ pid(所属进程,精确)在服务端过滤,过滤在分页之前生效:total 为命中数、totalAll 为过滤前的总数。结果按 limit/offset 分页。定位是 McpMachine=0(主机管理工具关闭)时的降级路径;若 host_inspect 出现在 tools/list 里,一律优先用它的 windows 项。";
tool["inputSchema"] = BuildFilteredPagedHostListInputSchema(
u8"按窗口标题子串过滤,ASCII 不区分大小写(如 notepad);匹配的是标题不是进程名",
@@ -2225,7 +2225,7 @@ std::string BuildToolsListResult(const Json::Value& id) {
{
Json::Value tool(Json::objectValue);
tool["name"] = "list_services";
tool["description"] = u8"获取指定在线 Windows 主机的服务列表(显示名、服务名、可执行文件路径、运行状态、启动类型)。仅 Windows 客户端支持;一次性返回,结果按 limit/offset 分页。不支持服务端过滤。定位是 McpMachine=0(主机管理工具关闭)时的降级路径,字段较少(无描述、登录身份);若 host_list_win32_services 出现在 tools/list 里,一律优先用它。";
tool["description"] = u8"获取指定在线 Windows 主机的服务列表(显示名、服务名、可执行文件路径、运行状态、启动类型)。仅 Windows 客户端支持;一次性返回,结果按 limit/offset 分页。不支持服务端过滤。定位是 McpMachine=0(主机管理工具关闭)时的降级路径,字段较少(无描述、登录身份);若 host_inspect 出现在 tools/list 里,一律优先用它的 win32_services 项。";
tool["inputSchema"] = BuildPagedHostListInputSchema();
tool["outputSchema"] = BuildServiceListOutputSchema();
@@ -2632,7 +2632,7 @@ std::string BuildToolsListResult(const Json::Value& id) {
{
Json::Value tool(Json::objectValue);
tool["name"] = "operate_window";
tool["description"] = u8"对指定在线 Windows 主机的窗口执行操作:close(关闭)/show(显示)/hide(隐藏)/minimize(最小化)/maximize(最大化)/restore(还原)/activate(激活到前台)。hwnd 取 list_windows 或 host_list_windows 返回的 hwnd。ok 仅表示已下发(窗口句柄可能已失效);action=activate 例外:工具会在动作后用窗口信息 RPC 复核 GetForegroundWindow,返回 ok/state(foreground|background|missing)/window,旧客户端不支持时返回 -32005(可退回 show)。关闭窗口只有本工具能做,host_control_window 不提供 close,且它会重新枚举可见窗口复核结果。dry_run=true 只校验 hwnd 是否还在可见窗口列表里并返回该窗口信息,不发送任何命令。";
tool["description"] = u8"对指定在线 Windows 主机的窗口执行操作:close(关闭)/show(显示)/hide(隐藏)/minimize(最小化)/maximize(最大化)/restore(还原)/activate(激活到前台)。hwnd 取 list_windows 或 host_inspect 的 windows 项返回的 hwnd。ok 仅表示已下发(窗口句柄可能已失效);action=activate 例外:工具会在动作后用窗口信息 RPC 复核 GetForegroundWindow,返回 ok/state(foreground|background|missing)/window,旧客户端不支持时返回 -32005(可退回 show)。关闭窗口只有本工具能做,host_control_window 不提供 close,且它会重新枚举可见窗口复核结果。dry_run=true 只校验 hwnd 是否还在可见窗口列表里并返回该窗口信息,不发送任何命令。";
tool["inputSchema"] = BuildOperateWindowInputSchema();
tool["outputSchema"] = BuildOperateWindowOutputSchema();
tools.append(tool);
@@ -2945,7 +2945,7 @@ void AppendHostTechnicalDetail(CMy2015RemoteDlg* parent, uint64_t devId, Json::V
caps["fileTransferV2"] = ctx->SupportsFileV2();
caps["c2cPaths"] = ctx->SupportsC2CPaths();
caps["registry"] = IsWindowsClient(ctx);
// windowInfo → get_foreground_window / host_list_windows 的矩形与 activate(SupportsWindowInfo)
// windowInfo → get_foreground_window / host_inspect 的 windows 项矩形与 activate(SupportsWindowInfo)
caps["windowInfo"] = ctx->SupportsWindowInfo();
// privacyOverlay → Android 的 remote_block_input(无障碍 overlay)。Windows 恒可用、
// 不声明这个位,所以这里只对「非 Windows 且声明了能力位」的主机为 true。
@@ -5251,7 +5251,7 @@ Json::Value BuildRemoteOpenInputSchema() {
hwndTypes.append("integer");
hwndTypes.append("string");
hwndProp["type"] = hwndTypes;
hwndProp["description"] = u8"可选:只推该窗口(DWM 可见边框,含标题栏),帧尺寸与归一化坐标都相对该窗口,带宽和点击精度都优于整屏。取 host_list_windows / get_foreground_window 返回的 hwnd(整数或 0x 前缀字符串);最小化窗口会被拒绝(-32009)。与 region 互斥。要求客户端能力位 CLIENT_CAP_WINDOW_INFO(新 Windows 客户端),老客户端返回 -32005。";
hwndProp["description"] = u8"可选:只推该窗口(DWM 可见边框,含标题栏),帧尺寸与归一化坐标都相对该窗口,带宽和点击精度都优于整屏。取 host_inspect 的 windows 项 / get_foreground_window 返回的 hwnd(整数或 0x 前缀字符串);最小化窗口会被拒绝(-32009)。与 region 互斥。要求客户端能力位 CLIENT_CAP_WINDOW_INFO(新 Windows 客户端),老客户端返回 -32005。";
props["window_hwnd"] = hwndProp;
Json::Value regionProp(Json::objectValue);
@@ -6027,7 +6027,7 @@ static std::string WindowNotFoundErrorJson(const Json::Value& id, uint32_t hwnd,
if (truncated)
return BuildError(id, -32009, win + " is not in the returned window list, and that list was "
"truncated at 96 windows (the host has more visible windows), "
"so the window may still exist; verify with host_list_windows "
"so the window may still exist; verify with host_inspect "
"or use the foreground window");
return BuildError(id, -32009, win + " is not in the current visible window list "
"(hidden, closed, or not a visible top-level window)");
@@ -11782,16 +11782,10 @@ const ToolPlatform kToolPlatforms[] = {
{ "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 },
// P2-1:10 个 host_list_* / host_get_hosts_file 合并为 host_inspect。
// 旧名是别名(不进 tools/list,也不进平台表);它们的目标 builder 自己会
// ResolveHost(requireWindows=true),所以别名仍然拿得到 -32005。
{ "host_inspect", kPlatWin },
{ "host_control_process", kPlatWin },
{ "host_control_window", kPlatWin },
{ "host_control_service", kPlatWin },