@williamzujkowski/live-coding-music-mcp 2.0.0 → 4.0.0

package/README.md

@@ -4,7 +4,7 @@
 >
 > **Unofficial fan project.** Not affiliated with, or endorsed by, the [Strudel project](https://codeberg.org/uzu/strudel). This adapter exists to make live-coding music accessible to beginners who want to try pattern-based music without learning the whole ecosystem first.
 >
-> **Status:** Beta | 77% test coverage | Published to npm | Actively developed
+> **Status:** Beta | 86% statement coverage | Published to npm | Actively developed
 
 <a href="https://glama.ai/mcp/servers/@williamzujkowski/live-coding-music-mcp">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@williamzujkowski/live-coding-music-mcp/badge" alt="live-coding-music-mcp server" />
@@ -13,16 +13,16 @@
 [![CI](https://github.com/williamzujkowski/live-coding-music-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/williamzujkowski/live-coding-music-mcp/actions)
 [![npm version](https://img.shields.io/npm/v/@williamzujkowski/live-coding-music-mcp.svg)](https://www.npmjs.com/package/@williamzujkowski/live-coding-music-mcp)
 [![Nerq Trust](https://nerq.ai/badge/live-coding-music-mcp)](https://nerq.ai/kya/live-coding-music-mcp)
-[![Tools](https://img.shields.io/badge/tools-66-green.svg)]()
+[![Tools](https://img.shields.io/badge/tools-26-green.svg)]()
 [![License](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)
 
 A Model Context Protocol (MCP) server that drives [Strudel.cc](https://strudel.cc/) from Claude for AI-assisted live-coding music, pattern generation, and algorithmic composition.
 
-**Current State: Beta.** The core workflow (init → generate → write → play → analyze) works reliably with real audio output and has 1470 passing tests covering 77% of statements. CI is hardened with OpenSSF Scorecard, SHA-pinned actions, CODEOWNERS, and Dependabot. Known coverage gaps exist (notably `AudioCaptureService` at 33% and `AudioAnalyzer` branch coverage at 48%) — see [open issues](https://github.com/williamzujkowski/live-coding-music-mcp/issues) for the full list.
+**Current State: Beta.** The core workflow (init → generate → write → play → analyze) works reliably with real audio output. 1771 tests pass, 86.76% statement coverage / 77.32% branch coverage. CI is hardened with OpenSSF Scorecard, SHA-pinned actions, CODEOWNERS, Dependabot, and lint as a blocking gate.
 
 **What "Beta" means here:**
 - Tool schemas are stable within minor versions; breaking changes require a major bump
-- Single-browser-session limitation (multi-session tracked in [#108](https://github.com/williamzujkowski/live-coding-music-mcp/issues/108))
+- Multi-session is supported as of v3.0.0 ([#108](https://github.com/williamzujkowski/live-coding-music-mcp/issues/108)) — named sessions get isolated browser, history, and audio-capture state
 - Upstream `@strudel/*` dependencies pinned to known-good versions; Dependabot bumps gated on CI
 - Expect hands-on iteration for non-standard patterns — report rough edges, they get fixed
 
@@ -44,40 +44,39 @@ A Model Context Protocol (MCP) server that drives [Strudel.cc](https://strudel.c
 
 ## Features
 
-### 🎹 Complete Music Control
-- **65 MCP Tools**: Comprehensive suite for music creation and manipulation
-- **Real Browser Automation**: Direct control of Strudel.cc through Playwright
-- **Live Audio Analysis**: Real-time frequency analysis via Web Audio API
-- **Pattern Generation**: AI-powered creation across 8+ music genres
-- **Music Theory Engine**: Scales, chords, progressions, euclidean rhythms
-- **Session Management**: Save, load, undo/redo with pattern storage
-
-### 🔧 Testing & Development Status
-- ✅ **Test Suite**: Comprehensive test coverage across unit, integration, and validation tests
-- ✅ **Code Coverage**: Actively tracked via CI
-- ✅ **Browser Integration**: Works with live Strudel.cc website
-- ✅ **Audio Analysis**: Real-time FFT analysis functional
-- ✅ **Pattern Generation**: Core music generation features working
-- ✅ **OIDC Publishing**: Secure npm publishing with provenance attestation
+### 🎹 Music control
+- **84 MCP tools** covering pattern editing, playback, audio analysis, generation, history, sessions, and Gemini-backed assists. 26 are the canonical consolidated tools (`pattern_store`, `edit_pattern`, `transform`, `analyze`, `history`, `playback`, `effect`, `shape`, `audio_capture`, `browser_window`, `generate_part`, `generate_rhythm`, `music_theory`, `session`, `ai_assist`, ...); the rest are deprecated aliases kept for one release ([#178](https://github.com/williamzujkowski/live-coding-music-mcp/issues/178)).
+- **4 MCP resources** for catalog browsing without burning tool calls: `strudel://examples`, `strudel://patterns`, `strudel://styles`, `strudel://docs/tools`.
+- **Real browser automation** of Strudel.cc through Playwright.
+- **Multi-session support** — every browser-touching tool accepts an optional `session_id`; sessions have isolated browser pages, undo/redo/history stacks, and audio-capture services.
+- **Audio analysis** via Web Audio API (FFT spectrum, tempo detection, key detection, rhythm complexity).
+- **Template-based pattern generation** across 8 genres (techno, house, dnb, ambient, trap, jungle, jazz, experimental); optional Gemini-backed `ai_assist` for feedback, suggestions, and jamming.
+- **Music theory helpers**: 15+ scales, 8+ chord progression styles, euclidean and polyrhythm generation.
+- **Pattern persistence**: JSON-backed save/load with tags + the in-memory edit history (undo/redo/restore/compare).
+- **Result envelope** on every `tools/call`: clients branch on `{ ok, errorCategory, isRetryable }` instead of parsing free-text.
+
+### 🔧 Testing & CI status
+- **1771 passing tests** across unit, integration, and example-validation suites.
+- **86.76% statement coverage / 77.32% branch coverage**.
+- **Lint blocking in CI**: 0 errors, ~163 warnings (mostly `any` in test mocks).
+- **OIDC trusted publishing** to npm with SLSA build provenance attestation on every release.
 
 **Not Production-Ready:** This is experimental software under active development. Use for exploration and experimentation. Expect breaking changes, bugs, and incomplete features. See [CONTRIBUTING.md](CONTRIBUTING.md) to help improve it.
 
-### 🎼 Example Patterns
+### 🎼 Example patterns
 
-Explore 17 curated example patterns across 10 genres in [`patterns/examples/`](patterns/examples/):
+18 example patterns ship in [`patterns/examples/`](patterns/examples/), grouped by genre:
 
-- **Techno**: Hard techno, minimal techno
-- **House**: Deep house, tech house
-- **Drum & Bass**: Liquid, neurofunk
-- **Ambient**: Dark ambient, drone
-- **Trap**: Modern trap, cloud trap
-- **Jungle**: Classic jungle, ragga jungle
-- **Jazz**: Bebop, modal jazz
-- **Intelligent DnB**: Atmospheric, liquid, LTJ Bukem style
-- **Trip Hop**: Portishead, Massive Attack, Flying Lotus style
-- **Boom Bap**: DJ Premier, Alchemist, golden era hip hop
+- **Techno**: hard-techno, minimal-techno
+- **House**: deep-house, tech-house
+- **Drum & Bass**: liquid-dnb, neurofunk
+- **Ambient**: dark-ambient, drone
+- **Trap**: modern-trap, cloud-trap
+- **Jungle**: classic-jungle, ragga-jungle
+- **Jazz**: bebop, modal-jazz
+- **Longform** (multi-minute pieces): dark-ambient-journey, driving-techno, liquid-dnb-roller, nu-jazz-session
 
-Each example includes pattern code, BPM, key, and description. See [`patterns/examples/README.md`](patterns/examples/README.md) for details.
+Each example is a JSON file with pattern code, BPM, key, and a description. See [`patterns/examples/README.md`](patterns/examples/README.md) for details. Agents can also list these via the `strudel://examples` MCP resource without making any tool calls.
 
 ## Migrating from `@williamzujkowski/strudel-mcp-server`
 
@@ -156,16 +155,21 @@ npm run build
 
 Common commands for immediate use:
 
-| Action | Command |
-|--------|---------|
+| Action | Tool call |
+|---|---|
 | Initialize browser | `init` |
-| Create techno beat | `generate_pattern` with `style: "techno"` |
-| Play pattern | `play` |
-| Stop playback | `stop` |
+| Create a techno beat in one shot | `compose({ style: "techno" })` |
+| Play pattern | `playback({ action: "play" })` |
+| Stop playback | `playback({ action: "stop" })` |
 | Get current pattern | `get_pattern` |
-| Analyze audio | `analyze` |
-| Save pattern | `save` with `name: "my-pattern"` |
-| Undo last change | `undo` |
+| Analyze audio (all features) | `analyze({ include: ["all"] })` |
+| Detect tempo only | `analyze({ include: ["tempo"] })` |
+| Save pattern | `pattern_store({ action: "save", name: "my-pattern" })` |
+| Undo last edit | `history({ action: "undo" })` |
+| Edit current pattern | `edit_pattern({ mode: "write", pattern: "..." })` |
+| Create an isolated session | `session({ action: "create", session_id: "live-1" })` |
+
+The legacy single-verb tools (`play`, `stop`, `save`, `undo`, `write`, `generate_pattern`, ...) were deprecated aliases during the `3.0.x` line and were removed in v4.0.0 ([#178](https://github.com/williamzujkowski/live-coding-music-mcp/issues/178)). Use the consolidated tools above.
 
 **One-shot workflow:**
 ```
@@ -197,7 +201,7 @@ Then ask Claude:
 
 <!-- TOOLS:START -->
 
-**66 tools** across 15 categories:
+**26 tools** across 14 categories:
 
 <details><summary><strong>Setup</strong> (1)</summary>
 
@@ -207,127 +211,94 @@ Then ask Claude:
 
 </details>
 
-<details><summary><strong>Pattern Editing</strong> (5)</summary>
+<details><summary><strong>Pattern Editing</strong> (2)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `write` | Write pattern to editor with optional auto-play and validation |
-| `append` | Append code to current pattern |
-| `insert` | Insert code at specific line |
-| `replace` | Replace pattern section |
+| `edit_pattern` | Mutate the current session pattern.  |
 | `get_pattern` | Get current pattern code |
 
 </details>
 
-<details><summary><strong>Playback</strong> (6)</summary>
+<details><summary><strong>Playback</strong> (2)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `status` | Get current browser and playback status (quick state check) |
-| `clear` | Clear the editor |
-| `play` | Start playing pattern |
-| `pause` | Pause playback |
-| `stop` | Stop playback |
+| `playback` | Control transport on the current session.  |
 | `set_tempo` | Set BPM |
 
 </details>
 
-<details><summary><strong>Storage</strong> (3)</summary>
+<details><summary><strong>Storage</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `save` | Save pattern with metadata |
-| `load` | Load saved pattern |
-| `list` | List saved patterns |
+| `pattern_store` | Persist patterns to disk and read them back.  |
 
 </details>
 
-<details><summary><strong>History</strong> (4)</summary>
+<details><summary><strong>History</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `undo` | Undo last action |
-| `redo` | Redo action |
-| `list_history` | List recent pattern history with timestamps and previews |
-| `restore_history` | Restore a previous pattern from history by ID |
+| `history` | Navigate or inspect the pattern edit history.  |
 
 </details>
 
-<details><summary><strong>Generation</strong> (8)</summary>
+<details><summary><strong>Generation</strong> (3)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `compose` | Generate, write, and play a complete pattern in one step. Auto-initializes browser if needed. |
-| `generate_pattern` | Generate complete pattern from style with optional auto-play |
-| `generate_drums` | Generate drum pattern |
-| `generate_bassline` | Generate bassline |
-| `generate_melody` | Generate melody from scale |
-| `generate_polyrhythm` | Generate polyrhythm |
-| `generate_fill` | Generate drum fill |
-| `generate_variation` | Create pattern variations |
+| `compose` | Generate, write, and play a complete pattern in one step. Auto-initializes default browser if needed. |
+| `generate_part` | Generate a single instrumental layer and append it to the current session pattern.  |
+| `generate_rhythm` | Generate a rhythmic pattern and append it to the current session.  |
 
 </details>
 
-<details><summary><strong>Music Theory</strong> (4)</summary>
+<details><summary><strong>Music Theory</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `generate_scale` | Generate scale notes |
-| `generate_chord_progression` | Generate chord progression |
-| `generate_euclidean` | Generate Euclidean rhythm |
-| `apply_scale` | Apply scale to notes |
+| `music_theory` | Music-theory queries.  |
 
 </details>
 
-<details><summary><strong>Transform</strong> (9)</summary>
+<details><summary><strong>Transform</strong> (3)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `transpose` | Transpose notes by semitones |
-| `reverse` | Reverse pattern |
-| `stretch` | Time stretch pattern |
-| `quantize` | Quantize to grid |
-| `humanize` | Add human timing variation |
-| `add_effect` | Add effect to pattern |
-| `remove_effect` | Remove effect |
-| `add_swing` | Add swing to pattern |
-| `set_energy` | Adjust the overall energy level of the current pattern on a 0-10 scale. 0: minimal/ambient, 1-2: sparse, 3-4: light/relaxed, 5-6: normal/moderate, 7-8: driving/intense, 9-10: maximum. Auto-plays after applying energy level. |
+| `transform` | Apply a single transform op to the current session pattern.  |
+| `effect` | Add or remove a Strudel effect on the current session pattern.  |
+| `shape` | Shape the current pattern along one of three high-level dimensions.  |
 
 </details>
 
-<details><summary><strong>AI</strong> (4)</summary>
+<details><summary><strong>AI</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `get_pattern_feedback` | Get AI-powered creative feedback on the current pattern using Google Gemini. Analyzes pattern structure and optionally audio. |
-| `jam_with` | AI generates a complementary layer to jam with your pattern. Analyzes current pattern to detect tempo, key, and existing layers, then generates a matching layer that fits musically. |
-| `shift_mood` | Transform current pattern to match a different emotional mood by adjusting tempo, effects, and note choices. Moods: dark, euphoric, melancholic, aggressive, dreamy, peaceful, energetic. |
-| `refine` | Incrementally refine the current pattern with simple directional commands. Supports: faster/slower (tempo), louder/quieter (gain), brighter/darker (filter cutoff), "more reverb"/drier (reverb). Auto-plays after applying refinement. |
+| `ai_assist` | Gemini-backed pattern assistance.  |
 
 </details>
 
-<details><summary><strong>Analysis</strong> (7)</summary>
+<details><summary><strong>Analysis</strong> (6)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `analyze` | Complete audio analysis |
-| `analyze_spectrum` | FFT spectrum analysis |
-| `analyze_rhythm` | Rhythm analysis |
-| `detect_tempo` | BPM detection |
-| `detect_key` | Key detection |
+| `analyze` | Audio analysis on the currently-playing pattern.  |
 | `validate_pattern_runtime` | Validate pattern with runtime error checking (monitors Strudel console for errors) |
-| `compare_patterns` | Compare two patterns from history showing differences |
+| `validate_pattern_local` | Validate pattern syntax against the in-process StrudelEngine (no browser required) |
+| `analyze_pattern_local` | Static analysis (events/cycle, complexity, optional BPM) without browser playback |
+| `query_pattern_events` | Enumerate events the pattern would emit between two cycle indices (max 16 cycles) |
+| `transpile_pattern` | Transpile pattern source via StrudelEngine; returns transpiled code or syntax error |
 
 </details>
 
-<details><summary><strong>Session</strong> (4)</summary>
+<details><summary><strong>Session</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `create_session` | Create a new isolated Strudel browser session. Sessions share one browser but have isolated contexts. |
-| `destroy_session` | Close and destroy a Strudel session, releasing its resources. |
-| `list_sessions` | List all active Strudel sessions with their metadata. |
-| `switch_session` | Change the default session used by other tools. |
+| `session` | Manage isolated Strudel browser sessions (multi-session, #108).  |
 
 </details>
 
@@ -336,41 +307,27 @@ Then ask Claude:
 | Tool | Description |
 |------|-------------|
 | `export_midi` | Export current pattern to MIDI file. Parses note(), n(), and chord() functions. |
-| `screenshot` | Take a screenshot of the current Strudel editor state |
-
-</details>
-
-<details><summary><strong>Audio</strong> (3)</summary>
-
-| Tool | Description |
-|------|-------------|
-| `start_audio_capture` | Start capturing audio from Strudel output. Audio must be playing for capture to work. |
-| `stop_audio_capture` | Stop audio capture and return the recorded audio as base64-encoded data. |
-| `capture_audio_sample` | Capture a fixed-duration audio sample from Strudel output. Audio must be playing. |
+| `browser_window` | Interact with the visible Strudel browser window.  |
 
 </details>
 
-<details><summary><strong>Debug</strong> (5)</summary>
+<details><summary><strong>Audio</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `show_browser` | Bring browser window to foreground for visual feedback |
-| `performance_report` | Get performance metrics and bottlenecks |
-| `memory_usage` | Get current memory usage statistics |
-| `diagnostics` | Get detailed browser diagnostics including cache, errors, and performance |
-| `show_errors` | Display captured console errors and warnings from Strudel |
+| `audio_capture` | Record audio output from the live Strudel session.  |
 
 </details>
 
-<details><summary><strong>Other</strong> (1)</summary>
+<details><summary><strong>Debug</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `suggest_pattern_from_audio` | Analyze the currently playing audio and suggest a complementary Strudel pattern using Gemini AI. Extracts tempo, key, and spectral features locally, then uses AI to generate a matching pattern. Returns pattern text (not auto-executed). |
+| `diagnostics` | Inspect server and browser state.  |
 
 </details>
 
-_Auto-generated from source. 66 tools registered._
+_Auto-generated from source. 26 tools registered._
 
 <!-- TOOLS:END -->
 
@@ -657,14 +614,15 @@ The Strudel MCP Server is built with a modular architecture that separates conce
 
 ### Core Components
 
-#### 1. **StrudelMCPServer** (`src/server/server.ts`)
+#### 1. **StrudelMCPServer** (`src/server/server.ts`, ~510 lines)
 
-Main MCP server implementation handling:
-- **65 Tool Definitions**: Complete API surface for music control
-- **Request Routing**: Directs tool calls to appropriate handlers
-- **State Management**: Tracks initialization, undo/redo stacks, pattern cache
-- **Error Handling**: Graceful degradation and informative error messages
-- **Lazy Initialization**: Browser starts only when needed
+Thin MCP dispatcher that:
+- Aggregates 26 tool definitions from the per-domain modules in `src/server/tools/`
+- Routes `tools/call` requests to the right module's `execute()`
+- Wraps every response in the discriminated result envelope (`{ ok, errorCategory, isRetryable, ... }`)
+- Tracks initialization, per-session history bundles, per-session audio capture services
+- Advertises and serves MCP resources (`strudel://examples`, etc.)
+- Lazy-initializes the default browser controller on first browser-touching call
 
 Key Features:
 ```typescript
@@ -769,28 +727,42 @@ Persistent pattern storage:
 live-coding-music-mcp/
 ├── src/
 │   ├── server/
-│   │   └── server.ts                    # MCP server
+│   │   ├── server.ts                    # MCP dispatcher (~510 lines)
+│   │   ├── resources.ts                 # MCP resources (#131)
+│   │   └── tools/
+│   │       ├── ai.ts, analysis.ts, capture.ts, compose.ts,
+│   │       ├── diagnostics.ts, editor.ts, generate.ts, history.ts,
+│   │       ├── playback.ts, session.ts, storage.ts, transform.ts,
+│   │       └── types.ts                 # ToolContext, Envelope, helpers
 │   ├── services/
-│   │   ├── MusicTheory.ts                # Theory engine
-│   │   └── PatternGenerator.ts           # Pattern creation
+│   │   ├── MusicTheory.ts                # Scale/chord/euclidean helpers
+│   │   ├── PatternGenerator.ts           # Template-based generation
+│   │   ├── SessionManager.ts             # Multi-session lifecycle (#108)
+│   │   ├── AudioCaptureService.ts        # Audio recording
+│   │   ├── MIDIExportService.ts          # MIDI export
+│   │   ├── GeminiService.ts              # Gemini API client (ai_assist)
+│   │   ├── StrudelEngine.ts              # @strudel/* wrapper
+│   │   └── StrudelEngineHelpers.ts       # Pure helpers (#107)
 │   ├── utils/
-│   │   └── Logger.ts                     # Logging utility
-│   ├── types/
-│   │   └── index.ts                      # TypeScript types
-│   ├── StrudelController.ts              # Browser automation
-│   ├── AudioAnalyzer.ts                  # Audio analysis
-│   ├── PatternStore.ts                   # Pattern persistence
+│   │   ├── Logger.ts
+│   │   ├── PatternValidator.ts           # Syntax + safety checks
+│   │   ├── ErrorRecovery.ts              # Retry / backoff
+│   │   ├── PerformanceMonitor.ts
+│   │   └── InputValidator.ts             # Input bound checks
+│   ├── StrudelController.ts              # Browser automation (~800 lines)
+│   ├── AudioAnalyzer.ts                  # Audio analysis (~800 lines)
+│   ├── PatternStore.ts                   # On-disk pattern persistence
 │   └── index.ts                          # Entry point
-├── tests/
-│   ├── browser-test.js                   # Browser integration
-│   ├── integration.test.js               # Integration tests
-│   ├── manual-test.js                    # Manual testing
-│   ├── mcp-tools.test.ts                 # MCP tool tests
-│   └── strudel-integration.js            # Full integration
-├── patterns/                             # Saved patterns
-├── config.json                           # Server configuration
-├── package.json                          # Dependencies
-└── tsconfig.json                         # TypeScript config
+├── src/__tests__/                        # Jest suites (unit + integration + browser)
+├── patterns/
+│   ├── examples/                         # 18 bundled example patterns
+│   └── *.json                            # Saved patterns at runtime
+├── scripts/
+│   ├── generate-tool-docs.ts             # README tool-table generator
+│   └── generate-changelog.ts
+├── config.json                           # Local config (gitignored)
+├── package.json
+└── tsconfig.json
 ```
 
 ### Data Flow
@@ -956,102 +928,49 @@ gh release create v$(node -p "require('./package.json').version") --generate-not
 
 The package uses OIDC trusted publishing with provenance attestation for supply chain security.
 
-### Project Structure
-
-```
-src/
-├── server/
-│   └── server.ts                    # MCP server
-│
-├── services/
-│   ├── MusicTheory.ts                # Music theory engine
-│   │   - 15+ scales (major, minor, modes, etc.)
-│   │   - Chord progressions (jazz, pop, blues, etc.)
-│   │   - Euclidean rhythm generation
-│   │   - Arpeggio generation
-│   │
-│   └── PatternGenerator.ts           # Pattern creation service
-│       - Genre-specific drum patterns
-│       - Bassline generation
-│       - Melody composition
-│       - Pattern variations
-│       - Complete track generation
-│
-├── utils/
-│   ├── Logger.ts                     # Logging utility
-│   ├── PerformanceMonitor.ts         # Performance tracking
-│   ├── PatternValidator.ts           # Pattern syntax validation
-│   └── ErrorRecovery.ts              # Error handling & recovery
-│
-├── types/
-│   └── index.ts                      # TypeScript type definitions
-│
-├── StrudelController.ts              # Browser automation
-│   - Chromium management via Playwright
-│   - CodeMirror editor manipulation
-│   - Playback control
-│   - Pattern validation
-│   - Error recovery
-│
-├── AudioAnalyzer.ts                  # Real-time audio analysis
-│   - Web Audio API injection
-│   - FFT spectral analysis
-│   - Frequency band detection
-│   - Playing state monitoring
-│
-├── PatternStore.ts                   # Pattern persistence
-│   - JSON-based storage
-│   - Tag-based organization
-│   - Metadata tracking
-│   - List caching
-│
-└── index.ts                          # Application entry point
-```
-
-### Adding New Tools
-
-To add a new MCP tool:
-
-1. **Define the tool** in `getTools()` method:
-```typescript
-{
-  name: 'my_new_tool',
-  description: 'Description of what it does',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      param1: { type: 'string', description: 'Parameter description' },
-      param2: { type: 'number', description: 'Numeric parameter' }
-    },
-    required: ['param1']
-  }
-}
-```
+### Adding new tools
+
+Tools live in per-domain modules under `src/server/tools/<domain>.ts`. `server.ts` just dispatches. To add a tool:
+
+1. **Pick the right domain module** (or add a new one). Add the tool definition to that module's `tools` array:
+
+   ```typescript
+   export const tools: Tool[] = [
+     // ...
+     {
+       name: 'my_new_tool',
+       description: 'One-line description; agents read this to pick between adjacent tools',
+       inputSchema: {
+         type: 'object',
+         properties: {
+           param1: { type: 'string', description: 'What it is' },
+           session_id: { type: 'string', description: 'Optional session ID (#108)' },
+         },
+         required: ['param1'],
+       },
+     },
+   ];
+   ```
 
-2. **Implement the handler** in `executeTool()` switch statement:
-```typescript
-case 'my_new_tool':
-  // Your implementation here
-  return await this.someService.doSomething(args.param1, args.param2);
-```
+2. **Add the case** to the module's `execute()` switch:
 
-3. **Add necessary service methods** if needed:
-```typescript
-// In appropriate service file
-async doSomething(param1: string, param2?: number): Promise<string> {
-  // Implementation
-  return `Result: ${param1}`;
-}
-```
+   ```typescript
+   case 'my_new_tool':
+     return await ctx.getController(args.session_id).doSomething(args.param1);
+   ```
 
-4. **Test the tool**:
-```bash
-# Build
-npm run build
+3. **Add a service method** if needed (`MusicTheory`, `PatternGenerator`, etc.) and surface it through `ToolContext` (`src/server/tools/types.ts`) if other modules need it.
 
-# Test via MCP
-echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"my_new_tool","arguments":{"param1":"test"}},"id":2}' | node dist/index.js
-```
+4. **Don't hand-edit the README tool table.** It auto-generates via `npm run build` → `scripts/generate-tool-docs.ts`. A Jest test plus a CI step guard against drift.
+
+5. **Use the envelope helpers** for returns: `ok(data)`, `empty(data)`, `err('validation', 'message')` from `src/server/tools/types.ts`. Raw returns still work — the dispatcher normalises them — but native envelope construction is clearer.
+
+6. **Build and test**:
+
+   ```bash
+   npm run build
+   echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"my_new_tool","arguments":{"param1":"test"}},"id":2}' | node dist/index.js
+   ```
 
 ### Testing Strategy
 
@@ -1074,7 +993,7 @@ npm run test:integration
 # - Pattern generation
 # - Audio analysis
 # - Pattern storage
-# - All 65 tools
+# - All 84 registered tools
 ```
 
 #### 3. Manual Testing
@@ -1289,12 +1208,19 @@ SMOOTHING=0.8
 
 ## Performance
 
-- **Pattern Generation**: <100ms
-- **Browser Initialization**: ~3 seconds
-- **Pattern Writing**: Instant
-- **Playback Start**: ~500ms
-- **Audio Analysis**: Real-time
-- **Memory Usage**: <150MB
+Measured against the current `StrudelController` cache + Strudel.cc on a developer machine:
+
+| Operation | Latency |
+|---|---|
+| Browser initialization | 1.5–2 s (with resource blocking) |
+| Pattern write | 50–80 ms (cached CodeMirror editor access) |
+| Pattern read (cached) | 10–15 ms |
+| Play / pause / stop | 100–150 ms |
+| Audio analysis (single FFT) | 10–15 ms |
+| Tempo detection | <100 ms (onset-based; degraded under headless audio) |
+| Key detection | <100 ms (Krumhansl-Schmuckler) |
+| Pattern generation | <100 ms (template-based) |
+| Process resident memory | ~120–150 MB |
 
 ## Advanced Usage
 
@@ -1555,7 +1481,7 @@ npm run build
 # Check if server responds
 echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js
 
-# Should return JSON with 65 tools
+# Should return JSON with 26 tools
 
 # Reinstall MCP server in Claude
 claude mcp remove strudel
@@ -1734,6 +1660,6 @@ Earlier versions of this package (including `@williamzujkowski/strudel-mcp-serve
 
 ---
 
-**v2.4.0** - Open Source | Experimental | [Report Issues](https://github.com/williamzujkowski/live-coding-music-mcp/issues) | [Contribute](https://github.com/williamzujkowski/live-coding-music-mcp/pulls)
+**v4.0.0** — Open source, AGPL-3.0-or-later, experimental | [Report issues](https://github.com/williamzujkowski/live-coding-music-mcp/issues) | [Contribute](https://github.com/williamzujkowski/live-coding-music-mcp/pulls)
 
 *This project is under active development. Core features work, but expect bugs and breaking changes. Not recommended for production use.*

package/dist/AudioAnalyzer.js

@@ -625,7 +625,6 @@ export class AudioAnalyzer {
             return 0;
         let syncopationScore = 0;
         for (let i = 1; i < onsets.length; i++) {
-            const interval = onsets[i] - onsets[i - 1];
             const phase = (onsets[i] % (meanInterval * 4)) / meanInterval;
             // Check if onset is on an off-beat (not on 0, 1, 2, 3)
             const nearestBeat = Math.round(phase);

package/dist/PatternStore.js

@@ -99,7 +99,6 @@ export class PatternStore {
         }
         try {
             const files = await fs.readdir(this.basePath);
-            const patterns = [];
             // Parallel file reading for better performance
             const readPromises = files
                 .filter(file => file.endsWith('.json'))