JinDaGe - mcp-audio-server MCP Details

article

README

🚀 音乐上下文协议（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以了解项目的版本历史和更新内容。

mcp-audio-server