SimpleRemoter/docs/Mcp_Design.md

# 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":"<VERSION_STR>"}
}}
```

#### 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 <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） |

> 与旧版「`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 <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` 参数

---

## 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` 附带可读摘要。