ESP32-C3 MCP 뮤직 서버

이 프로젝트의 루트 디렉토리는 MCP 서버로, OpenClaw, Claude Desktop 또는 기타 MCP 에이전트가 MQTT를 통해 ESP32-C3 오디오 클라이언트를 제어하여 음악을 재생할 수 있도록 합니다.

ESP32-C3 펌웨어 설명은 esp32-c3-client/README.md에 있습니다.

기능

• MQTT를 통해 ESP32-C3에 재생, 일시 정지, 정지, 볼륨, 다음 곡 등의 제어 명령 전송

• HTTP 음악 디렉토리에서 노래 목록 읽기

• 노래 이름으로 검색 및 재생 지원

• 전체 음악 목록 순차 재생 지원

• 재생 목록을 MQTT retained topic에 기록하여 ESP32-C3가 스스로 순차 재생하도록 지원

• ESP32-C3에 저장된 Wi-Fi 설정을 삭제하고 휴대폰 네트워크 설정 모드로 재진입 지원

실행 요구 사항

• Node.js 18 이상

• 접근 가능한 MQTT 브로커

• ESP32-C3 클라이언트가 펌웨어로 구워져 있고 동일한 MQTT 브로커에 연결되어 있어야 함

• HTTP 음악 디렉토리 (예: nginx로 노출된 MP3 파일 디렉토리)

설치

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가 제어 명령을 수신하는 topic

• MQTT_PLAYLIST_TOPIC: 재생 목록 retained 캐시 topic 접두사

• 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 메시지 규약

제어 topic 기본값:

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

재생 목록 topic 기본 접두사:

esp32-c3/music/playlist/active

MCP 서버는 retained 메시지를 게시하고, ESP32-C3는 이를 구독합니다:

esp32-c3/music/playlist/active/#

로컬 검사

Node.js 문법 검사:

node --check index.js

현재 package.json에는 자동화된 테스트 스크립트가 없습니다.