Files
SimpleRemoter/docs/Mcp_Design.md
T
yuanyuanxianganddeepseek-flash d9a1a9ebcb Fix: Record policy refusals in the MCP audit log
Every policy denial - read-only mode, one of the Mcp* switches turned
off, or a host that lacks the required capability - answers -32006. The
audit log only ever showed CALL_FAIL for those, which lumped them
together with parameter errors, offline hosts and timeouts, so after the
fact there was no way to tell "nobody called this" from "it was blocked
by policy".

The hooks all live in one place: the tools/call exit in the HTTP
handler now also reads error.code and error.message from the response it
already parses, and appends a CALL_DENIED event when the code is -32006.
The original CALL_FAIL line is still written, so its statistics keep
their old meaning, and the reason text is the fixed English sentence
each branch already returns - no tool arguments or user input reach the
log. Tool names taken from the request are flattened to a single line
first, both in the denied event and in the existing CALL_OK/CALL_FAIL
lines, so a crafted name cannot forge extra audit rows.

Also refresh the stale note in the design document that still called the
client search MAX_PATH overflow unfixed; the source was fixed in
8f718d9, but already-deployed clients still carry it, which is why the
smoke test keeps its search cases opt-in.

Verified on the Debug instance: with McpFileTransfer temporarily set to
0, download_file returns -32006 and the audit log gains the expected
CALL_DENIED line right after its CALL_FAIL; with the switch restored the
same call is CALL_OK again and no denied line appears. The read-only
smoke test passes 20/20.

Co-Authored-By: deepseek-flash
2026-10-25 14:28:16 +01:00

38 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),其余都会触达外部主机。

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 个搜索用例)。