NodeMCU MCP

Um serviço MCP para gerenciar dispositivos IoT NodeMCU (ESP8266).

GitHub
1
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

Serviço NodeMCU MCP (Model Context Protocol)

NodeMCU MCP Logo

GitHub license npm version smithery badge

Um serviço Model Context Protocol (MCP) para gerenciar dispositivos NodeMCU. Este serviço fornece tanto uma interface RESTful API/WebSocket padrão quanto implementa o Model Context Protocol para integração com ferramentas de IA como o Claude Desktop.

Visão Geral

O NodeMCU MCP fornece uma solução de gerenciamento para dispositivos IoT ESP8266/NodeMCU com estas capacidades principais:

  • Monitorar status e telemetria dos dispositivos
  • Enviar comandos para dispositivos remotamente
  • Atualizar configurações dos dispositivos
  • Integração com assistentes de IA através do protocolo MCP

Visualizações

NodeMCU MCP Architecture
Visão Geral da Arquitetura do Sistema

NodeMCU MCP Data Flow
Fluxo de Dados Entre Componentes

Claude + NodeMCU MCP Workflow
Como o Claude Desktop Interage com Dispositivos NodeMCU

Recursos

  • 🔌 Gerenciamento de Dispositivos: Registrar, monitorar e controlar dispositivos NodeMCU
  • 📊 Comunicação em Tempo Real: Interface WebSocket para atualizações em tempo real
  • ⚙️ Gerenciamento de Configuração: Atualizar configurações dos dispositivos remotamente
  • 🔄 Execução de Comandos: Enviar comandos de reinicialização, atualização e status remotamente
  • 📡 Coleta de Telemetria: Coletar dados de sensores e métricas dos dispositivos
  • 🔐 Autenticação: Acesso seguro à API com autenticação JWT
  • 🧠 Integração com IA: Trabalhe com Claude Desktop e outras ferramentas de IA compatíveis com MCP

Início Rápido

Pré-requisitos

  • Node.js 16.x ou superior
  • npm ou yarn
  • Para o cliente NodeMCU: Arduino IDE com suporte para ESP8266

Instalação

Instalando via Smithery

Para instalar o NodeMCU Manager para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @amanasmuei/nodemcu-mcp --client claude

Via npm (quando publicado)

# Global installation (recommended for MCP integration)
npm install -g nodemcu-mcp

# Local installation
npm install nodemcu-mcp

A partir do código-fonte

# Clone the repository
git clone https://github.com/amanasmuei/nodemcu-mcp.git
cd nodemcu-mcp

# Install dependencies
npm install

# Optional: Install globally for MCP integration
npm install -g .

Configuração

  1. Crie um arquivo .env baseado no exemplo:

    cp .env.example .env

  2. Atualize o arquivo .env com suas configurações:

    # Server Configuration
PORT=3000
HOST=localhost

# Security
JWT_SECRET=your_strong_random_secret_key

# Log Level (error, warn, info, debug)
LOG_LEVEL=info

Uso

Executando como Servidor de API

Modo de desenvolvimento com reinicialização automática:

npm run dev

Modo de produção:

npm start

Executando como Servidor MCP

Para integração com Claude Desktop ou outros clientes MCP:

npm run mcp

Se instalado globalmente:

nodemcu-mcp --mode=mcp

Opções de Linha de Comando

Usage: nodemcu-mcp [options]

Options:
  -m, --mode   Run mode (mcp, api, both)  [string] [default: "both"]
  -p, --port   Port for API server        [number] [default: 3000]
  -h, --help   Show help                  [boolean]
  --version    Show version number        [boolean]

Integração MCP

Este projeto agora usa o SDK oficial TypeScript do Model Context Protocol (MCP) para fornecer integração com Claude para Desktop e outros clientes MCP.

Ferramentas MCP

As seguintes ferramentas estão disponíveis através da interface MCP:

  • list-devices: Listar todos os dispositivos NodeMCU registrados e seu status
  • get-device: Obter informações detalhadas sobre um dispositivo NodeMCU específico
  • send-command: Enviar um comando para um dispositivo NodeMCU
  • update-config: Atualizar a configuração de um dispositivo NodeMCU

Usando com Claude para Desktop

Para usar este servidor com Claude para Desktop:

  1. Instale o Claude para Desktop em https://claude.ai/desktop
  2. Configure o Claude para Desktop editando ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "nodemcu": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/YOUR/PROJECT/mcp_server_sdk.js"
      ]
    }
  }
}
  1. Reinicie o Claude para Desktop
  2. Agora você deve ver as ferramentas NodeMCU na interface do Claude para Desktop

Executando o Servidor MCP de Forma Independente

Para executar o servidor MCP diretamente:

npm run mcp

Ou usando a CLI:

./bin/cli.js --mode=mcp

Documentação da API

Autenticação

  • POST /api/auth/login - Login e obtenção de token JWT

    {
  "username": "admin",
  "password": "admin123"
}

    Resposta:

    {
  "message": "Login successful",
  "token": "your.jwt.token",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin"
  }
}

  • POST /api/auth/validate - Validar token JWT

    {
  "token": "your.jwt.token"
}

API de Dispositivos

Todos os endpoints de dispositivos exigem autenticação com token JWT:

Authorization: Bearer your.jwt.token

Listar Dispositivos

GET /api/devices

Resposta:

{
  "count": 1,
  "devices": [
    {
      "id": "nodemcu-001",
      "name": "Living Room Sensor",
      "type": "ESP8266",
      "status": "online",
      "ip": "192.168.1.100",
      "firmware": "1.0.0",
      "lastSeen": "2023-05-15T14:30:45.123Z"
    }
  ]
}

Obter Detalhes do Dispositivo

GET /api/devices/:id

Resposta:

{
  "id": "nodemcu-001",
  "name": "Living Room Sensor",
  "type": "ESP8266",
  "status": "online",
  "ip": "192.168.1.100",
  "firmware": "1.0.0",
  "lastSeen": "2023-05-15T14:30:45.123Z",
  "config": {
    "reportInterval": 30,
    "debugMode": false,
    "ledEnabled": true
  },
  "lastTelemetry": {
    "temperature": 23.5,
    "humidity": 48.2,
    "uptime": 3600,
    "heap": 35280,
    "rssi": -68
  }
}

Enviar Comando para o Dispositivo

POST /api/devices/:id/command

Solicitação:

{
  "command": "restart",
  "params": {}
}

Resposta:

{
  "message": "Command sent to device",
  "command": "restart",
  "params": {},
  "response": {
    "success": true,
    "message": "Device restarting"
  }
}

Protocolo WebSocket

O servidor WebSocket está disponível no caminho raiz: ws://your-server:3000/

Para detalhes sobre as mensagens do protocolo WebSocket, consulte o código ou o diretório de exemplos.

Configuração do Cliente NodeMCU

Consulte o sketch Arduino no diretório examples para uma implementação completa do cliente.

Etapas Principais

  1. Instale as bibliotecas necessárias no Arduino IDE:

    • ESP8266WiFi
    • WebSocketsClient
    • ArduinoJson

  2. Configure o sketch com suas configurações de WiFi e servidor:

    // WiFi credentials
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";

// MCP Server settings
const char* mcpHost = "your-server-ip";
const int mcpPort = 3000;

  3. Envie o sketch para o seu dispositivo NodeMCU

Desenvolvimento

Estrutura do Projeto

nodemcu-mcp/
├── assets/             # Logo and other static assets
├── bin/                # CLI scripts
├── examples/           # Example client code
├── middleware/         # Express middleware
├── routes/             # API routes
├── services/           # Business logic
├── .env.example        # Environment variables example
├── index.js            # API server entry point
├── mcp_server.js       # MCP protocol implementation
├── mcp-manifest.json   # MCP manifest
└── package.json        # Project configuration

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

  1. Faça um fork do repositório
  2. Crie sua branch de recurso (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
  4. Envie para a branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

A Licença MIT é uma licença permissiva que permite que você:

  • Use o software comercialmente
  • Modifique o software
  • Distribua o software
  • Use e modifique o software privadamente

O único requisito é que a licença e o aviso de direitos autorais devem ser incluídos com o software.

Agradecimentos