# 生成客户端 MCP 工具(build_client)设计 > 2026-11-15。让模型把「生成一个连 1.2.3.4:443 的 Linux 客户端」这类需求直接落成 > 服务端本机上的一个客户端文件。实现在 `server/2015Remote/McpBuildClient.{h,cpp}`。 ## 1. 定位 `build_client` 是**服务端本地工具**,不针对任何在线主机: - 入参没有 `id`,平台门禁(`CheckToolPlatform`)因拿不到主机而直接放行; - `kToolPlatforms` 仍登记为全平台(`win|lnx|mac|apk`),与其它服务端本地工具一致; - 工具只读模板资源、写服务端本机文件,不向任何客户端下发命令。 它复用「生成服务端」对话框(`BuildDlg.cpp::CBuildDlg::OnBnClickedOk`)的字节搬运路径: ``` 读资源(res 目录优先,回退内嵌) → 构造 CONNECT_ADDRESS(地址/端口/类型/启动方式/分组/安装目录/主控 ID/pwdHash) → 模板发布日期校验(模板比主控新则拒绝) → 原地覆盖所有 FLAG_FINDEN 命中处 → 内嵌 TLS 信任锚(在 UPX / 增肥之前) → 落盘 → 可选 UPX / 增肥 ``` 对话框专属的 ShellCode AES / PE→ShellCode / 载荷伪装流程(需要额外的载荷文件与 图片容器)**不在本工具范围内**:传 `compress` 其他值会返回 `-32602` 并提示改用对话框。 ## 2. 开关与错误码 | 条件 | 行为 | |---|---| | `McpBuild=1` 且 `McpReadonly=0` | 工具出现在 `tools/list`,可调用 | | `McpBuild=0` | 不出现;直接调用返回 `-32006` | | `McpReadonly=1` | 工具出现但调用返回 `-32006`(与 `host_set_remark` / `host_set_watch_level` 这类只改服务端本地数据的工具一致:列出、调用时拒绝) | `McpBuild` 默认 `0`,改动需重启服务端生效。之所以不复用 `McpManage` / `McpFileWrite`: 生成的是**带主控凭据、可分发的客户端二进制**,风险等级与「操作在线主机」不同,需要能 单独关掉。工具同时要求只读模式关闭。 参数错误统一 `-32602`;文件已存在且 `overwrite=false`、输出路径是目录返回 `-32012`; 模板缺失 / 模板比主控新 / 找不到 `CONNECT_ADDRESS` / 写盘或 UPX 失败返回 `-32001`。 ## 3. 参数 | 参数 | 必填 | 说明 | |---|---|---| | `target` | 是 | `ghost` / `ghost_service` / `ghost_system` / `testrun_dll` / `testrun_memdll` / `testrun_injsc` / `testrun_service` / `testrun_system` / `serverdll` / `tinyrun` / `linux` / `macos` / `android` | | `arch` | 否 | `x64`(默认)/ `x86`;posix 固定架构,传 `x86` 返回 `-32602`;`testrun_injsc` 只支持 x64 | | `host` | 否 | 主控地址,可含分号分隔的多地址;省略取服务端当前有效主控地址(含上级 FRP) | | `port` | 否 | 省略取服务端当前有效端口 | | `protocol` | 否 | `tcp`(默认)/ `udp` / `http` / `random` / `kcp` / `ws` / `wss` | | `header_enc` | 否 | `hell`(默认)/ `shine` | | `running` | 否 | `random`(默认)/ `parallel` | | `group` | 否 | 分组名,≤23 字节 ANSI | | `install_location` | 否 | `programdata`(默认)/ `programfiles` / `systemroot` / `appdata` / `localappdata` | | `install_dir` / `install_name` | 否 | Windows 安装子目录/程序名,≤31 字节,按 Windows 文件名规则校验 | | `run_as_admin` | 否 | 默认 `false`;安装 Windows 服务时通常需要 | | `encrypt_address` | 否 | 默认 `true`;`testrun_injsc` 与 `tinyrun` 与对话框一致,不加密 | | `compress` | 否 | `none`(默认)/ `upx`;仅 Windows 目标 | | `tls_anchor` | 否 | 默认 `true`;见 §4 | | `padding_mb` | 否 | 0–256,仅 Windows 目标 | | `output_dir` | 否 | 默认主控程序目录;不存在会自动创建 | | `output_name` | 否 | 默认按 target 取 `ghost.exe` / `TestRun.exe` / `ServerDll.dll` / `TinyRun.dll` / `ghost` / `ghost.apk` | | `overwrite` | 否 | 默认 `false`;目标已存在时返回 `-32012`,确认后传 `true` 重试 | 字符串入参按 UTF-8 接收,落到 ANSI 结构体/路径前用 `Utf8ToCpExact` 严格转换; 服务端代码页表示不了的字符直接拒绝,不用 `?` 顶替(否则会写出路径或分组名都不对的 客户端)。 ## 4. 内嵌 TLS 信任锚 只有 `ghost` / `ghost_service` / `ghost_system` / `serverdll` 的 Windows 模板里有 `EmbeddedTlsAnchor` 块(`client/EmbeddedTlsAnchor.cpp`)。工具按以下顺序判定, 结果写入 `tlsAnchor`: | 状态 | 含义 | |---|---| | `disabled` | 入参 `tls_anchor=false` | | `not_applicable` | TestRun / TinyRun:模板不含客户端代码(TestRun 的锚要生成进 ServerDll.dll) | | `unsupported_platform` | Linux / macOS / Android 模板没有锚块,信任锚由主控在线下发 | | `skipped_protocol` | 协议不是 tcp/http(ws/wss 的锚是反代那张证书) | | `unavailable` | 服务端未启用可用 TLS 身份 | | `no_block` | 模板里没有锚块(资源未重编),按普通客户端生成,不视为失败 | | `embedded` | 已写入;`tlsAnchorSummary` 给出证书摘要 | 与对话框一致:`Ambiguous` / `TooLong` / `NoAnchor` 会中止生成(`-32001`), `NoBlock` 只提示;锚必须在 UPX / 增肥之前写入。 ## 5. 其它行为 - **版本校验**:模板 `szBuildDate` 比主控 `DLL_VERSION` 新时拒绝生成。 - **输出覆盖**:默认拒绝覆盖;`overwrite=true` 时才写。输出文件名不允许包含目录分隔符。 - **并发**:模块内用 `std::mutex` 串行化。`ReleaseUPX()` 固定把 `upx.exe` 释放到服务端 目录,两个并发生成会互相踩;串行化同时避免同一输出文件的写竞争。 - **审计**:每次成功/失败写一行 `[MCP] build_client ...` 到服务端日志(路径、目标、字节数)。 - **结果 tips**:KCP 需要主控 UDP 参数为 1、WS/WSS 需要反代、macOS 需 `install.sh`/codesign、 Android 需 apksigner、TestRun 需要 ServerDll.dll、锚未内嵌等。 - **UPX 失败**:返回 `-32001`,未压缩的文件保留在原路径(与对话框一致)。 ## 6. 「生成服务端」对话框的联动改进 同一批改动还修了对话框里几个平台联动问题(`BuildDlg.cpp`): 1. 选 Linux / macOS / Android 时,「安装目录」下拉框(`IDC_COMBO_INSTALL_LOC`)及其 标签(`IDC_STATIC_LOCATION`)现在与安装目录/程序名一起置灰。此前它们不在禁用清单里, 看起来仍可设置,但生成时根本不会被使用。 2. 运行模式(`IDC_COMBO_RUNTYPE`)对非 Windows 客户端无意义(`runningType` 只有 Windows `ClientDll` 消费),一并置灰。 3. 加壳选择切到非 Windows 目标时暂存并显示「无」,切回 Windows 时恢复;避免 「控件置灰但显示 ShellCode AES」与实际生成结果(强制 NONE)不一致。 4. 载荷类型 / 下载服务几行在非 Windows 目标下隐藏,而不是留下置灰的空行。 5. 「随机名称」「以管理员权限运行」两个菜单项在非 Windows 目标下置灰。 6. 内嵌 TLS 锚复选框的文案对 Linux/macOS/Android 改为「仅Windows客户端模板支持」, 不再误报「该目标不含客户端」。 ## 7. 验收记录(2026-11-15,Debug 实例) - `tools/list` 出现 `build_client`(`McpBuild=1`),关闭开关时不出现、直接调用 `-32006`。 - Linux:生成 10,285,456 字节,`tlsAnchor=unsupported_platform`;`encrypt_address=false` 时二进制里能检索到明文 host/port/分组/安装目录,原 `FLAG_FINDEN` 命中数归零。 - ghost x64:`tlsAnchor=embedded`;生成的 PE 被本机 Defender 隔离,属测试环境现象。 - Android:生成 11,929,218 字节,`tlsAnchor=unsupported_platform`,tips 提示重签。 - `arch=x86` + Linux、`testrun_injsc` + x86、未知 target、非字符串 target、显式但解析不出 的 `port`(如 `"443 "`)均返回 `-32602`;同名文件不传 `overwrite` 返回 `-32012`, 传 `true` 后 `overwritten=true`。 - 保护主控自身文件:`output_dir=Bin` + `output_name=Yama_x64d.exe` + `overwrite=true` 返回 `-32012`,不会覆盖运行中的服务端;`settings.ini` / `upx.exe` 同样受保护。 - 省略 `group` 时与对话框一致写入 `default`;`protocol` 允许数字形式(5 → ws)。 - `padding_mb=3` 的 TinyRun 产物比模板大 3 MB(分块追加,不一次性分配 256 MB); `compress=upx` 因 Defender 拒绝读取生成的 PE 而返回 `-32001`(UPX 自身报 `IOException: Invalid argument`),错误路径符合预期;UPX 临时文件按 `upx_mcp__.exe` 释放,测后无残留,也不会与对话框的固定 `upx.exe` 抢文件。 - `mcp/tools.json` 已用 Debug 实例的 `McpMachine=1` / `McpMachine=0` 两份抓取重新生成 (55 个工具),`check_platform_table.py` PASS。