Servidor de música MCP ESP32-C3

El directorio raíz de este proyecto es un servidor MCP, utilizado para permitir que OpenClaw, Claude Desktop u otros agentes MCP controlen un cliente de audio ESP32-C3 para reproducir música a través de MQTT.

Las instrucciones del firmware del ESP32-C3 se encuentran en esp32-c3-client/README.md.

Funcionalidades

• Enviar comandos de control como reproducir, pausar, detener, volumen y siguiente canción al ESP32-C3 a través de MQTT.

• Leer la lista de canciones desde un directorio de música HTTP.

• Soporte para buscar y reproducir por nombre de canción.

• Soporte para reproducción secuencial de toda la lista de música.

• Soporte para escribir listas de reproducción en un topic retenido de MQTT, para que el ESP32-C3 las reproduzca secuencialmente por sí mismo.

• Soporte para borrar la configuración Wi-Fi guardada en el ESP32-C3 y volver al modo de configuración por teléfono.

Requisitos de ejecución

• Node.js 18 o superior.

• Un broker MQTT accesible.

• Cliente ESP32-C3 flasheado y conectado al mismo broker MQTT.

• Un directorio de música HTTP, por ejemplo, un directorio de archivos MP3 expuesto por nginx.

Instalación

npm install

Copiar la plantilla de variables de entorno:

copy .env.example .env

En Windows PowerShell también puedes usar:

Copy-Item .env.example .env

Luego, modifica .env según tu situación real.

Variables de entorno

MQTT_BROKER=mqtt://esp32:esp32mqtt2026@localhost:1883
MQTT_TOPIC=esp32-c3/music/play
MQTT_PLAYLIST_TOPIC=esp32-c3/music/playlist/active
MUSIC_LIBRARY_URL=http://47.102.147.204:8080/mp3/
FETCH_TIMEOUT_MS=8000
MAX_PLAYLIST_FETCHES=3
MAX_PLAYLIST_ITEMS=50

Descripción:

• MQTT_BROKER: Dirección de conexión del broker MQTT, admite URL con nombre de usuario y contraseña.

• MQTT_TOPIC: Topic donde el ESP32-C3 recibe los comandos de control.

• MQTT_PLAYLIST_TOPIC: Prefijo del topic de caché retenido para listas de reproducción.

• MUSIC_LIBRARY_URL: Dirección del directorio de música HTTP, puede no incluir / al final.

• FETCH_TIMEOUT_MS: Tiempo de espera para obtener el directorio de música o archivos de lista de reproducción.

• MAX_PLAYLIST_FETCHES: Cantidad máxima de archivos de lista de reproducción a analizar.

• MAX_PLAYLIST_ITEMS: Cantidad máxima de canciones a almacenar en caché durante la reproducción secuencial.

Ejemplo de configuración MCP

En agentes que admiten servidores MCP stdio, configura el comando como:

{
  "mcpServers": {
    "esp32-c3-music": {
      "command": "node",
      "args": ["D:\\ESP32-C3-MCP\\index.js"],
      "cwd": "D:\\ESP32-C3-MCP"
    }
  }
}

Si el agente admite variables de entorno, también puedes colocar las variables de .env directamente en la configuración del servidor MCP.

Herramientas disponibles

list_music_library

Escanea MUSIC_LIBRARY_URL y devuelve los nombres de las canciones y las URL encontradas.

play_music

Reproduce una canción específica. Puedes pasar:

• url: Reproduce esta URL directamente.

• song_name: Busca y reproduce por nombre desde la biblioteca de música.

Si se pasan tanto url como song_name, se prioriza la url.

play_song_from_library

Busca y reproduce solo por song_name desde la biblioteca de música.

play_playlist

Reproduce la lista de la biblioteca de música en orden.

Primero escribe la lista en un topic retenido de MQTT:

esp32-c3/music/playlist/active/meta
esp32-c3/music/playlist/active/item/0
esp32-c3/music/playlist/active/item/1

Luego envía al MQTT_TOPIC:

{"action":"play_playlist","start_index":0}

Una vez que el ESP32-C3 lo recibe, comenzará a reproducir desde la lista almacenada localmente y, al terminar la canción actual, reproducirá la siguiente por sí mismo. De esta manera, el servidor MCP no necesita estar siempre en línea.

Parámetros:

• start_index: Desde qué canción comenzar, por defecto 0.

• max_songs: Cantidad máxima de canciones a almacenar y reproducir, por defecto MAX_PLAYLIST_ITEMS.

next_music

Siguiente canción o cambio de pista.

• Pasar url o song_name: Cambia directamente a la canción especificada, manteniendo la lógica original de reproducción de una sola canción.

• No pasar parámetros: Envía playlist_next, permitiendo que el ESP32-C3 salte a la siguiente canción en modo de lista de reproducción.

pause_music

Pausa la reproducción. El ESP32-C3 detendrá la reproducción actual, pero conservará la última URL.

stop_music

Detiene la reproducción y borra la última URL. También saldrá del modo de lista de reproducción.

set_volume

Establece el volumen, rango 0-100.

reset_wifi

Envía:

{"action":"reset_wifi"}

Una vez que el ESP32-C3 lo recibe, borrará la configuración Wi-Fi guardada y se reiniciará; tras el reinicio, activará el punto de acceso para la configuración por teléfono.

Nota: Esta herramienta requiere que el ESP32-C3 esté actualmente en línea y conectado a MQTT. Si el dispositivo ya está desconectado, no recibirá este mensaje MQTT y solo podrá activar el punto de acceso de configuración automáticamente después de que el firmware falle al conectarse.

Convención de mensajes MQTT

El topic de control por defecto es:

esp32-c3/music/play

Mensajes de control comunes:

{"action":"play","url":"http://example.com/song.mp3"}
{"action":"next","url":"http://example.com/next.mp3"}
{"action":"pause"}
{"action":"stop"}
{"action":"set_volume","volume":65}
{"action":"play_playlist","start_index":0}
{"action":"playlist_next"}
{"action":"reset_wifi"}

El prefijo por defecto para el topic de lista de reproducción es:

esp32-c3/music/playlist/active

El servidor MCP publicará mensajes retenidos, a los cuales el ESP32-C3 se suscribe:

esp32-c3/music/playlist/active/#

Verificación local

Verificar la sintaxis de Node.js:

node --check index.js

Actualmente, package.json aún no tiene scripts de prueba automatizados.