MCP Volumio

Volumeo MCP服务器

一种模型上下文协议（MCP）服务器，用于通过其WebSocket API控制Volumio音乐播放器。此服务器使AI代理和应用程序能够控制音乐播放、管理播放列表、浏览库以及与所有Volumeo功能进行交互。

主要特点

✨ 39综合工具 -使用前缀命名空间工具完全控制Volumeo(volumio_*) 📖 详细文件 -每个工具都有全面的文档字符串，其中包含使用示例和错误处理 📄 分页支持 -在搜索、浏览和队列操作中高效处理大型数据集 🔍 智能错误处理 -带有详细上下文的分类错误代码（连接、超时、验证等） 🐳 Docker就绪 -基于环境配置的生产就绪容器化部署 🔒 缺省巩固安全 -非根容器用户，HTTPS支持，使用Pydantic进行输入验证 📡 无状态HTTP -FastMCP采用HTTP流协议，实现高效通信 🔌 WebSocket客户端 -持久套接字。IO连接到Volumeio并自动重新连接

工具类别

回放控制

• 播放、暂停、停止播放
• 跳到下一首曲目，跳到上一首曲目
• 寻找特定的播放位置
• 查询当前玩家状态和轨迹信息

卷管理

• 将音量设置为特定水平（0-100%）
• 增加/减少音量
• 静音/取消静音音频

播放模式

• 启用/禁用随机洗牌模式
• 启用/禁用重复模式
• 获取/设置重复单曲

队列管理

• 将曲目添加到队列
• 按位置从队列中删除轨迹
• 将队列项目移动到不同位置
• 使用分页支持（限制/偏移）检索当前播放队列

播放列表管理

• 创建新播放列表
• 删除现有播放列表
• 将曲目添加到播放列表
• 从播放列表中删除曲目
• 播放整个播放列表
• Enqueue播放列表曲目

收藏夹管理

• 将曲目添加到收藏夹
• 从收藏夹中删除曲目

音乐库

• 搜索支持分页的音乐库（建议至少3个字符）
• 通过支持分页的URI浏览库
• 获取可用的音乐源（USB、NAS、Spotify、网络广播等）
• 获取可用的库过滤器（艺术家、专辑、流派等）

多房间音频

• 检索所有连接的多房间设备
• 获取设备状态和信息

睡眠和闹钟

• 获取/设置睡眠定时器
• 获取已配置的警报
• 添加新警报
• 删除警报

建筑

┌─────────────────────────────────────────┐
│         AI Application / Agent          │
└────────────────┬────────────────────────┘
                 │
                 │ HTTP/Streamable
                 ▼
┌─────────────────────────────────────────┐
│      Volumio MCP Server (FastAPI)       │
│  ├─ /health (Health checks)             │
│  ├─ /info (Server info)                 │
│  ├─ /mcp (MCP endpoint - streaming)     │
│  └─ Socket.io Client Manager            │
└────────────────┬────────────────────────┘
                 │
                 │ WebSocket (Socket.io)
                 ▼
┌─────────────────────────────────────────┐
│    Volumio Backend (WebSocket API)      │
│    Default: localhost:3000              │
└─────────────────────────────────────────┘

项目结构

mcp-volumio/
├── src/mcp_volumio/
│   ├── __init__.py              # Package initialization
│   ├── __main__.py              # Entry point
│   └── server.py                # Main MCP server implementation
├── pyproject.toml               # Python project configuration
├── Dockerfile                   # Docker container definition
├── docker-compose.yml           # HTTP deployment orchestration
├── docker-compose.https.yml     # HTTPS deployment orchestration
├── .env.example                 # Environment variables template
├── .dockerignore                # Docker ignore patterns
├── nginx/
│   ├── nginx.conf               # HTTP Nginx configuration
│   └── nginx-https.conf         # HTTPS Nginx configuration
├── ssl/
│   ├── README.md               # SSL certificate generation guide
│   └── (certificates - not in git)
├── scripts/
│   ├── start.sh                # Quick start script
│   ├── generate-ssl.sh         # SSL certificate generation
│   └── test-connection.py      # Connection test script
└── README.md                    # This file

需求

• Docker和Docker Compose（用于容器化部署）
• Python 3.11+（用于本地开发）
• Volumeio实例正在运行且可访问（默认值：localhost:3000）
• MCP服务器和Volumeio之间的网络连接

安装和部署

Docker快速入门（推荐）

1. 克隆存储库：

   git clone 
   cd mcp-volumio

1. 配置Volumeo连接：

   cp .env.example .env

编辑 .env 并设置您的Volumeo实例详细信息：

   # For Volumio on the same machine
   VOLUMIO_HOST=localhost
   VOLUMIO_PORT=3000

   # For Volumio on a different machine (recommended)
   VOLUMIO_HOST=192.168.1.100    # Replace with your Volumio's IP address
   VOLUMIO_PORT=3000

   # Optional: Change MCP server port (default: 8000)
   MCP_PORT=8000
   LOG_LEVEL=info

1. 构建并启动Docker容器：

   docker compose build
   docker compose up -d

1. 验证它是否正在运行：

   docker ps --filter "name=mcp-volumio-server"
   docker logs mcp-volumio-server

MCP服务器将在 http://localhost:8000.

Docker部署选项

HTTP部署（开发和本地使用）

使用docker编写：

# Start container
docker compose up -d

# View logs
docker logs mcp-volumio-server -f

# Stop container
docker compose down

# Rebuild and restart
docker compose up -d --build

通过命令行传递Volumeo主机名：

# Using environment variable
VOLUMIO_HOST=192.168.1.100 docker compose up -d

# Or edit .env file and restart
docker compose restart

手动运行Docker（不使用compose）：

docker build -t mcp-volumio:latest .

docker run -d \
  --name mcp-volumio-server \
  -p 8000:8000 \
  -e VOLUMIO_HOST=192.168.1.100 \
  -e VOLUMIO_PORT=3000 \
  -e LOG_LEVEL=info \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  mcp-volumio:latest

终点：

• MCP服务器： http://localhost:8000
• MCP可流式传输： http://localhost:8000/mcp

HTTPS部署（使用Nginx的生产环境）

1. 生成SSL证书：

   chmod +x scripts/generate-ssl.sh
   ./scripts/generate-ssl.sh

1. 为您的域更新.env：

   VOLUMIO_HOST=192.168.1.100  # Your Volumio IP
   DOMAIN_NAME=your-domain.com
   HTTPS_PORT=443
   HTTP_PORT=80

1. 从HTTPS开始：

   docker compose -f docker-compose.https.yml up -d

终点：

• MCP服务器： https://your-domain.com
• MCP可流式传输： https://your-domain.com/mcp

地方发展设置

1. 安装Python依赖项：

   uv sync

1. 创建.env文件：

   cp .env.example .env

1. 运行服务器：

   uv run python -m mcp_volumio

服务器将于启动 http://localhost:8000 并尝试连接到Volumio localhost:3000.

配置

环境变量

# MCP Server
MCP_HOST=0.0.0.0          # Server host (container)
MCP_PORT=8000             # Server port

# Volumio Connection
VOLUMIO_HOST=localhost    # Volumio instance host
VOLUMIO_PORT=3000         # Volumio instance WebSocket port

# Logging
LOG_LEVEL=info            # Logging level (debug, info, warning, error)

# Nginx/HTTPS
HTTP_PORT=80              # HTTP port
HTTPS_PORT=443            # HTTPS port
DOMAIN_NAME=localhost     # Domain for SSL certificates

Volumeo网络接入

确保您的Volumeo实例可访问：

# Test connectivity
curl http://:3000/api/v1/getstate

# Check if WebSocket is available
nc -zv  3000

用法

MCP工具

服务器公开了39个用于控制Volumeo的工具。所有工具都以前缀 volumio_ 以防止与其他MCP服务器一起使用时发生命名冲突。

示例：

播放当前曲目

# Request
{
  "name": "volumio_play",
  "arguments": {}
}

# Response
{"status": "success", "message": "Play command sent"}

设置音量

# Request
{
  "name": "volumio_set_volume",
  "arguments": {"volume": 75}
}

# Response
{"status": "success", "message": "Volume set to 75%"}

搜索音乐库

# Request
{
  "name": "volumio_search",
  "arguments": {"query": "Beatles"}
}

# Response
{"status": "success", "data": { ... }}

添加到播放列表

# Request
{
  "name": "volumio_add_to_playlist",
  "arguments": {
    "playlist_name": "My Favorites",
    "uri": "music-library/artist/The Beatles/Let It Be",
    "service": "mpd"
  }
}

# Response
{"status": "success", "message": "Added track to playlist 'My Favorites' (service: mpd)"}

API 参考

所有工具都以前缀 volumio_ 以防止多服务器环境中的命名冲突。

回放控制

音量控制

播放模式

队列管理

播放列表管理

音乐库

收藏夹

多房间

闹钟和睡眠

\*标有星号的工具返回具有结构化数据的已验证Pydantic模型。

监控与管理

集装箱监控

# Check container status
docker ps --filter "name=mcp-volumio-server"

# View logs
docker logs mcp-volumio-server -f

# View recent logs
docker logs mcp-volumio-server --tail 50

测试连接

chmod +x scripts/test-connection.py
python scripts/test-connection.py

停止/重新启动服务器

# Stop
docker-compose down

# Restart
docker-compose up -d

# Stop with data cleanup
docker-compose down -v

故障排除

服务器无法启动

1. 检查Docker：

   docker --version
   docker-compose --version

1. 检查Volumeo连接：

   curl http://:3000/api/v1/getstate

1. 查看日志：

   docker-compose logs mcp-server

无法连接到Volumeo

1. 验证Volumeio是否正在运行：

   ping 
   nc -zv  3000

1. 使用正确的Volumeo主机更新.env：

   VOLUMIO_HOST=
   VOLUMIO_PORT=3000

1. 重新启动服务器：

   docker-compose restart

HTTPS证书问题

1. 重新生成证书：

   ./scripts/generate-ssl.sh

1. 检查证书有效性：

   openssl x509 -in ssl/cert.pem -text -noout

1. 确保证书可读：

   ls -la ssl/
   chmod 644 ssl/cert.pem ssl/key.pem

发展

运行测试

uv run pytest -v

代码质量

# Format code
uv run black src/

# Lint code
uv run ruff check src/

# Type checking
uv run mypy src/

在当地建设

# Install dependencies
uv sync

# Run directly
uv run python -m mcp_volumio

# Build Docker image
docker build -t mcp-volumio:local .

API文件参考

有关Volumio的WebSocket API的详细信息，请参阅：

• Volumio WebSocket API文档

性能注意事项

• 无状态操作：服务器是无状态的，可以水平扩展
• 连接池：Socket.io客户端自动处理重新连接
• 超时管理：WebSocket命令的默认5秒超时
• 流媒体支持：用于高效长轮询的HTTP流协议

安全考虑

1. 网络接入：仅限制访问受信任的网络
2. SSL/TLS：在生产环境中使用HTTPS（请参阅SSL证书设置）
3. 认证：如果需要，在反向代理级别实施身份验证
4. 输入验证：所有输入参数均使用Pydantic进行验证
5. 集装箱安全：服务器在容器内以非root用户身份运行

许可证

有关详细信息，请参阅LICENSE文件。

贡献

欢迎投稿！请确保：

• 代码遵循黑色/褶边风格指南
• 所有测试均通过
• 文档已更新
• 提交消息是描述性的

支持

对于问题、功能请求或疑问：

1. 检查故障排除部分
2. 查看Volumio API文档
3. 检查应用程序日志： docker-compose logs mcp-server
4. 打开一个包含详细信息的问题

更新日志

v0.5.0（最新版本-第4阶段：错误处理）

• 增强的错误处理：具有6种错误代码类型的全面错误分类

- CONNECTION_ERROR, TIMEOUT_ERROR, VALIDATION_ERROR, VOLUMIO_ERROR, INTERNAL_ERROR, PARAMETER_ERROR

• 标准化错误响应：所有工具返回一致的错误格式和可选的详细信息
• 改进日志记录：为所有33个命令工具添加了日志记录（以前缺失）
• 更好的调试：错误响应包括上下文（事件名称、超时、参数）
• 分离的错误类型：TimeoutError、ValidationError和ConnectionError的处理方式不同
• 修复了Docker构建问题（uv.lock、README.md、.dockerinore）
• 将docker-compose.yml更新为现代语法（删除了过时的版本属性）

v0.4.0（第3阶段：分页支持）

• 大型数据集的分页：为3个高容量工具添加了分页支持

- volumio_get_queue：限制（1-200，默认值：50），偏移参数 - volumio_search：限制（1-200，默认值：50），偏移参数 - volumio_browse_library：限制（1-500，默认值：100），偏移参数

• 分页元数据：所有分页响应包括总计、偏移、限制、返回、has_more
• 按类别分页：搜索和浏览支持在每个结果类别中分页
• 客户端分页：高效的结果切片，因为Volumeio不支持服务器端分页
• 修复了带注释\[type，Field（）\]模式的默认参数处理

v0.3.0（第2阶段：综合文档）

• 根据MCP最佳实践，为所有39个工具添加了详细的文档字符串
• 工具文档包括:

- 功能和目的的清晰描述 - 完整的参数文档，包括类型、范围和示例 - 带有响应结构的详细返回值文档 - 使用示例（何时使用/何时不使用） - 全面的错误处理文档 - 关于Volumeo特定行为和限制的说明

• 通过上下文丰富的工具描述增强了AI代理的可用性

v0.2.0（第1阶段：MCP最佳实践）

• 突发：将所有39个工具重命名为 volumio_ 前缀（例如。， play → volumio_play)
• 突发：服务器名称从“Volumio”更改为“Volumio_mcp”
• 添加了全面的工具注释（readOnlyHint、destructiveHint、幂等Hint、openWorldHint）
• 改进了多服务器兼容性
• 用新的工具名称更新了所有文档

v0.1.0（初始版本）

• Volumeo MCP服务器的初步实现
• 39个音乐控制和管理工具
• 支持HTTP和HTTPS的Docker部署
• 具有无状态HTTP传输的FastMCP
• 插座。用于Volumeio通信的IO WebSocket客户端
• API完整文档