Openwrt MCP Server

openwrt-mcp服务器

openwrt-mcp-server 是一个基于Rust的MCP风格的桥接器，适用于OpenWrt和Linux边缘设备。如今，它通过HTTP和MQTT公开了一个单一设备JSON-RPC控制界面。长期的方向是让Rust服务器也在OpenWrt之外运行，作为一个独立的舰队MCP服务，可以通过EdgePulse和其他设备适配器管理许多OpenWrt设备。

当前部署模式：

• 一个设备的本地OpenWrt或Linux配套进程。
• 用于AI代理和编排系统的远程网桥端点。
• 未来的独立机群服务器，具有设备注册表、基于规则的访问控制和多租户隔离。

当前能力

• 使用的HTTP API warp.
• MQTT传输使用 rumqttc.
• JSON-RPC 2.0请求和响应信封。
• 通过令牌保护的HTTP端点 x-api-token 头球
• 带有启动验证的TOML配置。
• OpenWrt的真实上下文收集 ubus，Linux回退数据来自 /proc, /sys，以及 ip -j.
• 允许对支持的设备操作执行列出的命令。
• device.describe 传输、命令、命令风险元数据和上下文收集器的能力自检。
• 轻量级命令和上下文注册表作为未来模块的扩展点。
• 服务、配置、HTTP和MQTT事件的结构化JSON日志。
• 命令和上下文有效载荷的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模式文件。
• 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.token 当启用HTTP时。

HTTP API

所有HTTP端点都需要：

x-api-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/command.schema.json
• schema/context.schema.json

运行时验证目前是通过类型解析、命令分配、参数检查和配置验证来实现的。完整的JSON模式验证计划作为未来的强化步骤。

EdgePulse集成

openwrt-mcp-server 旨在与 ../edgepulse 作为远程MCP桥。EdgePulse应继续作为OpenWrt遥测、策略、命名操作、审计日志和AI代理对话状态的本地权威机构。此Rust服务器应将面向远程HTTP/MQTT/MCP的请求转换为可用的EdgePulse本地API。

看 docs/edgepulse集成路线图.md 详细的计划。

路线图

当前基线：

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

近期硬化：

• 运行时JSON模式验证。
• HTTP/MQTT请求和命令结果的持久审计日志。
• EdgePulse客户端适配器 edgepulse-ctl那么 ubus 或Unix套接字。
• 将直接变异命令替换为EdgePulse策略门控命名操作（如果可用）。
• 命令沙盒超出了最初的allowlist。
• 用于测试和调试请求的CLI实用程序。

舰队方向：

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

长期延期：

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