NodeMCU MCP

Un servicio MCP para gestionar dispositivos IoT NodeMCU (ESP8266).

GitHub
1
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge

Servicio NodeMCU MCP (Model Context Protocol)

NodeMCU MCP Logo

GitHub license npm version smithery badge

Un servicio de Model Context Protocol (MCP) para gestionar dispositivos NodeMCU. Este servicio proporciona tanto una interfaz RESTful API/WebSocket estándar como implementa el Model Context Protocol para la integración con herramientas de IA como Claude Desktop.

Descripción General

NodeMCU MCP proporciona una solución de gestión para dispositivos IoT ESP8266/NodeMCU con estas capacidades clave:

  • Monitorear el estado y la telemetría de los dispositivos
  • Enviar comandos a los dispositivos de forma remota
  • Actualizar las configuraciones de los dispositivos
  • Integración con asistentes de IA a través del protocolo MCP

Visualizaciones

NodeMCU MCP Architecture
Descripción General de la Arquitectura del Sistema

NodeMCU MCP Data Flow
Flujo de Datos Entre Componentes

Claude + NodeMCU MCP Workflow
Cómo Interactúa Claude Desktop con los Dispositivos NodeMCU

Características

  • 🔌 Gestión de Dispositivos: Registrar, monitorear y controlar dispositivos NodeMCU
  • 📊 Comunicación en Tiempo Real: Interfaz WebSocket para actualizaciones en tiempo real
  • ⚙️ Gestión de Configuración: Actualizar la configuración de los dispositivos de forma remota
  • 🔄 Ejecución de Comandos: Enviar comandos de reinicio, actualización y estado de forma remota
  • 📡 Recopilación de Telemetría: Recopilar datos de sensores y métricas de dispositivos
  • 🔐 Autenticación: Acceso seguro a la API con autenticación JWT
  • 🧠 Integración con IA: Trabajar con Claude Desktop y otras herramientas de IA compatibles con MCP

Inicio Rápido

Requisitos Previos

  • Node.js 16.x o superior
  • npm o yarn
  • Para el cliente NodeMCU: Arduino IDE con soporte para ESP8266

Instalación

Instalación mediante Smithery

Para instalar NodeMCU Manager para Claude Desktop automáticamente mediante Smithery:

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

Desde npm (una vez publicado)

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

# Local installation
npm install nodemcu-mcp

Desde el código fuente

# 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 .

Configuración

  1. Cree un archivo .env basado en el ejemplo:

    cp .env.example .env

  2. Actualice el archivo .env con su configuración:

    # Server Configuration
PORT=3000
HOST=localhost

# Security
JWT_SECRET=your_strong_random_secret_key

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

Uso

Ejecución como Servidor API

Modo de desarrollo con reinicio automático:

npm run dev

Modo de producción:

npm start

Ejecución como Servidor MCP

Para la integración con Claude Desktop u otros clientes MCP:

npm run mcp

Si está instalado globalmente:

nodemcu-mcp --mode=mcp

Opciones de Línea de Comandos

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]

Integración MCP

Este proyecto ahora utiliza el SDK oficial de TypeScript de Model Context Protocol (MCP) para proporcionar integración con Claude para Desktop y otros clientes MCP.

Herramientas MCP

Las siguientes herramientas están disponibles a través de la interfaz MCP:

  • list-devices: Listar todos los dispositivos NodeMCU registrados y su estado
  • get-device: Obtener información detallada sobre un dispositivo NodeMCU específico
  • send-command: Enviar un comando a un dispositivo NodeMCU
  • update-config: Actualizar la configuración de un dispositivo NodeMCU

Uso con Claude para Desktop

Para usar este servidor con Claude para Desktop:

  1. Instale Claude para Desktop desde https://claude.ai/desktop
  2. Configure 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 Claude para Desktop
  2. Ahora debería ver las herramientas NodeMCU en la interfaz de Claude para Desktop

Ejecución del Servidor MCP de Forma Independiente

Para ejecutar el servidor MCP directamente:

npm run mcp

O usando la CLI:

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

Documentación de la API

Autenticación

  • POST /api/auth/login - Iniciar sesión y obtener token JWT

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

    Respuesta:

    {
  "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 los endpoints de dispositivos requieren autenticación con un token JWT:

Authorization: Bearer your.jwt.token

Listar Dispositivos

GET /api/devices

Respuesta:

{
  "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"
    }
  ]
}

Obtener Detalles del Dispositivo

GET /api/devices/:id

Respuesta:

{
  "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 al Dispositivo

POST /api/devices/:id/command

Solicitud:

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

Respuesta:

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

Protocolo WebSocket

El servidor WebSocket está disponible en la ruta raíz: ws://your-server:3000/

Para obtener detalles sobre los mensajes del protocolo WebSocket, consulte el código o el directorio de ejemplos.

Configuración del Cliente NodeMCU

Consulte el sketch de Arduino en el directorio examples para una implementación completa del cliente.

Pasos Clave

  1. Instale las bibliotecas requeridas en Arduino IDE:

    • ESP8266WiFi
    • WebSocketsClient
    • ArduinoJson

  2. Configure el sketch con su configuración de WiFi y 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. Suba el sketch a su dispositivo NodeMCU

Desarrollo

Estructura del Proyecto

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

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar una Solicitud de Extracción (Pull Request).

  1. Haga un fork del repositorio
  2. Cree su rama de características (git checkout -b feature/amazing-feature)
  3. Realice sus cambios (git commit -m 'Add some amazing feature')
  4. Envíe a la rama (git push origin feature/amazing-feature)
  5. Abra una Solicitud de Extracción (Pull Request)

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para obtener más detalles.

La Licencia MIT es una licencia permisiva que le permite:

  • Usar el software comercialmente
  • Modificar el software
  • Distribuir el software
  • Usar y modificar el software de forma privada

El único requisito es que la licencia y el aviso de derechos de autor deben incluirse con el software.

Agradecimientos