ESP32-C3 MCP Music Server

Корневой каталог этого проекта представляет собой MCP-сервер, предназначенный для управления воспроизведением музыки на аудиоклиенте ESP32-C3 через MQTT с помощью OpenClaw, Claude Desktop или других MCP-агентов.

Инструкции по прошивке ESP32-C3 находятся в esp32-c3-client/README.md.

Функции

• Отправка команд управления (воспроизведение, пауза, стоп, громкость, следующая песня и т.д.) на ESP32-C3 через MQTT

• Чтение списка песен из HTTP-каталога музыки

• Поддержка поиска и воспроизведения по названию песни

• Поддержка последовательного воспроизведения всего списка музыки

• Поддержка записи плейлиста в MQTT retained topic для автономного воспроизведения на ESP32-C3

• Поддержка сброса сохраненных настроек Wi-Fi на ESP32-C3 для повторного входа в режим настройки через смартфон

Требования

• Node.js 18 или выше

• Доступный MQTT-брокер

• Клиент ESP32-C3 прошит и подключен к тому же MQTT-брокеру

• HTTP-каталог музыки, например, директория с MP3-файлами, опубликованная через nginx

Установка

npm install

Скопируйте шаблон переменных окружения:

copy .env.example .env

В Windows PowerShell также можно использовать:

Copy-Item .env.example .env

Затем измените .env в соответствии с вашей конфигурацией.

Переменные окружения

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

Описание:

• MQTT_BROKER: Адрес подключения к MQTT-брокеру, поддерживаются URL с именем пользователя и паролем

• MQTT_TOPIC: Топик, в который ESP32-C3 получает команды управления

• MQTT_PLAYLIST_TOPIC: Префикс для retained-топика кэша плейлиста

• MUSIC_LIBRARY_URL: Адрес HTTP-каталога музыки, в конце можно не ставить /

• FETCH_TIMEOUT_MS: Тайм-аут для получения каталога музыки или файлов плейлиста

• MAX_PLAYLIST_FETCHES: Максимальное количество анализируемых файлов плейлистов

• MAX_PLAYLIST_ITEMS: Максимальное количество песен, кэшируемых при последовательном воспроизведении

Пример конфигурации MCP

В агентах, поддерживающих MCP stdio server, настройте команду следующим образом:

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

Если агент поддерживает переменные окружения, можно также поместить переменные из .env непосредственно в конфигурацию MCP-сервера.

Доступные инструменты

list_music_library

Сканирует MUSIC_LIBRARY_URL и возвращает список найденных названий песен и их URL.

play_music

Воспроизводит указанную песню. Можно передать:

• url: Воспроизвести этот URL напрямую

• song_name: Найти и воспроизвести по названию из музыкальной библиотеки

Если переданы и url, и song_name, приоритет отдается url.

play_song_from_library

Поиск и воспроизведение только по song_name из музыкальной библиотеки.

play_playlist

Последовательное воспроизведение списка музыкальной библиотеки.

Сначала список записывается в MQTT retained topic:

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

Затем в MQTT_TOPIC отправляется:

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

После получения ESP32-C3 начинает воспроизведение из локально кэшированного списка, автоматически переходя к следующей песне после завершения текущей. Таким образом, MCP-серверу не нужно быть постоянно онлайн.

Параметры:

• start_index: С какой песни начать, по умолчанию 0

• max_songs: Максимальное количество песен для кэширования и воспроизведения, по умолчанию MAX_PLAYLIST_ITEMS

next_music

Следующая песня или переключение трека.

• Передача url или song_name: Прямое переключение на указанную песню, сохраняя логику воспроизведения одного трека

• Без параметров: Отправка playlist_next, чтобы ESP32-C3 перешел к следующей песне в режиме плейлиста

pause_music

Приостановка воспроизведения. ESP32-C3 остановит текущее воспроизведение, но сохранит последний URL.

stop_music

Остановка воспроизведения и очистка последнего URL. Режим плейлиста также будет завершен.

set_volume

Установка громкости, диапазон 0-100.

reset_wifi

Отправка:

{"action":"reset_wifi"}

После получения ESP32-C3 очистит сохраненные настройки Wi-Fi и перезагрузится, после чего откроет точку доступа для настройки через смартфон.

Примечание: этот инструмент требует, чтобы ESP32-C3 оставался онлайн и был подключен к MQTT. Если устройство уже оффлайн, оно не получит это сообщение MQTT, и придется дождаться автоматического включения точки доступа после неудачного подключения прошивки.

Соглашение о сообщениях MQTT

Топик управления по умолчанию:

esp32-c3/music/play

Типовые сообщения управления:

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

Префикс топика плейлиста по умолчанию:

esp32-c3/music/playlist/active

MCP-сервер публикует retained-сообщения, на которые подписывается ESP32-C3:

esp32-c3/music/playlist/active/#

Локальная проверка

Проверка синтаксиса Node.js:

node --check index.js

В текущем package.json пока нет скриптов автоматического тестирования.