Bibliotecas Relacionadas e Ecossistema¶
Bem-vindo ao espaço do Ecossistema ESP32. Nossas bibliotecas compartilham a mesma filosofia de engenharia: baixo consumo de memória, zero alocações na heap em caminhos críticos, APIs fluentes em C++ e confiabilidade para ambientes de produção.
Se o seu ESP32 precisa consumir APIs remotas em nuvem ou expor seu próprio hardware diretamente para agentes autônomos de Inteligência Artificial, essas soluções complementares oferecem uma experiência moderna no desenvolvimento embarcado.
ESP32-MCP: Servidor Model Context Protocol¶
A ESP32-MCP transforma seu microcontrolador em um servidor nativo de alta performance que implementa o padrão Model Context Protocol (MCP) sobre HTTP. Em vez de configurar bridges complexas em Python ou Node.js em um computador intermediário, o ESP32 fala o protocolo MCP diretamente pela rede local.
Com isso, assistentes de IA como Claude Desktop, Cursor e agentes autônomos LLM conseguem descobrir ferramentas, ler sensores em tempo real e comutar portas GPIO sem a necessidade de nenhum servidor intermediário.
Exemplo de Uso Simples¶
Veja como é direto registrar uma ferramenta de controle de hardware e iniciar o servidor MCP. Com vinculação direta de variáveis (variable binding), você não precisa escrever parsers de JSON nem schemas manuais:
#include <Arduino.h>
#include <WiFi.h>
#include <ESP32MCP.h>
const char* ssid = "SEU_WIFI_SSID";
const char* password = "SUA_SENHA_WIFI";
// Inicializa o servidor com nome e versão
MCPServer server("ESP32-Controlador", "1.0.0");
static bool ledState = false;
void setup() {
Serial.begin(115200);
pinMode(LED_BUILTIN, OUTPUT);
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED) { delay(500); }
// Registra ferramenta de controle de hardware com binding direto de variável
server.tool("set_led", "Liga ou desliga o LED integrado")
.destructive()
.param("state", &ledState, "true para ligar, false para desligar")
.handle([](MCPResult& r) {
digitalWrite(LED_BUILTIN, ledState ? HIGH : LOW);
r.text("LED agora está %s", ledState ? "LIGADO" : "DESLIGADO");
});
// Habilita ferramenta nativa de diagnóstico (uptime, heap livre, RSSI)
server.enableStatus();
// Inicia o servidor HTTP e cria a tarefa FreeRTOS em segundo plano no Core 1
server.begin();
}
void loop() {
// Seu loop principal fica 100% livre para leituras de sensores e tarefas em tempo real
delay(1000);
}
Por que rodar o MCP diretamente no ESP32?¶
O Model Context Protocol (MCP) é um padrão aberto criado pela Anthropic que padroniza a forma como aplicações de IA descobrem e acionam ferramentas externas, contexto e dados operacionais.
Até agora, conectar dispositivos embarcados a esse ecossistema exigia rodar um script auxiliar em um PC. A ESP32-MCP elimina completamente esse intermediário:
- Controle Físico em Tempo Real: Dê aos assistentes de IA mãos seguras e estruturadas para interagir com o mundo físico.
- Depuração de Hardware via Linguagem Natural: Peça ao Claude ou Cursor para checar o nível de memória, medir a qualidade do sinal Wi-Fi ou acionar pinos de teste durante o desenvolvimento do firmware.
- Automação com Agentes Autônomos: Permita que sistemas multiagentes consultem sensores sob demanda sem necessidade de polling contínuo.
Diferenciais Técnicos e Arquitetura¶
1. Zero Alocações na Heap no Caminho Crítico¶
A estabilidade em sistemas embarcados depende de previsibilidade de memória. A ESP32-MCP executa zero alocações dinâmicas de heap (malloc, new, free) durante a descoberta e execução de ferramentas.
Todos os parsers e geradores operam sobre buffers estáticos pré-dimensionados. Em testes de estresse com 10.000 invocações consecutivas, a variação da heap foi de exatamente 0 bytes, eliminando falhas por fragmentação de RAM.
2. API Declarativa Fluente com Variable Binding¶
Chega de criar schemas JSON manuais, rotinas repetitivas de validação ou parsing de strings. Ao vincular variáveis C++ diretamente com .param("state", &ledState), a biblioteca cuida de validação de tipos, limites e conversão para bool, int, float, double e char*.
3. Execução Autônoma em Segundo Plano via FreeRTOS (Core 1)¶
Ao chamar server.begin(), a biblioteca cria uma tarefa FreeRTOS dedicada no Core 1. Seu loop() principal do Arduino nunca é bloqueado, permitindo que malhas de controle PID, rotinas de display e aquisição de sensores rodem com máxima prioridade.
4. Diagnósticos Nativos e Acesso Seguro a GPIO¶
server.enableStatus(): Registra instantaneamente a ferramentaget_statusreportando uptime, heap livre, modelo do chip, versão do firmware e RSSI do Wi-Fi.server.enableGpio({12, 13, 14}): Expõe controle seguro de pinos GPIO restrito exclusivamente à lista de pinos permitidos por você.
5. Segurança Reforçada para Ambientes Reais¶
- Autenticação Bearer em Tempo Constante: Previne ataques de temporização (timing attacks) via
server.bearer("seu-token-secreto"). - Proteção Estrita de CORS: Rejeita requisições cross-origin por padrão, a não ser que as origens sejam explicitamente liberadas via
server.allowOrigin(...). - Proteção de Carga Útil: Limites rígidos de tamanho de requisição respondem com HTTP 413 em tentativas de sobrecarga.
6. Conformidade Completa com a Especificação MCP¶
Implementa o protocolo MCP moderno (transporte HTTP sem estado, discovery via server/discover e cabeçalhos MCP-Protocol-Version), com suporte retrocompatível para clientes legados (initialize, notifications/initialized e ping).
A Stack Embarcada Completa de IA: Saída e Entrada¶
A combinação de ESP32-HTTP-Client e ESP32-MCP proporciona uma arquitetura bidirecional completa de IA para Internet das Coisas:
| Papel | Biblioteca | Direção do Tráfego | Objetivo Principal |
|---|---|---|---|
| Cliente de IA (Saída) | ESP32-HTTP-Client | ESP32 → LLM Remoto | O microcontrolador envia requisições para OpenAI, Claude, Gemini, DeepSeek ou Ollama, mapeando as respostas JSON diretamente em variáveis C++. |
| Servidor de Ferramentas (Entrada) | ESP32-MCP | Assistente de IA → Hardware ESP32 | Claude Desktop, Cursor ou agentes locais executam chamadas para descobrir comandos, ler telemetria e acionar atuadores no ESP32. |
Conectando Claude Desktop ou Cursor ao seu ESP32¶
Configure seu arquivo de clientes de IA local (como o claude_desktop_config.json):
{
"mcpServers": {
"esp32_device": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://192.168.1.150/mcp"
]
}
}
}
Uma vez configurado, o Claude ou Cursor detecta automaticamente as ferramentas set_led e get_status. Você pode interagir em linguagem natural:
"Verifique se a heap livre do ESP32 está acima de 150 KB e acenda o LED integrado."
O assistente formulará as chamadas de ferramentas e as executará em sequência no microcontrolador via rede local em tempo real.
Instalação¶
Adicione a dependência da ESP32-MCP no seu platformio.ini:
- No Arduino IDE, acesse Sketch > Include Library > Manage Libraries...
- Busque por
ESP32-MCPe clique em Install. - Como alternativa, baixe o repositório em formato ZIP no GitHub e adicione através de Sketch > Include Library > Add .ZIP Library...
Links do Projeto e Recursos¶
-
Model Context Protocol (MCP) para ESP32
Explore o código-fonte, abra issues e acompanhe o desenvolvimento da biblioteca no GitHub.