IRCAM Amplify MCP Server

# Research: IRCAM Amplify MCP Server **Feature**: 001-ircam-amplify-mcp **Date**: 2025-12-12 **Status**: Complete (pending runtime verification) ## Research Tasks ### 1. IRCAM Amplify API Authentication **Decision**: Bearer token authentication via `Authorization` header **Rationale**: - IRCAM Amplify documentation indicates token-based authentication - Standard REST API pattern for SaaS services - Token obtained from IRCAM Amplify developer portal (app.ircamamplify.io) - Passed via `Authorization: Bearer <token>` header **Implementation**: ```typescript const headers = { 'Authorization': `Bearer ${process.env.IRCAM_AMPLIFY_API_KEY}`, 'Content-Type': 'application/json' }; ``` **Alternatives considered**: - API Key in query params: Rejected (less secure, visible in logs) - OAuth2 flow: Rejected (too complex for MCP server, designed for B2B) **Runtime verification needed**: Confirm exact header format with IRCAM API --- ### 2. IRCAM API Base URL & Endpoints **Decision**: Use `https://api.ircamamplify.io/v1` as base URL **Rationale**: - Standard SaaS API pattern with versioned endpoints - Documentation references app.ircamamplify.io for API access - Version prefix allows future API evolution **Endpoint Structure** (inferred from API categories): | Tool | Endpoint Pattern | |------|------------------| | Music Tagger | `POST /music-tagger/analyze` | | Stem Separator | `POST /stem-separator/separate` | | AI Music Detector | `POST /ai-music-detector/detect` | | Loudness Analyzer | `POST /loudness-analyzer/analyze` | | Job Status | `GET /jobs/{job_id}` | **Alternatives considered**: - GraphQL: Not documented by IRCAM - WebSocket: Overkill for request-response pattern **Runtime verification needed**: Confirm exact endpoint paths from IRCAM documentation or API response --- ### 3. Audio Input Method **Decision**: URL-based audio input only **Rationale**: - Spec decision: URL uniquement pour simplicité et compatibilité universelle - IRCAM accepts audio via URL reference (documented) - Avoids file upload complexity and MCP binary handling issues - LLMs can easily provide URLs from web sources **Implementation**: ```typescript interface AudioInput { audio_url: string; // Public URL to audio file } ``` **Supported formats** (based on industry standards): - MP3 (audio/mpeg) - WAV (audio/wav) - FLAC (audio/flac) - OGG (audio/ogg) - M4A (audio/mp4) **Alternatives considered**: - Base64 encoded audio: Rejected (large payloads, MCP message size limits) - File upload: Rejected (requires multipart, complex for MCP) --- ### 4. Asynchronous Job Handling **Decision**: Polling via `check_job_status` tool **Rationale**: - Spec decision: Pas de webhooks pour simplification - Long-running operations (stem separation: 30-60s) return job_id immediately - Client polls with job_id until completion - Simpler than webhooks (no callback server needed) **Job States**: | State | Description | |-------|-------------| | `pending` | Job queued, not started | | `processing` | Job actively processing | | `completed` | Job finished successfully | | `failed` | Job encountered error | **Implementation Pattern**: ```typescript // Initial request returns job_id { job_id: "abc123" } // Poll for status { status: "processing", progress: 45 } // Final result { status: "completed", result: { vocals_url: "...", ... } } ``` **Alternatives considered**: - Webhooks: Rejected per spec (requires HTTP server on client) - Server-Sent Events: Not supported by MCP protocol - Long polling: Unnecessary complexity --- ### 5. Error Response Format **Decision**: Standardized error structure with actionable messages **Rationale**: - Spec requirement: FR-010 clear error messages - LLMs need structured errors to provide helpful responses - Include error code, message, and suggested action **Error Structure**: ```typescript interface MCPError { code: string; // e.g., "INVALID_URL", "AUTH_FAILED" message: string; // Human-readable description suggestion?: string; // Action to resolve retry_after?: number; // Seconds to wait before retry } ``` **Error Codes**: | Code | HTTP Status | Message | |------|-------------|---------| | `MISSING_API_KEY` | - | Missing API key. Set IRCAM_AMPLIFY_API_KEY environment variable. | | `INVALID_API_KEY` | 401 | Invalid API key. Check IRCAM_AMPLIFY_API_KEY environment variable. | | `INVALID_URL` | 400 | Cannot access URL. Ensure the URL is public and accessible. | | `UNSUPPORTED_FORMAT` | 400 | Unsupported format. Accepted: MP3, WAV, FLAC, OGG, M4A. | | `FILE_TOO_LARGE` | 400 | File exceeds maximum size of 100MB. | | `RATE_LIMITED` | 429 | Rate limit reached. Retry after X seconds. | | `SERVICE_UNAVAILABLE` | 503 | IRCAM Amplify service unavailable. Please retry later. | | `JOB_NOT_FOUND` | 404 | Job not found or expired. Results are only available for 24 hours. | | `JOB_FAILED` | 500 | Job processing failed: [details] | --- ### 6. MCP SDK Integration **Decision**: Use @modelcontextprotocol/sdk with stdio transport **Rationale**: - Constitution mandate: SDK officiel Anthropic - stdio transport: Standard for local MCP servers - TypeScript native: Full type safety **Implementation Pattern**: ```typescript import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; const server = new Server({ name: 'ircam-amplify-mcp', version: '1.0.0' }, { capabilities: { tools: {} } }); // Register tools server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [analyzeMusic, separateStems, detectAiMusic, analyzeLoudness, checkJobStatus] })); // Start server const transport = new StdioServerTransport(); await server.connect(transport); ``` **Alternatives considered**: - Custom MCP implementation: Rejected (SDK is well-maintained) - HTTP transport: Rejected (stdio is simpler for local servers) --- ### 7. Response Mapping Strategy **Decision**: Transform IRCAM responses to LLM-friendly format **Rationale**: - IRCAM API responses may be verbose or nested - LLMs benefit from flat, descriptive structures - Consistent response shape across all tools **Transformation Examples**: Music Tagger (IRCAM → MCP): ```typescript // IRCAM response (hypothetical) { result: { tags: { genre: [...], mood: [...] }, bpm: 120, key: "C major" } } // MCP response { genre: ["electronic", "house"], mood: ["energetic"], tempo: 120, key: "C major", instruments: ["synth", "drums"] } ``` **Runtime verification needed**: Actual IRCAM response structures --- ## Summary of Decisions | Topic | Decision | Confidence | |-------|----------|------------| | Authentication | Bearer token via env var | High | | Base URL | https://api.ircamamplify.io/v1 | Medium (verify) | | Audio input | URL only | High (spec decision) | | Async handling | Polling with job_id | High (spec decision) | | Error format | Standardized with codes | High | | MCP SDK | @modelcontextprotocol/sdk stdio | High (constitution) | | Response mapping | Transform to flat LLM-friendly JSON | High | ## Next Steps 1. Confirm IRCAM API endpoints with actual API calls during implementation 2. Map actual IRCAM response structures to MCP output schemas 3. Implement retry logic for transient failures 4. Add request timeout handling (30s default)