Servicio MCP (Protocolo de contexto de modelo) de NodeMCU

Un servicio de Protocolo de Contexto de Modelo (MCP) para la gestión de dispositivos NodeMCU. Este servicio proporciona una interfaz API/WebSocket RESTful estándar e implementa el Protocolo de Contexto de Modelo 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:

• Supervisar el estado del dispositivo y la telemetría

• Enviar comandos a dispositivos de forma remota

• Actualizar las configuraciones del dispositivo

• Integración con asistentes de IA a través del protocolo MCP

Related MCP server: MCP Personal Assistant Agent

Visualizaciones

Características

• 🔌 Administración de dispositivos : registre, monitoree y controle dispositivos NodeMCU

• 📊 Comunicación en tiempo real : Interfaz WebSocket para actualizaciones en tiempo real

• ⚙️ Gestión de configuración : actualice la configuración del dispositivo de forma remota

• 🔄 Ejecución de comandos : envía comandos de reinicio, actualización y estado de forma remota

• 📡 Recopilación de telemetría : recopile datos de sensores y métricas del dispositivo

• 🔐 Autenticación : Acceso seguro a la API con autenticación JWT

• 🧠 Integración de IA : trabaje con Claude Desktop y otras herramientas de IA compatibles con MCP

Inicio rápido

Prerrequisitos

• Node.js 16.x o superior

• npm o hilo

• Para el cliente NodeMCU: Arduino IDE con soporte ESP8266

Instalación

Instalación mediante herrería

Para instalar NodeMCU Manager para Claude Desktop automáticamente a través de Smithery :

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

De npm (una vez publicado)

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

# Local installation
npm install nodemcu-mcp

De la 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

Ejecutándose como servidor API

Modo de desarrollo con reinicio automático:

npm run dev

Modo de producción:

npm start

Ejecutándose como servidor MCP

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

npm run mcp

Si se instala 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 del Protocolo de contexto de modelo (MCP) para brindar integración con Claude for Desktop y otros clientes de MCP.

Herramientas MCP

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

• list-devices : enumera todos los dispositivos NodeMCU registrados y su estado

• get-device : obtiene información detallada sobre un dispositivo NodeMCU específico

• send-command : envía un comando a un dispositivo NodeMCU

• update-config : actualiza la configuración de un dispositivo NodeMCU

Uso con Claude para escritorio

Para utilizar este servidor con Claude for Desktop:

1. Instale Claude para escritorio desde https://claude.ai/desktop

2. Configure Claude para escritorio editando ~/Library/Application Support/Claude/claude_desktop_config.json :

{
  "mcpServers": {
    "nodemcu": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/YOUR/PROJECT/mcp_server_sdk.js"
      ]
    }
  }
}

3. Reiniciar Claude para escritorio

4. Ahora debería ver las herramientas NodeMCU en la interfaz de Claude for 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 el 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 el token JWT

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

API de dispositivos

Todos los puntos finales del dispositivo requieren autenticación con un token JWT:

Authorization: Bearer your.jwt.token

Lista de 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

Pedido:

{
  "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 boceto de Arduino en el directorio examples para obtener una implementación completa del cliente.

Pasos clave

1. Instalar las bibliotecas necesarias en Arduino IDE:

   • ESP8266WiFi

   • Cliente WebSockets

   • ArduinoJson

2. Configura el boceto con tu configuración WiFi y del 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. Sube el boceto a tu 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

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

1. Bifurcar el repositorio

2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )

3. Confirme sus cambios ( git commit -m 'Add some amazing feature' )

4. Empujar a la rama ( git push origin feature/amazing-feature )

5. Abrir una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

La licencia MIT es una licencia permisiva que le permite:

• Utilizar el software con fines comerciales

• Modificar el software

• Distribuir el software

• Utilizar y modificar el software de forma privada

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

Expresiones de gratitud

• Protocolo de contexto del modelo para la especificación de integración

• NodeMCU para la increíble plataforma IoT

• Antrópico para Claude Desktop