# 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)