Metadata-Version: 2.4
Name: clash-verge-mcp-pro
Version: 0.1.0
Summary: 全面接管 Clash Verge / Mihomo 的 MCP 服务器:58 个工具,覆盖节点/规则/订阅/连接/DNS/场景预设,自动适配 unix socket
Author: cdxiaodong
License: MIT License
        
        Copyright (c) 2026 cdxiaodong
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: clash,clash-verge,mcp,mihomo,proxy
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.0
Requires-Dist: mcp>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: quickjs>=1.19.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# 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 源文件)。

## 安装

```bash
cd clash-verge-mcp-pro
uv sync   # 或 uv run 自动处理
```

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

```json
{
  "mcpServers": {
    "clash-verge-pro": {
      "command": "uv",
      "args": ["run", "--directory", "<项目绝对路径>", "clash-verge-mcp-pro"],
      "type": "stdio"
    }
  }
}
```

## 工具一览(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)

## 环境变量(可选)

- `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 账号
```
