MCP Audio Server

MCP 音频服务

用于音频处理和和弦分析的模型上下文协议（MCP）服务。

快速开始

使用 Docker Compose 可最快完成设置：

# Clone the repository
git clone https://github.com/yourusername/mcp-audio-server.git
cd mcp-audio-server

# Start the server
docker compose up -d

请求示例

# Analyze a WAV file
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"
}

功能

• 使用 FFmpeg 解码和规范化音频文件
• 音乐分析功能：
  • 速度检测（BPM）
  • 调性检测
  • 和弦分析与追踪
• RESTful API，提供结构化响应
• 对输入和输出进行 JSON 架构验证
• 完善的错误处理，并提供详细消息
• 通过并发控制管理资源
• 使用缓存优化性能
• 通过结构化日志和指标实现可观测性
• 全面的测试套件
• 使用 Docker 进行容器化部署

安装

Docker（推荐）

docker compose up -d

手动安装

1. 先决条件：

   • Python 3.10 或更高版本
   • FFmpeg
   • Poetry

2. 安装依赖项：

   poetry install
   

3. 运行服务：

   poetry run uvicorn mcp_audio_server.main:app --host 0.0.0.0 --port 8000
   

API 文档

服务运行时，可在 /docs 查看完整的 OpenAPI 规范：

http://localhost:8000/docs

端点

端点	描述
POST /analyze_chords	分析音频中的和弦、调性和速度
GET /health	健康检查端点
GET /ready	供负载均衡器使用的就绪检查
GET /metrics	Prometheus 指标（重定向至指标服务）

请求格式

{
  "audio_data": "base64-encoded-audio-data",
  "format": "wav",  // "wav", "mp3", "ogg", "m4a", "flac"
  "options": {
    "model": "basic"  // "basic" or "advanced"
  }
}

响应格式

{
  "schema_version": "1.0.0",
  "key": "C",
  "tempo": 120.0,
  "chords": [
    {
      "time": 0.0,
      "label": "C",
      "confidence": 0.9
    }
  ],
  "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": "DECODING_ERROR",
  "message": "Failed to decode audio file: Invalid file format",
  "details": {
    "format": "wav",
    "error": "Invalid WAV header"
  },
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000"
}

开发

开发指南请参阅 CONTRIBUTING.md。

测试

# Run all tests with coverage reporting
pytest

# Run specific tests
pytest tests/analysis/test_tempo.py

文档

API 文档根据 FastAPI 应用生成，可在 /docs 查看。

重新构建文档站点：

# Install documentation dependencies
poetry install --with docs

# Build documentation
poetry run mkdocs build

# Serve documentation locally
poetry run mkdocs serve

许可证与合规性

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

依赖项

所有依赖项及其对应的许可证均记录在 DEPENDENCIES.md 中。

更新日志

项目版本历史和变更请参阅 CHANGELOG.md。