Feature(Go): verify_tools --subset and MCP deployment docs

Add a third mode to verify_tools.py that validates the Go server end to
end: it fetches /mcp tools/list and requires the name set to equal the
nine implemented tools exactly (seven in readonly mode), compares
description / inputSchema / outputSchema field by field against
mcp/tools.json, and also checks the published order. Unlike --live,
extra or missing tools are failures, not notes.

The field-comparison loop is factored into report_field_diffs so
--offline / --live and --subset share one comparison, diff printer and
FIELDS tuple.

Document and deploy the endpoint: the systemd env example gains
YAMA_MCP_TOKEN / READONLY / TERM_IDLE / MAX_CONCURRENCY / READ_MAX,
the design doc moves to implemented and its section 10 now matches the
code (embedded tools_minimal.json, the three packet dispatch groups).
The tools README explains gen_go_tools.py --check and --subset.

Verified against a freshly built debug Go server on 16543/18090:
read-write mode passes with 9 tools, YAMA_MCP_READONLY=1 passes with 7,
and both mismatch directions (extra tools, missing tools) fail with
exit 1. gen_go_tools.py --check stays clean; no Go code changed.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-12 23:09:33 +01:00
1 parent 9ce1a58bc3
commit d4f10db1f2
4 files changed
+192 -39

No files matched your search

+29 -16
View File
@@ -1,6 +1,8 @@
# Go 服务端 MCP 最小工具集设计
> 版本:v1.0(定稿) 状态:**已自审(22 项问题全部修入正文),可施工** 日期:2026-11-12
> 版本:v1.0(定稿) 状态:**已实施(M0–M8 全部落地,2026-11-12)** 日期:2026-11-12
>
> 实施计划与各里程碑验收口径见 `Mcp_Go_Minimal_Implementation_Plan.md`。
>
> 前置文档:`Mcp_Tool_Optimization_Plan.md`(MFC 侧工具优化,已全部落地)、
> `Mcp_FileTransfer_Design.md`(V2 文件传输协议与无头接收端)、
@@ -424,10 +426,12 @@ MCP: 读临时文件 → 返回 → 删临时目录
- **路径校验是硬性安全要求**:`filename` 由客户端提供,必须校验它落在 `targetDir` 之内
(**用 `filepath.Rel` 判越界,不能用字符串前缀比较**,见 §8.3),否则拒收并中止传输。
没有这一步,被控端可以把任意文件写到主控磁盘任意位置。
- **没有可用的能力门**。`CLIENT_CAP_V2` 在 `common/commands.h:1289` 的
`DefaultCaps()` 里被**所有平台无条件声明**,拿它做门等于没门。MFC 侧的 V2 是
**服务端开关**(`2015RemoteDlg.cpp:2822` 的 `EnableFileV2`,默认关),不是客户端能力。
Go 侧不设这个开关,恒用 V2。
- **能力检查只作诊断兜底**。`CLIENT_CAP_V2` 在 `common/commands.h:1289` 的
`DefaultCaps()` 里被**所有现代客户端无条件声明**,拿它做真门等于没门。Go 侧保留
`SupportsCap(…, CLIENT_CAP_V2)` 检查的唯一作用,是让"能力串为空"的极老客户端直接
得到 `-32005`,而不是等到 94 号命令静默超时(见下一条)。MFC 侧的 V2 是**服务端
开关**(`2015RemoteDlg.cpp:2822` 的 `EnableFileV2`,默认关),不是客户端能力;
Go 侧不搬这个开关,恒用 V2。
- 真正的失败模式是**老客户端不认识 94 号命令**:它收到 `CMD_DOWN_FILES_V2` 后
不建子连接、不回任何包,表现为 `-32001` 超时。工具描述里要写明这条,
避免模型反复重试。
@@ -686,12 +690,16 @@ if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSepara
```
server/go/mcp/
server.go # /mcp handler、JSON-RPC 分发、鉴权、tools/list
tools.go # 9 个工具的定义表(name/description/inputSchema)
tools.go # //go:embed tools_minimal.json;只读过滤、工具表
tools_minimal.json # gen_go_tools.py 从 mcp/tools.json 抽取的 9 个工具(勿手改)
tools_local.go # list_hosts / get_host_detail / get_server_status / get_audit_log
tools_term.go # terminal_exec / terminal_close
errors.go # 错误码 + JSON-RPC 错误映射
audit.go # mcp.tool.call 审计
lock.go # 设备锁 + 全局信号量
session.go # 终端会话表、空闲回收
term.go # 哨兵、环形缓冲、输出清洗
term.go # 哨兵、环形缓冲
clean.go # 终端输出清洗(逐字节移植 MFC 的 CleanTerminalOutput)
screen.go # 主连接预览 RPC
filemgr.go # 文件管理器子连接(list_files)
filev2.go # V2 流式接收端(read_file)
@@ -710,16 +718,21 @@ cmd/main.go ──▶ web ──▶ mcp ──▶ hub ──▶ connection / pro
`web.New(...).WithMCP(mcpSrv)`(沿用 `WithDeviceHistory` / `WithConfig` 的链式风格,
`web/server.go:94`),以及 `MyHandler.mcp = mcpSrv`(TCP 分派侧)。
这样 `web` 和 `cmd` 都只依赖 `mcp`,不存在 `mcp → web` 的反向依赖。
- TCP 侧的分派(`cmd/main.go` 的 `OnReceive`)新增六个 case:
`TokenScreenPreviewRsp(248)` / `TokenDriveList(103)` / `TokenFileList(104)` /
`TokenFileListError(171)` / `CommandSendFileV2(85)` / `CommandFileCompleteV2(91)`,
统一转给 `mcp.Server.OnPacket(ctx, data)`,未命中在途请求就丢弃。
- TCP 侧的分派(`cmd/main.go` 的 `OnReceive`)按到达的连接分成三组,未命中在途请求就丢弃:
- `mcp.Server.OnPacket`:`TokenScreenPreviewRsp(248)`(主连接上的截图 RPC 回包)
- `mcp.Server.OnFilePacket`:`TokenDriveList(103)` / `TokenFileList(104)` /
`TokenFileListError(171)`(文件管理器子连接)
- `mcp.Server.OnTransferPacket`:`CommandSendFileV2(85)` / `CommandFileCompleteV2(91)`
(独立数据子连接或 POSIX 的文件管理器子连接)与 `TokenDownloadError(173)`
**为什么工具定义手写在 Go 里、不 embed `mcp/tools.json`**:9 个工具的 schema 手写约
300 行,而 embed 需要跨语言目录同步(`mcp/tools.json` 在仓库根,`//go:embed` 不能
引用父目录),要么加 Makefile 同步步骤、要么提交一份副本。手写 + 校验脚本更简单。
防漂移靠 `tools/mcp_tools/verify_tools.py` 增加 `--subset` 模式:把 Go 的
`tools/list` 抓下来,与 `mcp/tools.json` 里同名的工具逐字段比对,多一个少一个都报错。
**为什么 embed 一份生成的 `tools_minimal.json`、而不是手写或直接引用 `mcp/tools.json`**:
`mcp/tools.json` 在仓库根,`//go:embed` 不能引用父目录;手写 9 个 schema 又无法证明
与 MFC 的 JSON 一致。所以由 `tools/mcp_tools/gen_go_tools.py` 从 `mcp/tools.json` 原样
抽取(保持顺序,只留 name/description/inputSchema/outputSchema)生成 go 包内的副本并
嵌入二进制——改工具定义必须改 `mcp/tools.json` 再重新生成,不存在两份手写文字漂移的余地。
两道防漂移检查:`gen_go_tools.py --check`(生成副本是否为最新)与
`verify_tools.py --subset`(线上 `tools/list` 是否与 `mcp/tools.json` 同名工具逐字段
一致、名字集合是否恰好 9 个/只读 7 个)。
---