IRCAM Amplify MCP Server

# Data Model: IRCAM Amplify MCP Server **Feature**: 001-ircam-amplify-mcp **Date**: 2025-12-12 ## Overview Ce document définit les types TypeScript utilisés par le MCP server pour les entrées, sorties et communications avec l'API IRCAM Amplify. ## Core Types ### Audio Input ```typescript /** * Input audio reference - URL publique uniquement */ interface AudioInput { /** Public URL to audio file (MP3, WAV, FLAC, OGG, M4A) */ audio_url: string; } ``` ### Job Management ```typescript /** * Status d'une opération asynchrone */ type JobStatus = 'pending' | 'processing' | 'completed' | 'failed'; /** * Référence à un job asynchrone */ interface JobReference { /** Identifiant unique du job */ job_id: string; } /** * État complet d'un job */ interface JobState<T = unknown> { /** Statut actuel */ status: JobStatus; /** Progression en pourcentage (0-100) */ progress?: number; /** Résultat si completed */ result?: T; /** Message d'erreur si failed */ error?: string; } ``` ### Error Handling ```typescript /** * Codes d'erreur standardisés */ type ErrorCode = | 'MISSING_API_KEY' | 'INVALID_API_KEY' | 'INVALID_URL' | 'UNSUPPORTED_FORMAT' | 'FILE_TOO_LARGE' | 'RATE_LIMITED' | 'SERVICE_UNAVAILABLE' | 'JOB_NOT_FOUND' | 'JOB_FAILED' | 'UNKNOWN_ERROR'; /** * Structure d'erreur MCP */ interface MCPError { /** Code d'erreur machine-readable */ code: ErrorCode; /** Message human-readable */ message: string; /** Suggestion d'action corrective */ suggestion?: string; /** Délai avant retry (secondes) */ retry_after?: number; } ``` ## Tool-Specific Types ### analyze_music ```typescript /** * Résultat de l'analyse musicale (Music Tagger) */ interface MusicAnalysisResult { /** Genres détectés (ex: ["electronic", "house"]) */ genre: string[]; /** Ambiances/moods (ex: ["energetic", "uplifting"]) */ mood: string[]; /** Tempo en BPM */ tempo: number; /** Tonalité (ex: "C major", "A minor") */ key: string; /** Instruments détectés */ instruments: string[]; } ``` ### separate_stems ```typescript /** * Résultat de la séparation de stems */ interface StemSeparationResult { /** URL du stem vocals */ vocals_url: string; /** URL du stem drums */ drums_url: string; /** URL du stem bass */ bass_url: string; /** URL du stem other instruments */ other_url: string; } /** * Output peut être soit un job_id (async) soit le résultat direct */ type SeparateStemsOutput = JobReference | StemSeparationResult; ``` ### detect_ai_music ```typescript /** * Classification de contenu audio */ type AIClassification = 'ai_generated' | 'human_made' | 'uncertain'; /** * Résultat de la détection IA */ interface AIDetectionResult { /** Score de confiance 0-100 */ confidence: number; /** Classification finale */ classification: AIClassification; } ``` ### analyze_loudness ```typescript /** * Résultat de l'analyse loudness */ interface LoudnessAnalysisResult { /** Integrated loudness en LUFS */ integrated_lufs: number; /** True peak en dB */ true_peak_db: number; /** Loudness range (LRA) en LU */ loudness_range: number; } ``` ### check_job_status ```typescript /** * Input pour vérification de statut */ interface JobStatusInput { /** ID du job à vérifier */ job_id: string; } /** * Output de check_job_status * Le type du result dépend de l'opération originale */ type JobStatusOutput = JobState<StemSeparationResult>; ``` ## IRCAM API Types (Internal) Ces types représentent les réponses brutes de l'API IRCAM avant transformation. ```typescript /** * Réponse générique IRCAM API */ interface IrcamApiResponse<T> { success: boolean; data?: T; error?: { code: string; message: string; }; } /** * Réponse Music Tagger IRCAM (structure hypothétique) */ interface IrcamMusicTaggerResponse { result: { tags: { genre: string[]; mood: string[]; instruments: string[]; }; analysis: { bpm: number; key: string; time_signature: string; }; }; } /** * Réponse Stem Separator IRCAM */ interface IrcamStemSeparatorResponse { job_id?: string; result?: { stems: { vocals: { url: string }; drums: { url: string }; bass: { url: string }; other: { url: string }; }; }; } /** * Réponse AI Detector IRCAM */ interface IrcamAIDetectorResponse { result: { ai_probability: number; human_probability: number; classification: string; }; } /** * Réponse Loudness Analyzer IRCAM */ interface IrcamLoudnessResponse { result: { integrated: number; true_peak: number; range: number; short_term_max: number; }; } ``` ## Type Mapping | MCP Tool | Input Type | Output Type | IRCAM Type | |----------|------------|-------------|------------| | analyze_music | AudioInput | MusicAnalysisResult | IrcamMusicTaggerResponse | | separate_stems | AudioInput | SeparateStemsOutput | IrcamStemSeparatorResponse | | detect_ai_music | AudioInput | AIDetectionResult | IrcamAIDetectorResponse | | analyze_loudness | AudioInput | LoudnessAnalysisResult | IrcamLoudnessResponse | | check_job_status | JobStatusInput | JobStatusOutput | IrcamApiResponse | ## Validation Rules ### AudioInput Validation ```typescript const audioInputSchema = { audio_url: { type: 'string', format: 'uri', pattern: '^https?://', description: 'Must be a valid HTTP/HTTPS URL' } }; ``` ### Supported Audio Formats ```typescript const SUPPORTED_FORMATS = [ 'audio/mpeg', // MP3 'audio/wav', // WAV 'audio/x-wav', // WAV alt 'audio/flac', // FLAC 'audio/ogg', // OGG 'audio/mp4', // M4A 'audio/x-m4a' // M4A alt ]; const SUPPORTED_EXTENSIONS = ['.mp3', '.wav', '.flac', '.ogg', '.m4a']; ``` ### Size Limits ```typescript const MAX_FILE_SIZE_MB = 100; const MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024; ``` ## State Transitions ### Job Lifecycle ``` [Created] → pending → processing → completed ↘ ↗ → failed ← ``` | Transition | Trigger | Notes | |------------|---------|-------| | → pending | Job submitted | Initial state | | pending → processing | Worker picks up | Progress updates | | processing → completed | Success | Result available | | processing → failed | Error | Error message set | | any → expired | 24h elapsed | Job garbage collected |