Files
SimpleRemoter/mcp/tools.json
T
yuanyuanxianganddeepseek-flash 42dd70fe20 Fix(mcp): make terminal busy and cancel semantics usable by an agent
exec_command answered -32003 "device busy" with no way forward: the message
named neither the occupying session nor how to free it, and mcp_cancel_session
could only target in-flight calls, so a persistent terminal left behind by an
earlier session blocked the host until its idle timer expired. An agent had no
route back to a working state.

Build the busy text from the live session table: terminal sessions now report
parent session_id, idle and elapsed seconds, and point at terminal_exec (or
terminal_close with id and session_id) when a persistent session holds the
host, or at mcp_cancel_session(request_id) when the occupier is a running
exec_command. exec_command sweeps idle terminals before it begins a pending
wait, so a session abandoned after 300s does not require a terminal_* call
first; SweepIdleTerminals now requires started so it cannot reclaim a session
that is still in BeginTermPending and hand the device to a second caller.

Cancel becomes addressable and honest. id=0 is rejected with -32602 instead of
being treated as "all hosts", the calling request is excluded from matched and
released (previously the poll saw itself and released was never true), rows
carry cancellable, and when nothing was cancelled the reply lists what matched
and which close tool takes it. Instructions, tool description, inputSchema
(anyOf request_id/id/session_id) and the released description now agree:
kind=call only, persistent sessions close by id+session_id, pending and
file_transfer entries are released by cancelling the call that owns them.

tools.json is regenerated for the schema and description changes. Debug server
builds, check_platform_table.py and gen_go_tools.py --check pass; the Release
instance was not rebuilt or restarted.

Co-Authored-By: deepseek-flash
2026-11-13 11:56:25 +01:00

5409 lines
202 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"_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 条件解析而来,运行时不可见。",
"gate 为 \"!machine\" 表示该降级工具只在 McpMachine=0 时出现(开启主机管理后",
"由 host_inspect 的对应 aspect 取代,名字仍可作为别名调用);清单是开启态与",
"关闭态两份抓取的并集。",
"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": 54,
"tools": [
{
"name": "list_hosts",
"description": "列主机:默认只返回在线主机(含计算机名、IP、操作系统、版本、备注、分组、活动窗口、延迟等实时信息),include_offline=true 时连离线主机(历史连接过、当前未连接,来自主机列表记录)一起返回,在线主机排在最前面。query 子串匹配计算机名/备注/IP;group / os / client_type 为附加过滤条件(均可选、AND 组合、子串匹配、ASCII 不区分大小写);online=false 只看离线主机。过滤在分页之前生效:total 为命中台数,totalAll 为过滤前的主机库台数。结果按 limit/offset 分页(默认 100 条,上限 1000),hasMore 表示还有下一页。离线主机另有 last_seen(最后一次登录时间)、install_time 字段,但没有 rtt/version/activeWindow 等实时字段,也没有 clientType(按平台筛历史主机请用 os),group 恒为 default。authStatus 为主机授权状态(unauthorized/authorized_by_super/authorized_by_admin/forbidden)。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"
},
"include_offline": {
"description": "是否把离线主机一起返回,默认 false(只给在线);online=false 时无意义。list_all_hosts 别名默认 true。",
"type": "boolean"
},
"ip": {
"description": "只按 IP 过滤(search_hosts 的旧参数);与 query 同时给出时两者都需满足。",
"type": "string"
},
"limit": {
"description": "本次最多返回的条数,默认 100,上限 1000。",
"type": "integer"
},
"name": {
"description": "只按计算机名/备注过滤(search_hosts 的旧参数);与 query 同时给出时两者都需满足。",
"type": "string"
},
"offset": {
"description": "跳过前 N 条,默认 0;配合返回的 total/hasMore 翻页。",
"type": "integer"
},
"online": {
"description": "true(默认)返回在线主机;false 只返回离线主机(历史连接过、当前未连接)。",
"type": "boolean"
},
"os": {
"description": "按操作系统过滤(子串,不区分大小写,如 Windows、Linux、Android)。省略则不过滤。",
"type": "string"
},
"query": {
"description": "关键字:子串匹配计算机名、备注或 IP(ASCII 不区分大小写)。省略则不过滤。",
"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_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 的前提);Android 客户端只支持整屏目标,且需要已授权录屏与无障碍服务;还要求服务端 Web 远程服务已启动(WebSvrPort>0)",
"type": "boolean"
},
"screenPreview": {
"description": "能否截屏(get_screenshot 的前提)",
"type": "boolean"
},
"screenRegion": {
"description": "能否按区域/窗口/显示器原生分辨率截屏(get_screenshot 的 mode=region/window/monitor 前提);仅声明 CLIENT_CAP_SCREEN_REGION 的新 Windows 客户端为 true",
"type": "boolean"
},
"windowInfo": {
"description": "是否支持窗口信息(get_foreground_window、host_inspect 的 windows 项坐标/前后台字段、operate_window/host_control_window 的 activate);仅声明 CLIENT_CAP_WINDOW_INFO 的新客户端为 true",
"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": "get_activity_history",
"description": "获取指定在线主机的历史活动记录。Windows 与有桌面的 Linux 客户端返回前台窗口驻留记录,每行一条「[时间] [标题] 时长」;Android 客户端返回前台应用驻留记录(标题为「应用名 (包名)」,需开启无障碍服务);无桌面的 Linux 客户端返回登录记录与 shell 命令历史,每行带「[登录]」或「[命令]」标签(首行为「[来源]」说明)。主连接 RPC。结果按 limit/offset 分页(默认 100 条、上限 1000),新在前:offset=0 就是最近 limit 条,想看更早的再往后翻。total 为本机现有记录总数,hasMore 表示还有更早的记录;窗口后端只保留最近 500 条,所以 total 最多约 501(含进行中的当前窗口)。",
"gate": null,
"platforms": [
"win",
"lnx",
"apk"
],
"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": {
"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、一次性返回。Android 客户端用无障碍服务 takeScreenshot 抓屏(Android 11+ 且开启无障碍服务,此时登录会声明该能力位;只支持 mode=screen)。mode 可选 screen(默认,整虚拟桌面)/region(指定矩形)/window(指定 hwnd)/monitor(指定显示器);后三种默认按源尺寸 1:1 原生分辨率抓取(适合 OCR/视觉读字),需要较新的 Windows 客户端(CLIENT_CAP_SCREEN_REGION,否则 -32005),结果在 structuredContent.capture 里回报实际源矩形与缩放比例。",
"gate": null,
"platforms": [
"win",
"lnx",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"height": {
"description": "region 模式必填:矩形高度(像素,1~8192)。超出虚拟桌面的部分会被裁剪。",
"type": "integer"
},
"hwnd": {
"description": "window 模式必填:窗口句柄(整数或 0x 前缀字符串),取 host_inspect 的 windows 项 / get_foreground_window 返回的 hwnd。窗口最小化时无法抓取(返回错误),先 activate/restore。",
"type": [
"integer",
"string"
]
},
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"max_width": {
"description": "期望图片最大宽度(像素,钳制到 64~1920)。screen 模式省略或传 0 时沿用 RTT 自适应缩略图档位(最大 1024);region/window/monitor 模式省略/传 0 时按源尺寸 1:1 抓取(原生分辨率),显式传入才等比缩小。",
"type": "integer"
},
"mode": {
"description": "抓取范围,默认 screen。screen=整个虚拟桌面(可缩放);region=指定矩形;window=指定窗口;monitor=指定显示器。region/window/monitor 默认按源尺寸 1:1 抓取(原生分辨率,适合 OCR/视觉读字),只有显式传 max_width 才缩放;这三种需要较新的 Windows 客户端(能力位 CLIENT_CAP_SCREEN_REGION),否则返回 -32005。",
"enum": [
"screen",
"region",
"window",
"monitor"
],
"type": "string"
},
"monitor": {
"description": "monitor 模式:显示器序号,0=主显示器(默认),1..N 为其余显示器(按系统枚举顺序)。序号越界返回错误。",
"type": "integer"
},
"width": {
"description": "region 模式必填:矩形宽度(像素,1~8192)。超出虚拟桌面的部分会被裁剪。",
"type": "integer"
},
"x": {
"description": "region 模式:矩形左上角的虚拟桌面 X 坐标(可为负;多显示器时以虚拟桌面左上角为原点)。省略按 0 处理。",
"type": "integer"
},
"y": {
"description": "region 模式:矩形左上角的虚拟桌面 Y 坐标(可为负)。省略按 0 处理。",
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
},
"outputSchema": {
"properties": {
"capture": {
"properties": {
"height": {
"type": "integer"
},
"mode": {
"type": "string"
},
"native": {
"type": "boolean"
},
"scale": {
"type": "integer"
},
"width": {
"type": "integer"
},
"x": {
"type": "integer"
},
"y": {
"type": "integer"
}
},
"type": "object"
},
"image": {
"properties": {
"bytes": {
"type": "integer"
},
"height": {
"type": "integer"
},
"mimeType": {
"type": "string"
},
"width": {
"type": "integer"
}
},
"type": "object"
}
},
"required": [
"image"
],
"type": "object"
}
},
{
"name": "get_foreground_window",
"description": "获取指定在线 Windows 主机当前的前台窗口(GetForegroundWindow):标题、hwnd、pid、虚拟桌面坐标矩形、是否最小化/最大化、z 序与可见窗口总数。注入键鼠前先用它确认焦点在目标窗口上(remote_keyboard / remote_mouse 的 expect_hwnd 也可做同样的前置校验)。主连接 RPC、一次性返回;要求客户端能力位 CLIENT_CAP_WINDOW_INFO(新客户端),老客户端返回 -32005。只读。",
"gate": null,
"platforms": [
"win"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"outputSchema": {
"properties": {
"window": {
"properties": {
"bottom": {
"type": "integer"
},
"height": {
"type": "integer"
},
"hwnd": {
"type": "integer"
},
"isForeground": {
"type": "boolean"
},
"left": {
"type": "integer"
},
"maximized": {
"type": "boolean"
},
"minimized": {
"type": "boolean"
},
"pid": {
"type": "integer"
},
"right": {
"type": "integer"
},
"title": {
"type": "string"
},
"top": {
"type": "integer"
},
"visible": {
"type": "boolean"
},
"width": {
"type": "integer"
},
"zOrder": {
"type": "integer"
}
},
"type": [
"object",
"null"
]
},
"windowCount": {
"type": "integer"
}
},
"required": [
"window",
"windowCount"
],
"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_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": "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 说明裁剪情况。只读。",
"gate": null,
"platforms": [
"win",
"lnx",
"mac",
"apk"
],
"impl": "mfc",
"inputSchema": {
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ids"
]
}
],
"properties": {
"filter": {
"description": "只看包含该子串的行(ASCII 不区分大小写,如 error / TIMEOUT);过滤后再取末尾 limit 行",
"type": "string"
},
"id": {
"description": "主机 id,取 list_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_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": "取消在飞请求并尽快释放主机占用。只能取消 kind=call 的在飞调用:给 request_id(tools/call 的 JSON-RPC id,类型要与调用时一致)精确取消一次,或按 id(主机,必须非 0)/ session_id 取消匹配的调用(两个都给则必须同时匹配)。取消一次卡住的调用会连带释放它持有的 pending / file_transfer 等待;持久会话本身不会被关闭,terminal / remote_control / chat 分别用 terminal_close / remote_close / chat_close(两者都要同时给 id 与 session_id)。工具层的等待在 ≤500ms 内退出并走既有清理路径;本工具最多等 2s,返回 cancelled(真正取消的调用个数,不含本工具自身)、released(这些调用是否已释放占用)、waited_ms 与 matched(匹配到的所有会话,每项带 cancellable)。被取消的请求以 -32800 结束。等价于对 SSE 流发 notifications/cancelled。",
"gate": null,
"platforms": [
"win",
"lnx",
"mac",
"apk"
],
"impl": "mfc",
"inputSchema": {
"anyOf": [
{
"required": [
"request_id"
]
},
{
"required": [
"id"
]
},
{
"required": [
"session_id"
]
}
],
"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 内被取消的在飞调用(kind=call,不含本工具自身)是否已从服务端表中消失(主机已松开)",
"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_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 或 Android 主机上执行一条命令并返回 stdout 与退出码(受只读模式与命令白名单约束,默认仅允许只读命令前缀,见 McpReadonly / McpCmdWhitelist;Linux/Android 有独立的 POSIX 默认白名单,禁用 ; 反引号 $( ${ ! 等串联/子命令字符)。Android 上 shell 是 /system/bin/sh(mksh),可用命令由 toybox 提供。",
"gate": null,
"write": true,
"platforms": [
"win",
"lnx",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"command": {
"description": "要执行的命令(受只读模式与命令白名单约束,仅允许只读命令前缀;Windows 与 Linux 使用各自的内置默认白名单)",
"type": "string"
},
"id": {
"description": "主机 id,取 list_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 或 Android 主机上打开一个持久 shell 会话并返回 session_id 与终端模式。后续 terminal_exec 复用该会话(cwd/环境变量跨命令保持),用毕须 terminal_close。若该主机已有持久会话(包括 terminal_exec 隐式创建的),直接复用并返回 reused:true,不会报 -32003。Linux/Android 使用 POSIX PTY(UTF-8,is_pty=true),Android 的 shell 是 /system/bin/sh(mksh)。",
"gate": "terminal",
"write": true,
"platforms": [
"win",
"lnx",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_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"
},
"reused": {
"description": "true=该主机已有持久会话,本次直接复用(未新建);false=本次新建",
"type": "boolean"
},
"session_id": {
"description": "持久会话 token,后续 terminal_exec / terminal_close 用",
"type": "string"
}
},
"required": [
"session_id",
"is_pty"
],
"type": "object"
}
},
{
"name": "terminal_exec",
"description": "在已打开的持久会话中执行一条命令,或轮询取回正在运行的命令输出。带 command 时执行并在 timeout_ms 内等待;等待超时返回 done:false 与已产生的部分输出,会话不销毁(命令仍在远端运行)。session_id 可省略:自动复用该主机已有的持久会话,没有就隐式打开一个(结果里有 session_id 与 reused),不必先 terminal_open。不带 command、只传 session_id 时进入轮询模式:继续等待并取回增量输出,直到 done:true(此时有 exit_code)。命令不受白名单约束。PTY 会话(新 Windows 客户端 ConPTY / Linux 与新版 Android 的 POSIX PTY)下可用管道 | 与 && / || 串联,退出码取整条管道/串联,适合「ls -1 | wc -l」这类先过滤再回传的用法;不要用后台执行符 &(POSIX)或换行。老非 PTY Windows 客户端仍不支持 & 与 |,请拆成多条调用。",
"gate": "terminal",
"write": true,
"platforms": [
"win",
"lnx",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"command": {
"description": "要执行的命令(完整 shell,不受白名单约束)。省略时进入轮询模式:不执行新命令,只等待并取回当前会话的增量输出(上一条命令超时后用这个方式继续取)。PTY 会话(Windows ConPTY / Linux PTY)下可用管道 | 与 && / || 串联,退出码取整条管道/串联;不要用后台执行符 &(POSIX)或换行。老非 PTY 客户端仍不支持 & 与 |,请拆成多条调用。Linux 下通过 POSIX shell 执行,可用 ; 串联且退出码取最后一条命令",
"type": "string"
},
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"max_output_bytes": {
"description": "单次返回的原始输出上限(可选,默认 65536,最小 1024,最大 1048576);超出按换行边界截断并置 truncated:true,再轮询一次可取回剩余",
"type": "integer"
},
"session_id": {
"description": "会话 token。带 command 时可省略:自动复用该主机已有的持久会话,没有就在内部打开一个(结果里有 session_id 与 reused)。轮询模式必须提供",
"type": "string"
},
"timeout_ms": {
"description": "本次调用最多等待的毫秒数(可选,默认 20000,上限 600000)。等待超时不算失败:返回 done:false 与已产生的输出,命令仍在远端运行,继续轮询即可",
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
},
"outputSchema": {
"properties": {
"done": {
"description": "false=命令仍在运行,用同一工具只传 session_id 继续取增量;true=命令已结束,exit_code 有效",
"type": "boolean"
},
"dropped_bytes": {
"description": "因单条命令输出超过 8MB 上限被丢弃的最旧字节数(该命令累计,0 或省略=无丢失)",
"type": "integer"
},
"elapsed_ms": {
"description": "本次调用实际等待的毫秒数",
"type": "integer"
},
"exit_code": {
"description": "退出码(done=true 时提供):PTY 客户端(Windows ConPTY / Linux PTY)为命令的真实退出码;老客户端(非 PTY)仅区分 0/非 0;-1=未知(shell 进程退出)",
"type": "integer"
},
"is_pty": {
"description": "true=PTY(UTF-8)(Windows ConPTY / Linux PTY);false=老 cmd 管道(GBK)",
"type": "boolean"
},
"reused": {
"description": "true=复用了该主机已有的持久会话;false=本次隐式新建(省略 session_id 时)",
"type": "boolean"
},
"session_id": {
"description": "会话 token,原样回传,便于续接轮询",
"type": "string"
},
"stdout": {
"description": "本次新增的输出(已剥哨兵与 ANSI 转义)",
"type": "string"
},
"truncated": {
"description": "true=本次受 max_output_bytes 限制仍有剩余输出,立即再轮询即可取回",
"type": "boolean"
}
},
"required": [
"stdout",
"done",
"session_id"
],
"type": "object"
}
},
{
"name": "terminal_close",
"description": "关闭并释放指定持久会话(幂等:会话已不存在也返回成功)。",
"gate": "terminal",
"write": true,
"platforms": [
"win",
"lnx",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_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 或 Android 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id、抓屏帧尺寸(screen_w/screen_h)与目标(target)。默认推整屏/整虚拟桌面(可能等比缩放);可用 window_hwnd 只推一个窗口,或用 region 只推一个矩形区域,带宽、延迟和点击精度都更好,此时归一化坐标 0..1 相对该目标帧。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入;window_hwnd/region 仅支持声明 CLIENT_CAP_WINDOW_INFO 的新 Windows 客户端。Windows 多显示器下整屏目标需要新版客户端(整虚拟桌面抓屏),老客户端会被拒绝;window 目标不依赖虚拟桌面抓屏,不受此限。Android 主机只支持整屏目标,输入被翻译成触摸手势与全局动作(见 remote_mouse / remote_keyboard);抓屏依赖客户端已授权录屏(MediaProjection),未授权时 remote_open 会一直等不到屏幕子连接,注入还依赖无障碍服务在跑(未开启时命令照样下发但不生效,且没有回执)。",
"gate": "remote_control",
"write": true,
"platforms": [
"win",
"lnx",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"region": {
"description": "可选:只推该矩形区域(虚拟桌面物理像素,超出部分自动裁剪;裁剪后为空返回 -32009)。与 window_hwnd 互斥。region 内的归一化坐标 0..1 相对该矩形。要求新 Windows 客户端(窗口信息响应带虚拟桌面矩形),否则返回 -32005。",
"properties": {
"height": {
"description": "矩形高度(像素,1~8192)",
"type": "integer"
},
"width": {
"description": "矩形宽度(像素,1~8192)",
"type": "integer"
},
"x": {
"description": "矩形左上角 X(虚拟桌面绝对坐标,可为负;省略按 0)",
"type": "integer"
},
"y": {
"description": "矩形左上角 Y(虚拟桌面绝对坐标,可为负;省略按 0)",
"type": "integer"
}
},
"required": [
"width",
"height"
],
"type": "object"
},
"timeout_ms": {
"description": "等待屏幕子连接建立 + 分辨率到达的超时毫秒数(可选,默认 20000,上限 600000)",
"type": "integer"
},
"window_hwnd": {
"description": "可选:只推该窗口(DWM 可见边框,含标题栏),帧尺寸与归一化坐标都相对该窗口,带宽和点击精度都优于整屏。取 host_inspect 的 windows 项 / get_foreground_window 返回的 hwnd(整数或 0x 前缀字符串);最小化窗口会被拒绝(-32009)。与 region 互斥。要求客户端能力位 CLIENT_CAP_WINDOW_INFO(新 Windows 客户端),老客户端返回 -32005。",
"type": [
"integer",
"string"
]
}
},
"required": [
"id"
],
"type": "object"
},
"outputSchema": {
"properties": {
"region": {
"description": "region 目标时实际生效的矩形(虚拟桌面坐标,已裁剪;width/height 为物理像素)",
"properties": {
"height": {
"type": "integer"
},
"width": {
"type": "integer"
},
"x": {
"type": "integer"
},
"y": {
"type": "integer"
}
},
"type": "object"
},
"screen_h": {
"description": "抓屏帧高度(发送帧像素)",
"type": "integer"
},
"screen_w": {
"description": "抓屏帧宽度(发送帧像素:整屏/整虚拟桌面/目标窗口/区域,可能已等比缩放),用于把归一化坐标 0..1 映射为像素",
"type": "integer"
},
"session_id": {
"description": "控制会话 token,后续 remote_mouse / remote_keyboard / remote_close 用",
"type": "string"
},
"target": {
"description": "抓屏帧目标:screen=整屏/整虚拟桌面;window=目标窗口;region=指定区域",
"type": "string"
},
"window_hwnd": {
"description": "window 目标时的窗口句柄;其他目标不返回",
"type": "integer"
}
},
"required": [
"session_id",
"target",
"screen_w",
"screen_h"
],
"type": "object"
}
},
{
"name": "remote_close",
"description": "关闭并释放指定远程控制会话(幂等:会话已不存在也返回成功)。",
"gate": "remote_control",
"write": true,
"platforms": [
"win",
"lnx",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_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)。可选 expect_hwnd:注入前先确认目标窗口仍在可见列表里(整数或 0x 字符串);配合 require_foreground=true 还要求它已是前台,否则不发注入返回 -32000;同时默认在结果里回报注入后的前台窗口(structuredContent.foreground),用于确认按键真的进了目标窗口。窗口校验仅新 Windows 客户端支持,其他客户端返回 -32005。Android 主机没有键盘注入:只有 ESC(返回)/HOME(桌面)/APPS(任务列表)/PRINTSCREEN(截屏)这类全局动作、方向键(TV 主机)以及 key=V(粘贴当前剪贴板,需要新版 APK)生效,action=type 对 Android 直接返回 -32005,expect_hwnd 系列参数也返回 -32005;注入需要客户端开启无障碍服务,且没有回执(ok 只代表已下发)。",
"gate": "remote_control",
"write": true,
"platforms": [
"win",
"lnx",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"action": {
"description": "动作:key_down / key_up / key_press / type",
"type": "string"
},
"expect_hwnd": {
"description": "可选:注入前先确认目标窗口仍在当前可见窗口列表中(整数或 0x 前缀字符串)。顺带默认回报前台窗口;仅新 Windows 客户端支持(否则 -32005)。",
"type": [
"integer",
"string"
]
},
"id": {
"description": "主机 id,取 list_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"
},
"report_foreground": {
"description": "可选:注入后回报前台窗口(structuredContent.foreground)。给了 expect_hwnd 时默认 true",
"type": "boolean"
},
"require_foreground": {
"description": "可选:配合 expect_hwnd,要求该窗口已是前台,否则不发注入并返回 -32000。默认 false",
"type": "boolean"
},
"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": {
"expectedWindow": {
"description": "expect_hwnd 时注入前的目标窗口快照",
"type": "object"
},
"foreground": {
"description": "注入后的前台窗口(report_foreground 时返回;无前台窗口为 null)",
"type": [
"object",
"null"
]
},
"foregroundError": {
"description": "前台回报失败的原因(注入本身已成功)",
"type": "string"
}
},
"type": "object"
}
},
{
"name": "remote_mouse",
"description": "向已建立的远程控制会话注入鼠标事件。action 可选 move / down / up / click / right_click / middle_click / drag / scroll;坐标 x/y(及 drag 的 x2/y2)为归一化 0..1 浮点,默认相对整屏/整虚拟桌面(remote_open 用 window_hwnd/region 时相对该目标帧)。给 window_hwnd 时改为相对「该窗口与虚拟桌面的交集」(窗口完整可见时即窗口本身;0=左/上边缘,1=右/下边缘),可直接照 get_screenshot mode=window 的图量比例:服务端用该交集与虚拟桌面矩形换算成屏幕坐标,并默认要求该窗口在前台(require_foreground=false 可显式关闭;与 expect_hwnd 同时给出时须指向同一窗口);会话本身已锁定窗口/区域时不要再传 window_hwnd。button 可选 left/middle/right(默认 left);click 的 clicks 可选 1/2/3(默认 1);scroll 的 delta 正=向下滚、负=向上滚。可选 expect_hwnd / require_foreground / report_foreground 与 remote_keyboard 同义(新 Windows 客户端),可用它确认点击确实落在目标窗口。Android 主机把事件翻译成触摸:click=点按、right_click=长按、drag=滑动、scroll=上下滑,middle_click 无效果,down/up 单独使用无意义;window_hwnd 系列参数返回 -32005,注入需要客户端开启无障碍服务且没有回执(ok 只代表已下发)。",
"gate": "remote_control",
"write": true,
"platforms": [
"win",
"lnx",
"apk"
],
"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"
},
"expect_hwnd": {
"description": "可选:注入前先确认目标窗口仍在当前可见窗口列表中(整数或 0x 前缀字符串)。顺带默认回报前台窗口;仅新 Windows 客户端支持(否则 -32005)。",
"type": [
"integer",
"string"
]
},
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"report_foreground": {
"description": "可选:注入后回报前台窗口(structuredContent.foreground)。给了 expect_hwnd 时默认 true",
"type": "boolean"
},
"require_foreground": {
"description": "可选:配合 expect_hwnd,要求该窗口已是前台,否则不发注入并返回 -32000。默认 false",
"type": "boolean"
},
"session_id": {
"description": "remote_open 返回的 session_id",
"type": "string"
},
"window_hwnd": {
"description": "可选:以该窗口为坐标基准(整数或 0x 前缀字符串)。给定后 x/y(及 drag 的 x2/y2)变为相对「窗口与虚拟桌面的交集」的归一化坐标(窗口完整可见时即窗口本身),服务端用该交集与虚拟桌面矩形换算成屏幕坐标,可直接用 get_screenshot mode=window 图上的比例点。默认要求该窗口是前台(可用 require_foreground=false 显式关闭;与 expect_hwnd 同时给出时须指向同一窗口);窗口不存在/最小化/完全移出虚拟桌面时报错。仅新 Windows 客户端支持(窗口信息 RPC 需带虚拟桌面矩形),否则 -32005。会话本身已只推窗口/区域(remote_open 的 window_hwnd/region)时不要再传:坐标本来就相对目标帧。",
"type": [
"integer",
"string"
]
},
"x": {
"description": "归一化 X 坐标(0=屏幕最左,1=最右);给了 window_hwnd 时改为相对「窗口与虚拟桌面的交集」(窗口完整可见时即窗口),0=左边缘,1=右边缘",
"type": "number"
},
"x2": {
"description": "拖拽终点 X(仅 drag;坐标基准与 x 相同)",
"type": "number"
},
"y": {
"description": "归一化 Y 坐标(0=屏幕最上,1=最下);给了 window_hwnd 时改为相对「窗口与虚拟桌面的交集」(窗口完整可见时即窗口),0=上边缘,1=下边缘",
"type": "number"
},
"y2": {
"description": "拖拽终点 Y(仅 drag;坐标基准与 y 相同)",
"type": "number"
}
},
"required": [
"id",
"session_id",
"action",
"x",
"y"
],
"type": "object"
},
"outputSchema": {
"properties": {
"coordinateWindow": {
"description": "window_hwnd 时命中的窗口原始快照(left/top/right/bottom/width/height,未裁剪);实际归一化基准是 resolved.basis(窗口与虚拟桌面的交集)",
"type": "object"
},
"expectedWindow": {
"description": "expect_hwnd 时注入前的目标窗口快照",
"type": "object"
},
"foreground": {
"description": "注入后的前台窗口(report_foreground 时返回;无前台窗口为 null)",
"type": [
"object",
"null"
]
},
"foregroundError": {
"description": "前台回报失败的原因(注入本身已成功)",
"type": "string"
},
"resolved": {
"description": "window_hwnd 时换算后的发送帧归一化坐标(frame_x/frame_y,drag 另有 frame_x2/frame_y2);basis 为实际坐标基准矩形 left/top/right/bottom(窗口与虚拟桌面的交集,与 get_screenshot mode=window 的源矩形一致)",
"type": "object"
}
},
"type": "object"
}
},
{
"name": "remote_clipboard",
"description": "把文本写入远程主机的剪贴板(服务端按 GBK/ANSI 下发,Linux 客户端自动转回 UTF-8,Android 客户端按 GBK 解码;非 GBK 字符如 emoji 会丢失)。仅设置剪贴板,粘贴需随后用 remote_keyboard 注入 Ctrl+V;Linux 需要 X11 桌面与 xclip/xsel,Android 用 remote_keyboard 的 key=V(粘贴到当前焦点输入框,需要新版 APK;粘贴依赖无障碍服务)。",
"gate": "remote_control",
"write": true,
"platforms": [
"win",
"lnx",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_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_lock_screen",
"description": "把远程 Android 主机锁屏。报文是 COMMAND_SCREEN_CTRL_ALT_DEL(客户端的 Ctrl+Alt+Del 命令,目前只有 Android 实现:没有该组合键,客户端映射为系统的 GLOBAL_ACTION_LOCK_SCREEN)。需先 remote_open 建立会话;锁定后锁屏界面会挡住后续注入,要继续操作得先有人解锁(密码/指纹)。没有回执:ok 只代表命令已下发,实际是否锁上取决于系统策略(例如已设置设备管理器策略、部分定制 ROM 可能忽略),请随后用 get_screenshot 确认。只有声明 CLIENT_CAP_LOCK_SCREEN 的新版 APK 支持,老 APK 与 Windows/Linux 主机返回 -32005。",
"gate": "remote_control",
"write": true,
"platforms": [
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"session_id": {
"description": "remote_open 返回的 session_id",
"type": "string"
}
},
"required": [
"id",
"session_id"
],
"type": "object"
},
"outputSchema": {
"properties": {},
"type": "object"
}
},
{
"name": "remote_block_input",
"description": "锁定或解除目标主机的本机键鼠/触摸。做 GUI 自动化时先 block=true,真人碰一下屏幕就不会打断流程。必须带期限:max_block_ms(默认 300000 毫秒)到期由服务端自动解除,并在下一次调用结果的 auto_unblocked 里上报;remote_close 或会话闲置回收时服务端也会强制解除。Windows 用 BlockInput(),只在调用进程具备管理员权限(或 UIAccess)时为真,普通权限的客户端会静默失败且不上报结果;Android 用无障碍全屏透明 overlay 吃掉触摸,服务端注入的手势在飞行期间临时放行(等价于 Windows 在 ProcessCommand 前后 BlockInput(false) 的包裹),不声明相应能力位的老 APK 返回 -32005。两个限制:1) 成功只代表命令已送达,不保证真的锁住了——不要凭它断言对端已被锁;2) 若屏幕子连接因目标机断网被拆,服务端就再没有下发通道(Windows 只能等客户端进程退出,Android 客户端会在子连接断开时主动撤掉 overlay)。Linux/macOS 不支持,返回 -32005。",
"gate": "remote_control",
"write": true,
"platforms": [
"win",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"block": {
"description": "true=锁定对端键鼠,false=解除。必填(没有默认值,避免误锁)",
"type": "boolean"
},
"id": {
"description": "主机 id,取 list_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_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": "read_file",
"description": "按字节读取指定在线主机上的一个文本文件(分页 + 编码识别 + 整文件 SHA-256),只支持单个普通文件。path 为远程绝对路径:Windows 用 D:\\cfg\\app.ini 这类盘符路径,Linux/macOS 用 /etc/app.conf 这类 POSIX 路径。offset 支持负数(-200 = 最后 200 行,看日志尾部);limit 为最多返回的行数(默认 2000);encoding=auto 时按 BOM → UTF-8 合法性 → GBK 回退识别,也可显式传 utf-8 / gbk / latin1;max_bytes 限制本次返回的文本字节数(默认 262144=256KB,超出按 truncated=true 截断)。目录、或大于 2MB 的文件返回 -32602(请改用 download_file)。返回 size/encoding/eol/lines_total/offset/lines_returned/truncated/text/sha256(sha256 是整个文件,不是本次片段)。读配置文件/日志时用它,不要用 exec_command 的 type/Get-Content(GBK 会乱码、行尾会被归一化);看被管业务程序的日志尾部用 offset=-N(如 offset=-200,N 为行数)。",
"gate": "file_transfer",
"platforms": [
"win",
"lnx",
"mac"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"encoding": {
"description": "auto(默认,按 BOM → UTF-8 合法性 → GBK 回退)/ utf-8 / gbk / gb18030 / latin1",
"type": "string"
},
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"limit": {
"description": "最多返回的行数(1..200000,默认 2000)",
"type": "integer"
},
"max_bytes": {
"description": "本次返回文本的字节上限(1024..2097152,默认 262144=256KB),超出按 truncated=true 截断",
"type": "integer"
},
"offset": {
"description": "起始行(0 基)。负数表示从末尾倒数:-200 = 最后 200 行;默认 0",
"type": "integer"
},
"path": {
"description": "远程文件的绝对路径。Windows 用 D:\\cfg\\app.ini 这类盘符路径;Linux/macOS 用 /etc/app.conf 这类 POSIX 路径。必须是单个普通文件(目录或大于 2MB 的文件返回 -32602)",
"type": "string"
}
},
"required": [
"id",
"path"
],
"type": "object"
},
"outputSchema": {
"properties": {
"encoding": {
"description": "实际使用的编码:utf-8 / utf-16le / utf-16be / gbk / gb18030 / latin1",
"type": "string"
},
"eol": {
"description": "行尾风格:crlf / lf / cr / mixed / none",
"type": "string"
},
"lines_returned": {
"description": "本次返回的行数",
"type": "integer"
},
"lines_total": {
"description": "文件总行数(末尾换行不计空行)",
"type": "integer"
},
"offset": {
"description": "本次实际起始行(负数已换算成绝对行号)",
"type": "integer"
},
"path": {
"description": "远程路径(原样回传)",
"type": "string"
},
"sha256": {
"description": "整个文件的 SHA-256(不是本次片段),可与 download_file 的结果比对",
"type": "string"
},
"size": {
"description": "文件总字节数",
"type": "integer"
},
"text": {
"description": "文件内容(UTF-8,行以 \\n 分隔,已去掉 BOM)",
"type": "string"
},
"truncated": {
"description": "true=还有内容没返回(超出 limit / max_bytes),可调整 offset 继续读",
"type": "boolean"
}
},
"required": [
"path",
"size",
"encoding",
"eol",
"lines_total",
"offset",
"lines_returned",
"truncated",
"text",
"sha256"
],
"type": "object"
}
},
{
"name": "http_probe",
"description": "在指定在线 Windows 或 Linux 主机上请求一个 HTTP/HTTPS 地址,返回结构化结果(状态码、响应头、响应体、耗时),用于探测主机上或同网段的业务接口健康。url 必须是 http:// 或 https:// + IP 字面量(或 localhost)+ 可选 :端口 + 路径;只允许私网/回环地址(127.0.0.0/8、::1、10/8、172.16/12、192.168/16)与 localhost,域名和公网地址一律拒绝(域名要通过被管主机解析才有意义,服务端解析自己的 DNS 是错的)。默认 GET;method 支持 GET/POST/PUT/DELETE/HEAD/PATCH/OPTIONS;headers 为名→值的字符串对象;body 为请求体(≤2048 字节,按 UTF-8 发送)。不跟随重定向(3xx 原样返回,Location 在 headers 里);https 校验证书,自签名证书会失败。响应体最多返回 max_bytes(默认与上限均为 64KB),超出置 truncated=true;响应体是合法 UTF-8 时放在 body,否则 body 为空并给出 body_base64。实现上复用终端通道(需 McpTerminal=1、McpReadonly=0):会复用该主机已有的持久终端会话;没有则内部打开一个、用完即关(超时仍在跑时保留,便于轮询)。该主机上已有命令在跑或输出未取完时返回 -32003。",
"gate": "terminal",
"write": true,
"platforms": [
"win",
"lnx"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"body": {
"description": "请求体(可选,≤2048 字节),按 UTF-8 发送;POST/PUT/PATCH 时常用",
"type": "string"
},
"headers": {
"additionalProperties": {
"type": "string"
},
"description": "请求头(对象,名→值都是字符串),如 {\"Authorization\":\"Bearer x\"};序列化后上限 512 字节,不接受 Content-Length;Windows 上少数受限头(如 Connection、Expect、Range)会被系统拒收,Accept/User-Agent/Referer 已单独支持",
"type": "object"
},
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"max_bytes": {
"description": "响应体最多返回的字节数(默认 65536,范围 1-65536),超出置 truncated=true",
"type": "integer"
},
"method": {
"description": "HTTP 方法,默认 GET",
"enum": [
"GET",
"POST",
"PUT",
"DELETE",
"HEAD",
"PATCH",
"OPTIONS"
],
"type": "string"
},
"timeout_ms": {
"description": "请求超时毫秒数(默认 10000,范围 1000-60000);工具等待 = 该值 + 20 秒(含 shell 启动)",
"type": "integer"
},
"url": {
"description": "要请求的地址:http:// 或 https:// + IP 字面量(或 localhost)+ 可选 :端口 + 路径,如 http://127.0.0.1:8003/health",
"type": "string"
}
},
"required": [
"id",
"url"
],
"type": "object"
},
"outputSchema": {
"properties": {
"body": {
"description": "响应体(响应体是合法 UTF-8 时才填;否则为空,看 body_base64)",
"type": "string"
},
"body_base64": {
"description": "响应体的 base64(仅 body_encoding=base64 时提供,非 UTF-8 的二进制响应)",
"type": "string"
},
"body_bytes": {
"description": "本次返回的响应体字节数(被截断时即 max_bytes 内实际读到的)",
"type": "integer"
},
"body_encoding": {
"description": "body 的编码:utf-8 或 base64",
"type": "string"
},
"elapsed_ms": {
"description": "请求耗时毫秒(Windows 在 PowerShell 内计时;Linux 为服务端整轮计时)",
"type": "integer"
},
"headers": {
"description": "响应头(名→值;同名多值用逗号拼接)",
"type": "object"
},
"ok": {
"description": "true = 2xx/3xx;3xx 未跟随重定向",
"type": "boolean"
},
"status": {
"description": "HTTP 状态码",
"type": "integer"
},
"truncated": {
"description": "true = 响应体超过 max_bytes,只返回了前缀",
"type": "boolean"
},
"url": {
"description": "回显请求的 url",
"type": "string"
}
},
"required": [
"status",
"ok",
"headers",
"body",
"body_encoding",
"body_bytes",
"truncated",
"elapsed_ms",
"url"
],
"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_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_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_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": "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_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": "uninstall_host",
"description": "卸载指定在线主机上的被控程序(不可撤销)。报文是单字节 TOKEN_UNINSTALL,与主控在线列表右键「卸载主机」完全一样:Windows 客户端会退出并延时删除自身;Android 客户端会先回 BYE,再拉起系统的卸载确认框(Android 不允许静默卸载,必须有人在设备上点「确定」;没人确认就不会真的删除,Android 客户端却已按卸载退出连接,需要人工重开 App)。Linux/macOS 客户端没有该分支,返回 -32005。没有回执:ok/sent 只代表命令已送达;要确认主机确实消失就传 wait=true,工具会等它从在线列表下线。卸载后主机不会自动回来。",
"gate": "manage",
"write": true,
"platforms": [
"win",
"apk"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"wait": {
"description": "true 时等主机从在线列表消失再返回(默认 false,发完即走)。卸载后主机不会回线。",
"type": "boolean"
},
"wait_ms": {
"description": "wait=true 时的最长等待(毫秒,默认 30000)",
"maximum": 600000,
"minimum": 1000,
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
},
"outputSchema": {
"properties": {
"elapsed_ms": {
"description": "本次等待实际耗时(毫秒;wait=false 时为 0)",
"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_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_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_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_inspect",
"description": "一次取回在线 Windows 主机的多类主机管理信息(原 10 个 host_list_* 工具合并)。aspects 必填、可多选:processes(进程:PID/架构/窗口标题/路径/优先级/线程数/用户/工作集与文件大小)| windows(当前可见顶层窗口;只含可见窗口,单次最多 96 条,超出时 truncated=true 且列表不完整,不能据此断定某窗口不存在;hwnd 可交给 host_control_window / operate_window)| network(网络连接,进程视角、含 UDP;与 list_network_connections 的「连接管理」数据源不同)| software(已安装软件,来自注册表 Uninstall 项;不提供卸载)| browser_history(IE 浏览历史,隐私数据)| favorites(IE 收藏夹,隐私数据)| win32_services(Win32 服务;服务名可用于 host_control_service)| driver_services(驱动服务;字段同 win32_services)| scheduled_tasks(计划任务;任务名 + folder 可用于 host_control_task)| hosts_file(按行返回并自动识别 UTF-8/GBK)。注意:win32_services / driver_services 要求客户端以管理员权限运行——非提权客户端拿不到 SCM 句柄后直接不回应,调用会在约 12 秒后超时(同等场景 list_services 会明确报 access denied)。过滤参数按 aspect 生效、其余忽略(见各参数说明),在服务端完成且先于分页:total 为命中数、totalAll 为该项全部条目数。单个 aspect 时顶层就是该项的列表结果(与合并前的旧工具一致);多个 aspect 时汇总在 results.<aspect>,某个 aspect 失败只记入 errors.<aspect>、不影响其它 aspect,全部失败才 isError=true。每多选一个 aspect 就多一次子连接,耗时线性增长,不需要的不要选。只读。",
"gate": "machine",
"platforms": [
"win"
],
"impl": "mfc",
"inputSchema": {
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ids"
]
}
],
"properties": {
"arch": {
"description": "按架构过滤:processes",
"enum": [
"x86",
"x64"
],
"type": "string"
},
"aspects": {
"description": "要取的方面(必填、可多选、自动去重):processes=进程,windows=可见顶层窗口,network=网络连接(进程视角),software=已安装软件,browser_history=IE 浏览历史,favorites=IE 收藏夹,win32_services=Win32 服务,driver_services=驱动服务,scheduled_tasks=计划任务,hosts_file=hosts 文件",
"items": {
"enum": [
"processes",
"windows",
"network",
"software",
"browser_history",
"favorites",
"win32_services",
"driver_services",
"scheduled_tasks",
"hosts_file"
],
"type": "string"
},
"minItems": 1,
"type": "array"
},
"folder": {
"description": "按任务文件夹子串过滤(如 \\Microsoft):scheduled_tasks",
"type": "string"
},
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"ids": {
"description": "批量查询:一次传多台主机 id(最多 50 个),结果按台汇总在 results 里。与 id 二选一,仅只读工具支持;limit/offset 对每台主机各自生效。",
"items": {
"type": "string"
},
"type": "array"
},
"include_content": {
"description": "是否返回按行切分的内容,默认 true:hosts_file",
"type": "boolean"
},
"limit": {
"description": "本次最多返回条数,默认 100,上限 1000",
"type": "integer"
},
"local_port": {
"description": "按本地端口精确过滤:network",
"type": "integer"
},
"max_bytes": {
"description": "最多返回的原始字节数,默认 262144,上限 1048576:hosts_file",
"type": "integer"
},
"name": {
"description": "按名称子串过滤:processes(映像名)/ software(软件名)/ win32_services|driver_services(服务名或显示名)/ scheduled_tasks(任务名)",
"type": "string"
},
"offset": {
"description": "分页起点,默认 0",
"type": "integer"
},
"pid": {
"description": "按 PID 过滤:processes / windows(所属进程)/ network",
"type": "integer"
},
"process": {
"description": "按进程名子串过滤:network",
"type": "string"
},
"protocol": {
"description": "按协议过滤:network",
"enum": [
"tcp",
"udp",
"all"
],
"type": "string"
},
"publisher": {
"description": "按发布者子串过滤:software",
"type": "string"
},
"remote_port": {
"description": "按远端端口精确过滤:network",
"type": "integer"
},
"start_type": {
"description": "按启动类型子串过滤(如 Auto):win32_services / driver_services",
"type": "string"
},
"state": {
"description": "按状态子串过滤(如 ESTABLISHED):network",
"type": "string"
},
"status": {
"description": "按状态子串过滤(如 Running / Ready):win32_services / driver_services / scheduled_tasks",
"type": "string"
},
"title": {
"description": "按标题子串过滤:windows(窗口标题)/ browser_history(网页标题)",
"type": "string"
},
"url": {
"description": "按 URL 子串过滤:browser_history / favorites",
"type": "string"
}
},
"required": [
"aspects"
],
"type": "object"
},
"outputSchema": {
"anyOf": [
{
"additionalProperties": true,
"properties": {
"errors": {
"additionalProperties": {
"properties": {
"code": {
"description": "JSON-RPC 错误码,如 -32001 超时、-32005 平台不支持",
"type": "integer"
},
"message": {
"description": "错误说明",
"type": "string"
}
},
"type": "object"
},
"description": "只有失败的 aspect 才会出现;不影响其它 aspect 的结果",
"type": "object"
},
"results": {
"description": "按 aspect 名索引;每个值的形状与单 aspect 调用的顶层一致",
"properties": {
"browser_history": {
"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"
},
"driver_services": {
"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"
},
"favorites": {
"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"
},
"hosts_file": {
"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"
},
"network": {
"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"
},
"processes": {
"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"
},
"scheduled_tasks": {
"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"
},
"software": {
"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"
},
"win32_services": {
"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"
},
"windows": {
"properties": {
"hasMore": {
"type": "boolean"
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"total": {
"description": "过滤后的条目数",
"type": "integer"
},
"totalAll": {
"description": "未过滤的条目总数",
"type": "integer"
},
"truncated": {
"description": "为 true 时表示客户端的可见窗口多于单次返回上限(96 条),列表不完整",
"type": "boolean"
},
"windows": {
"items": {
"properties": {
"bottom": {
"description": "窗口矩形下边界(屏幕坐标,不含边界);height = bottom - top",
"type": "integer"
},
"canSee": {
"description": "客户端是否可抓取该窗口画面",
"type": "boolean"
},
"height": {
"type": "integer"
},
"hwnd": {
"description": "窗口句柄(十进制;也可用作 host_control_window / operate_window 的 hwnd)",
"type": "integer"
},
"isForeground": {
"description": "是否为当前前台窗口(全表最多一个 true)",
"type": "boolean"
},
"left": {
"description": "窗口矩形左边界(屏幕坐标,可能为负,多显示器时常见)",
"type": "integer"
},
"maximized": {
"description": "是否最大化",
"type": "boolean"
},
"minimized": {
"description": "是否最小化",
"type": "boolean"
},
"pid": {
"type": "integer"
},
"right": {
"description": "窗口矩形右边界(屏幕坐标,不含边界);width = right - left",
"type": "integer"
},
"title": {
"type": "string"
},
"top": {
"description": "窗口矩形上边界(屏幕坐标)",
"type": "integer"
},
"visible": {
"description": "是否可见;当前列表只含可见窗口,故恒为 true",
"type": "boolean"
},
"width": {
"type": "integer"
},
"zOrder": {
"description": "z 序,0 = 最顶层;数值越小越靠前",
"type": "integer"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"windows"
],
"type": "object"
}
},
"type": "object"
}
},
"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_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(最小化)/activate(激活到前台)/close(关闭)/show(显示)。hwnd 取 host_inspect 的 windows 项或 list_windows 返回的 hwnd。restore 等五个动作走主机管理链路,动作后重新枚举可见窗口复核:hide 后 hwnd 应消失,其余动作后仍应存在;activate 会额外复核 GetForegroundWindow,目标未成为前台则 ok=false、reason=not_foreground,且需要新客户端(窗口信息能力),旧客户端返回 -32005,可退回 restore。close/show 没有主机管理实现,转由主连接版 operate_window 处理(因此动作后不复核,ok 只表示已下发;McpManage=0 时返回 -32006)——它们只在 McpMachine=0 时才以 operate_window 之名出现在 tools/list。dry_run=true 只核实 hwnd 并返回窗口信息,不下发动作。",
"gate": "machine",
"write": true,
"platforms": [
"win"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"action": {
"description": "restore/hide/maximize/minimize/activate,以及 close/show(转主连接实现,需 McpManage=1)",
"enum": [
"restore",
"hide",
"maximize",
"minimize",
"activate",
"close",
"show"
],
"type": "string"
},
"dry_run": {
"description": "true 时只校验 hwnd 仍在可见窗口列表里并返回该窗口,不下发操作,默认 false",
"type": "boolean"
},
"hwnd": {
"description": "窗口句柄,取 host_inspect(aspects=[\"windows\"])或 list_windows 的 hwnd;整数或 0x 前缀字符串",
"type": [
"integer",
"string"
]
},
"id": {
"description": "主机 id,取 list_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/set_auto/set_manual。start 等五个动作走主机管理链路:客户端对每次控制都会自动回一份刷新后的服务列表,工具据此复核状态并如实返回 ok;stop 与 restart 归入危险操作,需要同时开启 McpMachineDangerous;restart 先 stop 再 start。set_auto/set_manual 没有主机管理实现,转由主连接版 control_service 处理(ok 只表示已下发、需另查状态;McpManage=0 时返回 -32006)——它们只在 McpMachine=0 时才以 control_service 之名出现在 tools/list。不提供删除服务。dry_run=true 只核实服务并返回当前状态,不下发命令(是否已是目标状态由你按 state 判断);set_auto/set_manual 不支持 dry_run(返回 -32602)。",
"gate": "machine",
"write": true,
"platforms": [
"win"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"action": {
"description": "start/stop/pause/continue/restart,以及 set_auto/set_manual(转主连接实现,需 McpManage=1)",
"enum": [
"start",
"stop",
"pause",
"continue",
"restart",
"set_auto",
"set_manual"
],
"type": "string"
},
"dry_run": {
"description": "true 时只校验服务存在并返回当前状态,不下发控制命令,默认 false",
"type": "boolean"
},
"id": {
"description": "主机 id,取 list_hosts 返回的 id 字段",
"type": "string"
},
"name": {
"description": "服务名(ServiceName,不是显示名),取 host_inspect 的 win32_services / driver_services 项的 name;与 service_name 二选一",
"type": "string"
},
"service_name": {
"description": "name 的旧参数名别名(与 name 等价,二选一)",
"type": "string"
}
},
"required": [
"id",
"action"
],
"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_hosts 返回的 id 字段",
"type": "string"
},
"name": {
"description": "任务名,取 host_inspect 的 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 / Android 主机上弹出「远程交谈」窗口,建立一次多轮文字对话。返回 session_id,后续 chat_send / chat_wait / chat_close 都要带上。客户端使用者会直接看到聊天窗口(无确认框;Android 上是应用内聊天界面,无障碍服务可用时会自动拉到前台,否则发一条可点开的通知)。同一主机同一时刻只允许一个会话;会话在客户端断开或空闲 10 分钟后自动失效。会话建立后应先用 chat_send 发送问候,再用 chat_wait 等待对方回复。",
"gate": "chat",
"platforms": [
"win",
"apk"
],
"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)显示(Windows 客户端按 UTF-16 渲染,Android 客户端按 GBK 解码);客户端不保证非中文系统能正确显示。发送成功只代表已写入子连接,不代表对方已读。请勿在同一条消息里塞入多段对话;需要等待回复时调用 chat_wait。",
"gate": "chat",
"platforms": [
"win",
"apk"
],
"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",
"apk"
],
"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",
"apk"
],
"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"
}
},
{
"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"
}
},
{
"name": "operate_window",
"description": "对指定在线 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)。仅在 McpMachine=0(主机管理工具关闭)时出现在 tools/list;开启后请用 host_control_window,它也接受 close/show。dry_run=true 只校验 hwnd 是否还在可见窗口列表里并返回该窗口信息,不发送任何命令。",
"gate": "!machine",
"write": true,
"manage": true,
"platforms": [
"win"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"action": {
"description": "操作:close(关闭) | show(显示) | hide(隐藏) | minimize(最小化) | maximize(最大化) | restore(还原) | activate(激活到前台,需新客户端)",
"type": "string"
},
"dry_run": {
"description": "true 时只校验窗口是否还存在并返回将被影响的对象,不发送任何窗口命令(默认 false)",
"type": "boolean"
},
"hwnd": {
"description": "窗口句柄,取 list_windows 返回的 hwnd 字段",
"type": "integer"
},
"id": {
"description": "主机 id,取 list_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": "命令已下发(不代表窗口已按预期变化);action=activate 时为前台复核结果",
"type": "boolean"
},
"state": {
"description": "action=activate 时的复核状态:foreground / background / missing / unknown",
"type": "string"
},
"truncated": {
"description": "为 true 时表示复核用的可见窗口列表被 96 条单次上限截断,未找到目标不代表窗口不存在(此时 state=unknown)",
"type": "boolean"
},
"verifyError": {
"description": "action=activate 且前台复核请求失败时的错误说明",
"type": "string"
},
"window": {
"description": "dry_run 时的目标窗口;action=activate 时为复核到的窗口快照(hwnd/title/pid/rect/flags 等),复核未找到为 null",
"type": [
"object",
"null"
]
}
},
"type": "object"
}
},
{
"name": "control_service",
"description": "控制指定在线 Windows 主机的服务:start(启动)/stop(停止)/set_auto(设为自动)/set_manual(设为手动)。service_name 取 list_services 返回的 service_name。ok 仅表示已下发(成功与否需再查 list_services 核对状态)。仅在 McpMachine=0(主机管理工具关闭)时出现在 tools/list;开启后请用 host_control_service,它也接受 set_auto/set_manual。",
"gate": "!machine",
"write": true,
"manage": true,
"platforms": [
"win"
],
"impl": "mfc",
"inputSchema": {
"properties": {
"action": {
"description": "操作:start(启动) | stop(停止) | set_auto(设为自动) | set_manual(设为手动)",
"type": "string"
},
"id": {
"description": "主机 id,取 list_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"
}
}
]
}