🚀 音乐上下文协议（MCP）音频服务器
本项目是一个用于音频处理和和弦分析的模型上下文协议（MCP）服务器，能够对音频进行解码、归一化、节拍检测、音调识别、和弦分析等操作，并提供标准化的RESTful API接口，方便与其他系统集成。
🚀 快速开始
使用Docker Compose可实现最快设置：
# 克隆仓库
git clone https://github.com/yourusername/mcp-audio-server.git
cd mcp-audio-server
# 启动服务器
docker compose up -d
示例请求
# 分析一个WAV文件
curl -X POST http://localhost:8000/analyze_chords \
-H "Content-Type: application/json" \
-d '{
"audio_data": "'$(base64 -i tests/fixtures/tempo/120bpm_with_chord.wav)'",
"format": "wav",
"options": {"model": "basic"}
}'
示例响应
{
"schema_version": "1.0.0",
"key": "C",
"tempo": 120.5,
"chords": [
{
"time": 0.0,
"label": "C",
"confidence": 0.92
},
{
"time": 1.0,
"label": "G",
"confidence": 0.87
}
],
"duration": 4.0,
"processing_info": {
"sample_rate": 44100,
"channels": 1,
"processing_time": 0.245,
"model_used": "basic"
},
"correlation_id": "550e8400-e29b-41d4-a716-446655440000"
}
✨ 主要特性
- 音频文件解码与归一化：支持多种音频格式，包括WAV、MP3等，并提供归一化处理。
- 音乐分析：
- 节拍检测：自动识别和计算音频的节拍信息。
- 音调识别：准确识别音频的主音调。
- 和弦分析：分解音频并识别其中的和弦结构。
- RESTful API：提供标准化的API接口，便于与其他系统集成。
- 错误处理与日志记录：详细的错误信息和日志输出，便于排查问题。
- 模型选择：支持不同的音乐分析模型（如“basic”和“advanced”），满足不同需求。
📦 安装指南
Docker安装
# 克隆仓库并启动服务
git clone https://github.com/yourusername/mcp-audio-server.git
cd mcp-audio-server
docker compose up -d
手动安装
-
安装依赖：
# 安装Python和相关工具 python3 install --user pip pip install poetry -
克隆仓库并运行：
git clone https://github.com/yourusername/mcp-audio-server.git cd mcp-audio-server poetry install poetry run uvicorn server.main:app --reload
📚 详细文档
API文档
API文档基于FastAPI生成，并托管在/docs路径下。
请求示例
curl -X POST http://localhost:8000/analyze_chords \
-H "Content-Type: application/json" \
-d '{"audio_data": "base64_encoded_audio", "format": "wav", "options": {"model": "basic"}}'
响应格式
{
"schema_version": "1.0.0",
"key": "C",
"tempo": 120.5,
"chords": [
{
"time": 0.0,
"label": "C",
"confidence": 0.92
},
{
"time": 1.0,
"label": "G",
"confidence": 0.87
}
],
"duration": 4.0,
"processing_info": {
"sample_rate": 44100,
"channels": 1,
"processing_time": 0.245,
"model_used": "basic"
},
"correlation_id": "550e8400-e29b-41d4-a716-446655440000"
}
错误响应
{
"error": {
"code": "INVALID_ARGUMENT",
"message": "音频数据无效或格式错误。"
}
}
开发指南
贡献指南
请参考CONTRIBUTING.md了解如何为项目贡献力量。
测试
# 运行所有测试并生成覆盖率报告
pytest --cov=mcp_audio_server tests/
# 运行特定测试
pytest tests/analysis/test_tempo.py
文档构建
要重新构建文档网站，请执行以下命令：
# 安装文档依赖项
poetry install --with docs
# 构建文档
poetry run mkdocs build
# 本地运行文档服务器
poetry run mkdocs serve
📄 许可证
此项目根据MIT许可证发布，具体内容请参阅LICENSE文件。
依赖项
所有依赖项及其相应许可信息详见DEPENDENCIES.md。
🔄 变更日志
查看CHANGELOG.md以了解项目的版本历史和更新内容。