IRCAM Amplify MCP Server

# Tasks: IRCAM Amplify MCP Server **Input**: Design documents from `/specs/001-ircam-amplify-mcp/` **Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/ **Tests**: Tests included as per constitution (80% coverage target with Vitest). **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. ## Format: `[ID] [P?] [Story] Description` - **[P]**: Can run in parallel (different files, no dependencies) - **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3, US4, US5) - Include exact file paths in descriptions ## Path Conventions Based on plan.md structure: - Source: `src/` at repository root - Tests: `tests/` at repository root - Tools: `src/tools/` - Utilities: `src/utils/` - Types: `src/types/` --- ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Project initialization and TypeScript/Node.js setup - [x] T001 Create project structure per plan.md with src/, tests/, src/tools/, src/utils/, src/types/ - [x] T002 Initialize Node.js project with package.json (name: ircam-amplify-mcp, type: module) - [x] T003 [P] Add TypeScript dependencies and create tsconfig.json (target: ES2022, module: NodeNext) - [x] T004 [P] Add @modelcontextprotocol/sdk dependency to package.json - [x] T005 [P] Add Vitest dependency and create vitest.config.ts - [x] T006 [P] Add tsup for building and configure build script in package.json - [x] T007 [P] Configure ESLint and Prettier in package.json and config files - [x] T008 Create .env.example with IRCAM_AMPLIFY_API_KEY placeholder - [x] T009 Create README.md with project overview and quick-start (copy from specs/001-ircam-amplify-mcp/quickstart.md) --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented **⚠️ CRITICAL**: No user story work can begin until this phase is complete - [x] T010 Create TypeScript types for MCP tools in src/types/mcp-tools.ts (AudioInput, JobReference, JobState, MCPError, ErrorCode) - [x] T011 [P] Create TypeScript types for IRCAM API responses in src/types/ircam-api.ts (IrcamApiResponse, IrcamMusicTaggerResponse, IrcamStemSeparatorResponse, IrcamAIDetectorResponse, IrcamLoudnessResponse) - [x] T012 Implement authentication utility in src/utils/auth.ts (getApiKey, createAuthHeaders using Bearer token) - [x] T013 [P] Implement HTTP client wrapper in src/utils/http.ts (fetch wrapper with timeout, error handling, retry logic) - [x] T014 [P] Implement input validation utility in src/utils/validation.ts (validateAudioUrl, validateJobId, SUPPORTED_FORMATS, SUPPORTED_EXTENSIONS) - [x] T015 [P] Implement error formatting utility in src/utils/errors.ts (MCPError creation, error code mapping, formatError function) - [x] T016 Create MCP server entry point skeleton in src/index.ts (Server setup, StdioServerTransport, tool registration placeholder) - [x] T017 [P] Create unit tests for auth utility in tests/unit/utils/auth.test.ts - [x] T018 [P] Create unit tests for validation utility in tests/unit/utils/validation.test.ts - [x] T019 [P] Create unit tests for errors utility in tests/unit/utils/errors.test.ts **Checkpoint**: Foundation ready - user story implementation can now begin in parallel --- ## Phase 3: User Story 1 - Analyze Music (Priority: P1) 🎯 MVP **Goal**: Expose `analyze_music` tool to extract genre, mood, tempo, key, and instruments from audio files **Independent Test**: Submit an audio URL and receive structured tags (genre, mood, tempo, key, instruments) in JSON format ### Tests for User Story 1 - [x] T020 [P] [US1] Create unit test for analyze-music tool in tests/unit/tools/analyze-music.test.ts (mock IRCAM API response, verify transformation) - [x] T021 [P] [US1] Create integration test for analyze_music in tests/integration/mcp-server.test.ts (mock HTTP, verify MCP tool registration and execution) ### Implementation for User Story 1 - [x] T022 [US1] Create MusicAnalysisResult type export in src/types/mcp-tools.ts if not already present - [x] T023 [US1] Implement analyze_music tool in src/tools/analyze-music.ts (call IRCAM Music Tagger API, transform response to MusicAnalysisResult) - [x] T024 [US1] Register analyze_music tool in src/index.ts (add to ListToolsRequestSchema handler, implement CallToolRequestSchema handler) - [x] T025 [US1] Add error handling for analyze_music (invalid URL, unsupported format, API errors) **Checkpoint**: User Story 1 complete - analyze_music tool functional and testable independently --- ## Phase 4: User Story 2 - Separate Stems (Priority: P1) **Goal**: Expose `separate_stems` tool to split audio into vocals, drums, bass, and other stems **Independent Test**: Submit a mixed audio URL and receive URLs to separated stems (or job_id for async processing) ### Tests for User Story 2 - [x] T026 [P] [US2] Create unit test for separate-stems tool in tests/unit/tools/separate-stems.test.ts (test sync and async responses) - [x] T027 [P] [US2] Create integration test for separate_stems in tests/integration/mcp-server.test.ts ### Implementation for User Story 2 - [x] T028 [US2] Create StemSeparationResult and SeparateStemsOutput types in src/types/mcp-tools.ts if not already present - [x] T029 [US2] Implement separate_stems tool in src/tools/separate-stems.ts (call IRCAM Stem Separator API, handle job_id vs direct result) - [x] T030 [US2] Register separate_stems tool in src/index.ts - [x] T031 [US2] Add error handling for separate_stems (timeout handling, job creation errors) **Checkpoint**: User Story 2 complete - separate_stems tool functional (requires US5 for async job polling) --- ## Phase 5: User Story 3 - Detect AI Music (Priority: P1) **Goal**: Expose `detect_ai_music` tool to detect if audio is AI-generated or human-made **Independent Test**: Submit an audio URL and receive confidence score (0-100) and classification (ai_generated/human_made/uncertain) ### Tests for User Story 3 - [x] T032 [P] [US3] Create unit test for detect-ai-music tool in tests/unit/tools/detect-ai-music.test.ts - [x] T033 [P] [US3] Create integration test for detect_ai_music in tests/integration/mcp-server.test.ts ### Implementation for User Story 3 - [x] T034 [US3] Create AIDetectionResult and AIClassification types in src/types/mcp-tools.ts if not already present - [x] T035 [US3] Implement detect_ai_music tool in src/tools/detect-ai-music.ts (call IRCAM AI Music Detector API, transform response) - [x] T036 [US3] Register detect_ai_music tool in src/index.ts - [x] T037 [US3] Add error handling for detect_ai_music **Checkpoint**: User Story 3 complete - detect_ai_music tool functional and testable independently --- ## Phase 6: User Story 4 - Analyze Loudness (Priority: P1) **Goal**: Expose `analyze_loudness` tool to measure integrated LUFS, true peak, and loudness range **Independent Test**: Submit an audio URL and receive loudness metrics (integrated_lufs, true_peak_db, loudness_range) ### Tests for User Story 4 - [x] T038 [P] [US4] Create unit test for analyze-loudness tool in tests/unit/tools/analyze-loudness.test.ts - [x] T039 [P] [US4] Create integration test for analyze_loudness in tests/integration/mcp-server.test.ts ### Implementation for User Story 4 - [x] T040 [US4] Create LoudnessAnalysisResult type in src/types/mcp-tools.ts if not already present - [x] T041 [US4] Implement analyze_loudness tool in src/tools/analyze-loudness.ts (call IRCAM Loudness Analyzer API, transform response) - [x] T042 [US4] Register analyze_loudness tool in src/index.ts - [x] T043 [US4] Add error handling for analyze_loudness **Checkpoint**: User Story 4 complete - analyze_loudness tool functional and testable independently --- ## Phase 7: User Story 5 - Check Job Status (Priority: P1) **Goal**: Expose `check_job_status` tool to poll async operations and retrieve results when ready **Independent Test**: Submit a job_id and receive status (pending/processing/completed/failed), progress percentage, and result when completed ### Tests for User Story 5 - [x] T044 [P] [US5] Create unit test for check-job-status tool in tests/unit/tools/check-job-status.test.ts (test all status states) - [x] T045 [P] [US5] Create integration test for check_job_status in tests/integration/mcp-server.test.ts ### Implementation for User Story 5 - [x] T046 [US5] Create JobStatusInput and JobStatusOutput types in src/types/mcp-tools.ts if not already present - [x] T047 [US5] Implement check_job_status tool in src/tools/check-job-status.ts (call IRCAM Jobs API, handle all status states) - [x] T048 [US5] Register check_job_status tool in src/index.ts - [x] T049 [US5] Add error handling for check_job_status (job not found, job expired, job failed) **Checkpoint**: User Story 5 complete - check_job_status tool functional, enables async workflows for US2 --- ## Phase 8: Polish & Cross-Cutting Concerns **Purpose**: Improvements that affect multiple user stories - [x] T050 [P] Create full MCP server integration test in tests/integration/mcp-server.test.ts (test all 5 tools together) - [x] T051 [P] Add CHANGELOG.md with initial release notes - [x] T052 [P] Add LICENSE file (MIT) - [x] T053 [P] Add .github/ISSUE_TEMPLATE.md for bug reports - [x] T054 [P] Add .github/PULL_REQUEST_TEMPLATE.md with checklist - [x] T055 Verify all tools work together with end-to-end test scenario - [ ] T056 Run quickstart.md validation (manual test of documented steps) - [x] T057 Final code cleanup and formatting (npm run lint, npm run format) - [x] T058 Update README.md with final tool documentation and examples - [x] T059 Build and package for npm publishing (npm run build, verify dist/) --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies - can start immediately - **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories - **User Stories (Phase 3-7)**: All depend on Foundational phase completion - User stories CAN proceed in parallel (all are P1 priority) - Recommended order: US1 → US2 → US3 → US4 → US5 (US5 enables US2 async) - **Polish (Phase 8)**: Depends on all user stories being complete ### User Story Dependencies - **User Story 1 (analyze_music)**: Can start after Phase 2 - No dependencies on other stories - **User Story 2 (separate_stems)**: Can start after Phase 2 - US5 needed for complete async flow - **User Story 3 (detect_ai_music)**: Can start after Phase 2 - No dependencies on other stories - **User Story 4 (analyze_loudness)**: Can start after Phase 2 - No dependencies on other stories - **User Story 5 (check_job_status)**: Can start after Phase 2 - Enhances US2 async capability ### Within Each User Story 1. Tests written FIRST and FAIL before implementation 2. Types before implementation 3. Tool implementation 4. Tool registration in index.ts 5. Error handling 6. Story complete before moving to next ### Parallel Opportunities - All Setup tasks marked [P] can run in parallel (T003-T007) - All Foundational tasks marked [P] can run in parallel (T011, T013-T015, T017-T019) - Once Foundational phase completes, all user stories can start in parallel - All tests for a user story marked [P] can run in parallel - All Polish tasks marked [P] can run in parallel (T050-T054) --- ## Parallel Example: Phase 2 Foundational ```bash # Launch all parallel foundational tasks together: Task: "Create TypeScript types for IRCAM API responses in src/types/ircam-api.ts" Task: "Implement HTTP client wrapper in src/utils/http.ts" Task: "Implement input validation utility in src/utils/validation.ts" Task: "Implement error formatting utility in src/utils/errors.ts" Task: "Create unit tests for auth utility in tests/unit/utils/auth.test.ts" Task: "Create unit tests for validation utility in tests/unit/utils/validation.test.ts" Task: "Create unit tests for errors utility in tests/unit/utils/errors.test.ts" ``` ## Parallel Example: User Story 1 ```bash # Launch tests for User Story 1 together: Task: "Create unit test for analyze-music tool in tests/unit/tools/analyze-music.test.ts" Task: "Create integration test for analyze_music in tests/integration/analyze-music.test.ts" ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup 2. Complete Phase 2: Foundational (CRITICAL - blocks all stories) 3. Complete Phase 3: User Story 1 (analyze_music) 4. **STOP and VALIDATE**: Test analyze_music independently 5. Deploy/demo if ready - single tool is already useful! ### Incremental Delivery 1. Complete Setup + Foundational → Foundation ready 2. Add User Story 1 (analyze_music) → Test → Deploy (MVP!) 3. Add User Story 5 (check_job_status) → Test → Enables async 4. Add User Story 2 (separate_stems) → Test → Deploy (with async support) 5. Add User Story 3 (detect_ai_music) → Test → Deploy 6. Add User Story 4 (analyze_loudness) → Test → Deploy 7. Each story adds value without breaking previous stories ### Recommended Order for Solo Developer ``` Setup → Foundational → US1 → US5 → US2 → US3 → US4 → Polish ``` This order prioritizes: 1. analyze_music (most common use case) 2. check_job_status (enables async for all tools) 3. separate_stems (most differentiated feature, needs async) 4. detect_ai_music (useful for platforms) 5. analyze_loudness (useful for mastering) --- ## Task Summary | Phase | Tasks | Parallel Tasks | |-------|-------|----------------| | Setup | 9 | 5 | | Foundational | 10 | 7 | | US1: analyze_music | 6 | 2 | | US2: separate_stems | 6 | 2 | | US3: detect_ai_music | 6 | 2 | | US4: analyze_loudness | 6 | 2 | | US5: check_job_status | 6 | 2 | | Polish | 10 | 5 | | **Total** | **59** | **27** | --- ## Notes - [P] tasks = different files, no dependencies - [Story] label maps task to specific user story for traceability - Each user story is independently completable and testable - Verify tests fail before implementing (TDD approach per constitution) - Commit after each task or logical group - Stop at any checkpoint to validate story independently - All 5 user stories are P1 (MVP critical) - implement in suggested order for best value delivery