# 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`（握手） 请求： ```json {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"claude","version":"..."}}} ``` 响应： ```json {"jsonrpc":"2.0","id":1,"result":{ "protocolVersion":"2025-06-18", "capabilities":{"tools":{}}, "serverInfo":{"name":"yama","version":""} }} ``` #### 3.3.2 `tools/list` 请求：`{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}` 响应： ```json {"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"} } } } }, "required":["hosts"] } }]}} ``` #### 3.3.3 `tools/call` 请求： ```json {"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 台主机在线。"}], "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 | 示例（方法未实现）： ```json {"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：抽公共函数**。 ```cpp // 公共函数：提取单台在线主机的完整数据（含 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`（当前活动窗口，即被控端正在做什么） 输出结构 `{"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 ` 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） | > 与旧版「`McpPort=0` 即禁用」不同：启用与否改由独立的 `McpEnabled` 开关控制，`McpPort` 回归纯端口语义，二者解耦。 ### 3.7 生命周期接入 在 `2015RemoteDlg.cpp` Web 服务启动块（约 `2048-2081`）之后，新增 MCP 启动逻辑。`McpServer` 与 `CWebService` 同为单例：提供 `static McpServer& Instance()` 与全局 `inline McpServer& McpServer()` 访问器（仿 `WebService()`，见 `WebService.h` 末尾的全局访问器写法）。 ```cpp 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` 空闲）： ```cpp #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` 显示）： ```cpp #define HIDE_MENU_MCP_SETTINGS 0 // MCP设置 ``` 4. **`FeatureFlags.h`**：新增运行时许可位，占用 MenuFlags 保留段 `[43-63]` 的首位（紧跟 `MF_REQUEST_AUTH` 之后）： ```cpp #define MF_MCP_SETTINGS (1ULL << 43) // HIDE_MENU_MCP_SETTINGS ``` 5. **`2015RemoteDlg.cpp`**：`#include "McpSettingsDlg.h"`，然后消息映射 + 处理器 + 剪枝： ```cpp ON_COMMAND(ID_MCP_SETTINGS, &CMy2015RemoteDlg::OnMcpSettings) // ... void CMy2015RemoteDlg::OnMcpSettings() { CMcpSettingsDlg dlg(this); dlg.DoModal(); } ``` 并在扩展菜单剪枝块（`pExtMenu`，约 `2015RemoteDlg.cpp:1225` 之后）追加： ```cpp 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）。保存时落盘并弹重启提醒： ```cpp 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 侧： ```bash claude mcp add yama --transport http http://127.0.0.1:6544/mcp -H "Authorization: Bearer " ``` `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` 参数 --- ## 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` 附带可读摘要。