# OpenWrt LuCI HTTP MCP

标准 OpenWrt LuCI Web 界面的只读 MCP 表达，通过 LuCI 原生 `POST /ubus/` JSON-RPC 接口读取状态和运行其诊断页中的固定命令，不使用 SSH，也不在路由器上安装代理。

当前版本：`0.4.0`。以 OpenWrt 25.12.3 / LuCI openwrt-25.12 为 ground truth；可选方法不存在时返回明确的 `supported: false`，不会把权限或认证错误误报为不支持。

## 安全范围

- 使用现有 LuCI `root` 登录，不创建新账户。
- 密码只从环境变量读取，不写入源码或日志。
- 不注册任意 ubus 调用、任意 shell、重启、固件升级或 UCI 写入工具。
- `ip`、`nft`、`dmesg`、软件目录和网络诊断只执行代码中写死的程序与参数结构；不经过 shell。
- 网络诊断只允许经过校验的目标，Ping 次数、Traceroute 超时和跳数均不可由调用者改变。
- 返回给模型前隐藏密码、PSK、community、令牌、会话标识、私钥、HTTP Authorization 和 URL 内嵌认证材料。
- 单次 LuCI 响应限制为 2 MiB，单个 MCP 结果限制为 256 KiB；超限返回有效 JSON 错误而非截断内容。

这只是 Demo。root 密码通过普通 HTTP 发送时没有传输加密，只应在可信 LAN 中临时测试。长期使用应开启 LuCI HTTPS，并改为受限 rpcd 账户。

## 环境要求

- Node.js 20 或更高版本
- OpenWrt/LuCI 可通过局域网访问
- `uhttpd-mod-ubus` 与 `rpcd` 正常工作

## 安装

```powershell
cd C:\absolute\path\to\openwrt-luci-mcp-demo
npm install
```

不要复制 `.env.example` 后把真实密码提交到 Git。推荐直接在 MCP 客户端的进程环境中设置变量：

```text
OPENWRT_URL=http://router.example.invalid
OPENWRT_USERNAME=root
OPENWRT_PASSWORD=<LuCI root 密码>
OPENWRT_ALLOW_INSECURE_HTTP=1
```

`OPENWRT_ALLOW_INSECURE_HTTP=1` 是显式风险确认。若 LuCI 已启用 HTTPS，请使用 `https://...` 并删除该变量。

## 运行

```powershell
npm start
```

stdio 是 MCP 协议通道；程序日志只写入 stderr。通常由 MCP 客户端启动本程序，而不是手动交互。

参考 [`mcp-config.example.json`](./mcp-config.example.json) 配置客户端，并把其中的 Node 与 `src/index.mjs` 路径改为绝对路径。

## 工具

- `router_capabilities`
- `router_luci_pages`
- `router_system_info`
- `router_interfaces`
- `router_interface_details`
- `router_routing_config`
- `router_network_device`
- `router_port_status`
- `router_vlan_config`
- `router_dhcp_leases`
- `router_dhcp_config`
- `router_dns_config`
- `router_known_hosts`
- `router_wifi_overview`
- `router_wifi_details`
- `router_wifi_clients`
- `router_services`
- `router_processes`
- `router_realtime_stats`
- `router_routes`
- `router_neighbors`
- `router_firewall_status`
- `router_firewall_config`
- `router_nftables_rules`
- `router_wifi_scan`
- `router_logs`
- `router_connections`
- `router_storage`
- `router_packages`
- `router_package_catalog`
- `router_time_status`
- `router_system_settings`
- `router_network_diagnostics`
- `router_network_consistency`
- `router_run_diagnostic`
- `router_security_audit`
- `router_client_summary`

每个工具同时返回兼容的文本 JSON 和 MCP `structuredContent`。路由、DHCP/DNS、Firewall、VLAN、大型规则和软件目录使用 `offset`、`limit` 分页。

v0.4.0 增加 LuCI 网络配置控制面的只读表达：静态路由与策略规则、dnsmasq/odhcpd、DNS 记录、Firewall 关系、DSA/swconfig VLAN、基础 System 设置，以及配置与运行态一致性检查。工具只读取已提交配置；不会读取其他 LuCI 会话中尚未应用的 UCI 暂存变更。

`router_network_diagnostics` 只分析现有状态。`router_run_diagnostic` 对应 LuCI Network → Diagnostics 页面，会产生 Ping、Traceroute 或 DNS 流量，但不修改配置。`router_package_catalog` 只调用 LuCI package manager 的 `list-installed` 和 `list-available`，不更新软件源。

## LuCI 页面覆盖

| LuCI 页面 | MCP 工具 | 状态 |
| --- | --- | --- |
| Status → Overview | `router_system_info`, `router_interfaces`, `router_port_status`, `router_dhcp_leases`, `router_wifi_details` | supported |
| Status → Realtime Graphs | `router_realtime_stats` | supported |
| Status → Routes | `router_routes`, `router_neighbors` | supported |
| Status → System Log | `router_logs` | supported |
| Status → Processes | `router_processes` | supported |
| Status → Firewall | `router_firewall_status`, `router_nftables_rules` | supported |
| Network → Interfaces | `router_interfaces`, `router_interface_details` | supported |
| Network → Switch/VLAN | `router_vlan_config`, `router_port_status` | supported/conditional |
| Network → Wireless | `router_wifi_overview`, `router_wifi_details`, `router_wifi_clients`, `router_wifi_scan` | supported |
| Network → Routing | `router_routing_config`, `router_routes` | supported |
| Network → DHCP | `router_dhcp_config`, `router_dhcp_leases` | supported |
| Network → DNS | `router_dns_config` | supported |
| Network → Diagnostics | `router_network_diagnostics`, `router_run_diagnostic` | supported |
| Network → Firewall Configuration | `router_firewall_config`, `router_firewall_status` | supported |
| System → System | `router_system_settings`, `router_time_status` | supported |
| System → Software | `router_packages`, `router_package_catalog` | supported |
| System → Mount Points | `router_storage` | supported |

同一矩阵可由 `router_luci_pages` 读取。Switch/VLAN 仅在 DSA bridge-vlan 或旧 swconfig 配置存在时支持。WireGuard、SQM、UPnP 等可选 LuCI 应用不在 v0.4.0 范围内。

没有提供以下能力：

```text
uci.set / uci.delete / uci.apply
任意 file.exec / file.write / file.remove
system.reboot
luci.setPassword
hostapd.*.del_client
```

## 测试

27 项测试使用本机模拟 `/ubus/` 服务，不连接或修改真实路由器：

```powershell
npm test
```

## 一次性真实连接检查

在 PowerShell 中使用安全密码提示，不把密码写入文件：

```powershell
$secure = Read-Host 'LuCI root password' -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
try {
  $env:OPENWRT_PASSWORD = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
  $env:OPENWRT_URL = 'http://router.example.invalid'
  $env:OPENWRT_USERNAME = 'root'
  $env:OPENWRT_ALLOW_INSECURE_HTTP = '1'
  npm run check:live
}
finally {
  [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
  Remove-Item Env:OPENWRT_PASSWORD -ErrorAction SilentlyContinue
}
```

该检查只调用 `system.board`、`system.info` 和 `luci.getVersion`。

## 目标路由器核验范围

通过已登录 LuCI 页面确认以下模块在目标路由器上存在且可正常读取，没有出现 RPC access denied：

- 活动 IPv4/IPv6 路由、策略规则和邻居表
- nftables `fw4` 运行时状态
- 系统日志
- Wi-Fi 信道分析
- 软件包管理器
- 网络诊断
- 静态路由、DHCP/DNS 与 Firewall 配置
- DSA/bridge-vlan 与基础 System 设置

实现方法与 OpenWrt 25.12 使用的 LuCI/rpcd 接口保持一致；若将来更换固件或裁剪 LuCI 软件包，可调用 `router_capabilities` 和 `router_luci_pages` 核对实际支持情况。