MCP Audio Server

🚀 音樂上下文協議（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

手動安裝

1. 安裝依賴：

   # 安裝Python和相關工具
   python3 install --user pip
   pip install poetry
   

2. 克隆倉庫並運行：

   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以瞭解項目的版本歷史和更新內容。