Files
SimpleRemoter/docs/Mcp_Design.md
T
yuanyuanxianganddeepseek-flash eaa10cc7d3 Fix: Make the MCP command sentinel robust and fail stalled downloads fast
Re-verified every finding of the 2026-10-25 MCP test report against the source and
then end-to-end on the Debug instance, and fixed the ones that live on the server.

P1/P3/P4 share one root cause: the sentinel was appended to the command line, so any
command that swallows the rest of its line (rem, cmd /c, if, for) swallowed the
sentinel too and the call always timed out. On ConPTY clients the command and the
sentinel are now sent as two lines, the sentinel prints %errorlevel% (whose echoed
text is a literal template, not digits) so folding echo can no longer be mistaken
for the sentinel, and FindSentinel returns the real exit code (9009, 1, 0, ...)
instead of 0/1. Old non-PTY clients keep the single-line form, since their echo
skipping depends on the write length.

ConPTY also returns a rendered screen stream rather than a byte stream, so stripped
VT sequences leave duplicate text behind; output cleaning now cuts through the
echoed command line, strips the echoed sentinel line and erases any leftover
sentinel text by its per-command nonce. StripAnsi no longer leaves the backslash of
an OSC terminated by ST.

A terminal session destroyed by a timeout used to report the same "not found" text
as a typo in the session id; a 600s tombstone now says what happened instead.
download_file gets a stall watchdog: no data for 60s fails with a clear message and
releases the host, where a missing remote path used to hold the whole host for the
full 600s default timeout.

Also corrects the get_activity_history annotation (it does reach the remote host),
completes the -32007/-32008/-32009 error table, documents the sentinel design in
Mcp_Design.md 12.1, and corrects the report's claim that the tools blocked during a
transfer are local DB reads -- they are remote machine-manager fetches, and purely
server-local tools are unaffected.

Co-Authored-By: deepseek-flash
2026-10-25 17:09:39 +01:00

51 KiB
Raw Blame History

YAMA 服务端 MCP 支持方案

版本:1.0 状态:Final(定稿) 适用范围:server/2015Remote/(C++/MFC 服务端,生产主流)


1. 背景与目标

1.1 背景

MCP(Model Context Protocol)是 Anthropic 提出的开放协议,让 AI 助手(Claude Code、Claude Desktop 等)通过标准化的工具调用接口访问外部系统的能力。

YAMA 服务端维护了「在线主机列表」这一核心数据,如果能通过 MCP 暴露出去,用户就能在 Claude Code 里直接问「现在有多少台机器在线?」「列出所有在线的 Windows 主机」等,由 AI 调用工具获取实时数据。

1.2 本期范围(MVP)

只跑通 MCP,只实现一个工具,把可扩展架构搭起来:

  • 传输方式:Streamable HTTP(POST /mcp,JSON-RPC 2.0 over HTTP)
  • 工具数量:1 个 —— list_online_hosts(获取在线主机列表)
  • 暴露范围:启用开关(默认关闭,经「扩展 → MCP设置」对话框开启)+ 绑定地址可配置(默认 127.0.0.1 仅本机)+ token 认证(env / THIS_CFG / 随机)
  • 后续:逐步添加工具(进程列表、命令执行、屏幕截图等),架构不动

1.3 非目标(明确不做)

  • 不做 SSE 服务器推送(本期工具调用是 request/response 即可)
  • 不做多用户/角色体系(复用现有 WebService 认证或静态 token)
  • 不做写操作工具(操控主机的工具属于后续阶段,需单独评审安全边界)
  • 不碰现有 Web 控制台的 WebSocket 服务

2. 现状分析

C++ 服务端已有大量可直接复用的资产,MCP 的落地成本因此大幅降低。

现成资产 位置 在 MCP 中的角色
HTTP 服务器 httplib.h(header-only,file_server.h:34 已用) MCP 的 HTTP 传输层
JSON 库 jsoncpp/json.h(WebService.cpp 已用) JSON-RPC 编解码
Token 认证 WebServiceAuth.h(GenerateToken / ValidateToken / ComputeSHA256) 可选升级路径;MVP 用简单静态 token 比对(见 §3.5)
在线主机列表 → JSON CWebService::BuildDeviceListJson()(WebService.cpp:1506) 工具 list_online_hosts 的核心逻辑
在线主机数据源 CMy2015RemoteDlg::m_HostList(2015RemoteDlg.h:345,m_cs 保护)+ context::IsLogin() + context::GetClientData() 取数入口
配置系统 THIS_CFG.GetInt/GetStr("settings", ...) MCP 端口/token 配置

2.1 关键结论

  • HTTP、JSON、认证、主机列表 JSON 全部现成,MCP 侧不需要重新造轮子。
  • 唯一需要手写的是 MCP 的 JSON-RPC 2.0 协议层,因为 C++ 没有官方 MCP SDK(官方仅有 TS/Python/Java/Kotlin/C#/Go)。

2.2 BuildDeviceListJson 现状

WebService.cpp:1506 的 CWebService::BuildDeviceListJson(const std::string& username) 已实现:

  • 遍历 m_pParentDlg->m_HostList,过滤 ctx->IsLogin()
  • 输出字段:id / name / remark / ip / os / location / rtt / version / activeWindow / online / group / screen / clientType
  • 已处理 GBK/UTF-8 编码分叉(activeWindow 字段按客户端能力位选择编码页,见 WebService.cpp:1581 附近的 GetClientEncoding)

该方法是 private(WebService.h:160,位于 private 段)。MCP 侧需通过公开入口复用(见 §3.4)。


3. 方案设计

3.1 总体架构

2015Remote.exe(MFC 服务端进程)
├─ IOCP TCP 服务(被控端连接,现有)
├─ WebService(ws::Server,Web 控制台,现有,8080)
└─ McpServer(httplib,新增,默认禁用,经「MCP设置」开启后监听 127.0.0.1:6544)
      POST /mcp → JSON-RPC 分发
                    ├─ initialize
                    ├─ tools/list
                    └─ tools/call
                          └─ list_online_hosts → 复用 BuildHostJson(公共函数,§3.4)

核心决策:独立起一个 httplib server,不挂到现有 ws::Server。

理由:

  • 现有 ws::Server 的 HttpHandler 只有 path 参数、无 POST body(SimpleWebSocket.h:345),强挂 MCP 需改动其底层,侵入大、有回归风险。
  • 独立 server 零耦合、零风险,且天然满足「仅 127.0.0.1」的绑定需求。

3.2 新增文件清单

文件 职责 估算量
McpServer.h / McpServer.cpp httplib 封装、POST /mcp 路由、token 校验、生命周期 ~120 行
McpProtocol.h / McpProtocol.cpp JSON-RPC 2.0 协议层:initialize / tools/list / tools/call 分发 ~250 行
McpTools.h / McpTools.cpp 工具注册表 + list_online_hosts 实现 ~80 行
McpSettingsDlg.h / McpSettingsDlg.cpp 「MCP设置」配置对话框(启用/端口/绑定/token + 重启提醒) ~150 行
修改 2015RemoteDlg.cpp / .h 启动/停止 McpServer + 菜单项接线(ID_MCP_SETTINGS → OnMcpSettings) ~30 行
修改 2015Remote.rc / resource.h / UIBranding.h / FeatureFlags.h ID_MCP_SETTINGS 菜单项 + IDD_DIALOG_MCP_SETTINGS 对话框资源 + HIDE_MENU_MCP_SETTINGS + MF_MCP_SETTINGS 许可位 少量

头文件/实现可合并精简,实际以「一个 McpServer 类 + 一个工具注册表 + 一个协议分发函数」为最小形态,文件拆分仅为可读性。

3.3 协议层设计(JSON-RPC 2.0)

MCP 是 JSON-RPC 2.0。MVP 只需实现以下方法:

3.3.1 initialize(握手)

请求:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"claude","version":"..."}}}

响应:

{"jsonrpc":"2.0","id":1,"result":{
  "protocolVersion":"2025-06-18",
  "capabilities":{"tools":{}},
  "serverInfo":{"name":"yama","version":"<VERSION_STR>"}
}}

3.3.2 tools/list

请求:{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

响应:

{"jsonrpc":"2.0","id":2,"result":{"tools":[{
  "name":"list_online_hosts",
  "description":"获取当前所有在线主机的列表,包含计算机名、IP、操作系统、版本、备注、分组、活动窗口、延迟等实时信息。",
  "inputSchema":{"type":"object","properties":{},"required":[]},
  "outputSchema":{
    "type":"object",
    "properties":{
      "hosts":{
        "type":"array",
        "items":{
          "type":"object",
          "properties":{
            "id":{"type":"string"},
            "name":{"type":"string"},
            "remark":{"type":"string"},
            "ip":{"type":"string"},
            "os":{"type":"string"},
            "location":{"type":"string"},
            "rtt":{"type":"string"},
            "version":{"type":"string"},
            "activeWindow":{"type":"string"},
            "online":{"type":"boolean"},
            "group":{"type":"string"},
            "screen":{"type":"string"},
            "clientType":{"type":"string"},
            "tls":{"type":"boolean"}
          }
        }
      }
    },
    "required":["hosts"]
  }
}]}}

3.3.3 tools/call

请求:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_online_hosts","arguments":{}}}

响应(结构化输出:structuredContent 承载主机数组,content 附带可读摘要):

{"jsonrpc":"2.0","id":3,"result":{
  "structuredContent":{
    "hosts":[
      {"id":"123","name":"DESKTOP-ABC","remark":"我的Windows","ip":"192.168.0.92",
       "os":"Windows 10","location":"上海市","rtt":"12","version":"...",
       "activeWindow":"WeChat","online":true,"group":"default","screen":"1:1920x1080","clientType":"EXE"}
    ]
  },
  "content":[{"type":"text","text":"共 1 台主机在线。"}],
  "isError":false
}}

3.3.4 可选实现

  • ping:返回空 result(便于健康检查)
  • notifications/initialized:客户端通知,可忽略

3.3.5 错误响应(JSON-RPC 2.0 标准)

协议层必须处理以下错误,返回标准 error 结构(id 回填请求 id):

场景 code message
请求体不是合法 JSON -32700 Parse error
请求结构不合法(缺 jsonrpc/method 等) -32600 Invalid Request
方法未实现 -32601 Method not found
参数非法 -32602 Invalid params
内部错误 -32603 Internal error

示例(方法未实现):

{"jsonrpc":"2.0","id":1,"error":{"code":-32601,"message":"Method not found"}}

3.3.6 传输层约定(Streamable HTTP 最小子集)

  • 客户端 POST /mcp,请求头 Content-Type: application/json、Accept: application/json, text/event-stream。
  • 服务端返回 Content-Type: application/json(MVP 工具调用为 request/response,无需 SSE 流式)。
  • initialize 响应可回填 Mcp-Session-Id 头用于会话管理;MVP 单会话可省略,实现时对照最新 MCP 规范确认。
  • 仅接受 POST /mcp,其余路径/方法返回 404/405。

3.4 工具设计:list_online_hosts

取数方案(已定:抽公共函数)

BuildDeviceListJson 目前是 CWebService 的 private 方法,且依赖 m_pParentDlg。为满足「MCP 与 WebService 是平级数据消费者、不互相依赖」的原则,采用方案 C:抽公共函数。

// 公共函数:提取单台在线主机的完整数据(含 GBK/UTF-8 编码处理),返回 UTF-8 的 Json::Value
Json::Value BuildHostJson(context* ctx, _ClientList* clientMap);
  • CWebService::BuildDeviceListJson 内部改调该公共函数,Web 侧签名与输出不变(零回归)。
  • McpServer 侧持 CMy2015RemoteDlg*(SetParentDlg),在 m_cs 锁内遍历 m_HostList、IsLogin() 过滤,对每台主机调 BuildHostJson,组装为结构化输出。
  • 职责边界:用户名/分组过滤(username → allowed_groups)、m_cs 加锁、以及外层结构(Web 的 {"cmd","devices"} vs MCP 的 {"hosts"})属于调用方,不进公共函数;BuildHostJson 只负责「单台主机 → Json::Value」的字段序列化与编码转换。其中 remark 依赖 m_ClientMap->GetClientMapData(id, MAP_NOTE),故 clientMap 作为参数传入。

选型说明:方案 A(MCP 依赖 CWebService 单例)依赖方向错误,且 WebSvrPort=0 时 m_pParentDlg 为空导致取不到数;方案 B(MCP 自持父对话框复制逻辑)违反 DRY、重复易错的编码处理。故取 C。

返回内容(全量,含实时信息)

保留 BuildDeviceListJson 的全部字段,不做精简,以支持「AI 协助监督客户端运行状态」的场景:

  • 基础标识:id / name / remark / ip / os / location / group / version / clientType / screen
  • 实时信息:rtt(延迟)、activeWindow(当前活动窗口,即被控端正在做什么)
  • 连接凭据:tls(布尔,对应在线主机列表的 TLS 列;true 表示该客户端本轮以 TLS 模式登录,是登录时的凭据而非实时探测;老客户端/空值一律 false)

输出结构 {"hosts": [...]},每台主机一个对象,字段与 §3.3.2 的 outputSchema 一致。

3.5 安全设计

  • 绑定地址:默认 127.0.0.1(仅本机回环,其他机器无法访问);可经 McpBind 配置为 0.0.0.0(所有网卡)或内网 IP(如 192.168.0.92)以支持远程调用。
    • 非回环绑定时 token 经明文 HTTP 传输,需强 token,并建议配合防火墙限制源 IP 或启用 HTTPS(项目已有 WebHTTPS 实践)。
  • 静态 token 校验:每个 POST /mcp 请求校验 Authorization: Bearer <token> header;不匹配返回 HTTP 401。
  • token 来源(优先顺序):环境变量 YAMA_MCP_TOKEN → THIS_CFG 的 McpToken → 两者皆空则随机生成。
    • 前两者任一非空即作为固定 token;仅当两者皆空时才随机生成(仅本次进程运行期间有效,进程重启后重新生成不同的 token)。
    • 随机生成时必须将 token 输出到日志(Mprintf),否则用户无从获知、无法在 Claude Code 侧配置。
    • 环境变量名 YAMA_MCP_TOKEN 建议同 BRAND_WEB_ENV_VAR 一样在 UIBranding.h 定义为宏(如 BRAND_MCP_ENV_VAR),避免散落硬编码字符串。
  • 只读边界:MVP 仅一个只读工具,不暴露任何写/操控能力。
  • HTTP 方法限制:仅接受 POST /mcp,其余返回 404/405。

3.6 配置设计

沿用现有 THIS_CFG(settings 节):

配置键 默认值 说明
McpEnabled 0 MCP 总开关:0 = 禁用(默认),1 = 启用。经「扩展 → MCP设置」对话框设置
McpPort 6544 MCP 监听端口;仅当 McpEnabled=1 时生效;未配置用默认 6544
McpBind 127.0.0.1 监听地址;默认仅本机;可设 0.0.0.0(所有网卡)或内网 IP(如 192.168.0.92)以支持远程
McpToken 空(UI 默认随机值) 静态 token;对话框内「token 必填、默认随机值」——首次打开若为空则预填随机并随保存持久化。运行时优先级:env YAMA_MCP_TOKEN → McpToken → 皆空则随机生成(见 §3.5)
McpKeylog 0 键盘记录工具 get_keylog 的独立开关(见 §9.3);与 McpReadonly 无关,改动需重启生效

与旧版「McpPort=0 即禁用」不同:启用与否改由独立的 McpEnabled 开关控制,McpPort 回归纯端口语义,二者解耦。

3.7 生命周期接入

在 2015RemoteDlg.cpp Web 服务启动块(约 2048-2081)之后,新增 MCP 启动逻辑。McpServer 与 CWebService 同为单例:提供 static McpServer& Instance() 与全局 inline McpServer& McpServer() 访问器(仿 WebService(),见 WebService.h 末尾的全局访问器写法)。

auto mcpEnabled = THIS_CFG.GetInt("settings", "McpEnabled", 0);   // 默认禁用
auto mcpPort    = THIS_CFG.GetInt("settings", "McpPort", 6544);
auto mcpBind    = THIS_CFG.GetStr("settings", "McpBind", "127.0.0.1");
if (mcpEnabled) {
    // token 优先顺序:env YAMA_MCP_TOKEN → THIS_CFG McpToken → 皆空则随机(仅本次进程有效)
    const char* envTok = getenv("YAMA_MCP_TOKEN");
    std::string mcpToken;
    if (envTok && *envTok) {
        mcpToken = envTok;
    } else {
        mcpToken = THIS_CFG.GetStr("settings", "McpToken", "");
    }
    if (mcpToken.empty()) {
        mcpToken = GenerateRandomToken();  // 32 hex 随机串
        Mprintf("[McpServer] YAMA_MCP_TOKEN / McpToken 均未设置,本次进程随机 token:%s\n", mcpToken.c_str());
    }
    McpServer().SetParentDlg(this);   // 方案 C:MCP 需遍历 m_HostList,须持父对话框指针
    McpServer().SetToken(mcpToken);
    if (!McpServer().Start(mcpBind, mcpPort)) {
        Mprintf("McpServer start failed on %s:%d\n", mcpBind.c_str(), mcpPort);
    }
}

并在退出路径(OnDestroy / ExitInstance 对应位置)调用 McpServer().Stop()。

3.8 「MCP设置」配置对话框

MCP 默认不启用,通过主对话框「扩展 → MCP设置」菜单项打开配置对话框来开启。菜单项位置:2015Remote.rc 扩展菜单(POPUP "扩展(&X)")内、「地理信息(&L)」子菜单(纯真数据库 / IP2Region)的 END 之后、「插件设置」之前。

3.8.1 菜单与资源接线

  1. resource.h:新增命令 ID(取当前空闲段,经查 33077 空闲):
    #define ID_MCP_SETTINGS   33077
    
  2. 2015Remote.rc:在「地理信息(&L)」子菜单 END 之后、插件设置 之前插入:
    MENUITEM "MCP设置(&M)...",                  ID_MCP_SETTINGS
    
    并新增对话框资源 IDD_DIALOG_MCP_SETTINGS(「启用 MCP」复选框 + 端口/绑定地址/token 三个编辑框 + 确定/取消按钮)。
  3. UIBranding.h:扩展菜单隐藏开关新增一行(默认 0 显示):
    #define HIDE_MENU_MCP_SETTINGS   0   // MCP设置
    
  4. FeatureFlags.h:新增运行时许可位,占用 MenuFlags 保留段 [43-63] 的首位(紧跟 MF_REQUEST_AUTH 之后):
    #define MF_MCP_SETTINGS       (1ULL << 43)  // HIDE_MENU_MCP_SETTINGS
    
  5. 2015RemoteDlg.cpp:#include "McpSettingsDlg.h",然后消息映射 + 处理器 + 剪枝:
    ON_COMMAND(ID_MCP_SETTINGS, &CMy2015RemoteDlg::OnMcpSettings)
    // ...
    void CMy2015RemoteDlg::OnMcpSettings()
    {
        CMcpSettingsDlg dlg(this);
        dlg.DoModal();
    }
    
    并在扩展菜单剪枝块(pExtMenu,约 2015RemoteDlg.cpp:1225 之后)追加:
    if (SHOULD_HIDE_MENU(HIDE_MENU_MCP_SETTINGS, MF_MCP_SETTINGS))
        pExtMenu->DeleteMenu(ID_MCP_SETTINGS, MF_BYCOMMAND);
    

实现注意:2015Remote.rc 为 UTF-16 编码,菜单与对话框资源须由 VS 资源编辑器维护(手工改文本易破坏编码与资源 ID 引用)。IDD_DIALOG_MCP_SETTINGS 需在 resource.h 分配独立空闲的 IDD_ 数值(与 ID_MCP_SETTINGS 分开);对话框内控件 ID(如 IDC_CHK_ENABLE_MCP / IDC_EDIT_MCP_PORT / IDC_EDIT_MCP_BIND / IDC_EDIT_MCP_TOKEN)同理。

3.8.2 对话框字段与默认值

控件 绑定配置键 默认值 说明
「启用 MCP」复选框 McpEnabled 未勾选(0) 勾选后持久化 McpEnabled=1
端口 McpPort 6544 数字编辑框,仅当启用时有效
绑定地址 McpBind 127.0.0.1 默认仅本机;可改 0.0.0.0 / 内网 IP
Token McpToken 随机值 必填;为空时预填随机 token

3.8.3 初始化与保存

打开时读 THIS_CFG 回填;token 为空则当场生成随机值预填(32 hex)。保存时落盘并弹重启提醒:

BOOL CMcpSettingsDlg::OnInitDialog()
{
    CDialogLangEx::OnInitDialog();
    int enabled  = THIS_CFG.GetInt("settings", "McpEnabled", 0);
    int port     = THIS_CFG.GetInt("settings", "McpPort", 6544);
    std::string bind = THIS_CFG.GetStr("settings", "McpBind", "127.0.0.1");
    std::string tok  = THIS_CFG.GetStr("settings", "McpToken", "");
    if (tok.empty()) tok = GenerateRandomToken();   // 预填随机,随保存持久化
    // 回填到控件:m_bEnabled / m_nPort / m_strBind / m_strToken
    return TRUE;
}

void CMcpSettingsDlg::OnBnClickedBtnSave()
{
    // 从控件收集:enabled / port / bind / token
    if (enabled && token.empty()) {
        MessageBoxL(_TR("Token 不能为空"), _TR("提示"), MB_ICONWARNING);
        return;
    }
    THIS_CFG.SetInt("settings", "McpEnabled", enabled ? 1 : 0);
    THIS_CFG.SetInt("settings", "McpPort", port);
    THIS_CFG.SetStr("settings", "McpBind", bind);
    THIS_CFG.SetStr("settings", "McpToken", token);
    MessageBoxL(_TR("MCP 设置已保存。\n启用/端口/绑定地址/Token 的改动需重启程序生效。"),
                _TR("提示"), MB_ICONINFORMATION);
    CDialogLangEx::OnOK();
}

3.8.4 与运行时 token 逻辑的衔接

对话框的「默认随机 token」是把随机值写入 McpToken 并持久化,于是下次启动走 env → McpToken 的固定 token 分支;运行时「两者皆空则随机」分支仅在用户从未通过对话框设置过(或手动清空 token)时兜底,两者不冲突。GenerateRandomToken() 为 MCP 侧新增的小工具函数(32 hex 随机串,可用 rand_s / BCryptGenRandom 实现;如需可复用 WebServiceAuth.h 的 ComputeSHA256 派生)。


4. 实施步骤

步骤 内容 验收
1 新建 McpProtocol:JSON-RPC 分发 + initialize/tools/list/tools/call(含 jsoncpp 解析/序列化) 单元自测:手写请求串,验证响应
2 新建 McpServer:httplib 起 127.0.0.1:6544,POST /mcp 路由 + token 校验(含随机生成) curl 请求返回 401/正常
3 抽公共函数 BuildHostJson,CWebService::BuildDeviceListJson 改调之 Web 输出不变,零回归
4 注册 list_online_hosts 工具:handler 持父对话框、m_cs 锁内遍历、调 BuildHostJson 组装 tools/call 返回主机列表
5 新增 McpSettingsDlg + 菜单项接线(ID_MCP_SETTINGS / OnMcpSettings / HIDE_MENU_MCP_SETTINGS / IDD_DIALOG_MCP_SETTINGS 资源) 对话框可启用/禁用、配置端口/绑定/token,保存落盘并提示重启
6 接入 2015RemoteDlg 启动/停止(按 McpEnabled 门控)+ 配置 服务端启动后端口监听正常
7 Claude Code 接入验证(见 §5) 见验收标准

5. 验收标准

  1. 在「MCP设置」对话框启用并重启服务端后,127.0.0.1:6544 监听正常,外部地址无法访问;未启用时该端口不监听。
  2. 无 token 的请求返回 HTTP 401;错误 token 返回 401;正确 token 通过。
  3. curl 模拟 initialize → tools/list → tools/call 全流程,返回符合 JSON-RPC 2.0 与 MCP 规范。
  4. Claude Code 侧:
    claude mcp add yama --transport http http://127.0.0.1:6544/mcp -H "Authorization: Bearer <token>"
    
    claude mcp list 能看到 yama,在对话中问「列出在线主机」能正确触发工具并返回列表。
  5. 现有 Web 控制台、IOCP 主服务功能无回归。

6. 风险与约束

风险 说明 应对
无官方 C++ MCP SDK 需手写 JSON-RPC 协议层 仅实现 3 个方法,量小可控;协议稳定后再考虑抽库
MCP 规范版本演进 protocolVersion 字符串需与客户端匹配 实现时对照最新规范;initialize 返回可协商版本
并发安全 遍历 m_HostList 需持 m_cs MCP 与 WebService 采用相同的「m_cs 锁内遍历」模式
字符编码 GBK/UTF-8 分叉 复用公共函数 BuildHostJson 的编码处理,不自造
token 存储 THIS_CFG 的 token 会明文落盘;随机 token 会打印到日志 本地回环 + 只读,风险可控;敏感场景建议仅用 env 并妥善保管

7. 后续扩展规划(本期不做)

  • 工具:get_host_processes(进程列表)、execute_command(命令执行)、capture_screen(截图)等
  • 写操作工具的安全边界评审(操作对象、权限、审计)
  • 认证升级:复用 WebServiceAuth 的签名 token / 过期机制
  • 分组过滤:list_online_hosts 加 group 参数
  • P9 远程交谈(已实现):chat_open / chat_send / chat_wait / chat_close,独立开关 McpChat(默认 0,与只读开关无关);协议不变,客户端聊天窗口改为 Unicode 对话框以支持非中文系统(见 docs/Mcp_Chat_Design.md)

8. 决策记录

决策记录(全部已定):

  • ✅ 启用开关:新增 McpEnabled,默认 0(禁用)。MCP 默认不启动,须用户在「扩展 → MCP设置」对话框手动开启。
  • ✅ 端口:McpPort 可配置,未配置默认 6544(纯端口语义,不再兼任启用开关)。
  • ✅ token:优先顺序 env YAMA_MCP_TOKEN → THIS_CFG.McpToken → 皆空则随机生成(仅本次进程有效,打印到日志)。对话框内 token 必填、默认随机值(预填并随保存持久化到 McpToken)。
  • ✅ 绑定地址:默认 127.0.0.1(仅本机);可配置为 0.0.0.0 或内网 IP(如 192.168.0.92)以支持多人协作跨机调用。
  • ✅ 配置入口:主对话框「扩展」菜单,位于「地理信息(&L)」子菜单下方新增「MCP设置」菜单项,打开独立配置对话框。
  • ✅ 生效方式:MCP 启用/端口/绑定/token 的改动均需重启服务端生效,对话框保存后弹窗提醒「重启程序生效」。
  • ✅ 取数方案:C(抽公共函数 BuildHostJson,MCP 与 WebService 平级复用)。
  • ✅ 返回字段:全量,含实时信息(rtt / activeWindow),支持 AI 监督场景。
  • ✅ 序列化:structuredContent + outputSchema,content 附带可读摘要。

9. 增补(2026-10-25:N1–N5)

本轮在既有工具族(P2–P9)之上补齐「能找到主机、能一次查多台、输出不撑爆上下文、认证可追溯」四件事,全部为服务端改动,客户端零改动。

9.1 N1 离线主机可见

  • 新增工具 list_all_hosts(online / offline 两个布尔过滤,默认都为 true),数据源是 m_ClientMap(主机列表历史记录,GetAll() 快照 + m_cs 保护),在线条目复用 BuildHostJson,离线条目由 BuildOfflineHostJson 生成,字段:id / name / remark / ip / os / location / online / group / last_seen / install_time / authStatus。
  • search_hosts 的 online 参数:true = 仅在线,false = 仅离线(修复此前 online=false 永远返回空列表的问题),缺省 = 仅在线(与改动前一致,不改变既有调用方看到的结果)。两类都要请用 list_all_hosts。
  • authStatus 是 ClientValue::Authorized 的三态枚举(unauthorized / authorized_by_super / authorized_by_admin / forbidden),不是布尔值。
  • get_host_detail 对「在 m_ClientMap 里但当前离线」的 id 不再返回 -32002,改为返回该主机的最后记录(online=false),使 list_all_hosts 的结果可直接消费。

9.2 N2 批量只读调用

  • 只读工具支持 ids: [](最多 50 个),与 id 二选一(inputSchema 用 anyOf 表达)。命中批量的工具:get_host_detail / list_processes / list_windows / list_services / list_files / list_registry / get_client_log / get_activity_history / list_network_connections / 全部 host_list_* / host_get_hosts_file。
  • 写操作工具传 ids 直接 -32602 拒绝(不逐个执行,避免误操作扩散)。
  • 返回:{tool, total, succeeded, failed, results:[{id, ok, data|error, text}]};content 里是「共 N 台,成功 X 台,失败 Y 台」+ 最多 ~1200 字节的失败明细。
  • limit / offset 对每台主机各自生效;批量是串行执行,单台超时会占用整批等待时间。

9.3 N3 get_keylog

  • 复用客户端既有键盘记录链路:主连接下发 COMMAND_KEYBOARD(169) → 客户端建子连接 → 子连接回 TOKEN_KEYBOARD_START(293) 作为就绪包绑定 → 之后每约 1 秒推一包 TOKEN_KEYBOARD_DATA(294)。
  • 服务端把击键流累积(不是一问一答),窗口 duration_ms(默认 4000,1000–15000)或字节上限 max_bytes(默认 64 KiB,1024–256 KiB)先到者结束;结束时 EndManagedSession(..., cancelIo=true) 关闭子连接 —— 与 MFC 关对话框同一路径,客户端据此停止记录。
  • 复用 P8 的挂起会话表(新增 PendingKind::Keylog,仍受「单设备单飞行」约束),就绪包绑定、迟到包墓碑、子连接断开唤醒全部沿用 P8 逻辑;绑定后服务端回 COMMAND_NEXT,让客户端 WaitForDialogOpen 立即返回(本工具不开 UI)。
  • 返回 {id, duration_ms, bytes, lines, lineCount, truncated},文本按客户端代码页转 UTF-8(GetClientEncoding)。注意:客户端连上后会先把缓冲区里已有的历史记录推过来,所以结果既含历史也含窗口期内的新击键。
  • 独立开关 McpKeylog(默认 0,不要求只读关)。工具只在开关打开时出现在 tools/list,关闭时直接调用返回 -32006。
  • 隐私:击键内容只进本次响应;审计只记 CALL_OK tool=get_keylog ms=… bytes=…,不落任何正文。

9.4 N4 认证加固

  • 静态 token 校验失败:返回 401,并按来源 IP 计数;60 秒窗口内失败 10 次即封禁该 IP 900 秒,封禁期内返回 429 + Retry-After。失败表上限 1024,满时先清理过期项。
  • 环回来源(127.0.0.1 / ::1)只记账不封禁:内置 frpc 把 MCP 端口映射出去时是「本机连本机」,且这条转发没开 Proxy Protocol(httplib 不解析),服务端看到的源地址恒为环回。若按 IP 封禁,一次外部扫描就能把隧道后面所有客户端(包括自己)锁死 15 分钟。审计里这类封禁触发记为 AUTH_BLOCK ... scope=proxy-source-exempt。
  • 审计文件 <exe>\logs\mcp_audit.log(追加写,5 MB 轮转为 .1),每行:时间戳(毫秒)、事件、来源 IP、详情。
    • AUTH_FAIL:UA(截断/清洗)、body 大小、是否因此被封禁。
    • AUTH_BLOCK:封禁生效。
    • CALL_OK / CALL_FAIL:tool=、耗时 ms=、响应字节数 bytes=。
    • CALL_DENIED:被策略拒绝的调用(-32006)另记一条,含 tool= 与固定原因文本,见 §10.8。
  • 审计不记录 token、密码、哈希、剪贴板内容或工具返回正文。

9.5 N5 列表输出治理

  • 列表类工具统一 limit / offset:默认 limit=100,硬上限 1000,offset 默认 0;非正数按默认值处理。
  • structuredContent 统一附 total / totalAll / offset / limit / hasMore,与 McpMachine.cpp 既有约定一致(host_list_* / list_network_connections 本来就是这样)。
  • content 摘要统一为「共 N <单位>,本次返回第 a-b 条(还有更多,可用 offset 继续取)。」;hasMore=false 时不再出现「继续取」的误导提示;offset 越界时明确写「offset 超出范围,本次返回 0 条」。
  • 实现集中在 McpInternal.h/.cpp:PageWindow / ResolvePageWindow / ApplyPageWindow / WritePageFields / AppendPagingProps / PageSummary。
  • list_files 仍受客户端单次 500 条的硬限制(total=500 表示客户端截断,不是服务端分页)。

10. 增补(2026-10-25:A 批加固 / B 批非破坏性能力)

A 批只改服务端传输、元数据与校验,不动任何既有工具语义;B 批新增三个工具(两个写主机库、一个远程搜索)。客户端零改动。

10.1 A1/A2 传输层加固(CMcpServer::Start)

httplib 默认值对 MCP 场景不合适,改为显式配置:

项 默认 现在 原因
请求体上限 不限(SIZE_MAX) 2 MB(超出 413 RequestEntityTooLarge) 只收 JSON 参数,文件内容走子连接分块,绝不进 HTTP body
读超时 5s 15s 经 frp 隧道上传参数时,单次 recv 不该 5s 就断
写超时 5s 60s get_screenshot 大图 base64、慢链路下 5s 会写断响应
线程池 max(8, 核数-1) 固定 32 chat_wait(最长 55s)与批量只读会长期占线程

读超时是 socket 空闲读超时,不是「处理时长上限」:search_file 阻塞 20s、chat_wait 阻塞 55s 都正常返回(已实测)。

10.2 A3 工具注解(McpInternal::ApplyToolAnnotations)

  • tools/list 每个工具都带 annotations:readOnlyHint / destructiveHint / idempotentHint / openWorldHint,由 McpInternal.cpp 的 kToolHints 表按名登记,末尾统一补一次。
  • 未登记的工具按规范默认值处理(destructiveHint=true),即新增工具必须显式登记,漏登记只会更保守,不会误标成只读。
  • 只读工具的 destructiveHint 一律 false(按规范对只读工具无意义,避免客户端误报「破坏性」)。
  • openWorldHint=false 只给「只读服务端本机状态」的工具(list_online_hosts / search_hosts / list_all_hosts / get_host_detail / get_activity_history / get_audit_log / get_server_status),其余都会触达外部主机。

10.3 A4 get_host_detail 字段补全

在线主机现在返回:id / name / online / ip / publicIp / location / group / os / version / exeVersion / clientType / clientPath / systemBits / programBits / cpuCores / memoryGB / monitors / screen / user / isAdmin / pid / installTime / activeWindow / rtt / tls;离线主机返回 authStatus / last_seen / install_time 等最后记录。

注意 memoryGB 是 double:客户端 GetMemorySizeGB() 上报的就是浮点字符串(如 "27.800000000000001" 的原始形态),不能按整数解析。服务端按 1 位小数规范化,并给 jsoncpp 写入器设 15 位有效数字,避免输出 17 位噪声。

10.4 B1 主机库写入:host_set_remark / host_set_watch_level

  • 写的是服务端本机的 _ClientList(MAP_NOTE / MAP_LEVEL),只影响主控端自己的展示:不下发命令、不改远端状态。
  • 门控:McpReadonly=0 即可(不要求 McpManage);在线/离线(历史记录)主机都能写,id 在主机库中存在即可。
  • host_set_remark:remark 必填(空串 = 清除),严格 GBK 转换(emoji、ö 等不可表示字符报 -32602),长度上限 63 GBK 字节(主机库列 char Note[64])。
  • host_set_watch_level:level 0–3。重复写同一值幂等。
  • 写后 SaveToFile(GetDbPath()) 落库,并用 LVM_REDRAWITEMS 让在线列表那一行立刻刷新(MCP 线程不直接碰 CListCtrl)。
  • 审计只记「set/cleared + 字节数」与 level=,不记录备注正文。

10.5 B2 远程文件搜索:search_file

链路(旧文件管理器,不是 SimplePlugins 版):

主连接 COMMAND_LIST_DRIVE → 客户端建子连接 → 子连接回 TOKEN_DRIVE_LIST
  → 服务端 OnDriveList 下发 COMMAND_SEARCH_FILE [根目录 \0][模式 \0](ANSI/GBK 两个 C 串)
  → N × TOKEN_SEARCH_FILE_LIST(分片)→ TOKEN_SEARCH_FILE_FINISH

协议来自 client/FileManager.cpp(COMMAND_LIST_DRIVE → LoopFileManager → CFileManager)。客户端工程是 MultiByte,所有字段都是 GBK,服务端用 Utf8ToCpExact 严格转换,不可表示即 -32602。

要点:

  • 模式:不含 * / ? 时客户端当成 *pattern*(不区分大小写的子串),含通配符时走 WildcardMatch。
  • 递归:客户端只有递归搜索(深度 32,最多 10000 条,跳过隐藏/系统目录与重解析点)。recursive=false 由服务端按「父目录 == 根目录」过滤实现。
  • 路径归一化:客户端用 wsprintf("%s\\*.*") 枚举,根目录带尾部反斜杠会拼成 C:\\*.* 导致 FindFirstFile 失败、搜索秒回 0 条。服务端统一切成正斜杠→反斜杠并去尾斜杠(C:\ → C:,客户端再拼回 C:\*.*)。
  • 超时:timeout_ms 默认 20000(1000–120000)。到点先下发 COMMAND_FILES_SEARCH_STOP,再等 5s 收尾;收不到 FINISH 也返回已收到的部分结果,finished=false。
  • 收集上限:5000 条 / 4 MB 原始包,超出即让客户端停搜并置 truncated=true(保护服务端内存,整盘搜索能命中几十万条)。
  • 子连接身份校验:TOKEN_SEARCH_FILE_LIST / TOKEN_SEARCH_FILE_FINISH 都按 context* 比对当前 pending 的子链接,旧搜索(已放弃)的尾包一律不受理,避免迟到的 FINISH 终止新搜索。
  • 已知风险(客户端既有缺陷,仓库内已修):client/FileManager.cpp 的 SearchFilesRecursive 曾用无界 wsprintf 往 char[MAX_PATH] 里拼路径(strPath、szFullPath),全程没有长度检查。目录一深(累计路径超过 260)就栈溢出:Debug 客户端弹 Run-Time Check Failure #2 - Stack around the variable 'strPath' was corrupted 并挂住搜索线程,Release 客户端静默破坏栈。MFC 文件管理器的「搜索」走同一函数,与 MCP 无关。源码已于 2026-10-25 修掉(commit 8f718d9,入口/逐条目长度预判);已部署的老客户端仍带这个缺陷,所以 tools/mcp_smoke.ps1 的搜索用例仍是 opt-in(-SearchPath)。
  • 无头路由:MFC 对话框存在时搜索结果走 OnReceiveComplete;只有无头子连接(MCP 调用)才会进 MessageHandle,所以这两条 case 只影响 MCP。TOKEN_SEARCH_FILE_LIST 分支绝不 CancelIO(后面还有 FINISH 与剩余分片)。
  • 输出:{files:[{path,name,dir,size,modified}], finished, truncated, total, totalAll, offset, limit, hasMore}。

10.6 A5 冒烟测试脚本

tools/mcp_smoke.ps1:只调只读工具(列表/详情/搜索 + 传输层负例),断言分页字段、注解、401/413、批量汇总。

$env:YAMA_MCP_TOKEN = '<token>'
powershell -ExecutionPolicy Bypass -File tools\mcp_smoke.ps1                     # 默认 6544(Release)
powershell -ExecutionPolicy Bypass -File tools\mcp_smoke.ps1 -Base http://127.0.0.1:6545/mcp

token 只从 -Token / env 读取,不落仓库、不打印;无在线主机时加 -SkipHost。退出码 0/1,可接 CI。

10.7 明确不做的两项

  • get_clipboard:剪贴板常含口令/令牌/私钥,属"读即泄密",且客户端没有"只读不覆盖"的现成链路;已有 remote_clipboard 覆盖写。需要时用 get_screenshot + 人工确认。
  • close_window:operate_window 的 close 动作已覆盖(同一 COMMAND_WINDOW_CONTROL 链路),不重复造工具。

10.8 D 批:拒绝也入审计

动机:所有策略拒绝(只读模式、Mcp* 开关关闭、主机不支持某能力)都返回 -32006,而审计里只有 CALL_FAIL——和「参数错」「主机离线」「超时」混在一起,事后分不清「没人调过」和「被策略拦下」。

  • 实现放在 tools/call 的统一出口(CMcpServer 的 HTTP 处理器),不在 24 个 -32006 分支里逐个埋点:成功解析响应体后多取 error.code / error.message,code == -32006 就追加一条
    <时间> CALL_DENIED ip=<来源> tool=<工具名> reason=<固定英文原因>
    
    同一调用仍会留下原有的 CALL_FAIL 行,所以 CALL_FAIL 的统计口径不变。
  • reason 全部是各分支写死的英文句子(如 File transfer is disabled: requires McpFileTransfer=1),不含调用参数或用户输入,落盘安全;审计依旧不记录 token、参数或返回正文。
  • 其他错误码(-32602 参数、-32002 主机离线、-32001 超时等)不额外记事件,靠 CALL_FAIL 行即可。
  • 验证(Debug 实例):把 McpFileTransfer 临时置 0 重启后调 download_file,审计立刻出现 CALL_FAIL ... tool=download_file ms=1 bytes=114 紧跟 CALL_DENIED ... reason=File transfer is disabled: requires McpFileTransfer=1;恢复 McpFileTransfer=1 重启后同一调用恢复 CALL_OK 且无 CALL_DENIED。冒烟脚本 20/20 通过(未指定 -SearchPath 时跳过 2 个搜索用例)。

11. 增补(C 批:读侧增强,不改客户端)

11.1 C1 get_audit_log 分页与过滤

改动前每次调用都返回镜像里的全部条目(环形缓冲上限 1000 条),调用方没法只看关心的部分,日志一多就会把工具返回值撑大。

  • 新增入参:type(类型列子串,不区分大小写,如 MCP 能匹配 MCP命令执行)、keyword(正文子串,不区分大小写)、limit / offset(沿用统一分页,默认 100、上限 1000)。
  • 过滤在分页之前生效:total 是命中条数、totalAll 是镜像里的全部条数;hasMore 针对命中的条目。摘要会补一句「过滤前共 N 条」,方便判断是不是过滤写错了。
  • 读取仍在 m_cs 临界区内完成(UI 线程会并发写入),过滤循环里先做 GBK→UTF-8 转换再比对,避免拿两种编码互相比。
  • outputSchema 补 total/totalAll/offset/limit/hasMore(与其它列表工具一致)。
  • 注意 get_audit_log 读的是主界面消息镜像,不是 logs\mcp_audit.log;两者的条目内容和保留策略都不同(前者是 1000 条环形缓冲,后者是 5 MB 文件滚动)。
  • 验证(Debug 实例):limit=2 两页分别返回第 1-2 / 3-4 条且 hasMore=true,offset=999 返回「offset 超出范围」;type=mcp 命中 MCP命令执行(大小写不敏感)、type=提示 命中「使用提示 / 提示信息」、keyword=监听 命中「监听端口: 6543成功」;冒烟脚本 23/23 通过(新增分页字段、条数上限、过滤未命中 3 项断言)。

11.2 C2 新工具 get_server_status

排查「改动到底生效没有」「为什么某个工具被拒」时,原先只能靠 list_online_hosts 加 get_audit_log 侧面推断;现在有一个服务端自身的状态快照。纯内存、只读、不建子连接。

返回(structuredContent.status):

字段 含义
app_name / version 品牌名与 BRAND_VERSION(当前 1.4.1)
exe_build_time exe 文件的最后写入时间=链接时间(比 __DATE__/__TIME__ 可靠,后者是编译单个 .cpp 的时间)
uptime_sec 进程已运行秒数(GetProcessTimes 的创建时间起算,不是开机时间,也不受 MCP 启停影响)
bind / port MCP 实际监听的地址与端口(Start 时记录,非从配置回读)
switches readonly / terminal / remote_control / file_transfer / manage / machine / machine_dangerous / keylog / chat
hosts online / offline 台数(与 list_all_hosts 同源)
sessions pending(一次性/管理/键盘记录挂起) / terminal / remote_control / file_transfer / chat 在飞会话数
blocked_auth_ips 当前处于鉴权封禁期的来源 IP 数
  • 不返回 token、McpCmdWhitelist 内容或任何配置原文;switches 只报布尔值。
  • sessions 各项各取各自的锁、取完即放,是「大致同一时刻」的估算值,不能当一致性快照用。
  • 工具注解登记为只读 + 非破坏性 + 幂等 + 不触达外部主机;tools/list 总数变为 53。
  • 验证(Debug 实例):返回 Yama v1.4.1,已运行 17 秒,监听 127.0.0.1:6545;在线主机 1 台、离线 3160 台;terminal_open 期间 sessions.terminal=1、terminal_close 后回到 0;冒烟脚本 26/26 通过(新增 3 项:正常返回、版本/端口/开关齐全、不含 token)。

11.3 C3 主机列表过滤:list_online_hosts / list_all_hosts

这两个工具原先只有分页,想找「某个分组」「某个平台」的主机只能翻页或改用 search_hosts(后者不支持 client_type,且对在线/离线的取舍规则不同)。

  • 新增三个可选入参(两个工具共用同一套实现):group / os / client_type,均为子串匹配、ASCII 不区分大小写、AND 组合,口径与 search_hosts 一致。
  • 过滤在分页之前生效:total 为命中台数、totalAll 为过滤前总数(list_online_hosts 是全部在线数,list_all_hosts 是主机库总数);摘要改用「共 N 台主机匹配」并补一句过滤前规模,写错条件时一眼能看出来。
  • list_all_hosts 摘要里的在线/离线拆分也按命中条目统计。
  • 离线主机没有 clientType(历史记录里不存这个字段),所以带 client_type 条件时离线主机不会命中——按平台筛历史主机用 os。
  • 验证(Debug 实例):client_type=exe 命中 1 台(EXE/os=Windows 11),client_type=lnx 命中 0 台但 totalAll 仍为 1;list_all_hosts 带 group=default 命中 3161 台并正确拆分在线 1 / 离线 3160,os=zzz 命中 0 台;冒烟脚本 28/28 通过(新增过滤未命中、totalAll 不变 2 项断言)。

11.4 C4 search_file 结果侧过滤

search_file 的搜索条件(根目录 + 通配模式)由客户端执行,改不动;但把匹配项拿回服务端后可以再筛一遍,省掉 AI 端逐条比对。

  • 新增四个可选入参,都在服务端对已收集的匹配项做过滤,不减少客户端侧搜索耗时:
    • min_size / max_size:字节数,整数,闭区间;负数或非数字返回 -32602;两者都给出且 min_size > max_size 返回 -32602。
    • modified_after:接受 YYYY-MM-DD(当天 00:00:00 之后)或 YYYY-MM-DD HH:MM:SS;格式不符返回 -32602。客户端返回的 modified 是定宽 "YYYY-MM-DD HH:MM:SS",可直接字典序比较,所以两种写法都合法("2026-01-01" <= "2026-01-01 08:00:00")。
    • name_only:布尔,命中项只保留 path / name 两个字段,适合只要文件清单时省 token。
  • 过滤在分页之前:total 为命中条数、totalAll 为过滤前条数;摘要补一句「过滤前共 N 条(大小/修改时间/精简字段过滤在服务端进行,不减少客户端搜索耗时)」。
  • 过滤只看服务端已收到的条目,所以仍受 max_results / timeout_ms 截断:客户端没搜完时,过滤结果也是部分的(truncated / finished 字段照旧反映这一点)。
  • 验证(Debug 实例,根目录 C:\Windows\Fonts、*.ttf):基线 255 条;min_size=1000000 → 39 条且 totalAll=255;name_only=true 每条只有 path/name;modified_after=2026-01-01 → 165 条、2026-06-03 00:00:00 → 130 条、2027-01-01 → 0 条;min_size=-5、min_size=10 & max_size=5、modified_after=2026/01/01、modified_after=2026-01-01 12:00 均返回预期的 -32602。冒烟脚本 33/33 通过(新增 3 项:min_size 过滤后 totalAll 不变、name_only 精简字段、非法 modified_after 返回 -32602;后三项需带 -SearchPath 才执行)。

12. 错误码速查(E 批:冒烟与文档)

工具的失败分三类,AI 端应按 code 决定下一步,而不是读 message 文本。message 是给人看的英文说明,随实现变化,不作为契约。

code 含义 典型触发 建议动作
-32700 Parse error 请求体不是合法 JSON 修正客户端序列化
-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 重试;持续出现看主机是否卡住
-32002 Host offline / not found 主机 id 不存在、主连接已断、会话 id 不存在或已关闭 先 list_online_hosts 刷新再选主机
-32003 Busy 该主机已有同类请求在飞(终端/截屏/文件/聊天会话),或同设备重复 chat_open 等前一个结束或先 *_close
-32004 Send failed 命令写入主连接失败(连接刚断) 重试一次;仍失败按 -32002 处理
-32005 Not supported on this host 需要 Windows 的工具用在 LNX/MAC/APK 主机上 换 Windows 主机,或改用跨平台只读工具(list_files 等)
-32006 Policy refused 只读模式 / 对应 Mcp* 开关关闭 / 主机不支持该能力(如 V2 文件传输) 不要重试:这是配置决定,需管理员改服务端配置
-32007 Not in command whitelist exec_command 的命令不在 McpCmdWhitelist 里,或词边界不匹配(dir 过、dirx 拒) 不要重试:换成白名单内的命令,或请管理员加白名单项
-32008 Rejected by validation 同一码覆盖四类语义:exec_command 含 shell 元字符 &|<>^ 或控制字符(含 \r\n);路径/参数含非法字符;老客户端不支持 V2 文件传输格式;remote_open 遇到多显示器 按 message 修正参数;多显示器/老客户端属能力限制,换目标或换主机
-32009 Target not found kill_network_connection 的四元组在当前连接表里查不到(dry_run 传假四元组最常见) 先用 host_list_network_state 取真实四元组再 dry_run 校验
  • 命令超时会销毁持久会话(terminal_exec):等服务端收集到哨兵超时返回 -32001,会话随即被销毁并留 600 秒「墓碑」;对同一 session_id 再发命令返回 -32002,文案明确写 Terminal session was destroyed after this command timed out (waited N ms); call terminal_open again,与「id 写错」(Terminal session not found: <id>)区分开。

  • download_file 有停滞看门狗:60 秒没收到任何数据(远程路径不存在/不可访问最典型)即失败,返回 -32001 且文案带 File transfer stalled: no data received for 60s ...,主机立即释放,不必等 timeout_ms。真实的大文件传输只要还在持续收数据就不会触发。

  • -32006 会额外在审计日志里记一条 CALL_DENIED(§10.8),其余错误只体现在 CALL_FAIL 行。

  • 批量调用(带 ids[])整体不报错:每个 id 的结果单独带 error,顶层用 succeeded / failed / skipped 汇总;只有整批请求本身非法(超过 50 个 id、写操作传 ids)才返回顶层 -32602。

  • 冒烟脚本 tools/mcp_smoke.ps1 覆盖了上表的可复现项:-32601(未知 method)、-32602(未知工具/缺参数/51 个 id)、-32002(不存在的主机)、-32006(任一开关关闭时自动挑一个关着的功能验证,并断言审计里出现 CALL_DENIED;全部开启时跳过)。其余码由各批次的功能验证覆盖(-32001/-32003 等需要构造竞态或超时,不进冒烟)。

  • 本次验证(Debug 实例,McpKeylog 临时置 0):get_keylog 返回 -32006,Bin\logs\mcp_audit.log 末尾出现 CALL_DENIED ... tool=get_keylog reason=Keyboard log is disabled (McpKeylog=0);此时冒烟 34/34 通过。恢复开关后 -32006 与审计两条转为跳过,32/32 通过;带 -SearchPath 时 37/37 通过。

12.1 命令哨兵与输出清洗(测试报告 P1/P3/P4 的修复)

exec_command 与 terminal_exec 都靠哨兵判断「命令已执行完、退出码是多少」。哨兵有两种形态:

客户端 下发内容 退出码
ConPTY(is_pty=true,新版 Windows 客户端) 第一行 @echo off & <cmd>;第二行单独 echo __MCP_DONE_<nonce>__%errorlevel% 命令的真实退出码
老 ShellManager 管道(is_pty=false) 单行 ` 2>&1 && echo _MCP_DONE__0

为什么 PTY 要分两行下发:rem hello、cmd /c exit 0、if、for 这类「吞行」命令会把同一行里的 && echo 哨兵 一起吞掉(rem/cmd /c 把行内剩余文本当作自己的参数),哨兵永不出现,于是必然超时并销毁会话。哨兵独立成行后由 shell 自己执行,不再受命令行影响。老客户端只能维持单行形态:client/ShellManager.cpp 按「写入字节数」跳过回显,多写一行会吃掉上一行的输出。

为什么用 %errorlevel%:ConPTY 会把输入整行回显进输出流(80 列会折行)。回显文本里是字面 %errorlevel% 而不是数字,而 FindSentinel 只认「标记 + 数字」,折行回显再也不可能被误判成哨兵(评审 P3:ver 曾因回显里的 __1 被判成 exit_code=1),同时还能拿到真实退出码(如 nosuchcmd 的 9009)。

输出清洗顺序:剥 ANSI(OSC 序列以 ESC\ 结尾时两字节一起吞,否则会残留 \)→ CRLF 归一 → 从缓冲区开头删到「我们下发的命令行回显」结束(顺带清掉 shell 启动画面与提示符)→ 删哨兵行回显 → 按 nonce 擦掉残留的哨兵文本 → 去首尾空行。最后一步是必需的:ConPTY 送回来的是屏幕渲染流(带光标移动/擦除序列),剥掉序列后同一行可能重复出现,哨兵会留下副本(实测不擦时 rem hello 只剩哨兵、cmd /c echo abc 成了 abc__MCP_DONE_x__0)。nonce 每条命令随机生成,命令的真实输出不可能包含它,所以按 nonce 擦除不会误伤业务输出。

已知边界:屏幕渲染流里「光标下移空行」会被剥成紧邻行(例如 ping 的统计块会贴在最后一条回复后面),不影响语义。