小智AI (xiaozhi.me / 自建服务端)
        │  WebSocket MCP 接入点 (wss://.../mcp_endpoint/mcp/?token=...)
        ▼
   mcp_pipe.py 桥接（官方方案，断线自动重连）
        │  stdio JSON-RPC
        ▼
   music_mcp  (python -m music_mcp)
        │
        ├─ 工具: search_song / play_song / get_play_url / list_sources / local_player_control
        ├─ 资源: resource://read_from_http
        │        └─ HTTP Range 分页读取远程音频（Base64 Blob + [DONE]）
        └─ 音源适配器: kuwo / netease / migu / kugou

git clone https://github.com/ABUGG-007/xiaozhi-mcp-music.git
cd xiaozhi-music-mcp

# uv 方式（Windows）
uv venv .venv --python 3.13
uv pip install --python .venv/Scripts/python.exe -r requirements-dev.txt

# Windows 也可以直接一键安装
setup.bat

cp .env.example .env          # Windows: copy .env.example .env
cp mcp_config.example.json mcp_config.json

# 小智控制台 -> 智能体 -> 配置角色页面，复制的专属 MCP 接入点
MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=你的token

# 音源开关（逗号分隔，全部可用）
MUSIC_SOURCES=kuwo,netease,migu,kugou

# 本地播放器（小智硬件播放不需要；仅电脑本地调试用）
LOCAL_PLAYER=none
AUTO_PLAY_LOCAL=false

python bridge.py            # Windows 直接双击 run.bat

python -m music_mcp                          # stdio 模式
python scripts/check_sources.py "青花瓷"      # 音源自检
$env:SMOKE_QUERY="青花瓷"; python scripts/mcp_smoke.py   # 协议冒烟测试

{
  "type": "resource_link",
  "uri": "resource://read_from_http",
  "name": "青花瓷 - 周杰伦",
  "description": "https://...mp3",
  "mimeType": "audio/mpeg"
}

{
  "uri": "resource://read_from_http",
  "arguments": {"url": "https://...mp3", "start": 0, "end": 102400}
}

.
├── music_mcp/                 # MCP 服务器核心
│   ├── mcp_server.py          # 轻量 JSON-RPC stdio 协议实现
│   ├── app.py                 # 工具装配（search/play/list）
│   ├── resource_proxy.py      # 音频分页读取代理
│   ├── local_player.py        # 可选本地播放器
│   └── sources/               # 音源适配器（kuwo/netease/migu/kugou）
├── scripts/                   # 自检与冒烟测试脚本
├── tests/                     # 离线单元/集成测试（16 项）
├── mcp_pipe.py                # 官方桥接（WebSocket <-> stdio）
├── bridge.py                  # 一键启动桥接
├── mcp_config.example.json    # 桥接配置模板
├── setup.bat / run.bat        # Windows 安装/运行脚本
├── start_bridge_hidden.ps1    # 后台隐藏启动
├── enable_autostart.ps1/.bat  # 开机自启
├── xiaozhi_role_prompt.txt    # 小智角色提示词
└── pyproject.toml             # 打包与测试配置

# 离线测试：协议握手、工具注册、Range 分页、416 结束、
#          无 Range 服务器防死循环、酷我特殊返回格式解析
python -m pytest tests -q