openwrt-mcp-server

openwrt-mcp-server

openwrt-mcp-server 是一个基于 Rust 的 MCP 风格桥接程序，适用于 OpenWrt 和 Linux 边缘设备。目前，它通过 HTTP 和 MQTT 提供单设备 JSON-RPC 控制接口。长期目标是让 Rust 服务也能在 OpenWrt 之外作为独立的设备群 MCP 服务运行，通过 EdgePulse 和其他设备适配器管理多台 OpenWrt 设备。

当前部署模式：

• 用于单台设备的 OpenWrt 或 Linux 本地伴随进程。
• 面向 AI Agent 和编排系统的远程桥接端点。
• 未来的独立设备群服务，支持设备注册表、基于规则的访问控制和多租户隔离。

当前功能

• 使用 warp 的 HTTP API。
• 使用 rumqttc 的 MQTT 传输。
• JSON-RPC 2.0 请求和响应封装。
• 通过 x-api-token 标头保护 HTTP 端点。
• TOML 配置及启动验证。
• 从 OpenWrt ubus 收集实际运行上下文；在 Linux 上则回退为从 /proc、/sys 和 ip -j 获取数据。
• 对受支持的设备操作执行允许列表中的命令。
• device.describe 能力内省，用于查看传输方式、命令、命令风险元数据和上下文收集器。
• 轻量级命令和上下文注册表，作为未来模块的扩展点。
• 为服务、配置、HTTP 和 MQTT 事件生成结构化 JSON 日志。
• schema/ 目录下提供命令和上下文载荷的 JSON Schema 文档。

项目结构

• src/context/collector.rs：收集设备上下文。
• src/context/registry.rs：声明内置上下文收集器和扩展元数据。
• src/executor/command.rs：分发允许列表中的命令。
• src/executor/registry.rs：声明命令名称、必需参数和风险级别。
• src/http/routes.rs：提供经过身份验证的 HTTP JSON-RPC 端点。
• src/mqtt/handler.rs：处理 MQTT 订阅、分发和响应发布。
• src/config/mod.rs：加载并验证 config.toml。
• src/logging.rs：输出精简的 JSON 日志记录。
• src/model/types.rs：定义共享的请求、结果和上下文类型。
• schema/：包含已记录载荷结构的 JSON Schema 文件。
• docs/edgepulse-integration-roadmap.md：介绍 EdgePulse、设备群、RBAC 和多租户计划。

构建和测试

cargo build --release
cargo test

部署到 OpenWrt 时，请使用 OpenWrt SDK 或适用于设备的 musl 目标进行交叉编译。

配置

config.toml 示例：

[mqtt]
broker = "mqtt://localhost:1883"
client_id = "openwrt-one"
username = "mcp-user"
password = "mcp-pass"
topic_prefix = "mcp/device/openwrt-one"

[http]
enable = true
listen_addr = "0.0.0.0"
port = 8080
token = "your-api-token"

当前验证会拒绝以下情况：

• mqtt.broker、mqtt.client_id 或 mqtt.topic_prefix 为空。
• MQTT 主题前缀包含 + 或 #。
• http.listen_addr 无效。
• http.port = 0。
• 启用 HTTP 时，http.token 为空。

HTTP API

所有 HTTP 端点都需要：

x-api-token: <configured token>

获取当前上下文：

curl -H 'x-api-token: change-me' \
  http://127.0.0.1:8080/api/context

描述服务能力：

curl -H 'x-api-token: change-me' \
  http://127.0.0.1:8080/api/describe

执行允许列表中的命令：

curl -H 'x-api-token: change-me' \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"device.executeCommand","params":{"command":"get_context"},"id":"cmd-1"}' \
  http://127.0.0.1:8080/api/cmd

支持的内置命令在 src/executor/registry.rs 中声明。

MQTT API

命令主题：

{topic_prefix}/cmd

响应主题：

{topic_prefix}/resp

能力请求示例：

{
  "jsonrpc": "2.0",
  "method": "device.describe",
  "params": {},
  "id": "describe-1"
}

命令请求示例：

{
  "jsonrpc": "2.0",
  "method": "device.executeCommand",
  "params": {
    "command": "restart_interface",
    "args": {
      "interface": "wan"
    }
  },
  "id": "cmd-1"
}

Schema

Schema 文件记录了预期的载荷：

• schema/command.schema.json
• schema/context.schema.json

目前，运行时验证通过类型化解析、命令允许列表、参数检查和配置验证实现。完整的 JSON Schema 验证计划作为未来的加固步骤实现。

EdgePulse 集成

openwrt-mcp-server 旨在与 ../edgepulse 集成，作为远程 MCP 桥接服务。EdgePulse 应继续作为 OpenWrt 本地的权威组件，负责遥测、策略、命名操作、审计日志和 AI Agent 对话状态。本 Rust 服务应将面向远程 HTTP/MQTT/MCP 的请求转换为 EdgePulse 本地 API 调用（如果可用）。

详细计划请参见 docs/edgepulse-integration-roadmap.md。

路线图

当前基线：

• 单设备 HTTP/MQTT JSON-RPC 桥接。
• OpenWrt/Linux 上下文收集。
• 命令和上下文注册表。
• device.describe 内省。
• 结构化 JSON 日志。
• 配置验证。
• 架构文档。

近期加固：

• 运行时 JSON Schema 验证。
• 持久化审计日志，记录 HTTP/MQTT 请求和命令结果。
• 为 edgepulse-ctl 接入 EdgePulse 客户端适配器，随后支持 ubus 或 Unix 套接字。
• 在可用时，用由 EdgePulse 策略控制的命名操作替代直接修改命令。
• 超越初始允许列表的命令沙箱。
• 用于测试和调试请求的 CLI 实用工具。

设备群方向：

• 在 OpenWrt 之外运行独立的 MCP 服务模式。
• 设备注册表和显式目标选择。
• 针对用户、服务账户、设备、方法和权限的基于规则的访问控制。
• 支持租户感知的配置、令牌、MQTT 路由、上下文缓存、策略和审计记录。
• 多租户设备群服务运行。

长期扩展：

• 用于仪表板和实时操作的 WebSocket 传输。
• 流式遥测指标端点。
• 针对低带宽 MQTT 的上下文增量压缩。
• 安全启动和系统完整性报告。
• 支持定期执行命令的调度程序。