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"

安装与检查

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 或修复建议。没有捕获到连接表示证据缺失，不表示静态规则实际命中或未命中。

工具

工具	返回的路由器侧事实
snapshot_network	系统、网络、服务、监听、路由、nftables 与能力快照
inspect_config_state	Nikki 生成配置摘要、文件身份、Mihomo runtime 与 provider 摘要
trace_dns	router-local、Mihomo、LAN listener、bootstrap DNS 与地址属性
observe_client	指定客户端窗口内的新连接、Mihomo 日志与 conntrack 事件
inspect_flow	指定流的 DNS、实际代理链、转发路由、nftables 与 conntrack
capture_flow	有界 tcpdump 包元数据和 TCP/UDP/DNS 机械摘要
inspect_subscriptions	Nikki 缓存文件身份、更新时间与 Mihomo provider 状态
read_logs	按来源、窗口、条数和文本过滤的脱敏日志
compare_snapshots	当前 MCP 进程内两个快照的字段级差异

实机 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 开发规格。