IRCAM Amplify MCP Server

# IRCAM Amplify MCP Server MCP (Model Context Protocol) server for IRCAM Amplify audio processing APIs. Enables any MCP-compatible LLM to analyze music, separate stems, detect AI-generated audio, and more. ## Features - **Music Analysis**: Extract genre, mood, tempo, key, and instruments from audio - **Stem Separation**: Split audio into vocals, drums, bass, and other instruments - **AI Detection**: Detect whether music is AI-generated or human-made - **Loudness Analysis**: Measure LUFS, true peak, and dynamic range - **Async Job Handling**: Poll long-running operations with progress tracking ## Supported Audio Formats MP3, WAV, FLAC, OGG, M4A (max 100MB) ## Quick Start ### Prerequisites - **Node.js 18+** ([download](https://nodejs.org/)) - **IRCAM Amplify API Key** from [app.ircamamplify.io](https://app.ircamamplify.io) - An MCP-compatible client (Claude Desktop, Cline, etc.) ### Installation ```bash npm install -g ircam-amplify-mcp ``` Or run directly with npx: ```bash npx ircam-amplify-mcp ``` ### Configuration #### 1. Set your API key ```bash export IRCAM_AMPLIFY_API_KEY="your-api-key-here" ``` #### 2. Configure your MCP client **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "ircam-amplify": { "command": "npx", "args": ["ircam-amplify-mcp"], "env": { "IRCAM_AMPLIFY_API_KEY": "your-api-key-here" } } } } ``` ## Available Tools | Tool | Description | Input | Output | |------|-------------|-------|--------| | `analyze_music` | Extract genre, mood, tempo, key, instruments | `audio_url` | `{ genre[], mood[], tempo, key, instruments[] }` | | `separate_stems` | Split into vocals, drums, bass, other | `audio_url` | `{ vocals_url, drums_url, bass_url, other_url }` or `{ job_id }` | | `detect_ai_music` | Detect AI vs human-made music | `audio_url` | `{ confidence, classification }` | | `analyze_loudness` | Measure LUFS, peak, dynamic range | `audio_url` | `{ integrated_lufs, true_peak_db, loudness_range }` | | `check_job_status` | Poll async operations | `job_id` | `{ status, progress, result }` | ## Usage Examples ### Analyze a song > "Analyze this song: https://example.com/song.mp3" **Response:** ```json { "genre": ["electronic", "house"], "mood": ["energetic", "uplifting"], "tempo": 128, "key": "A minor", "instruments": ["synthesizer", "drums", "bass"] } ``` ### Separate stems > "Separate the vocals from this track: https://example.com/track.mp3" **Response (sync for short files):** ```json { "vocals_url": "https://cdn.ircamamplify.io/stems/vocals.wav", "drums_url": "https://cdn.ircamamplify.io/stems/drums.wav", "bass_url": "https://cdn.ircamamplify.io/stems/bass.wav", "other_url": "https://cdn.ircamamplify.io/stems/other.wav" } ``` **Response (async for longer files):** ```json { "job_id": "abc123-def456" } ``` ### Check if AI-generated > "Is this track AI-generated? https://example.com/mystery.mp3" **Response:** ```json { "confidence": 85, "classification": "ai_generated" } ``` Classification values: `ai_generated`, `human_made`, or `uncertain` ### Analyze loudness > "Check if this master is ready for Spotify: https://example.com/master.wav" **Response:** ```json { "integrated_lufs": -14.0, "true_peak_db": -1.0, "loudness_range": 6.0 } ``` ### Check job status > "Check the status of job abc123-def456" **Response:** ```json { "status": "completed", "progress": 100, "result": { "vocals_url": "...", "drums_url": "...", "bass_url": "...", "other_url": "..." } } ``` Status values: `pending`, `processing`, `completed`, `failed` ## Error Handling The server provides detailed error messages with actionable suggestions: | Error Code | Meaning | Suggestion | |------------|---------|------------| | `MISSING_API_KEY` | API key not configured | Set `IRCAM_AMPLIFY_API_KEY` environment variable | | `INVALID_API_KEY` | API key rejected | Verify key at app.ircamamplify.io | | `INVALID_URL` | Cannot access audio URL | Ensure URL is publicly accessible | | `UNSUPPORTED_FORMAT` | Audio format not supported | Use MP3, WAV, FLAC, OGG, or M4A | | `FILE_TOO_LARGE` | File exceeds 100MB limit | Use a shorter audio clip | | `RATE_LIMITED` | Too many requests | Wait and retry | | `JOB_NOT_FOUND` | Job ID invalid or expired | Job results expire after 24 hours | ## Development ```bash # Install dependencies npm install # Run in development mode npm run dev # Build for production npm run build # Run tests npm test # Type check npm run typecheck # Lint and format npm run lint npm run format ``` ## Architecture ``` src/ ├── index.ts # MCP server entry point ├── types/ │ ├── mcp-tools.ts # MCP tool type definitions │ └── ircam-api.ts # IRCAM API response types ├── tools/ │ ├── analyze-music.ts # Music tagging tool │ ├── separate-stems.ts # Stem separation tool │ ├── detect-ai-music.ts # AI detection tool │ ├── analyze-loudness.ts # Loudness analysis tool │ └── check-job-status.ts # Job polling tool └── utils/ ├── auth.ts # API key management ├── http.ts # HTTP client with retry ├── validation.ts # Input validation └── errors.ts # Error formatting ``` ## License MIT - See [LICENSE](LICENSE) for details. ## Support - **IRCAM Documentation**: [docs.ircamamplify.io](https://docs.ircamamplify.io) - **Get API Key**: [app.ircamamplify.io](https://app.ircamamplify.io) - **Issues**: [GitHub Issues](https://github.com/your-org/ircam-amplify-mcp/issues)