IRCAM Amplify MCP Server

# Implementation Plan: IRCAM Amplify MCP Server **Branch**: `001-ircam-amplify-mcp` | **Date**: 2025-12-12 | **Spec**: [spec.md](./spec.md) **Input**: Feature specification from `/specs/001-ircam-amplify-mcp/spec.md` ## Summary Créer un serveur MCP (Model Context Protocol) permettant à tout LLM compatible d'utiliser les APIs IRCAM Amplify pour le traitement audio. Le MVP expose 5 outils : analyse musicale (Music Tagger), séparation de stems (Stem Separator), détection IA (AI Music Detector), analyse loudness (Loudness Analyzer), et vérification de statut des jobs asynchrones. L'approche technique suit la constitution : Node.js + TypeScript + SDK MCP officiel, avec une architecture simple (single project) et une authentification via variable d'environnement. ## Technical Context **Language/Version**: TypeScript 5.x, Node.js 18+ (LTS) **Primary Dependencies**: @modelcontextprotocol/sdk (SDK MCP officiel), fetch natif (Node 18+) **Storage**: N/A (pas de persistence, utilise les URLs temporaires IRCAM) **Testing**: Vitest (rapide, TypeScript natif) **Target Platform**: Cross-platform (macOS, Linux, Windows) via Node.js **Project Type**: Single project (MCP server standalone) **Performance Goals**: Réponse MCP < 100ms (hors temps API IRCAM) **Constraints**: Pas de webhooks (polling uniquement), URLs publiques uniquement pour audio **Scale/Scope**: 5 tools MVP, extensible à 17+ APIs post-MVP ## Constitution Check *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* | Principe | Statut | Justification | |----------|--------|---------------| | **I. MCP-First Design** | PASS | Chaque tool MCP = 1 API IRCAM, réponses JSON pour LLMs | | **II. Developer Experience** | PASS | npm install + env var, quick-start < 5 min | | **III. Sécurité & Credentials** | PASS | Token via IRCAM_AMPLIFY_API_KEY, jamais en logs | | **IV. Qualité & Tests** | PASS | Vitest + mocks API, coverage 80% target | | **V. Documentation Vivante** | PASS | README + quickstart + tool docs inclus | | **VI. Open Source Best Practices** | PASS | MIT, CHANGELOG, PR template | | **Stack Technique** | PASS | Node.js 18+, TypeScript, @modelcontextprotocol/sdk, Vitest, tsup | **Constitution Check Result**: ALL GATES PASSED ## Project Structure ### Documentation (this feature) ```text specs/001-ircam-amplify-mcp/ ├── spec.md # Feature specification ├── plan.md # This file ├── research.md # Phase 0: API research & decisions ├── data-model.md # Phase 1: Data entities & types ├── quickstart.md # Phase 1: Getting started guide ├── contracts/ # Phase 1: MCP tool schemas │ ├── analyze-music.json │ ├── separate-stems.json │ ├── detect-ai-music.json │ ├── analyze-loudness.json │ └── check-job-status.json └── tasks.md # Phase 2: Implementation tasks (via /speckit.tasks) ``` ### Source Code (repository root) ```text src/ ├── index.ts # MCP server entry point ├── tools/ # One file per MCP tool │ ├── analyze-music.ts │ ├── separate-stems.ts │ ├── detect-ai-music.ts │ ├── analyze-loudness.ts │ └── check-job-status.ts ├── utils/ │ ├── auth.ts # IRCAM API authentication │ ├── http.ts # HTTP client wrapper │ ├── validation.ts # Input validation │ └── errors.ts # Error formatting └── types/ ├── ircam-api.ts # IRCAM API response types └── mcp-tools.ts # MCP tool input/output types tests/ ├── unit/ │ ├── tools/ # Tool logic tests │ └── utils/ # Utility tests └── integration/ └── mcp-server.test.ts # Full server tests with mocks package.json tsconfig.json vitest.config.ts README.md ``` **Structure Decision**: Single project structure selected. No frontend/backend split needed - this is a standalone MCP server. Structure follows constitution's recommended layout with `src/tools/`, `src/utils/`, `src/types/`. ## Complexity Tracking > No Constitution violations detected. All design choices align with principles. | Aspect | Choice | Aligned With | |--------|--------|--------------| | Single project | MCP server only | Constitution: Simple structure | | No external HTTP lib | fetch natif Node 18+ | Constitution: Pas de dépendance externe | | No ORM/DB | URLs temporaires IRCAM | Spec: Storage hors scope | | Polling vs webhooks | check_job_status tool | Spec: Simplification async | ## Phase Summary ### Phase 0: Research (research.md) - IRCAM Amplify API authentication pattern - IRCAM API endpoint structures for 4 target APIs - Job status polling mechanism - Error response formats ### Phase 1: Design (data-model.md, contracts/, quickstart.md) - TypeScript types for IRCAM API responses - MCP tool JSON schemas for all 5 tools - Quick-start guide for developers ### Phase 2: Tasks (via /speckit.tasks) - Implementation tasks broken down by tool - Testing tasks - Documentation tasks