MCP Audio Server

MCP Audio サーバー

オーディオ処理とコード分析のための Model Context Protocol（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 ドキュメント

サーバーの起動中は、完全な OpenAPI 仕様を /docs で確認できます。

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 のもとでライセンスされています。詳細は LICENSE ファイルを参照してください。

依存関係

すべての依存関係とそれぞれのライセンスについては、DEPENDENCIES.md に記載されています。

変更履歴

プロジェクトのバージョン履歴と変更内容については、CHANGELOG.md を参照してください。