sdkwork-aiot: Servidor IoT com Suporte a Agentes e MCP
Sdkwork-Cloud/sdkwork-aiot
Servidor IoT com IA integrada e suporte MCP para ecossistema Xiaozhi
Ver no GitHubServidor IoT inteligente em Rust que integra capacidades de IA com dispositivos IoT, compatível com o Protocolo Xiaozhi. Oferece suporte nativo a Agentes de IA e servidores MCP, com simulador terminal cross-platform para testes locais de compatibilidade e gerenciamento de ativação com registros persistentes.
Instalação
npx convez-ai Sdkwork-Cloud/sdkwork-aiot1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Conectar dispositivos IoT (ESP32, gateways) a capacidades de IA e agentes Claude
- Testar compatibilidade de protocolos Xiaozhi em desenvolvimento local
- Orquestrar fluxos de trabalho entre IoT devices e ferramentas MCP
Veredito

Ferramenta especializada e bem-construída em Rust para quem precisa integrar IoT com IA. Adequada para integradores e construtores de ecosistemas IoT, mas requer familiaridade com Xiaozhi Protocol e infraestrutura em containers/cloud.
README
A tradução para o português deste README ainda está na fila.
sdkwork-aiot-server
Xiaozhi Gateway Simulator
The standalone gateway includes a cross-platform terminal UI simulator for local Xiaozhi compatibility checks.
Start the gateway:
$env:SDKWORK_AIOT_GATEWAY_BIND='127.0.0.1:18080'
cargo run -p sdkwork-aiot-gateway
Start the simulator UI (in another terminal):
$env:SDKWORK_AIOT_XIAOZHI_SIMULATOR_GATEWAY_HTTP='http://127.0.0.1:18080'
cargo run -p sdkwork-aiot-xiaozhi-simulator-ui
The simulator exercises the same compatibility surface used by ESP32 firmware:
- OTA metadata:
POST /iot/xiaozhi/ota - WebSocket session route:
/iot/xiaozhi/ws - Xiaozhi handshake headers or browser query parameters:
Protocol-Version,Device-Id,Client-Id,Authorization - Device-to-server messages:
hello,listen,abort,mcp, binary Opus frames - Server-to-device responses: server
hello,stt,llm,tts, MCPinitialize, MCPtools/list
Default simulator env overrides:
SDKWORK_AIOT_XIAOZHI_SIMULATOR_GATEWAY_HTTPSDKWORK_AIOT_XIAOZHI_SIMULATOR_PROTOCOL_VERSIONSDKWORK_AIOT_XIAOZHI_SIMULATOR_DEVICE_IDSDKWORK_AIOT_XIAOZHI_SIMULATOR_CLIENT_IDSDKWORK_AIOT_XIAOZHI_SIMULATOR_TOKEN
The legacy browser path GET /simulators/xiaozhi now returns migration JSON and
is no longer the primary simulator surface.
Xiaozhi Activation + MCP Config
The gateway now supports a restart-safe activation challenge registry and optional simulator MCP tool catalog override.
Activation challenge registry:
SDKWORK_AIOT_XIAOZHI_ACTIVATION_REGISTRY_PATH: optional file path used to persist OTA-issued activation challenges.SDKWORK_AIOT_XIAOZHI_ACTIVATION_REGISTRY_KIND: optional backend selector:file(default when path is set),sqlite, orredis.SDKWORK_AIOT_XIAOZHI_ACTIVATION_REGISTRY_REDIS_URL: Redis connection URL used when kind isredis, for exampleredis://127.0.0.1:6379/0.SDKWORK_AIOT_XIAOZHI_ACTIVATION_REGISTRY_REDIS_PREFIX: optional Redis key prefix (defaultsdkwork:aiot:xiaozhi:activation).SDKWORK_AIOT_XIAOZHI_ACTIVATION_REGISTRY_LOCK_WAIT_MILLIS: lock wait timeout for shared registry file (default2000).SDKWORK_AIOT_XIAOZHI_ACTIVATION_REGISTRY_LOCK_POLL_MILLIS: lock retry poll interval (default20).SDKWORK_AIOT_XIAOZHI_ACTIVATION_REGISTRY_LOCK_STALE_MILLIS: stale lock file eviction threshold (default30000).- If no durable backend is configured, the registry is in-memory only (old behavior).
Optional integration test with real Redis:
- Set
SDKWORK_AIOT_GATEWAY_TEST_REDIS_URL=redis://127.0.0.1:6379/0before runningcargo test -p sdkwork-aiot-gateway -- --nocapture --test-threads=1to enable the Redis-backed end-to-end activation registry test.
Simulator MCP tool catalog:
SDKWORK_AIOT_XIAOZHI_SIMULATOR_MCP_TOOLS_PATH: optional JSON file path for overriding built-in simulator tools.SDKWORK_AIOT_XIAOZHI_MCP_POLICY_RULES: optional inline policy rules for MCP tool allow/deny decisions.SDKWORK_AIOT_XIAOZHI_MCP_POLICY_LOG_ALLOW: when set to1/true/yes/on, emit allow decision logs for all MCP calls. By default, allow logs are emitted only when a concrete policy rule matched; deny logs are always emitted.- Supported JSON shapes:
- object root:
{ "tools": [ ... ] } - array root:
[ ... ]
- object root:
- Tool entry fields:
name,description,inputSchema,userOnly, optionalresultText. - If loading fails or file is empty, gateway falls back to built-in tools.
Policy rule format:
- Rules are
;-separated. - Each rule is
allow|...ordeny|.... - Supported predicates:
tool=<name>,transport=<websocket|mqtt>,device_prefix=<prefix>,client_prefix=<prefix>. - Numeric argument predicates are also supported:
arg_<field>_gt=<n>,arg_<field>_gte=<n>,arg_<field>_lt=<n>,arg_<field>_lte=<n>,arg_<field>_eq=<n>,arg_<field>_ne=<n>. - String argument predicates:
arg_<field>_str_eq=<text>,arg_<field>_str_ne=<text>,arg_<field>_str_prefix=<prefix>. - Boolean argument predicates:
arg_<field>_bool_eq=true|false,arg_<field>_bool_ne=true|false. - First matching rule wins. If no rule matches, tool call is allowed.
- Rule index in logs is zero-based.
Example:
deny|tool=self.reboot|transport=websocket;allow|tool=self.reboot|transport=websocket|device_prefix=lab-
Numeric threshold example:
deny|tool=self.audio_speaker.set_volume|transport=websocket|arg_volume_gt=80
For explicit assembly in custom bootstraps/tests, gateway now exposes
standard_gateway_server_with_plugins_activation_registry_and_mcp_tools(...)
to inject OTA provider, activation verifier, activation registry, and MCP tool
provider together.
When the bootstrap also needs to reuse the exact injected MCP provider across
long-running session loops, use
standard_gateway_server_and_session_options_with_plugins_activation_registry_and_mcp_tools(...)
and pass the returned session options into the option-aware WS/MQTT helpers.
For long-running websocket/MQTT loops, gateway session handlers can also reuse a
preloaded provider via XiaozhiSessionOptions:
XiaozhiSessionOptions::from_env(): load once from env/file fallback.XiaozhiSessionOptions::from_mcp_tool_provider_and_invoker(...): inject both tool catalog and custom execution layer for plugin-style tool call handling.XiaozhiSessionOptions::from_mcp_tool_provider_invoker_and_policy(...): additionally inject authorization policy hooks before tool execution.xiaozhi_websocket_session_reply_with_options(...): websocket reply path with injected options.xiaozhi_mqtt_session_reply_with_options(...): MQTT reply path with injected options.
Rule-based policy implementations also expose lightweight decision counters via
RuleBasedXiaozhiSimulatorMcpToolPolicy::stats_snapshot():
allow_by_rule_matchesallow_no_rule_matchesdeny_by_rule_matches
Gateway process endpoint for runtime visibility:
GET /internal/xiaozhi/mcp-policy/stats: returns current rule-based MCP policy counters when the active session policy supports stats.{"policy":"rule_based",...}when default rule-based policy is active.{"policy":"custom","stats_available":false}when a custom policy does not expose counters.
MQTT + UDP Bridge (Optional)
The gateway can run an optional MQTT+UDP compatibility bridge for
xiaozhi.mqtt_udp flows.
Enable it:
$env:SDKWORK_AIOT_GATEWAY_MQTT_BRIDGE_ENABLE='1'
cargo run -p sdkwork-aiot-gateway
Key runtime knobs:
SDKWORK_AIOT_GATEWAY_MQTT_HOST/SDKWORK_AIOT_GATEWAY_MQTT_PORTSDKWORK_AIOT_GATEWAY_MQTT_SUBSCRIBE_TOPIC/..._PUBLISH_TOPICSDKWORK_AIOT_GATEWAY_MQTT_RECONNECT_BASE_MILLIS/..._MAX_MILLISSDKWORK_AIOT_GATEWAY_MQTT_PUBLISH_RETRY_ATTEMPTS/..._RETRY_DELAY_MILLISSDKWORK_AIOT_GATEWAY_MQTT_MAX_OUTBOUND_PER_EVENTSDKWORK_AIOT_GATEWAY_MQTT_PUBLISH_DROP_COOLDOWN_MILLISSDKWORK_AIOT_GATEWAY_UDP_BINDSDKWORK_AIOT_GATEWAY_SESSION_IDLE_TIMEOUT_SECONDSSDKWORK_AIOT_GATEWAY_BRIDGE_STATS_LOG_INTERVAL_SECONDS
Behavior:
- MQTT reconnect uses exponential backoff with a cap.
- Publish failures are retried with bounded attempts.
- Per-event outbound publish fan-out is bounded (excess payloads are dropped and counted).
- UDP session state is purged after idle timeout.
- Bridge health counters are periodically logged to stderr.
- Bridge runtime health can be pulled via
GET /internal/bridge/health. - Bridge counters can be pulled via
GET /internal/bridge/stats. - Prometheus-style metrics can be pulled via
GET /internal/bridge/metrics.
SDKWork Documentation Contract
Domain: device Capability: aiot-runtime Package type: rust-crate Status: standard
Public API
Public exports are declared in specs/component.spec.json under contracts.publicExports.
Required SDK Surface
@sdkwork/aiot-app-sdk@sdkwork/aiot-backend-sdk
Configuration
Configuration keys and runtime entrypoints are declared in specs/component.spec.json.
SaaS/Private/Local Behavior
This module follows the canonical standards linked from specs/component.spec.json, including deployment and runtime configuration rules where applicable.
Security
Do not add secrets, live tokens, manual auth headers, or app-local credential handling to this module.
Extension Points
Extension points are limited to declared public exports, runtime entrypoints, SDK clients, events, and config keys.
Verification
cargo fmt --all -- --checkcargo test --workspacecargo check --workspace
Owner And Status
Owner and lifecycle status are tracked in specs/component.spec.json.