MCP Audio Server

🚀 Music Context Protocol (MCP) Audio Server

A Model Context Protocol (MCP) server for audio processing and chord analysis.

🚀 Quick Start

Use Docker Compose for the fastest setup:

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

# Start the server
docker compose up -d

Example Request

# 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"}
  }'

Example Response

{
  "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"
}

✨ Features

This server has the following features:

• Audio file decoding and normalization: Supports multiple audio formats, including WAV, MP3, etc., and provides normalization processing.
• Music analysis:
  • Beat detection: Automatically identifies and calculates the beat information of the audio.
  • Key identification: Accurately identifies the main key of the audio.
  • Chord analysis: Decomposes the audio and identifies the chord structure within it.
• RESTful API: Provides a standardized API interface for easy integration with other systems.
• Error handling and logging: Detailed error information and log output for easy troubleshooting.
• Model selection: Supports different music analysis models (such as "basic" and "advanced") to meet different needs.

📦 Installation

Docker Installation

# Clone the repository and start the service
git clone https://github.com/yourusername/mcp-audio-server.git
cd mcp-audio-server
docker compose up -d

Manual Installation

1. Install dependencies:

   # Install Python and related tools
   python3 install --user pip
   pip install poetry
   

2. Clone the repository and run:

   git clone https://github.com/yourusername/mcp-audio-server.git
   cd mcp-audio-server
   poetry install
   poetry run uvicorn server.main:app --reload
   

📚 Documentation

The API documentation is generated based on FastAPI and hosted at the /docs path.

Request Example

curl -X POST http://localhost:8000/analyze_chords \
  -H "Content-Type: application/json" \
  -d '{"audio_data": "base64_encoded_audio", "format": "wav", "options": {"model": "basic"}}'

Response Format

{
  "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 Response

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "The audio data is invalid or the format is incorrect."
  }
}

🛠️ Development Guide

Contribution Guide

Please refer to CONTRIBUTING.md to learn how to contribute to the project.

Testing

# Run all tests and generate a coverage report
pytest --cov=mcp_audio_server tests/

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

Documentation Building

To rebuild the documentation website, execute the following commands:

# Install documentation dependencies
poetry install --with docs

# Build the documentation
poetry run mkdocs build

# Run the documentation server locally
poetry run mkdocs serve

📄 License

This project is released under the MIT License. Please refer to the LICENSE file for specific details.

Dependencies

All dependencies and their corresponding license information can be found in DEPENDENCIES.md.

📝 Changelog

Check CHANGELOG.md to learn about the project's version history and updates.