# 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 示例：

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

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

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

## 安装与检查

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

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

## 启动

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

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

Codex 注册与验证步骤见 [Codex 客户端配置示例](examples/codex.md)。

## 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 流量，验证九个工具、同流量关联、脱敏以及长任务清理。

```powershell
$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 实施规格](docs/implementation-spec.md)和 [0.2 开发规格](docs/v0.2-development-spec.md)。