OpenWrt Network Diagnostics MCP

面向 OpenWrt、Nikki 与 Mihomo 的只读诊断 MCP。它向 Agent 提供路由器侧 Observation、机械 Correlation 和证据缺口；故障判断与修复决策仍由 Agent 结合客户端证据完成。

0.2 只支持已经实机验证的组合：FriendlyElec NanoPi R5S、ImmortalWrt 25.12、Nikki、Mihomo 与 firewall4/nftables。所有 Evidence bundle 使用 schema_version: 2。

准备

• Windows 工作站安装 Node.js 24 和 OpenSSH Client。

• SSH config 存在可免交互登录的 Host openwrt。

• 路由器安装 conntrack、tcpdump、yq、ip、nft 与 ubus。

• Mihomo external controller 在路由器 loopback 的 9090 端口可用。

• MIHOMO_SECRET 只通过 MCP 子进程环境变量提供。

SSH config 示例：

Host openwrt
  HostName 192.0.2.1
  User root
  IdentityFile C:/Users/<you>/.ssh/openwrt_ed25519

完成标准：以下命令输出设备信息且不要求密码。

ssh -o BatchMode=yes openwrt "ubus call system board"

Related MCP server: firewalla-mcp-server

安装与检查

cd D:\Workspace\OpenWrt-MCP
npm ci
npm run check

npm run check 会编译项目并运行 Node.js 内置测试。构建输出位于 dist/，不提交到 Git。

启动

$env:MIHOMO_SECRET = Read-Host "Mihomo secret" -MaskInput
npm run build
npm start

MCP 使用 stdio：stdout 只承载协议，审计摘要写入 stderr。正常退出会关闭 Mihomo SSH 隧道。

Codex 注册与验证步骤见 Codex 客户端配置示例。

Agent 取证流程

1. 先调用 snapshot_network 建立系统、接口、路由、防火墙与能力基线。默认 detail=summary；只有需要完整但仍有界的规范化证据时才使用 detail=full。

2. 按问题范围调用 inspect_config_state 或 trace_dns。把 generated config 与 runtime state 视为不同来源。

3. 用户准备复现时调用 observe_client，窗口为 5–60 秒。双栈设备可显式提供 client_ipv6；MCP 不自动认定 IPv4/IPv6 属于同一设备。

4. 已知客户端与目标后调用 inspect_flow，关联 DNS、Mihomo、同地址族转发路由、nftables 与严格过滤的 conntrack；必要时可显式使用 detail=full。

5. 现有证据不足时由 Agent 显式调用 capture_flow。默认 30 秒，接口自动按客户端回程路由选择；同一时间只运行一个长观察或抓包。

6. 修改前后分别运行 snapshot_network，再用 compare_snapshots 计算字段差异。

MCP 不返回 verdict、confidence、root cause 或修复建议。没有捕获到连接表示证据缺失，不表示静态规则实际命中或未命中。

工具

实机 smoke test

smoke test 会从指定 LAN 客户端建立真实 Google HTTPS/TLS 流量，验证九个工具、同流量关联、脱敏以及长任务清理。

$env:MIHOMO_SECRET = Read-Host "Mihomo secret" -MaskInput
npm run smoke:live -- 192.0.2.20

完成标准：进程退出码为 0，九个工具均返回 schema v2；必需 Observation 成功，不支持的 bootstrap endpoint 被明确标记；summary 小于 full；并输出 secret_leaked: false。

安全边界

• 只执行固定、校验后的 SSH 命令与 Mihomo GET 请求。

• 不提供任意 shell、原始 BPF、配置写入、服务重启、策略切换、连接删除或软件安装。

• 不返回订阅 URL、认证字段、节点凭据、私钥、完整配置或 PCAP。

• 抓包不落盘，最多 60 秒、200 条包元数据、snaplen 256，并受字节上限和取消信号约束。

• 快照只保存在当前 MCP 进程内，进程退出后失效。

更完整的需求与边界见 0.1 实施规格和 0.2 开发规格。