mcp_audio_server

# MCP Audio Server An independent MCP Audio Server example project, providing music search and paginated audio reading capabilities. This project was separated from `xiaozhi-esp32-server-golang/examples/mcp_audio` and organized into a standalone Go project, suitable for direct testing and as a template for your own audio MCP Server. ## Features - Provides the `musicPlayer` tool - Returns playable audio resources via `ResourceLink` - Paginated reading of audio data through `resource/read` - Returns `BlobResourceContents`, where `Blob` is base64 encoded - Supports both `stdio` and Streamable HTTP transport methods ## Tools and Resources ### Tool: `musicPlayer` Input: ```json { "query": "Jay Chou" } ``` Output: - `ResourceLink.URI`: `resource://read_from_http` - `ResourceLink.Name`: Actual song name - `ResourceLink.Description`: Actual audio URL - `ResourceLink.MIMEType`: `audio/mpeg` ### Resource: `resource://read_from_http` Paginated reading of audio content through `resource/read`, with parameters in `Arguments`: ```json { "url": "https://example.com/audio.mp3", "start": 0, "end": 102400 } ``` Output is `BlobResourceContents`: - `MIMEType`: `audio/mpeg` - `Blob`: base64 encoded audio binary When the server returns empty data, it will return base64 encoded `[DONE]` as a stream end marker. ## Environment Requirements - Go 1.24+ - Accessible external music search and audio links ## Install Dependencies ```bash go mod tidy ``` ## Running ### 1. `stdio` Mode Default is `stdio`: ```bash go run . ``` ### 2. HTTP Mode ```bash go run . -t http ``` or ```bash go run . --transport http ``` In HTTP mode: - Listening port: `3001` - MCP path: `/mcp` - Full address: `http://localhost:3001/mcp` ## Call Flow 1. Client calls `musicPlayer` 2. Server searches for songs and returns `ResourceLink` 3. Client initiates `resource/read` based on `ResourceLink.URI` 4. Client passes `url`, `start`, and `end` in `Arguments` 5. Server returns base64 encoded `BlobResourceContents` 6. Client decodes and plays while receiving, until `[DONE]` is received ## Quick Testing After starting HTTP mode, you can connect to `http://localhost:3001/mcp` with an MCP-compatible client. For local verification: ```bash go build . ``` ## Notes - Current song search relies on `github.com/scroot/music-sd` - Search results and actual audio links depend on external site capabilities, stability affected by external services - This repository is more suitable as a template for audio MCP Tool integration; if you want to integrate your own audio source, consider keeping the following protocol conventions: ```text Tool -> ResourceLink -> resource/read(Arguments pagination) -> Blob(base64) -> [DONE] ``` ## Project Structure ```text . ├── LICENSE ├── README.md ├── go.mod ├── go.sum └── main.go ```