爱快路由控制 MingShi350/dsh-ikuai-mcp

dsh-ikuai-mcp

在 DeepSeek Harness (DSH) 里控制爱快 (iKuai) 软路由。纯 Node 零依赖的 MCP stdio server + DSH 宿主半：模型侧出现 11 个 mcp__ikuai__ 工具，另有 3 个宿主工具（ikuai_credentials_status / ikuai_set_credentials / ikuai_ping）。写操作默认关闭。

- 只读：系统状态、LAN/WAN 接口、在线终端、DHCP 地址池与绑定、DNS、静态路由、VLAN、DDNS、端口映射
- 通用读写 ikuai_api_call：需 IKUAI_ALLOW_WRITES=1，且每次调用传 confirm: true
- 连接参数存 DSH 凭据中心，改密码/换 IP 不用重启 DSH
- 默认 https://192.168.1.1（爱快出厂 LAN 地址），用户名 admin

安装

用法：把这个仓库地址（或本地目录）发给你 DSH 里的 AI，说一句「按 README 的安装一节把 dsh-ikuai-mcp 装好」。

交给 DSH 里的 AI（照做即可）

1. 安装进 profile（三选一，把占位符换成实际值）：

dsh plugin --profile web add /绝对路径/dsh-ikuai-mcp # 本地目录（必须是绝对路径）
dsh plugin --profile web add github:MingShi350/dsh-ikuai-mcp # GitHub
dsh plugin --profile web add dsh-ikuai-mcp # npm

2. 确认写进了 profile（bundles 里应出现 dsh-ikuai-mcp）：

node -e 'const p=require(process.env.HOME+"/.dsh/profiles/web/package.json");console.log(p.dsh.profile.bundles.filter(b=>b.includes("ikuai")))'

3. 重启 dsh web。这一步交给用户做，agent 不要 kill 宿主进程（会中断当前会话）。
装了 dshmarket 的话，界面上的「待重启」提示旁有一键重启。

4. 配置连接参数（见下一节）。不要猜 IP 和密码，问用户要。

5. 验证：调用 ikuai_credentials_status，再调用 ikuai_ping。

判断装好没有

| 现象 | 含义 | 处理 |
| 工具列表里出现 11 个 mcp__ikuai__ | 装好了 | 去配置连接参数 |
| 只有 ikuai_credentials_status / ikuai_set_credentials / ikuai_ping | 宿主半起来了，MCP 那一行没起 | 看 mcp-server:ikuai 开关是否被关；确认第 2 步的 bundles 里有它；确认重启过 |
| 一个都没有 | 插件没装上 | 回到第 1 步 |

原理（手工安装时才需要看）

package.json 的 dsh.bundle.patch 指向 cordis.patch.yml，里面的 - insert: 两行分别是宿主半和 @deepseek-ai/dsh-mcp-client（以 stdio 挂载 server/ikuai-mcp-server.mjs）。dsh plugin add 会自动把包名追加进 ~/.dsh/profiles/<profile>/dsh.profile.bundles，启动时装配；不想装包也可以手工把那两行并进 profile 的 cordis.patch.yml。

配置：改爱快 IP / 加账号密码

取值优先级：环境变量 > DSH 凭据中心 > 默认值。默认值：

| 键 | 默认值 | 说明 |
| IKUAI_URL | https://192.168.1.1 | 爱快 web 管理地址；只写 192.168.1.1 会自动补 https:// |
| IKUAI_USERNAME | admin | web 登录用户名 |
| IKUAI_PASSWORD | 空 | 必须配，否则工具直接报「未配置 IKUAI_PASSWORD」 |

改 IP

先用浏览器确认管理地址能打开：默认 192.168.1.1；改过 LAN 网段就用改后的地址；端口不是 80/443 要带上，例如 http://192.168.1.1:81。然后任选一种：

A. 让 agent 调工具写进凭据中心（不用重启）

ikuai_set_credentials { "url": "192.168.1.1", "username": "admin", "password": "你的web登录密码" }

会先归一化地址 → 再用这组参数试连一次 → 成功才写入。连不上就不落盘（确需强存加 "allowUnverified": true）。
写入后 5 秒内生效。

B. 在 GUI 里填（推荐，密码不进对话记录）

设置 → 凭据中心 → 新增 IKUAI_URL（值如 192.168.1.1），同样方式加 IKUAI_USERNAME、IKUAI_PASSWORD。

C. 环境变量

给启动 DSH 的进程设 IKUAI_URL=http://192.168.1.1，需重启。注意环境变量优先于凭据中心，设了之后在凭据中心改同名值不生效。

加账号密码

密码就是你登录爱快 web 管理页的那个密码。

- 推荐：设置 → 凭据中心 → 加 IKUAI_PASSWORD（明文只存 ~/.dsh/.credentials.yaml，权限 0600，不进对话记录）
- 或者调 ikuai_set_credentials { "password": "..." } —— 该参数是明文，会留在会话记录里，能用 GUI 就用 GUI

验证

ikuai_credentials_status → 四项生效值与来源（env / 凭据中心 / 默认值） ikuai_ping → ✅ 登录成功：192.168.1.1（用户 admin） mcp__ikuai__ikuai_status → CPU / 内存 / 在线终端数

ikuai_ping 结果对照：

| 返回 | 含义 |
| ✅ 登录成功：… | 通了 |
| ❌ 登录失败：code=1005 账号或密码错误 | 用户名/密码不对 |
| ❌ 连接失败：connect ECONNREFUSED … | 地址或端口不对 |
| ❌ …响应不是 JSON（地址可能不是爱快 web 管理端口） | 这个端口不是爱快管理页 |

什么时候要重启

| 改的是 | 重启？ |
| 凭据中心里的 IKUAI_ | 不用（每次调用重读，5s 缓存） |
| server/.mjs 代码 | 重挂 MCP 子进程：能力面板把 mcp-server:ikuai 关掉再打开，或 kill server/ikuai-mcp-server.mjs（配了 reconnect 会自动拉起） |
| lib/index.mjs 或 cordis.patch.yml | 重启 dsh web |

写权限（默认只读）

任何非 show/get/list/query/search 的调用默认被拒。开启方式二选一，都不用重启：

1. 推荐：设置 → 凭据中心 添加 IKUAI_ALLOW_WRITES = 1（5s 生效；改回 0 立刻恢复只读）
2. 给 DSH 进程设 IKUAI_ALLOW_WRITES=1（需重启）

开启后每次写仍要传 "confirm": true；插件不提供「让模型自己开写权限」的工具。写之前先 show 拿原记录（含 id/uuid），改字段后 edit 回写。排序参数必须大写（ORDER_BY + ORDER），小写会被静默忽略。

工具清单

| 工具 | func_name | 说明 |
| ikuai_status | homepage | CPU/内存/温度/在线终端数/连接数/运行时长/WAN 线路 |
| ikuai_interfaces | lan | 物理端口、上下线、netinfo（内外网 IP/网关）、VLAN 失败项 |
| ikuai_online_devices | monitor_lanip | 在线终端：IP/MAC/名称/流量/连接数；分页 + order_by/order |
| ikuai_dhcp_pools | dhcp_server | 各 LAN/VLAN 地址池、租期、网关、DNS |
| ikuai_dhcp_bindings | dhcp_static | 静态绑定 + 动态租约混合列表（static_status: 1=静态） |
| ikuai_dns_config | dns | 本机 DNS 开关、上游 DNS、代理规则、缓存 |
| ikuai_static_routes | static_rt + static_rt_table | 用户静态路由规则 + 生效路由表 |
| ikuai_vlan_config | vlan | VLAN ID/名称/成员端口/tag |
| ikuai_ddns_config | ddns | DDNS 配置与最近解析 IP（密码/AK 已脱敏） |
| ikuai_port_mapping | dnat + netmap + upnpd_leases | 端口映射、1:1 映射、UPnP 租约 |
| ikuai_api_call | 任意 | 通用读写兜底（ACL/QoS/流控/域名黑名单/syslog 等） |

V3 → V4 模块名：V4 改了名，用旧名会 code=1003 Access denied —— dhcp_addr_bind→dhcp_static、port_mapping→dnat、upnp→upnpd、static_routing→static_rt、 mac_bind→acl_mac/mac_comment。插件会自动回退候选名。
注意 V4 对不存在的模块也回同样的 1003，无法与「无权限」区分。

安全

- 爱快用自签证书，客户端必须放开证书校验；只在受信内网用，不要指向公网设备。
- 密码明文存 ~/.dsh/.credentials.yaml（0600）。插件不把凭据写进 process.env。
- 结果按字段名尽力脱敏：pass|pwd|secret|token|credential|api_key|access_key、以 key 结尾的字段，以及 LTAI…/AKIA… 形式的云 AccessKeyId；不认识的字段名原样返回，别当脱敏网关用。
- 写操作能改坏网络（DHCP、路由、端口映射），所以默认只读 + 每次 confirm。

自测

离线，不需要路由器也不需要凭据：

npm test
node tests/mock-test.mjs # 握手、11 工具、会话过期重登、写请求不重放、写闸门、脱敏、坏地址不崩
node tests/host-test.mjs # 宿主半：env 不被污染、来源标注、set_credentials 校验与先试连后落盘

排错

| 现象 | 处理 |
| 看不到 mcp__ikuai__* | 能力面板 mcp-server:ikuai 是否被关；bundles 里有没有它；是否重启过 |
| 报「未配置 IKUAI_PASSWORD」 | 凭据中心里加 IKUAI_PASSWORD |
| 报 code=1005 | 用户名/密码不对；若该值来自环境变量，改完要重启 |
| 报 ECONNREFUSED / 超时 | 地址或端口不对，先确认浏览器能打开该地址 |
| 改配置没生效 | 凭据中心的值 5s 内生效；若存在同名环境变量，它会盖住凭据中心 |
| 写操作被拒 | 默认只读，见「写权限」；并确认传了 confirm: true |

已知限制

- 写操作只有通用透传，没有为 DHCP/DNS/路由写专用写工具（字段名随固件变化）。
- 未覆盖 Docker / QEMU / 行为审计 / AC 管理 / SD-WAN，用 ikuai_api_call 直接调 func_name。
- 会话 10 分钟重登一次；爱快并发登录会互相顶号，别同时开着 web UI 做写操作。
- 部分字段是设备回吐的原始字节（如 DHCP 租约的 hostname），按 UTF-8 解可能是乱码。
- 大结果不裁剪：ikuai_online_devices 默认 100 行 × 约 50 字段，按需调小 limit。
- 仅在 iKuai V4 (4.0.311 x64) 上完整实测；V3 走候选名回退，未逐项验证。

许可与致谢

MIT，见 LICENSE。作者：MingShi350。

API 用法与 func_name 清单参考 beck-8/ikuai-mcp（MIT，© 2026 Beck），本项目是独立的 Node 实现，详见 THIRD-PARTY-NOTICES.md。