JinDaGe - openwrt-mcp-server MCP Details

article

README

🚀 openwrt-mcp-server

openwrt-mcp-server 是一个轻量级且可扩展的 MCP（模型上下文协议）服务器，专为在基于 OpenWrt 的嵌入式路由器和设备上运行而设计。它借助 MQTT 和 HTTP 实现设备与外部 AI 系统之间的双向通信，采用 JSON-RPC 2.0 作为消息格式。

此服务器旨在为 AI 代理提供一个安全且结构化的接口，用于：

查询实时设备上下文（网络、Wi-Fi、系统指标）
远程执行系统级命令
支持实时命令响应和上下文流式传输

✨ 主要特性

使用 Rust 编写，具备高性能和安全性。
支持 MQTT（通过 rumqttc）和 HTTP（通过 warp）。
与 JSON-RPC 2.0 兼容，便于 AI 模型集成。
采用模块化架构，支持未来扩展。
拥有完整的 TOML 配置，所有字段均在代码中实际使用（见下文）。
具备安全的 HTTP API，采用基于令牌的身份验证（通过 x-api-token 标头）。
所有代码注释和文档均使用英文编写，以支持国际协作。
编译无警告（所有配置字段均被使用）。
内存占用低，适合嵌入式 OpenWrt 目标设备。

🌎 使用场景

AI 驱动的家庭网关监控与编排。
边缘管理的设备集群上下文报告。
通过 AI 实现自动恢复和自我修复的网络策略。
与大语言模型（LLM）和编排管道（如 n8n、LangChain）进行集成。

🛠️ 组件

context/collector.rs：从 OpenWrt 收集运行时状态（ubus、uci、ifstatus）。
mqtt/handler.rs：处理 MQTT 连接、身份验证、主题订阅（使用所有配置字段），并调度/响应 JSON-RPC 命令。
http/routes.rs：提供用于状态和命令输入的 RESTful API，所有端点均需基于令牌的身份验证。
executor/command.rs：执行经过验证的系统级指令。
config/mod.rs：加载并验证完整的 .toml 配置，包括所有 MQTT/HTTP 字段。
所有模块的文档均为英文。

🛡️ 协议

遵循 JSON-RPC 2.0。有关完整消息模式，请参阅 REQUIREMENTS.md。

🔧 安装指南

cargo build --release

推荐进行 OpenWrt（musl）交叉编译以进行部署。

🌐 配置

示例 config.toml（所有字段均为必需且会被使用）：

[mqtt]
broker = "mqtts://iot.example.com:8883"
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 使用 client_id、username、password 和 topic_prefix 进行连接和主题管理。
HTTP 服务器使用 enable、listen_addr、port 和 token 实现安全的 API 访问。

🚀 路线图

[x] 初始支持 MQTT + HTTP 双协议。
[x] 完整的 TOML 配置，所有字段在代码中使用。
[x] JSON-RPC 2.0 命令和上下文模式（调度和响应逻辑在 MQTT/HTTP 中）。
[x] 安全的 HTTP API，基于令牌的身份验证。
[x] 所有代码注释和文档均使用英文编写。
[ ] 上下文收集器与 UCI/UBUS/ifstatus 集成。
[ ] 设备功能自省（device.describe）。
[ ] WebSocket 传输层用于实时控制。
[ ] 命令允许列表和沙箱化。
[ ] 插件式扩展性，支持新命令模块。
[ ] 流数据遥测指标通道（如 /metrics）。
[ ] CLI 接口用于测试/调试命令。
[ ] 可选的 gRPC 支持。
[ ] 完善文档和示例。

openwrt-mcp-server