diff --git a/docs/Mcp_Design.md b/docs/Mcp_Design.md index 580155e..c4a618b 100644 --- a/docs/Mcp_Design.md +++ b/docs/Mcp_Design.md @@ -597,7 +597,7 @@ token 只从 `-Token` / env 读取,不落仓库、不打印;无在线主机 ### 10.8 D 批:拒绝也入审计 -动机:所有策略拒绝(只读模式、`Mcp*` 开关关闭、主机不支持某能力)都返回 `-32006`,而审计里只有 `CALL_FAIL`——和「参数错」「主机离线」「超时」混在一起,事后分不清「没人调过」和「被策略拦下」。 +动机:策略拒绝(只读模式、`Mcp*` 开关关闭,以及老客户端 V2 这类能力缺失)返回 `-32006`;平台/能力位不匹配的多数返回 `-32005`。此前审计里只有 `CALL_FAIL`——和「参数错」「主机离线」「超时」混在一起,事后分不清「没人调过」和「被策略拦下」。 - 实现放在 `tools/call` 的统一出口(`CMcpServer` 的 HTTP 处理器),不在 24 个 `-32006` 分支里逐个埋点:成功解析响应体后多取 `error.code` / `error.message`,`code == -32006` 就追加一条 ``` @@ -678,12 +678,12 @@ token 只从 `-Token` / env 读取,不落仓库、不打印;无在线主机 | `-32600` | Invalid Request | 缺 `jsonrpc` / `method` / 非法 `tools/call` 结构 | 修正请求 | | `-32601` | Method not found | `method` 不是 `initialize` / `tools/list` / `tools/call` 等 | 修正请求 | | `-32602` | Invalid params | 未知工具名、缺必填参数、参数类型/取值非法、批量 `ids` 超过 50 个、`search_file` 过滤参数非法、文本无法转 GBK | 改参数重试,重试同样的请求不会成功 | -| `-32001` | Timeout | 等客户端就绪/等子连接/等搜索结果超时(`timeout_ms` 内没等到) | 可加大 `timeout_ms` 重试;持续出现看主机是否卡住 | +| `-32001` | Timeout / execution failure | 多为等客户端就绪/等子连接/等搜索结果超时(`timeout_ms` 内没等到);也用于工具自身失败(`http_probe` 解析失败、目标端未确认写入)与已取消(`Request cancelled`) | 先看 `message`:超时且工具支持 `timeout_ms` 可加大重试;子连接没建立/反复超时通常重试无效;`Request cancelled` 可直接重试;其余按 `message` 处理 | | `-32002` | Host offline / not found | 主机 id 不存在、主连接已断、会话 id 不存在或已关闭 | 先 `list_online_hosts` 刷新再选主机 | | `-32003` | Busy | 该主机已有同类请求在飞(终端/截屏/文件/聊天会话),或同设备重复 `chat_open`。`message` 末尾带 `(tool=..., elapsed=Ns)` 点名占用者 | 用 `mcp_list_sessions` 看全部会话;等前一个结束、先 `*_close`,或 `mcp_cancel_session` 释放 | | `-32004` | Send failed | 命令写入主连接失败(连接刚断) | 重试一次;仍失败按 `-32002` 处理 | | `-32005` | Not supported on this host | 能力限制,改参数也修不好:需要 Windows 的工具用在 LNX/MAC/APK 主机上;`remote_open` 遇到多显示器(阶段一);主机无屏幕预览/控制能力位 | 换主机或换工具;不要改参数重试 | -| `-32006` | Policy refused | 只读模式 / 对应 `Mcp*` 开关关闭 / 主机不支持该能力(如 V2 文件传输) | **不要重试**:这是配置决定,需管理员改服务端配置 | +| `-32006` | Policy refused | 只读模式 / 对应 `Mcp*` 开关关闭;MFC 端还包括老客户端不支持 V2 文件传输(`download_file` / `upload_file` / `read_file` / `copy_files_c2c`;Go 端这种情况返回 `-32005`) | **不要重试**:开关/只读需管理员改服务端配置,老客户端需升级 | | `-32007` | Not in command whitelist | `exec_command` 的命令不在 `McpCmdWhitelist` 里,或词边界不匹配(`dir` 过、`dirx` 拒) | **不要重试**:换成白名单内的命令,或请管理员加白名单项 | | `-32012` | Rejected by validation | 只覆盖「参数被校验拒绝、改参数可修」:`exec_command` 含 shell 元字符(Windows `&\|<>^`;Linux `&\|<>;` 与反引号、`$(` `${` `!`)或控制字符(含 `\r\n`);`terminal_exec` 含控制字符(含换行),或**老非 PTY 会话**里含 `&`/`\|`,或 POSIX 会话里含裸后台 `&`;路径/参数含非法字符。**`-32008` 是同一语义的历史别名**(早期实现用它,已发布的客户端/文档可能仍在匹配),新代码一律用 `-32012` | 按 `message` 修正参数后重试 | | `-32009` | Target not found | 远端路径/注册表键不存在(win32 `2`/`3`,由新客户端主动回报);`kill_network_connection` 的四元组在当前连接表里查不到(`dry_run` 传假四元组最常见) | 先用 `list_files`/`list_registry`(或 `host_list_network_state`)确认目标存在 | diff --git a/server/2015Remote/McpServer.cpp b/server/2015Remote/McpServer.cpp index 7d470cf..726eb0a 100644 --- a/server/2015Remote/McpServer.cpp +++ b/server/2015Remote/McpServer.cpp @@ -283,16 +283,21 @@ const char* kServerInstructions = u8"2) 工具的可见性与开关\n" u8"tools/list 只返回当前服务端开关允许的工具:终端(terminal)、远程控制(remote_control)、" u8"文件传输(file_transfer)、文件写入(file_write)、管理动作(manage)、主机管理(machine)、键盘记录(keylog)、" - u8"远程交谈(chat)各有独立开关。工具不在列表里就是不可用,直接调用返回 -32006;" + u8"远程交谈(chat)各有独立开关。工具不在列表里通常就不可用,直接调用会被拒(-32006 或 -32005);" + u8"例外是下文提到的降级别名(list_processes / list_windows / list_services、operate_window / " + u8"control_service,以及 list_online_hosts / search_hosts / list_all_hosts 等旧名)——" + u8"它们不在列表里但仍可调用。" u8"当前开关状态可查 get_server_status 的 switches。只读模式(readonly=true)会挡掉大部分写工具," u8"但只改服务端本地数据的 host_set_remark / host_set_watch_level 仍会列出,调用时才被拒;" - u8"get_keylog 也始终可见,只读模式下只是它的 clear / set_offline 参数被拒,读取不受影响。\n" + u8"get_keylog 只受 McpKeylog 开关控制(与只读模式无关):开关关闭时它不在列表里;只读模式下" + u8"只是它的 clear / set_offline 参数被拒,读取不受影响。\n" u8"同一能力存在两套工具时优先用主机管理族:host_inspect(aspects 选 processes / windows / " u8"win32_services 等,支持 pid/title/status 等服务端过滤,字段更全),list_processes / " u8"list_windows / list_services 是它在 McpMachine=0 时的降级路径。窗口与服务控制同样只有一套" u8"名字(需 McpManage=1):McpMachine=0 时是 operate_window / control_service,开启后是 " u8"host_control_window / host_control_service;后者也接受 close/show 与 set_auto/set_manual" - u8"(转给前一套实现)。\n" + u8"(转给前一套实现)。危险的主机管理动作目前只有两类——冻结/恢复进程、stop/restart 服务——" + u8"另需 McpMachineDangerous=1:工具照常列出,调用时返回 -32006。\n" u8"\n" u8"3) 错误码与动作\n" u8"-32002 主机离线或不存在:先刷新主机列表再选,不要拿旧快照反复重试。\n" @@ -303,12 +308,18 @@ const char* kServerInstructions = u8"chat → chat_close。pending / file_transfer 是某次在飞调用的等待态,取消那次调用就一并释放。\n" u8"-32004 命令未能送达主机:多半是链路瞬断,可重试一次。\n" u8"-32005 该主机不支持这项能力:换主机或换工具,改参数没有用。\n" - u8"-32006 策略拒绝:开关未开或只读模式,重试无效,需要管理员改服务端配置。\n" + u8"-32006 策略拒绝:开关未开、只读模式,或目标端能力不足(老客户端不声明 CLIENT_CAP_V2 时," + u8"download_file / upload_file / read_file / copy_files_c2c 会返回 -32006),重试无效:" + u8"前者需管理员改服务端配置,后者需升级客户端。\n" u8"-32007 不在命令白名单:换成白名单内的命令,重试无效。\n" u8"-32012 参数被校验拒绝(命令里的 shell 元字符、控制字符等):按 message 修正参数后重试。" u8"历史版本用 -32008 表示同一语义,遇到时按同样方式处理。\n" u8"-32009 目标不存在(文件/目录等):先列一次确认目标,再重试。\n" - u8"-32001 超时:可加大 timeout_ms 重试一次;持续超时说明主机卡住。\n" + u8"-32001 多为超时,也可能是工具自身失败或已被取消:先看 message。是超时时,工具支持 timeout_ms " + u8"就先加大重试一次,不支持就缩小范围(分页、限定目录/单台)再试;子连接/会话没建立、同一主机" + u8"反复超时通常重试无效(主机卡住、链路断、老客户端不认命令),先用 mcp_list_sessions 观察;" + u8"message 写 Request cancelled 的表示客户端已中止,可直接重试;http_probe 解析失败、" + u8"目标端未确认写入等其他 -32001 按 message 处理,加大 timeout_ms 没用。\n" u8"-32800 请求被取消:这是客户端自己取消(notifications/cancelled / mcp_cancel_session / 连接断开)" u8"导致的中止,不是主机故障;主机占用已释放,可以直接重试。\n" u8"-32602 参数错误:按 message 修正后重试。\n" @@ -319,6 +330,7 @@ const char* kServerInstructions = u8"文件:list_files 列盘(省略 path)或列目录 → search_file 按名字查找(递归深度 32、最多 1 万条," u8"从盘符根扫描很慢且易截断,尽量指定具体目录)→ 看文本内容用 read_file(按字节解码,自动识别 UTF-8/GBK," u8"offset=-N 看尾部,不要用 type/Get-Content 读配置和日志)→ download_file 取回、upload_file 送到目标。" + u8"注意 local_dir / local_path 指 MCP 服务端(主控)所在机器的本地路径,不是模型或用户所在机器的路径。" u8"整理目标机上的东西用 delete_path / move_path / create_folder(需 McpFileWrite 开关)," u8"它们的 ok 同样只代表客户端回了完成包,真实结果看 verified(true=复核确认生效、" u8"false=复核确认未生效、null=复核没做成);删除不可恢复,recursive 必须显式传 true。" @@ -348,7 +360,8 @@ const char* kServerInstructions = u8"lnx(LNX):不支持服务、注册表、键日志、文件搜索/删除/移动/建目录、" u8"窗口列表(list_windows)与窗口信息(get_foreground_window)、网络连接列表与断开" u8"(list_network_connections / kill_network_connection)、" - u8"块输入、host_* 全族、chat_* 全族、operate_window、power_action、uninstall_host。远程控制与截屏要求目标机" + u8"块输入、host_* 全族(host_set_remark / host_set_watch_level 除外,它们只改服务端本地数据," + u8"任何平台都可用)、chat_* 全族、operate_window、power_action、uninstall_host。远程控制与截屏要求目标机" u8"有 X11/Xorg(或 XWayland)桌面,纯 Wayland 或无桌面的服务器不行。\n" u8"mac(MAC):在 lnx 的基础上,还不支持远程控制全族(remote_open / remote_close / " u8"remote_mouse / remote_keyboard / remote_clipboard)、get_screenshot、" @@ -373,7 +386,9 @@ const char* kServerInstructions = u8"(客户端未实现 SYSTEM 等命令)。\n" u8"copy_files_c2c 是唯一有方向性的工具:源端 src_id 必须是 win,目标端 dst_id 可以是 " u8"win / lnx / mac。Linux 和 macOS 只能当接收方,不能当发送方(反向不支持)。\n" - u8"这些不支持的组合会立刻返回 -32005,不会白等超时;反之,遇到超时不要当成平台不支持。\n" + u8"这些不支持的组合多数会立刻返回 -32005;少数要等子连接才暴露的(老客户端不认命令等)" + u8"可能表现为 -32001 超时,平台门禁 McpPlatformGuard=0 关闭时也会这样。反之,遇到超时" + u8"也别直接当成平台不支持,先按上面的矩阵确认平台。\n" u8"\n" u8"6) 安全约定\n" u8"写操作前先读一次现状,动作后再用读工具复核;删改类工具的 ok 只表示命令已送达客户端,不代表成功。" diff --git a/server/go/mcp/server.go b/server/go/mcp/server.go index b8079c6..684d594 100644 --- a/server/go/mcp/server.go +++ b/server/go/mcp/server.go @@ -408,7 +408,7 @@ const serverInstructions = `这是 YAMA 服务端的 MCP 端点(Go 实现) 1) 主机 id 是 64 位无符号十进制字符串,由服务端分配,无法从 IP 或计算机名推算。需要 id 时先用 list_hosts 取得,拿不到就向用户确认,不要猜。 2) tools/list 只返回当前模式允许的工具;只读模式隐藏 terminal_exec / terminal_close,直接调用被隐藏的工具返回 -32006。 -3) 错误码与动作:-32002 主机离线或不存在(先刷新列表);-32003 主机忙(同一台主机同一时刻只允许一个操作,重试无效,等前一个结束);-32004 命令未送达(多为链路瞬断,可重试一次);-32005 主机不支持该能力(换主机或换工具,改参数无用);-32006 策略拒绝(重试无效,需管理员改服务端配置);-32001 超时(可加大 timeout_ms 重试一次);-32602 参数错误(按 message 修正)。 +3) 错误码与动作:-32002 主机离线或不存在(先刷新列表);-32003 主机忙(同一台主机同一时刻只允许一个操作,重试无效,等前一个结束);-32004 命令未送达(多为链路瞬断,可重试一次);-32005 主机不支持该能力(换主机或换工具,改参数无用;老客户端不声明 CLIENT_CAP_V2 时 read_file 也返回 -32005,需升级客户端);-32006 只读模式拒绝(terminal_exec / terminal_close;重试无效,需管理员关掉只读);-32001 多为超时,也可能是工具自身失败或已被取消:工具支持 timeout_ms 时先加大重试一次;子连接/会话没建立或同一主机反复超时通常重试无效(主机卡住、链路断或老客户端不认命令);message 写 Request cancelled 的表示客户端已中止,可直接重试;-32602 参数错误(按 message 修正)。 4) get_screenshot 的 screen 模式按链路状况自适应缩放,max_width 省略时最大 1024;region/window/monitor 模式需要声明 CLIENT_CAP_SCREEN_REGION 的较新 Windows 客户端,否则返回 -32005。 5) list_files / read_file 走文件传输通道;read_file 只接受单个普通文件且不超过 2 MiB,目录用 list_files,大文件分段读取。 6) terminal_exec 需要客户端支持终端(CLIENT_CAP_TERMINAL),会在目标主机上创建持久会话;用完调用 terminal_close 释放,闲置会话由服务端回收。 diff --git a/tools/mcp_tools/README.md b/tools/mcp_tools/README.md index 9bed78d..e0623cd 100644 --- a/tools/mcp_tools/README.md +++ b/tools/mcp_tools/README.md @@ -88,14 +88,17 @@ python tools/mcp_tools/verify_tools.py --live mcp/tools.json | 命令分支 | `client/`、`linux/main.cpp`、`macos/main.mm`、`android/app/src/main/cpp/main.cpp` | | 能力位 | `common/commands.h` 的 `LOGIN_INFOR::DefaultCaps()`;Linux 另在 `linux/main.cpp:RefreshLoginCaps` 追加 `SCREEN_PREVIEW` | -当前分布(61 个工具): +当前分布(54 个工具): | platforms | 数量 | 典型工具 | |---|---|---| -| `win+lnx+mac+apk` | 10 | 只读写服务端本地数据:`list_online_hosts` / `get_audit_log` / `mcp_*` | -| `win+lnx+mac` | 6 | 进程列表、文件列取、日志、V2 文件传输、`copy_files_c2c` | -| `win+lnx` | 12 | `remote_*` 全族、`get_screenshot`、`get_activity_history`、`exec_command` / `terminal_*` / `kill_process` | -| `win` | 33 | 服务 / 注册表 / 键日志 / 文件写 / **`list_windows`** / `get_foreground_window` / `host_*` / `chat_*` / `power_action` | +| `win+lnx+mac+apk` | 9 | 只读写服务端本地数据:`list_hosts` / `get_host_detail` / `get_client_log` / `get_audit_log` / `get_server_status` / `mcp_*` / `host_set_remark` / `host_set_watch_level` | +| `win+lnx+apk` | 11 | `remote_*` 全族、`exec_command` / `terminal_*`、`get_screenshot`、`get_activity_history` | +| `win+lnx+mac` | 6 | 进程列表、文件列取 / V2 文件传输(含 `read_file`)、`copy_files_c2c` | +| `win+lnx` | 2 | `http_probe`、`kill_process` | +| `win+apk` | 6 | `remote_block_input`、`uninstall_host`、`chat_*` 全族 | +| `win` | 19 | 服务 / 注册表 / 键日志 / 文件搜索与写入 / **`list_windows`** / `get_foreground_window` / `host_inspect` / `host_control_*` / `operate_window` / 网络连接 / `power_action` | +| `apk` | 1 | `remote_lock_screen` | **注意 `exec_command` / `terminal_*` / `kill_process` 不在 `win+lnx+mac` 组**: macOS 客户端其实有对应实现(`macos/main.mm:753` 的 `ShellworkingThread` 跑 PTY, @@ -107,8 +110,9 @@ macOS 客户端其实有对应实现(`macos/main.mm:753` 的 `ShellworkingThre `SystemManager.h:38` 和 macOS 的 `SystemManager.mm:39` 都有 `COMMAND_WSLIST` 的 `case` 分支,看起来是支持的。但 `BuildListWindows` 把命令发在**主连接**上 (`McpServer.cpp:2931`),而这两个平台的主循环只处理 `COMMAND_SYSTEM` -(起 SystemManager 子连接),`WSLIST` 在子连接里才被处理——走不到。实测 Linux -上直接超时 `-32001`。那两个 `case` 是给 SystemDlg 窗口管理用的,不是 MCP 这条路径。 +(起 SystemManager 子连接),`WSLIST` 在子连接里才被处理——走不到。关掉平台门禁 +(`McpPlatformGuard=0`)时实测 Linux 上直接超时 `-32001`;默认门禁开启时,这张表 +会先拦下并返回 `-32005`。那两个 `case` 是给 SystemDlg 窗口管理用的,不是 MCP 这条路径。 Windows 是在主循环里处理的(`client/KernelManager.cpp:1491`),所以正常。 ### 平台优先级(产品定位)