get_audit_log used to hand back every entry in the main window's message mirror on each call. The mirror is a 1000-entry ring buffer, so a busy server returned a lot of text the caller never looked at, and there was no way to ask for just the MCP entries or just the ones mentioning a particular subject. The tool now takes the same limit/offset pair as the other list tools and two optional substring filters: type matches the type column and keyword matches the message text, both case-insensitive. Filtering runs before paging, so total counts the matches while totalAll keeps the size of the whole mirror, and the summary line adds the pre-filter count when a filter is in use so a typo is easy to spot. The GBK to UTF-8 conversion moved into the filter loop so the comparison happens between strings in the same encoding, still under the dialog's critical section. The output schema gains total/totalAll/offset/limit/hasMore, and the smoke test now asserts the paging fields, the limit bound and an empty result for a filter that cannot match, bringing it to 23 checks. Verified on the Debug instance: limit=2 returns entries 1-2 then 3-4 with hasMore set, offset=999 reports the out-of-range text, type=mcp matches the "MCP命令执行" entry, type=提示 matches both hint types and keyword=监听 matches the listening-port line. Co-Authored-By: deepseek-flash
39 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 附带可读摘要):
{"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 菜单与资源接线
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 |
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附带可读摘要。
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: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 项断言)。