# clash-verge-mcp-pro

全面接管 Clash Verge Rev / Mihomo 的 MCP 服务器(二开自 [mcp-server-clash-verge](https://github.com/IS5416/mcp-server-clash-verge))。

## 相比原版的改进

| 问题 | 原版 | 本项目 |
|---|---|---|
| 传输方式 | 仅 TCP HTTP(Clash Verge 默认不开,直接连不上) | 自动适配 **Unix Socket / Named Pipe / TCP** |
| SDK 兼容 | 旧低阶 API,新版 mcp SDK 下无法启动 | 基于 mcp SDK 2.x `MCPServer` |
| 规则修改 | 只读 | **增/删/屏蔽规则,持久化 + 热重载** |
| 配置生成 | 无 | **完整复刻 Clash Verge enhance 链**(SeqMap 卡片 → 模板合并 → 内置守卫 → TUN → DNS → 全局/订阅级 Merge+Script → 权威字段恢复 → 无效引用清理) |
| JS 脚本 | 不支持 | 内置 **quickjs** 引擎执行 Script 卡片 |
| 工具数量 | 7 | 58 |

## 架构

```
┌─ 运行时层 mihomo_* ──→ Mihomo 外部控制器(unix socket / TCP 自动检测)
│   节点切换 / 模式 / 连接管理 / providers / DNS 查询 / 缓存清理 / 核心重启
│
└─ 文件层 verge_* ──→ ~/Library/Application Support/io.github.clash-verge-rev.clash-verge-rev/
    profiles.yaml 订阅切换 · rules/proxies/groups 卡片增删改 ·
    Merge.yaml 全局合并 · verge.yaml 应用设置 · dns_config.yaml ·
    enhance 链重新生成 → PUT /configs {path} 热重载核心
```

关键设计:生成的配置写入**独立文件** `clash-verge-mcp.yaml`,不覆盖 Clash Verge 自己的
`clash-verge.yaml`,与 UI 双向兼容(UI 下次重新生成时读取的是同一份 profiles 源文件)。

## 安装

### 🚀 一句话安装(推荐)

把这句话贴给你的 AI Agent(Claude Code / Cursor / AionUi 等),它会自动完成全部安装配置:

```
帮我安装 clash-verge-mcp-pro 这个 MCP:读取 https://raw.githubusercontent.com/cdxiaodong/clash-verge-mcp-pro/main/SETUP.md 并严格按步骤执行,装完验证能连上我本机的 Clash Verge,再告诉我怎么用。
```

### 手动安装

**方式一:PyPI(零安装)**

```bash
uvx clash-verge-mcp-pro   # uvx 自动从 PyPI 拉取运行
```

**方式二:源码**

```bash
git clone https://github.com/cdxiaodong/clash-verge-mcp-pro.git
cd clash-verge-mcp-pro && uv sync
```

MCP 配置(Claude Code `~/.claude.json` / AionUi / Cursor 等):

```json
{
  "mcpServers": {
    "clash-verge-pro": {
      "command": "uvx",
      "args": ["clash-verge-mcp-pro"],
      "type": "stdio"
    }
  }
}
```

源码方式则把 args 换成:`["run", "--directory", "<项目绝对路径>", "clash-verge-mcp-pro"]`,command 改为 `uv`。

## 工具一览(58 个)

**运行时层 — 基础**
- `mihomo_status` / `mihomo_restart_core` / `mihomo_upgrade_core`
- `mihomo_list_proxies` / `mihomo_switch_proxy` / `mihomo_test_delay` / `mihomo_test_group_delay` / `mihomo_unfix_proxy`
- `mihomo_get_configs` / `mihomo_patch_configs` / `mihomo_reload_config`
- `mihomo_list_rules`
- `mihomo_list_connections` / `mihomo_close_connection` / `mihomo_close_all_connections`
- `mihomo_list_providers` / `mihomo_update_provider` / `mihomo_healthcheck_provider`
- `mihomo_dns_query` / `mihomo_flush_cache`

**运行时层 — 实时流与自动化**
- `mihomo_recent_logs`(WS 采集核心日志,排障利器)
- `mihomo_traffic_snapshot` / `mihomo_memory_snapshot`
- `auto_select_fastest`(测速 → 切最快节点 → 断旧连接,一句话完成)

**文件层 — 规则与订阅**
- `verge_add_rules` / `verge_remove_rules` / `verge_list_rule_overrides` ← 规则增删改
- `verge_add_subscription` / `verge_update_subscription` / `verge_subscription_info`(流量/到期监控)
- `verge_list_profiles` / `verge_switch_profile` / `verge_read_profile`

**文件层 — 节点/组/规则集**
- `verge_add_proxies`(任意协议自定义节点)
- `verge_add_group` / `verge_remove_group`
- `verge_add_ruleset` / `verge_remove_ruleset`(ACL4SSR 等第三方规则集)

**文件层 — 配置与调试**
- `verge_get_merge` / `verge_update_merge`
- `verge_get_settings` / `verge_patch_settings`
- `verge_get_dns_config` / `verge_save_dns_config`
- `verge_preview_config` / `verge_apply_config`
- `verge_trace_domain`(模拟规则匹配,查"为什么这个域名没走代理")
- `verge_check_rules`(重复规则/不可达规则体检)

**安全网**
- `verge_backup` / `verge_list_backups` / `verge_rollback`(所有破坏性操作自动先备份)

**场景与审计**
- `verge_save_scene` / `verge_apply_scene` / `verge_list_scenes` / `verge_delete_scene`(模式+各组节点选择+规则卡片的一键场景切换,如"游戏模式")
- `verge_audit_routing`(批量域名分流审计:每个域名命中哪条规则、走哪个出口)
- `verge_diff`(apply 前预览:将生成的配置 vs 运行中的配置)
- `mihomo_update_geo`(在线更新 geoip/geosite/mmdb)

## 功能实测截图

以下截图来自与 AI 助手(AionUi / Claude)的一次真实会话,所有数据均为线上实测:

**核心状态 / 内存 / 实时流量** — 自动探测 Unix Socket 直连核心:

![核心状态](docs/images/01-core-status.png)

**代理组全量读取** — 12 个组的类型、当前选择、节点延迟:

![代理组](docs/images/02-proxy-groups.png)

**节点延迟实测** — HTTP 实测 123ms,非缓存值:

![延迟测试](docs/images/03-delay-test.png)

**规则追踪** — 一句话回答"google.com 走哪条路?命中哪条规则?":

![规则追踪](docs/images/04-trace-domain.png)

**订阅流量监控** — 已用 / 剩余 / 到期时间(订阅链接已脱敏):

![订阅信息](docs/images/05-subscription-info.png)

**活动连接监控** — 哪个进程、访问什么、走哪条链、代理还是直连:

![连接监控](docs/images/06-connections.png)

**实战排障案例** — ToDesk 无法登录,用 `mihomo_recent_logs` + `mihomo_list_connections` 组合拳 3 分钟排除代理嫌疑、定位到系统服务未启动:

![实战排障](docs/images/07-troubleshooting-case.png)

## 环境变量(可选)

- `MIHOMO_API_URL`:覆盖控制器地址,支持 `unix:///path/to.sock` 或 `http://host:port`
- `MIHOMO_API_SECRET`:覆盖 API 密钥
- `CLASH_VERGE_HOME`:覆盖数据目录(多客户端适配;缺省自动探测 Clash Verge Rev → 旧版 → ClashX 路径)

## 已知边界

- 切换订阅/修改 verge.yaml 后,Clash Verge **UI 状态不会实时同步**(应用重启后一致);核心侧立即生效
- 修改 `verge.yaml` 中系统代理/TUN 等应用级开关,建议随后调用 `verge_apply_config`,部分需重启应用
- `mihomo_upgrade_core` 仅 alpha 内核支持
- 规则追踪不评估逻辑规则(AND/OR/NOT)与 GEOIP/GEOSITE(需要 mmdb/geosite 数据)

## 发布 PyPI(待办)

```bash
uv build
uv publish --token <pypi-token>   # 需要你自己注册 PyPI 账号
```