openwrt-mcp-server

openwrt-mcp-server is a Rust-based MCP-style bridge for OpenWrt and Linux edge devices. Today it exposes a single-device JSON-RPC control surface over HTTP and MQTT. The long-term direction is to let the Rust server also run outside OpenWrt as a standalone fleet MCP service that can manage many OpenWrt devices through EdgePulse and other device adapters.

Current deployment modes:

- Local OpenWrt or Linux companion process for one device.
- Remote bridge endpoint for AI agents and orchestration systems.
- Future standalone fleet server with device registry, rule-based access control, and multi-tenant isolation.

Current Capabilities

- HTTP API using warp.
- MQTT transport using rumqttc.
- JSON-RPC 2.0 request and response envelopes.
- Token-protected HTTP endpoints via the x-api-token header.
- TOML configuration with startup validation.
- Real context collection from OpenWrt ubus, with Linux fallback data from /proc, /sys, and ip -j.
- Allowlisted command execution for supported device actions.
- device.describe capability introspection for transports, commands, command risk metadata, and context collectors.
- Lightweight command and context registries as extension points for future modules.
- Structured JSON logs for service, config, HTTP, and MQTT events.
- JSON Schema documentation for command and context payloads under schema/.

Project Layout

- src/context/collector.rs: Collects device context.
- src/context/registry.rs: Declares built-in context collectors and extension metadata.
- src/executor/command.rs: Dispatches allowlisted commands.
- src/executor/registry.rs: Declares command names, required args, and risk levels.
- src/http/routes.rs: Exposes authenticated HTTP JSON-RPC endpoints.
- src/mqtt/handler.rs: Handles MQTT subscription, dispatch, and response publishing.
- src/config/mod.rs: Loads and validates config.toml.
- src/logging.rs: Emits compact JSON log records.
- src/model/types.rs: Defines shared request/result/context types.
- schema/: Contains JSON Schema files for documented payload shapes.
- docs/edgepulse-integration-roadmap.md: Describes EdgePulse, fleet, RBAC, and multi-tenant plans.

Build and Test

cargo build --release
cargo test

For OpenWrt deployment, cross-compile with the OpenWrt SDK or a musl target appropriate for the device.

Configuration

Example 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"

Validation currently rejects:

- Empty mqtt.broker, mqtt.client_id, or mqtt.topic_prefix.
- MQTT topic prefixes containing + or #.
- Invalid http.listen_addr.
- http.port = 0.
- Empty http.token when HTTP is enabled.

HTTP API

All HTTP endpoints require:

x-api-token: <configured token>

Get current context:

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

Describe server capabilities:

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

Execute an allowlisted command:

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

Supported built-in commands are declared in src/executor/registry.rs.

MQTT API

Command topic:

{topic_prefix}/cmd

Response topic:

{topic_prefix}/resp

Example capability request:

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

Example command request:

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

Schemas

Schema files document the expected payloads:

- schema/command.schema.json
- schema/context.schema.json

Runtime validation is currently implemented through typed parsing, command allowlisting, argument checks, and config validation. Full JSON Schema validation is planned as a future hardening step.

EdgePulse Integration

openwrt-mcp-server is intended to integrate with ../edgepulse as a remote MCP bridge. EdgePulse should remain the OpenWrt-local authority for telemetry, policy, named actions, audit logs, and AI agent conversation state. This Rust server should translate remote HTTP/MQTT/MCP-facing requests into EdgePulse local APIs where available.

See docs/edgepulse-integration-roadmap.md for the detailed plan.

Roadmap

Current baseline:

- Single-device HTTP/MQTT JSON-RPC bridge.
- OpenWrt/Linux context collection.
- Command and context registries.
- device.describe introspection.
- Structured JSON logs.
- Config validation.
- Schema documentation.

Near-term hardening:

- Runtime JSON Schema validation.
- Persistent audit log for HTTP/MQTT requests and command results.
- EdgePulse client adapter for edgepulse-ctl, then ubus or Unix socket.
- Replace direct mutation commands with EdgePulse policy-gated named actions where available.
- Command sandboxing beyond the initial allowlist.
- CLI utility for testing and debugging requests.

Fleet direction:

- Standalone MCP server mode outside OpenWrt.
- Device registry and explicit target selection.
- Rule-based access control for users, service accounts, devices, methods, and permissions.
- Tenant-aware config, tokens, MQTT routing, context caches, policies, and audit records.
- Multi-tenant fleet service operation.

Longer-term extensions:

- WebSocket transport for dashboards and live operations.
- Streaming telemetry metrics endpoint.
- Context delta compression for low-bandwidth MQTT.
- Secure boot and system integrity reporting.
- Scheduler support for recurring commands.