esp cyd mcp

Una implementación integral de servidor de Model Context Protocol (MCP) para la placa ESP32 CYD (Cheap Yellow Display). Este proyecto proporciona amplias capacidades de control remoto para la placa ESP32-2432S028R a través de una interfaz MCP basada en WebSocket.

GitHub
12
Prueba este MCPPatrocinado

Documentación

Servidor MCP ESP32 CYD

Una implementación integral de servidor de Protocolo de Contexto de Modelo (MCP) para la placa ESP32 CYD (Pantalla Amarilla Económica). Este proyecto proporciona amplias capacidades de control remoto para la placa ESP32-2432S028R a través de una interfaz MCP basada en WebSocket.

Características

Núcleo del Servidor MCP

  • Implementación del protocolo MCP basada en WebSocket
  • Compatible con JSON-RPC 2.0
  • Comunicación bidireccional en tiempo real
  • Soporte para múltiples clientes
  • Notificaciones de eventos

Categorías de Herramientas

Herramientas de Pantalla (más de 20 herramientas)

  • display.clear - Limpiar pantalla con color
  • display.text - Dibujar texto con posicionamiento y estilo
  • display.line - Dibujar líneas con grosor
  • display.rectangle - Dibujar contornos de rectángulos
  • display.fillRectangle - Dibujar rectángulos rellenos
  • display.circle - Dibujar contornos de círculos
  • display.fillCircle - Dibujar círculos rellenos
  • display.pixel - Dibujar píxeles individuales
  • display.backlight - Controlar retroiluminación encendida/apagada
  • display.brightness - Establecer brillo de pantalla (0-255)
  • display.rotation - Establecer rotación de pantalla (0-3)
  • display.progressBar - Dibujar barras de progreso
  • display.info - Obtener información de pantalla

Herramientas Táctiles (más de 10 herramientas)

  • touch.getState - Obtener estado táctil actual
  • touch.enable - Habilitar/deshabilitar entrada táctil
  • touch.calibrate - Calibrar pantalla táctil
  • touch.getHistory - Obtener eventos táctiles recientes
  • touch.simulate - Simular eventos táctiles
  • touch.getCalibration - Obtener valores de calibración
  • touch.saveCalibration - Guardar calibración en archivo
  • Detección de gestos (soporte de deslizamiento)

Herramientas GPIO (más de 15 herramientas)

  • gpio.pinMode - Establecer modo de pin (entrada/salida/PWM)
  • gpio.digitalWrite - Escribir valor digital
  • gpio.digitalRead - Leer valor digital
  • gpio.analogWrite - Salida PWM
  • gpio.analogRead - Leer valor analógico
  • gpio.attachInterrupt - Adjuntar interrupciones
  • gpio.setPWM - Configurar PWM con frecuencia
  • gpio.tone - Generar tonos
  • gpio.pulseIn - Medir duración de pulso

Herramientas de Sensores (más de 10 herramientas)

  • sensor.readTemperature - Leer sensor de temperatura
  • sensor.readLight - Leer sensor de luz
  • sensor.readInternalTemp - Temperatura interna del ESP32
  • sensor.readHallSensor - Sensor Hall incorporado
  • sensor.readBatteryVoltage - Voltaje de fuente de alimentación
  • sensor.readAll - Leer todos los sensores a la vez
  • sensor.calibrate - Calibrar sensores
  • sensor.getEnvironment - Resumen ambiental

Herramientas de Red (más de 15 herramientas)

  • network.status - Obtener estado de red
  • network.connect - Conectar a WiFi
  • network.scan - Escanear redes
  • network.startAP - Iniciar punto de acceso
  • network.httpRequest - Realizar solicitudes HTTP
  • network.ping - Hacer ping a hosts
  • network.getTime - Obtener hora NTP
  • network.setMDNS - Configurar mDNS

Herramientas del Sistema (más de 20 herramientas)

  • system.info - Información integral del sistema
  • system.restart - Reiniciar ESP32
  • system.sleep - Modos de suspensión profunda/ligera
  • system.memory - Estadísticas de memoria
  • system.tasks - Información de tareas FreeRTOS
  • system.setCPUFrequency - Control de velocidad de CPU
  • system.performanceMode - Optimización de rendimiento
  • system.factoryReset - Restablecimiento de fábrica

Herramientas de Archivos (más de 15 herramientas)

  • file.list - Listar archivos/directorios
  • file.read - Leer contenido de archivos
  • file.write - Escribir en archivo
  • file.delete - Eliminar archivos
  • file.mkdir - Crear directorios
  • file.copy - Copiar archivos
  • file.storage - Estadísticas de almacenamiento
  • Soporte para SPIFFS y tarjeta SD

Herramientas de Audio (más de 15 herramientas)

  • audio.tone - Reproducir tono único
  • audio.playMelody - Reproducir melodías
  • audio.beep - Sonidos de pitido simples
  • audio.playPattern - Patrones de tono personalizados
  • audio.notification - Sonidos de notificación
  • audio.alarm - Patrones de alarma
  • audio.setVolume - Control de volumen
  • Melodías predefinidas (Mario, Star Wars, etc.)

Requisitos de Hardware

  • Placa ESP32-2432S028R (CYD)
  • Pantalla TFT ILI9341 de 2.8" (240x320)
  • Controlador táctil resistivo XPT2046
  • Opcional: Tarjeta SD para almacenamiento de archivos
  • Opcional: Sensores externos (temperatura, luz)

Instalación

  1. Instalar PlatformIO o Arduino IDE
  2. Clonar este repositorio
  3. Abrir el proyecto en PlatformIO
  4. Compilar y subir a su placa ESP32 CYD
git clone https://github.com/yourusername/esp32-cyd-mcp
cd esp32-cyd-mcp
pio run -t upload

Configuración

Editar include/config.h para personalizar:

  • Credenciales WiFi
  • Asignaciones de pines
  • Puertos del servidor
  • Configuración de pantalla
  • Calibración de sensores

Uso

Conexión al Servidor MCP

  1. Encender la placa ESP32 CYD
  2. Conectar a WiFi o usar el modo AP
  3. Encontrar la dirección IP del dispositivo en la pantalla
  4. Conectar vía WebSocket a ws://[IP]:3001

Ejemplo de Solicitud MCP

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/invoke",
  "params": {
    "name": "display.text",
    "arguments": {
      "text": "Hello MCP!",
      "x": 50,
      "y": 100,
      "color": "white",
      "size": 2
    }
  }
}

Uso con Claude Desktop

Agregar a su configuración de Claude Desktop:

{
  "mcpServers": {
    "esp32-cyd": {
      "command": "websocat",
      "args": ["ws://192.168.1.100:3001"]
    }
  }
}

Documentación de la API

Invocación de Herramientas

Todas las herramientas se invocan usando el método estándar MCP tools/invoke:

{
  "method": "tools/invoke",
  "params": {
    "name": "tool.name",
    "arguments": { ... }
  }
}

Notificaciones de Eventos

El servidor envía notificaciones para varios eventos:

  • touch.event - Eventos de entrada táctil
  • sensor.update - Actualizaciones periódicas de sensores
  • network.event - Cambios de estado de red
  • gpio.interrupt - Eventos de interrupción GPIO

Desarrollo

Agregar Nuevas Herramientas

  1. Crear archivo de encabezado en include/tools/
  2. Implementar en src/tools/
  3. Registrar herramientas en el método registerTools()
  4. Agregar inicialización en main.cpp

Estructura del Proyecto

esp32-cyd-mcp/
├── include/
│   ├── config.h           # Configuration
│   ├── mcp_server.h       # MCP server core
│   └── tools/            # Tool headers
├── src/
│   ├── main.cpp          # Main application
│   ├── mcp_server.cpp    # MCP implementation
│   └── tools/           # Tool implementations
├── platformio.ini        # PlatformIO config
└── README.md

Solución de Problemas

  • Problemas de Conexión WiFi: Verificar credenciales en config.h
  • Táctil No Funciona: Ejecutar herramienta de calibración táctil
  • Problemas de Pantalla: Verificar configuración de rotación de pantalla
  • Problemas de Memoria: Monitorear heap libre, reducir uso de herramientas

Licencia

Este proyecto es de código abierto y está disponible bajo la Licencia MIT.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, envíe solicitudes de extracción o abra problemas para errores y solicitudes de funciones.

Agradecimientos

  • Comunidad ESP32 por el soporte de hardware
  • Biblioteca TFT_eSPI para controladores de pantalla
  • Especificación MCP para el diseño del protocolo