P11 closes the plan's last batch, entirely on the server side: no client change is required for any of it. Long-running tools now expose a cancellation flag that every wait loop checks in 500 ms slices. A cancelled tool returns through the cleanup branch it already had (late first packets still get absorbed, sub connections still get closed, pending entries still get deleted), so there is no second cleanup path to keep in sync, and the host is released within a second. Three sources set the flag: notifications/cancelled (matched on the exact JSON-RPC id, with a fallback to the display form so a request_id copied out of the session list round-trips), mcp_cancel_session (by request_id, host id or session id), and a failed SSE write when the client has gone away. The dispatcher rewrites a cancel-induced failure to -32800 so callers do not mistake it for a host fault. tools/call requests carrying _meta.progressToken are answered as text/event-stream on the same POST: the tool runs on its own thread and both the notifications/progress events and the final JSON-RPC response go out through one chunked provider. Requests without a token are unchanged. download_file reports files done vs. expected, upload_file reports bytes sent vs. total. Two new local-only tools, mcp_list_sessions and mcp_cancel_session, list and cancel in-flight sessions (calls, pending one-shots, terminal, remote control, file transfer, chat). They are deliberately not gated by the feature switches or readonly mode, since that is the only way out of a stuck request. The -32003 busy message now names the occupier: "Device busy: ... (tool=download_file, elapsed=12s)". power_action gains wait/wait_ms to verify the result against the main connection's presence (went_offline, came_back, elapsed_ms); not seeing the transition is reported as ok, not as a failure. kill_process, operate_window and the four host_control_* tools accept dry_run, which validates the target against one fresh snapshot and returns what would be affected without sending anything. Validation rejections now use -32012; -32008 stays as documented historical alias. One implementation note worth recording: the per-thread call context uses FLS, not thread_local. Any static thread_local in this server crashes the process about a second after start, because some threads come from shellcode/MemoryModule images that never ran PE TLS initialisation. Verified against a real Debug server and a real Windows client over MCP: the smoke test now passes 104 checks with 0 failures, including cancellation releasing the host in under a second, the cancelled request returning -32800, notifications/cancelled returning 202, 63 progress events with exact byte counts for a 64 MB upload, and a cleanly terminated SSE stream. Not exercised in this pass: power_action's wait=true path (it would take the test host down) and the -32006 readonly/switch-off section (every switch was on during the run). Co-Authored-By: deepseek-flash
77 KiB
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 是可读摘要 + 同一份结构的紧凑 JSON):
{"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 台主机在线。"},
{"type":"text","text":"{\"hosts\":[{\"id\":\"123\",\"name\":\"DESKTOP-ABC\",...}]}"}
],
"isError":false
}}
第二个文本块来自 §14:规范要求返回 structuredContent 时也把序列化 JSON 放进 TextContent,否则只读 content 的客户端拿不到 id。
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 无关,改动需重启生效 |
McpToolTimeoutMs |
20000 |
工具等待客户端响应的默认超时(ms),clamp 到 [1000, 600000];各工具自己的 timeout_ms 参数优先。ini-only(无设置界面控件),改动需重启生效 |
McpHttps |
0 |
1 = 对外端口说 HTTPS(native TLS,见 §13),httplib 退到 127.0.0.1:McpInternalPort;0 = 保持明文。经「MCP设置」对话框的「启用 HTTPS」复选框设置,改动需重启生效 |
McpCertPath |
空(回退 [tls] CertPath) |
MCP 专用证书(PEM)。面向公网客户端时应为公共 CA 证书(如 Let's Encrypt 的 fullchain.pem),不要复用设备端口的自签证书。对话框「证书路径」行可填/浏览;为空时按回退规则预填 [tls] 的值 |
McpKeyPath |
空(回退 [tls] KeyPath) |
与 McpCertPath 配对的私钥,须为 PKCS#8(-----BEGIN PRIVATE KEY-----)。对话框「私钥路径」行可填/浏览 |
McpInternalPort |
空(取 McpPort+1) |
McpHttps=1 时 httplib 实际监听的回环端口,仅绑定 127.0.0.1。ini-only(对话框不暴露,自动取 McpPort+1) |
对话框里「证书路径/私钥路径」两行仅在勾选「启用 HTTPS」后可编辑;保存时校验两者非空且文件存在(加载失败会导致 MCP 监听 fail-closed,故提前挡住),格式仍以服务端实际加载为准。
与旧版「
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 菜单与资源接线
resource.h:新增命令 ID(取当前空闲段,经查33077空闲):#define ID_MCP_SETTINGS 330772015Remote.rc:在「地理信息(&L)」子菜单END之后、插件设置之前插入:并新增对话框资源MENUITEM "MCP设置(&M)...", ID_MCP_SETTINGSIDD_DIALOG_MCP_SETTINGS(「启用 MCP」复选框 + 端口/绑定地址/token 三个编辑框 + 确定/取消按钮)。UIBranding.h:扩展菜单隐藏开关新增一行(默认0显示):#define HIDE_MENU_MCP_SETTINGS 0 // MCP设置FeatureFlags.h:新增运行时许可位,占用 MenuFlags 保留段[43-63]的首位(紧跟MF_REQUEST_AUTH之后):#define MF_MCP_SETTINGS (1ULL << 43) // HIDE_MENU_MCP_SETTINGS2015RemoteDlg.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 |
| 「启用 HTTPS」复选框 | McpHttps |
未勾选(0) |
勾选后本端口同时接受 TLS(§13);未勾选时下面两行置灰 |
| 证书路径 | McpCertPath |
空(回退 [tls] CertPath) |
PEM;带「浏览」按钮。为空时按回退规则预填 [tls] 的值 |
| 私钥路径 | McpKeyPath |
空(回退 [tls] KeyPath) |
PKCS#8;带「浏览」按钮 |
保存时若勾选了 HTTPS,证书/私钥必须非空且文件存在,否则弹提示并留在对话框(身份加载失败会让 MCP 监听 fail-closed,故提前挡住);HTTPS 改动与其它项一样重启生效。
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. 验收标准
- 在「MCP设置」对话框启用并重启服务端后,
127.0.0.1:6544监听正常,外部地址无法访问;未启用时该端口不监听。 - 无 token 的请求返回 HTTP 401;错误 token 返回 401;正确 token 通过。
curl模拟initialize→tools/list→tools/call全流程,返回符合 JSON-RPC 2.0 与 MCP 规范。- Claude Code 侧:
claude mcp add yama --transport http http://127.0.0.1:6544/mcp -H "Authorization: Bearer <token>"claude mcp list能看到yama,在对话中问「列出在线主机」能正确触发工具并返回列表。 - 现有 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附带可读摘要(2026-10-26 起再追加一份紧凑 JSON,见 §14)。
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仍受服务端ParseFileList的 500 条硬限制(total=500且原目录确有更多条目时表示截断,不是服务端分页)。客户端侧不截断、按需扩缓冲一次性回全量;本轮未加truncated标记(要加得改服务端ParseFileList的调用约定),仍靠「total=500且hasMore」判断。
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:level0–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。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 文件传输) |
不要重试:这是配置决定,需管理员改服务端配置 |
-32007 |
Not in command whitelist | exec_command 的命令不在 McpCmdWhitelist 里,或词边界不匹配(dir 过、dirx 拒) |
不要重试:换成白名单内的命令,或请管理员加白名单项 |
-32012 |
Rejected by validation | 只覆盖「参数被校验拒绝、改参数可修」:exec_command 含 shell 元字符(Windows &|<>^;Linux &|<>; 与反引号、$( ${ !)或控制字符(含 \r\n);terminal_exec 含 &/|/换行;路径/参数含非法字符。-32008 是同一语义的历史别名(早期实现用它,已发布的客户端/文档可能仍在匹配),新代码一律用 -32012 |
按 message 修正参数后重试 |
-32009 |
Target not found | 远端路径/注册表键不存在(win32 2/3,由新客户端主动回报);kill_network_connection 的四元组在当前连接表里查不到(dry_run 传假四元组最常见) |
先用 list_files/list_registry(或 host_list_network_state)确认目标存在 |
-32010 |
Access denied | 目标存在但权限不足(win32 5):非提权客户端的服务枚举(OpenSCManager)、受保护目录(如 System Volume Information)、受保护注册表键(如 HKLM\SAM) |
不要重试:需客户端提权(管理员运行)或换目标 |
-32011 |
Destination write failed | 文件传输的目标端已收到数据但写盘失败:copy_files_c2c / upload_file 的目标主机回了回执且 status != 0(message 带 status、首个 errno、实收文件数) |
不要原样重试:按文案判断(errno 13/1→权限、2→路径不存在、28→磁盘满),先修目标端目录/权限 |
-32800 |
Request cancelled | 客户端取消了这次调用:notifications/cancelled、mcp_cancel_session 或 SSE 流断开(检测到断开会置同一个取消位)。工具在 ≤1s 内退出等待并走既有的超时清理路径,主机占用已释放 |
不是主机故障,可直接重试;终止类命令可能已经执行,重试前先读一次现状 |
-
命令超时会销毁持久会话(
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>)区分开。 -
新客户端把失败改成结构化回报(
TOKEN_SERVICE_ERROR=170/TOKEN_FILE_LIST_ERROR=171/TOKEN_REG_ERROR=172/TOKEN_DOWNLOAD_ERROR=173,布局[token:1][win32 码:4 LE]):list_services(未提权)、list_files/list_registry(路径/键不存在或拒绝访问)、download_file(远端路径全部不存在)都在客户端侧就失败并立即回报,服务端转译成-32009/-32010,亚秒级返回,不再靠超时猜。老客户端不发这些包,成功路径报文一律不变,因此老客户端/老服务端的行为与改造前完全一致(老服务端把未知 token 走default丢弃)。 -
工具放弃后的「迟到首包」一律吸收,不会弹 MFC 窗口:文件/服务/注册表/进程/日志/终端这几族的子连接都是「建成即发首包」。工具超时清理挂起后,客户端可能才把首包发上来,此时没有挂起会话,
MessageHandle只能把它当成人手点击,于是弹出文件管理器/服务管理器/注册表/进程管理器/日志/终端窗口(构造超时场景时实测出现过文件管理器窗口)。现在各等待函数在放弃分支登记「设备 → 该工具的首包 token」(CMcpServer::MarkLateFirstPacketForTool),包到达时TakeToolFirstPacket一次性吸收并关子连接:list_files/download_file/upload_file/search_file→TOKEN_DRIVE_LIST;list_services/control_service→TOKEN_SERVERLIST;list_registry→TOKEN_REGEDIT;list_processes/kill_process→TOKEN_PSLIST;list_windows/operate_window→TOKEN_WSLIST;get_client_log→TOKEN_REPORT_LOG;get_activity_history→TOKEN_REPORT_ACTIVITY(主连接,只丢包不关连接);exec_command/terminal_open→TOKEN_SHELL_START+TOKEN_TERMINAL_START。成功路径不登记,命中即消费,标记 5 分钟后过期。已知代价:同一主机在工具超时后 5 分钟内手动点开对应窗口,可能被这枚标记吞掉一次(再点即可)——比误弹窗口更可接受。 -
MCP 工具在飞时不弹客户端的老式提示框:新客户端在失败分支同时发结构化 token 和老的
ClientMsg(只为兼容老服务端),后者会PostMessageA(WM_SHOWERRORMSG)在服务端 UI 上弹框。TOKEN_CLIENT_MSG分支现在发现该设备有挂起请求/文件传输时就只记日志不弹框。实测list_services(未提权)时客户端子连接已被服务端关掉,ClientMsg根本发不出来,这条属兜底。 -
download_file有停滞看门狗兜底:60 秒没收到任何数据即失败,返回-32001且文案带File transfer stalled: no data received for 60s ...。新客户端的TOKEN_DOWNLOAD_ERROR让这条路基本不再触发,看门狗只用来兜住「客户端卡住/老客户端」。 -
-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;全部开启时跳过)、-32009(新客户端的list_files/list_registry/download_file不存在路径负例)。其余码由各批次的功能验证覆盖(-32001/-32003等需要构造竞态或超时,不进冒烟)。 -
本次验证(Debug 实例):冒烟 40/40 通过(原 37 项 + 3 条
-32009负例);-32010由list_services(未提权客户端,win32=5)、list_files "C:\System Volume Information"、list_registry "HKLM\SAM\SAM\Domains\Account"三条实测覆盖。
12.1 命令哨兵与输出清洗(测试报告 P1/P3/P4 的修复)
exec_command 与 terminal_exec 都靠哨兵判断「命令已执行完、退出码是多少」。哨兵有三种形态:
| 客户端 | 下发内容 | 退出码 |
|---|---|---|
POSIX PTY(Linux,RES_CLIENT_TYPE=LNX) |
第一行 PS1=;第二行 <cmd>;第三行 echo __MCP_DONE_<nonce>__$? |
命令的真实退出码 |
ConPTY(is_pty=true,新版 Windows 客户端) |
第一行 @echo off & <cmd>;第二行单独 echo __MCP_DONE_<nonce>__%errorlevel% |
命令的真实退出码 |
老 ShellManager 管道(is_pty=false) |
单行 ` 2>&1 && echo _MCP_DONE__0 |
POSIX 形态与 Windows 的差别:
- 不能用
@echo off & <cmd>/%errorlevel%:Linux 的bash -i把它们当字面量,哨兵永远不会出现,必然超时。 - 先发一行
PS1=:交互式 bash 每读一行都打印提示符(user@host:cwd$),提示符会混进 stdout(Windows ConPTY 不会)。清空PS1后提示符消失。这一行的回显排在下发的命令行回显之前,会被「从缓冲区开头删到命令行回显结束」那一步一并切掉,不进入返回文本。 $?是上一行的退出码:PS1=与命令各占一行,哨兵只取命令那一行的状态,未被PS1=干扰。
为什么 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 的统计块会贴在最后一条回复后面),不影响语义。
13. 增补(2026-10-26:MCP HTTPS / native TLS)
13.1 目标与取舍
公网 MCP 客户端(Claude Desktop、WorkBuddy 等)多数只接受 https:// 端点,而 MCP 一直是明文 httplib。三条路里选了第三条:
| 方案 | 结论 |
|---|---|
| 在 vps 上用 nginx 反代加 TLS | 不行:vps 的 80/443/6544 都由 frps 持有,nginx 只在 8080,且反代会让 token 以明文经过 vps |
引入 OpenSSL / cpp-httplib 的 CPPHTTPLIB_OPENSSL_SUPPORT |
新增第三方依赖与证书/私钥加载路径,仓库已有 Schannel 实现 |
| 复用仓库既有的 Schannel 入站实现,在 MCP 端口上终结 TLS | ✅ 零新依赖,ServerTlsSession/ServerTlsIdentity 已在设备端口跑通 |
13.2 结构:同端口嗅探 + 明文直通
客户端 ──TLS──▶ [McpTlsProxy] :McpPort ──明文──▶ httplib 127.0.0.1:McpInternalPort
客户端 ──明文─▶ │ 0x16 0x03 ? (只绑回环,不对外)
McpTlsProxy(McpTlsProxy.h/.cpp)在McpBind:McpPort上监听,首包用MSG_PEEK判 TLS(首字节0x16且次字节0x03,与设备端口 §5.2 同一套路):TLS 走ServerTlsSession::HandshakeWithCred+Decrypt/Encrypt,否则按字节原样转发。- 因此同一端口两种用法并存:本机既有的
http://127.0.0.1:6544/mcp不用改,远端可以用https://host:6544/mcp。 McpHttps=0时完全不启动前端,行为与改造前一致(httplib 直接监听McpBind:McpPort)。
13.3 身份:第二份证书,独立 CNG 键名
ServerTlsLoadIdentityFromPem(cert, key, L"YamaMcpTlsKey", id) 构造进程内第二份入站身份,与设备端口的 ServerTlsIdentity(YamaServerTlsKey、通常自签 CN=localhost)并存:证书/私钥各读各的,持久化私钥用不同键名,互不覆盖。HandshakeWithCred 是新增的重载,设备端口仍用 Handshake(同一份逻辑,只是取凭据的方式不同)。
fail-closed:证书/私钥读不出来、CNG 导入失败、端口被占任一项失败,McpServer::Start 会把 httplib 一起停掉并返回 false——绝不允许「以为在跑 HTTPS、其实没在监听」。
13.4 实测(Debug 实例,自签证书)
| 场景 | 结果 |
|---|---|
https://127.0.0.1:6545/mcp(--cacert server.crt)无 token |
401,证书校验通过 |
同一端口 http://127.0.0.1:6545/mcp 无 token |
401(明文直通未受影响) |
TLS + token:initialize / tools/list / tools/call get_server_status |
正常,53 个工具 |
| 同一条 TLS 连接上连发两个请求(keep-alive) | 两次都 200,复用连接 |
| 错误 token | 401(回环来源的鉴权封禁豁免仍生效) |
内部端口 6546 |
只监听 127.0.0.1 |
McpCertPath 指向不存在的文件后重启 |
MCP 整体不启动,无任何监听(fail-closed) |
| 公共 CA 的 ECDSA 证书(Let's Encrypt P-256 fullchain + PKCS#8 私钥) | 身份加载成功,TLS 无 token 401、带 token initialize/tools/list 正常(53 工具) |
| 本地 CA 三级链(叶 + 中间,中间证书不在系统库) | 服务端下发 2 张证书,openssl s_client -CAfile root.crt 得 Verify return code: 0 |
设备端口 6543 TLS(回归) |
握手正常 |
McpHttps 删除后重启(回归) |
明文明监听,无内部端口 |
13.5 Schannel 的一个坑(已修在共用层)
ServerTlsSession 原先把「首次收到的字节」直接喂给 AcceptSecurityContext。如果这批字节只是半条 ClientHello,Schannel 会先建出一个坏上下文,补齐后再送返回 SEC_E_UNKNOWN_CREDENTIALS (0x80090301),握手必失败。设备端口因为累积了整包才分类、且客户端 ClientHello 通常一次到齐,一直没暴露;MCP 前端按 8 字节嗅探后接手,稳定触发。
现在 HandshakeWithCred 在首次 ASC 之前先凑齐一整条 TLS 记录(5 字节头 + 负载,上限 18432 字节,首字节非 0x16 或缺字节超时则 fail-closed),调用方给多少字节都行。这也顺带修好了设备端口在「ClientHello 被 TCP 分片」时的同类隐患。
13.6 部署公网证书
- 把公共 CA 签发的证书链与私钥(PKCS#8)放到本机,例如
Bin\certs\mcp-fullchain.pem/Bin\certs\mcp-key.pem。证书支持 RSA 与 ECDSA(P-256/P-384/P-521),可以写成「叶证书 + 中间证书」的 fullchain(见 13.8)。 - 「扩展 → MCP设置」勾选「启用 HTTPS」,在两行里填/浏览证书与私钥(也可直接改 ini:
McpHttps=1、McpCertPath=<证书>、McpKeyPath=<私钥>),保存后重启 YAMA。注意「端口」填的是对外端口,httplib 自动退到127.0.0.1:McpPort+1。 - frp 的
YAMA-MCP-*映射指向本机McpPort不变——TLS 在 YAMA 内终结,vps 只转发密文。 - 证书续期后需重新拷贝 + 重启 YAMA(当前不做热加载)。
客户端配置形如:
{
"mcpServers": {
"yama": {
"type": "http",
"url": "https://web.just-do-it.icu:6544/mcp",
"headers": { "Authorization": "Bearer <McpToken>" }
}
}
}
13.7 已知限制
- 按 IP 的鉴权封禁对远端不生效:
IsAuthBlocked按来源 IP 计数,而经 frp 或本前端转发的请求来源都是127.0.0.1,命中既有的「代理来源豁免」。因此远端的暴力尝试不受「10 次失败 / 60 秒 → 封 15 分钟」约束,真正的防线是 token 熵(32 hex ≈ 128 bit)与审计日志里的AUTH_FAIL记录。经 frp 暴露时改造前就已如此;但若改造前是把McpPort直接绑在公网地址(不经 frp),远端 IP 原本会被封禁,开启本前端后一律变成环回、不再封禁——按部署方式评估这一差异。要补需在本前端把真实来源 IP 以受信头注入 httplib 请求,属于后续工作。 - 证书不热加载:换/续证书需重启 YAMA。
- 只支持 HTTP/1.1(与 httplib 一致),不做 ALPN h2。
13.8 证书类型与证书链(2026-10-26 补齐)
早期实现只认 RSA:私钥一律按 BCRYPT_RSAFULLPRIVATE_BLOB 导出后再写入持久化键,遇到 ECDSA 证书(Let's Encrypt 自 2024 年起默认签发 P-256)会在导出处拿 NTE_BAD_TYPE (0x8009000a) 并报错退出。现在按证书公钥类型分两路落盘(ServerTlsSession.cpp 的 BuildIdentity):
| 证书公钥 | 落盘方式 |
|---|---|
| RSA | 导入 PKCS#8 为临时键 → 导出 BCRYPT_RSAFULLPRIVATE_BLOB → NCryptCreatePersistedKey + NCryptSetProperty + NCryptFinalizeKey |
| ECDSA(P-256/P-384/P-521) | 导入 PKCS#8 时在参数表里给出键名(NCRYPTBUFFER_PKCS_KEY_NAME),MS Software KSP 直接持久化 |
ECDSA 这条是 MS Software KSP 唯一可行的一条,其余几条均已实测不通:NCryptCreatePersistedKey 后写 EC 私钥 BLOB,SetProperty 返回 0 但 Finalize 给 NTE_INVALID_PARAMETER (0x80090027);导入后再 NCryptSetProperty(NCRYPT_NAME_PROPERTY) 给 NTE_NOT_SUPPORTED (0x80090029)(不带键名即匿名临时键,Schannel 用不上);把临时键句柄经 CERT_KEY_CONTEXT_PROP_ID 挂到证书上,Schannel 报 SEC_E_NO_CREDENTIALS (0x8009030e)。NCRYPTBUFFER_PKCS_KEY_NAME 的值必须含结尾 NUL,少了同样报 0x80090027。曲线只支持具名 P-256/P-384/P-521,显式参数形式的曲线会带明确报错退出。
证书链:Schannel 的握手在进程外完成,建链时只查系统证书库——fullchain 里的中间证书塞进叶证书自带的内存库或 paCred 数组都不会被下发(实测只发叶证书,缺中间证书的客户端建链失败)。因此加载身份时把 fullchain 第 2 张起的证书补进「当前用户\中间证书颁发机构」库(Cert:\CurrentUser\CA,已在库中则跳过;.NET 的 SslStreamCertificateContext 也是这么做的),Schannel 建好链后随握手下发。证书文件因此可以、也建议写成「叶证书 + 中间证书」的 fullchain(Let's Encrypt 的 fullchain.pem 即如此)。副作用:进程所在账户的 CA 库里会多出这些中间证书(公开信息,留在库里无害)。
14. 增补(2026-10-26:结果外露 —— content 同时携带结构化 JSON)
14.1 问题
改造前,列表/查询类工具的 content 只有一句可读摘要(“共 1 台主机匹配。”),真正的载荷(hosts[]、processes[]、files[]、session_id……)只在 structuredContent 里。MCP 规范(Tools → Structured Content)明确建议:返回 structuredContent 的工具应同时把序列化后的 JSON 放进一个 TextContent 块,正是为了这种只把 content 交给模型的客户端。实测 WorkBuddy 就属这类:它把 search_hosts 的结果格式化成“共 1 台主机匹配”交给模型,id 完全不可见,于是后续 get_host_detail / exec_command / 终端 / 远程控制全部无从下手(用户侧表现为模型去猜 1–3100 的 id,而主机 id 是 64 位雪花值,如 986530101822679521,猜测不可能命中)。
14.2 实现
-
McpInternal::BuildResult统一收口:结果里structuredContent为非空对象/数组时,追加一个{type:"text", text:"<紧凑JSON>"}块到content末尾。所有工具(含McpMachine.cpp/McpChat.cpp的BuildStructuredResult漏斗)自动生效,新增工具无需额外处理;空{}(remote_mouse这类动作结果)不追加。 -
正文已经承载同一份载荷的工具用
SetStructuredTextPayload(result, payload)只外露差异部分,避免同一内容在上下文里出现两三次:工具 外露的文本块 exec_command/terminal_exec{"exit_code":N}(stdout 已在正文里)get_keylogid/duration_ms/bytes/lineCount/truncated(行内容已在正文里,最多 16 KB)get_activity_history{"records":[…]}(activityHistory与records是同一份数据的两种形态)host_get_hosts_filelines+ 元数据(不再重复content原文) -
控制键以
$structuredTextPayload成员的形式挂在 result 上,BuildResult消费后立即removeMember,不会出现在响应里。 -
列表类工具本就有
limit/offset分页,补出来的 JSON 与structuredContent同量级,不会失控。
14.3 验证
Debug 实例(Bin\Yama_x64d.exe,临时端口)实测:list_all_hosts 的 content[1] 含完整主机 JSON(id / ip / last_seen …),get_server_status 的 content[1] 是 {"status":{…}},search_hosts 空结果时是 {"hasMore":false,"hosts":[],…};content[0] 的既有摘要文案一字未改。
14.4 影响面
- 响应体积:列表类工具约翻倍(分页上限内),执行类工具只多一个退出码字段。
- 既有断言不受影响:摘要仍在
content[0],内部批量工具(ids批量调用)仍只读content[0].text并另取structuredContent。
15. 增补(2026-10-26:copy_files_c2c 客户端间直传)
第 54 个工具:把文件从一台客户端直接发到另一台,服务端只做包中继,不落盘。复用 V2 文件传输的 C2C 通道(FileChunkPacketV2.dstClientID != 0),新增协议号 COMMAND_C2C_SEND_FILES=174(服务端给源端下路径清单)、TOKEN_C2C_SEND_RESULT=175(源端回传发送结果),以及能力位 CLIENT_CAP_C2C_PATHS=0x0008(老客户端因此被提前拒绝并提示升级)。
- 工具契约:
src_id/dst_id/paths[]/dst_dir/ 可选timeout_ms;返回transfer_id/file_count/total_bytes/receiver_ack。 - 开关:
McpFileTransfer=1 && McpReadonly=0(会写远程),注解登记为破坏性 + 非只读,McpInternal的 gating 表同步。 - 源端必须是 Windows 客户端(
-32005);目标端可以是 Windows / Linux / macOS(2026-10-27 起)。POSIX 目标给绝对 POSIXdst_dir(/tmp/recv),服务端在建会话前校验形态,非法-32602。 receiver_ack:Linux 目标端落盘后会回一包TOKEN_C2C_RECV_RESULT=176(能力位CLIENT_CAP_C2C_RECV_ACK=0x0010),true表示目标端确认写入、total_bytes是实收值;写入失败统一-32011(带 status/errno)。Windows/macOS 目标端不回执,仍为false,需list_files复核。- 实施中一个坑:服务端既有的 C2C 中继分支会在源端子连接上挂进度对话框,而
NotifyProc对挂了hDlg的连接会把后续包交给对话框——源端最后那包结果就被当 V1 文件块吃掉,工具只能超时。现按「该 host 是否有 MCP 的 C2C 会话」跳过对话框,MFC 手动 C2C 不变。 - 协议细节、落盘路径语义(
dst_dir+ 相对公共父目录,Windows 与 POSIX 两种目标端)、回执与错误码映射(含-32011)、限制与实测见 Mcp_FileTransfer_Design.md §14。
16. 增补(2026-10-27:download_file / upload_file 支持 Linux/macOS 主机)
此前两个工具把 LNX/MAC 目标端直接拒掉(-32005)。现在放开,改动集中在服务端的路径门禁与 POSIX 接收端:
upload_file不需要客户端新指令:Linux/macOS 的文件接收走common/FileTransferV2.h,dstClientID != 0的包按 C2C 语义落盘,目录由包里的 name 派生。服务端按RES_CLIENT_TYPE校验remote_dir:POSIX 目标必须是绝对/…、不含\、不含..段(-32602);Windows 目标行为不变。download_file:POSIX 文件管理器(common/FileManager.h)补齐两块——每个文件末尾发FileCompletePacketV2(流式 SHA-256,新增common/sha256_posix.h;读失败/截断不发,不谎报校验通过),以及下载失败时回TOKEN_DOWNLOAD_ERROR(errno→win32,服务端转成-32009/-32010,不用等停滞看门狗)。upload_file的receiver_ack:Linux 目标端会回TOKEN_C2C_RECV_RESULT=176,服务端在发送完成后等 ≤5 s,true表示已确认写入;回执报错-32011;声明会回执却不回(且传输含字节)-32001。Windows/macOS 目标端仍恒为false。- 空文件:worker 对 0 字节文件只发完成包(无路径字段),POSIX 接收端无从建文件。服务端只对 POSIX 目标补一个长度 0 的末块,接收端据此建空文件;Windows 目标的空文件仍不落地(V2 协议既有边界,未改)。
- 顺带修掉一个下载完成判定的边界:条目顺序由客户端决定,目录可能排在文件之后(如空子目录),
OnFileChunkV2改为按filesDone + directoryCount >= totalFiles判完成,不再出现「文件全部收完还干等超时」。 - 协议细节、POSIX 路径规则、错误码新语义与实测(含 3 MB 二进制、中文名、空文件、空目录的 SHA-256 往返)见 Mcp_FileTransfer_Design.md §15。
17. 增补(2026-10-27:档 1 工具支持 Linux 客户端)
Linux 客户端(LNX)早已实现下面这些工具的线上协议,只是服务端按客户端类型一律拒绝。本次只放开服务端的判定,不改 Linux 客户端、不加能力位:
| 工具 | 线上协议(已存在) | 服务端改动 |
|---|---|---|
kill_process |
主连接 COMMAND_SYSTEM → 子连接 TOKEN_PSLIST → COMMAND_KILLPROCESS + PID 数组 → 刷新列表(linux/SystemManager.h,kill(SIGKILL),忽略 pid<=1) |
只拒绝 MAC/APK |
exec_command |
COMMAND_SHELL → TOKEN_TERMINAL_START → PTY(common/PTYHandler.h,bash -i) |
只拒绝 MAC;POSIX 白名单 / 元字符集 / 哨兵(§12.1) |
terminal_open / terminal_exec / terminal_close |
同上,CMD_TERMINAL_RESIZE + COMMAND_NEXT 启动读线程 |
只拒绝 MAC;posix 透传到哨兵与编码(UTF-8) |
remote_open / remote_close / remote_mouse / remote_keyboard / remote_clipboard |
COMMAND_SCREEN_SPY → TOKEN_BITMAPINFO → COMMAND_SCREEN_CONTROL + MSG64_LNX(linux/ScreenHandler.h,XTest 注入);剪贴板 COMMAND_SCREEN_SET_CLIPBOARD |
只拒绝 MAC;输入事件改为一条一包(见下) |
要点:
- POSIX 默认白名单是独立的一份(
kDefaultCmdWhitelistPosix):同名的 POSIX 命令语义与 Windows 不同(find能-exec、hostname能改名、sort -o能写文件),因此只收「参数也基本只读」的命令。env刻意不收——env <程序>等于执行任意命令,会让白名单形同虚设。管理员显式配置McpCmdWhitelist时两种平台共用配置(配置者自负其责)。 - 元字符集按平台分开:Linux 拒绝
& | < > ;与反引号、$(${!(!在交互式 bash 里触发历史展开);^在 POSIX 里不是元字符,因此grep -v ^# /etc/hosts这类只读命令在 Linux 上可用,Windows 上仍按原规则拒绝。 - 输入事件一条一包:协议允许
[COMMAND_SCREEN_CONTROL][MSG64*N]批量,Windows 客户端(CScreenManager::ProcessCommand)也支持批量;但linux/ScreenHandler.h只处理包内第一条,批量会让key_press只按下不抬起(X11 自动重复)、click只按下、type只打首字符。服务端因此按消息拆包(SendScreenCtrlEvents),对 Windows 完全等价(它本来就一条一条处理),新老 Linux 客户端也都不用升级。 remote_keyboard的type仍是 ASCII-only:Linux 侧VKtoKeySym把 VK 映射为 keysym 后走 XTest,IME 组合输入做不到;非 ASCII 走remote_clipboard+Ctrl+V(Linux 客户端把服务端下发的 GBK 转回 UTF-8 再调xclip/xsel,需要 X11 桌面)。- 限制:纯 Wayland 会话无法抓屏/注入(要 X11 或 XWayland);多显示器仍按 §7.2 拒绝(Linux 客户端心跳里
RES_RESOLUTION依赖xrandr,没有xrandr的系统上报0:0*0,按「无法判定」放行);remote_*需要安装libX11+libXtst,剪贴板需要xclip/xsel。 - 验收(Debug 实例 + WSL Ubuntu 24.04 客户端,WSLg
DISPLAY=:0):exec_command真实退出码(ls不存在路径 → 2)、-32007/-32008负例、grep -v ^#放行、输出无提示符噪声;持久终端cd/环境变量保持、false→ 1、;串联取末条、close幂等;kill_process杀死自己起的sleep且remaining为空、pid 1被跳过;remote_open返回 3840x1140、remote_mouse归一化 (0.5,0.5) 落在 (1920,570)、xev观测到按键/按钮成对、剪贴板中文往返 UTF-8 一致。Windows 客户端同批工具回归无变化。