IRCAM Amplify MCP Server

# Feature Specification: IRCAM Amplify MCP Server **Feature Branch**: `001-ircam-amplify-mcp` **Created**: 2025-12-12 **Status**: Draft **Input**: User description: "Je souhaite creer un MCP qui permet d'utiliser les API de ircamamplify.io dont la documentation est accessible ici docs.ircamamplify.io. L'objectif est de permettre a n'importe quel LLM d'utiliser ces APIs, aussi bien pour repondre a des questions, que pour creer des applications" ## Design Decisions (Simplifications for Universal Compatibility) Les décisions suivantes ont été prises pour garantir un MCP simple, léger et compatible avec tous les environnements : | Aspect | Décision | Justification | |--------|----------|---------------| | Input audio | URL uniquement | Universel, pas de dépendance filesystem | | Opérations async | Polling (pas webhooks) | Pas besoin de serveur HTTP côté client | | Credentials | Variable d'environnement `IRCAM_AMPLIFY_API_KEY` | Standard MCP | | Scope v1 | 4 APIs prioritaires | MVP fonctionnel rapidement | | Storage | Hors scope | URLs temporaires IRCAM suffisantes | ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Analyze Music with AI (Priority: P1 - MVP) As a developer or LLM user, I want to analyze audio files to extract musical information (genre, mood, tempo, key, instruments) so that I can automatically tag and categorize music or answer questions about audio content. **Why this priority**: Music tagging is the use case le plus demandé. Fournit une valeur immédiate pour répondre aux questions sur la musique. **Independent Test**: Soumettre une URL audio et recevoir les tags structurés (genre, mood, tempo, key, instruments). **Acceptance Scenarios**: 1. **Given** un LLM avec accès au MCP et une URL audio valide, **When** l'analyse est demandée, **Then** le système retourne genre, mood, tempo, tonalité et instruments détectés en JSON. 2. **Given** une URL audio invalide ou inaccessible, **When** l'analyse est demandée, **Then** le système retourne une erreur claire indiquant le problème d'accès. 3. **Given** un format audio non supporté, **When** l'analyse est demandée, **Then** le système retourne la liste des formats acceptés. --- ### User Story 2 - Separate Audio Stems (Priority: P1 - MVP) As a developer or LLM user, I want to separate audio files into individual stems (vocals, drums, bass, other) so that I can enable remixing or karaoke applications. **Why this priority**: Stem separation est une fonctionnalité unique et très demandée, différenciante pour ce MCP. **Independent Test**: Soumettre une URL de piste mixée et recevoir des URLs vers les stems séparés. **Acceptance Scenarios**: 1. **Given** un LLM avec une URL audio, **When** la séparation est demandée, **Then** le système retourne des URLs vers vocals, drums, bass et other stems. 2. **Given** une opération de séparation en cours, **When** le statut est vérifié via `check_job_status`, **Then** le système retourne l'état (pending/processing/completed/failed) et les URLs si terminé. --- ### User Story 3 - Detect AI-Generated Music (Priority: P1 - MVP) As a developer or content platform, I want to detect whether audio is AI-generated versus human-created for content authenticity verification. **Why this priority**: Détection IA devient critique pour les plateformes musicales et la conformité. **Independent Test**: Soumettre une URL audio et recevoir un score de confiance AI vs Human. **Acceptance Scenarios**: 1. **Given** un LLM avec une URL audio, **When** la détection IA est demandée, **Then** le système retourne un score de confiance (0-100%) et une classification (ai_generated/human_made/uncertain). --- ### User Story 4 - Analyze Audio Loudness (Priority: P1 - MVP) As a developer, I want to analyze the loudness characteristics of audio files for mastering and normalization purposes. **Why this priority**: Analyse de loudness est rapide, simple et utile pour le mastering audio. **Independent Test**: Soumettre une URL audio et recevoir les métriques de loudness (LUFS, peak, dynamic range). **Acceptance Scenarios**: 1. **Given** un LLM avec une URL audio, **When** l'analyse loudness est demandée, **Then** le système retourne integrated LUFS, true peak, loudness range en JSON. --- ### User Story 5 - Check Job Status (Priority: P1 - MVP) As a developer, I want to check the status of long-running operations so that I can retrieve results when ready. **Why this priority**: Essentiel pour gérer les opérations asynchrones sans webhooks. **Independent Test**: Soumettre un job_id et recevoir le statut actuel avec résultats si terminé. **Acceptance Scenarios**: 1. **Given** un job_id valide pour une opération en cours, **When** le statut est demandé, **Then** le système retourne {status: "processing", progress: 45}. 2. **Given** un job_id pour une opération terminée, **When** le statut est demandé, **Then** le système retourne {status: "completed", result: {...}}. 3. **Given** un job_id invalide ou expiré, **When** le statut est demandé, **Then** le système retourne une erreur claire. --- ### Edge Cases (Décisions concrètes) | Situation | Comportement | |-----------|--------------| | URL inaccessible | Erreur : "Cannot access URL. Ensure the URL is public and accessible." | | Fichier > limite (ex: 100MB) | Erreur : "File exceeds maximum size of 100MB." | | Format non supporté | Erreur : "Unsupported format. Accepted: MP3, WAV, FLAC, OGG, M4A." | | Rate limit IRCAM atteint | Erreur : "Rate limit reached. Retry after X seconds." + header Retry-After | | Clé API invalide | Erreur : "Invalid API key. Check IRCAM_AMPLIFY_API_KEY environment variable." | | Clé API manquante | Erreur : "Missing API key. Set IRCAM_AMPLIFY_API_KEY environment variable." | | Timeout opération (>5min) | Auto-retry 1x, puis erreur avec job_id pour vérification ultérieure | | Service IRCAM indisponible | Erreur : "IRCAM Amplify service unavailable. Please retry later." | | Job expiré (>24h) | Erreur : "Job expired. Results are only available for 24 hours." | ## Requirements *(mandatory)* ### Functional Requirements #### MVP (v1.0) - **FR-001**: Le MCP DOIT exposer l'outil `analyze_music` pour le Music Tagger API - **FR-002**: Le MCP DOIT exposer l'outil `separate_stems` pour le Stem Separator API - **FR-003**: Le MCP DOIT exposer l'outil `detect_ai_music` pour l'AI Music Detector API - **FR-004**: Le MCP DOIT exposer l'outil `analyze_loudness` pour le Loudness Analyzer API - **FR-005**: Le MCP DOIT exposer l'outil `check_job_status` pour vérifier les opérations asynchrones - **FR-006**: Le MCP DOIT s'authentifier via la variable d'environnement `IRCAM_AMPLIFY_API_KEY` - **FR-007**: Le MCP DOIT accepter uniquement des URLs publiques comme input audio - **FR-008**: Le MCP DOIT retourner des réponses JSON structurées et lisibles par les LLMs - **FR-009**: Le MCP DOIT retourner un `job_id` pour les opérations longues (>5 secondes) - **FR-010**: Le MCP DOIT fournir des messages d'erreur clairs en anglais avec actions correctives #### Post-MVP (v2.0+) - **FR-011**: Exposer les Voice APIs (AI Speech Detector, Audio-Text Aligner, Talk Analyzer) - **FR-012**: Exposer les autres Music APIs (Cover Detector, Infringement Detector, Quality Check, etc.) - **FR-013**: Exposer les utility APIs (Storage, Converter, Editing) - **FR-014**: Support optionnel des fichiers locaux via file:// URLs ### MCP Tools Schema (MVP) ``` Tool: analyze_music Input: {audio_url: string} Output: {genre: string[], mood: string[], tempo: number, key: string, instruments: string[]} Tool: separate_stems Input: {audio_url: string} Output: {job_id: string} | {vocals_url: string, drums_url: string, bass_url: string, other_url: string} Tool: detect_ai_music Input: {audio_url: string} Output: {confidence: number, classification: "ai_generated"|"human_made"|"uncertain"} Tool: analyze_loudness Input: {audio_url: string} Output: {integrated_lufs: number, true_peak_db: number, loudness_range: number} Tool: check_job_status Input: {job_id: string} Output: {status: "pending"|"processing"|"completed"|"failed", progress?: number, result?: object, error?: string} ``` ### Key Entities - **Audio URL**: URL publique pointant vers un fichier audio (MP3, WAV, FLAC, OGG, M4A) - **Job**: Opération asynchrone avec identifiant unique, statut et résultat optionnel - **Analysis Result**: Données structurées retournées par les APIs d'analyse - **Stem URLs**: Ensemble d'URLs temporaires pointant vers les stems audio séparés (valides 24h) ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Les 5 outils MVP sont invocables par tout LLM compatible MCP - **SC-002**: L'analyse musicale retourne des résultats en moins de 10 secondes pour des fichiers < 5 minutes - **SC-003**: 95% des requêtes valides réussissent quand IRCAM Amplify est disponible - **SC-004**: Les messages d'erreur permettent de résoudre le problème sans documentation externe dans 90% des cas - **SC-005**: Un développeur peut configurer et utiliser le MCP en moins de 5 minutes - **SC-006**: Le MCP fonctionne sur macOS, Linux et Windows sans modification ## Assumptions - L'utilisateur possède une clé API IRCAM Amplify valide - Les fichiers audio sont accessibles via URL publique (pas d'auth requise pour télécharger) - Le MCP s'exécute dans un environnement avec accès internet - Les formats audio supportés par IRCAM incluent au minimum : MP3, WAV, FLAC, OGG, M4A - Les URLs de résultats IRCAM restent valides pendant au moins 24 heures - Les LLMs utilisant ce MCP supportent le protocole MCP standard ## Out of Scope (v1.0) - Gestion de stockage de fichiers - Support des webhooks (utiliser polling via check_job_status) - Upload de fichiers locaux (utiliser URLs publiques) - Voice APIs (AI Speech Detector, Audio-Text Aligner, Talk Analyzer) - APIs utilitaires (Storage, Editing, Converter) - Cache local des résultats - Interface utilisateur ou dashboard