clash-control-mcp

v1.0.0-rc.1

Published

a month ago

Adapter-backed, transaction-safe MCP control for Clash Verge Rev / Mihomo | Adapter 强绑定的安全事务化控制服务

0High
0Medium
0Low

huaqing0

Clash Control MCP

English | 简体中文

面向 Clash Verge Rev / Mihomo 的安全事务化 MCP Server。当前版本：1.0.0-rc.1。

Clash Control MCP 让 Codex、ZCode、Claude Code 等 MCP 客户端读取、诊断并在明确权限边界内管理 Clash Verge Rev。面向普通用户的受支持产品强制包含 Adapter； Core-only 只保留为降级恢复和开发路径，不再作为发行安装选项。项目包含：

Core MCP：环境探测、运行状态、配置审计、Profile/规则链检查、有限运行时操作；
事务与恢复：预览、校验、确认、快照、应用、验证、回滚和重启后恢复；
优化助手：网络、DNS、规则、代理组、健康检查及常见服务的只读证据采集；
必需的 Clash Verge Adapter：为经过验证的 Verge 版本提供受认证的持久化写入；
Adapter 安装、升级、验证、卸载及无签名补丁生命周期工具。

安全边界

Controller secret 只从 MCP 客户端的私有环境配置读取；
Adapter token 保存在当前用户拥有、权限为 0600 的凭据文件中，客户端只保存 CLASH_VERGE_ADAPTER_TOKEN_FILE 路径；
MCP 返回统一经过敏感字段脱敏，Controller/Adapter 若原样回显运行时 secret/token，也会按精确值移除；
不提供用户可控的任意命令、任意文件路径、任意 URL 请求或任意 API 透传；
延迟测试和外部诊断只使用固定或 allowlist 目标；
持久化修改必须经过 capability gate、预览/确认、并发状态检查、验证及补偿回滚；
RECOVERY_REQUIRED 会阻断后续写操作；
官方 Clash Verge 不含 Adapter 时，Adapter 所有写入能力 fail closed，但 Core MCP 的只读能力和受支持的 Mihomo 运行时能力仍可使用。

完整策略见 SECURITY.md。

环境要求

| 组件 | 平台 | Clash Verge Rev | 状态 | |---|---|---|---| | 完整 MCP + Adapter 产品 | macOS Apple Silicon (arm64) | 2.5.1 | 受支持发行路径 | | 无签名补丁 | macOS Apple Silicon (arm64) | 2.5.1 | RC 必需组件，未公证 | | Core-only 降级模式 | 仅开发/恢复 | 2.0.0+ | 不是用户发行安装路径 | | 任意组件 | 任意 | < 2.0.0 | 不支持 |

Node.js 要求：20.19.0 或更高版本。

完整安装（必须安装 Adapter）

v1.0.0-rc.1 面向用户仅支持 macOS Apple Silicon、官方 Clash Verge Rev 2.5.1 和 Node.js 20.19.0 或更高版本。npm 包不再提供 Core-only setup 命令。

安装 MCP 和受控生命周期安装器：

npm install --global clash-control-mcp@next

从 v1.0.0-rc.1 GitHub Release 下载 Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64.zip，或者使用：

gh release download v1.0.0-rc.1 \
  --repo huaqing0/clash-control-mcp \
  --pattern 'Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64.zip'
unzip Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64.zip

Clash Verge 保持运行，先执行零写盘预检：

clash-control-adapter patch-install \
  --patch-package "$PWD/Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64" \
  --dry-run

完全退出 Clash Verge，执行完整安装；随后重启 Clash Verge 和 MCP 客户端并验收：

clash-control-adapter patch-install \
  --patch-package "$PWD/Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64" \
  --clients codex,zcode,trae
clash-control-adapter patch-verify

安装器会探测 Controller、创建可验证备份、写入受管理客户端配置，且不会打印 Controller secret 或 Adapter token。验证完成后调用 clash.capabilities，必须看到通过认证的 Adapter 握手才算完整安装。

主要功能

当前注册 66 个 MCP tools，主要分为：

环境与能力：clash.capabilities、clash.doctor、Verge 探测；
运行时读取：状态、代理组、Provider、连接、Profile；
有限运行时操作：固定目标延迟测试、确认后的代理选择、Provider 刷新、单连接关闭；
配置事务：workspace、预览、校验、apply、rollback、resume、recovery status；
Verge 设置：DNS、TUN、端口、LAN、IPv6、日志级别等 capability-gated 操作；
Profile/规则链：Profile chain、Merge/Override/Rules 检查与受认证写入；
优化诊断：网络、DNS、规则、代理组、健康检查、OpenAI、GitHub、YouTube、 Streaming；
Verge Preferences：Basic、Theme、Layout、Hotkeys 的读取及 Adapter 受控写入。

完整工具列表和每项约束见英文 README。

Clash Verge Adapter

Profile 激活/刷新、持久化 Profile 写入、Verge 内存同步及 Preferences/Hotkeys Adapter 是受支持产品的必需组件，只监听 127.0.0.1:33331，使用每次安装生成的 Bearer token。

源码 checkout 中的统一入口：

npm ci
npm run build
npm exec -- clash-control-adapter --help

支持命令：

install
upgrade
verify
uninstall
patch-install
patch-verify
patch-uninstall

完整安装必须使用显式下载的固定版本 Release 补丁，或单独构建并经过校验的 Adapter .app；npm 安装本身不会静默替换 Clash Verge 客户端。

安装流程

先做零写盘预演：

npm exec -- clash-control-adapter install \
  --dry-run \
  --adapter-build "/absolute/path/to/Clash Verge.app" \
  --clients codex,zcode

退出 Clash Verge 后执行真实安装：

npm exec -- clash-control-adapter install \
  --adapter-build "/absolute/path/to/Clash Verge.app" \
  --clients codex,zcode

未签名本机 QA Build 必须显式增加 --allow-unsigned-qa，不得把该选项作为正式签名发行的替代品。

安装完成后状态为 PENDING_RESTART。重新启动 Clash Verge 和 MCP 客户端，再执行：

npm exec -- clash-control-adapter verify \
  --clients codex,zcode \
  --recover-on-failure

验证器先用错误 token 挑战服务，再检查监听进程属于当前用户且可执行文件来自已检查的 /Applications/Clash Verge.app，随后才发送真实 token，并在 Profile 读取后再次检查监听 PID 未变化。

升级与卸载

升级：

npm exec -- clash-control-adapter upgrade \
  --adapter-build "/absolute/path/to/new/Clash Verge.app" \
  --clients codex,zcode

升级省略 --clients 时沿用已验证安装记录中的客户端集合和精确路径；显式传入时必须与记录完全一致。没有 VERIFIED acceptance lineage 的旧安装不会自动迁移，请先从可信备份恢复官方 App，再按当前流程重新安装。

卸载前预演：

npm exec -- clash-control-adapter uninstall --dry-run

退出 Clash Verge 后卸载：

npm exec -- clash-control-adapter uninstall

卸载器只恢复安装事务记录且 hash 校验通过的官方 App 备份；找不到可信恢复基线时会 fail closed。

完整说明见 ADAPTER-INSTALLATION.md。

无签名补丁

Apple Silicon 用户可使用针对官方 Clash Verge Rev 2.5.1 的固定版本补丁流程。该补丁：

不是完整 Clash Verge 客户端；
使用 Ad-hoc 签名，没有 Apple Developer ID 或公证；
必须从可信项目发布页获取，并核对发布页单独提供的 SHA-256；
版本、架构、Bundle ID 或全内容 hash 不匹配时停止。

安装：

clash-control-adapter patch-install \
  --patch-package "/absolute/path/to/Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64" \
  --dry-run

clash-control-adapter patch-install \
  --patch-package "/absolute/path/to/Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64" \
  --clients codex,zcode,trae

验证和卸载：

clash-control-adapter patch-verify
clash-control-adapter patch-uninstall

详见 ADAPTER-PATCH-INSTALLATION.md。

常见问题

Adapter 写工具为什么返回 `BLOCKED`？

必需的 Adapter 安装缺失、未完成或不再通过认证/版本/capability 检查。只读回退仅用于诊断和恢复，不代表完整安装；不要绕过 capability gate。

`PENDING_RESTART` 怎么处理？

重启 Clash Verge 和所选 MCP 客户端，然后运行 Adapter verify。没有完成验证前，安装事务不能声明为 VERIFIED。

出现 `RECOVERY_REQUIRED` 怎么处理？

停止后续写操作，不要删除 backups/、manifest 或 journal。按 Adapter 故障与恢复检查并恢复。

为什么安装器拒绝已有配置？

安装器不会覆盖未知来源的同名 MCP entry，也不会读取或替换 symlink/hard-link、错误 owner、权限不是 0600 的现有敏感配置。先根据错误修正安全属性，或手工配置独立的 MCP entry。

Adapter token 会写进 MCP 客户端配置吗？

不会。客户端配置只保存 CLASH_VERGE_ADAPTER_TOKEN_FILE；Controller secret 因 stdio MCP 启动模型需要，仍保存在所选客户端的私有环境配置中。

可以在远程 Controller 上使用吗？

可以显式配置 HTTP(S) Controller origin，但 secret 会发送到该 origin。只应使用你信任且已妥善保护的 Controller；默认和最常见配置仍是 loopback。

开发与验证

npm ci
npm run check:format
npm run typecheck
npm run build
npm test -- --no-file-parallelism
npm pack --dry-run --json

真实 Controller smoke test 会生成 gitignored 的 API-SMOKE-TEST.json。该文件可能含机器运行元数据，不得公开发布。

漏洞报告

优先使用 GitHub Private Vulnerability Reporting： https://github.com/huaqing0/clash-control-mcp/security/advisories/new。如果私密通道不可用，只能公开提交“不含漏洞细节”的联系请求。

许可证

MCP Server：MIT。独立 Adapter 源码项目适用其 GPL-3.0 许可证与相应发行义务。