live-coding-music-mcp

🎵 MCP server for AI-assisted live-coding music via strudel.cc

Unofficial fan project. Not affiliated with, or endorsed by, the Strudel project. 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 | 86% statement coverage | Published to npm | Actively developed

A Model Context Protocol (MCP) server that drives 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. 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
• Multi-session is supported as of v3.0.0 (#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

Table of Contents

• Features
• Installation
• Quick Reference
• Quick Start
• Available Tools
• Usage Examples
• Architecture
• Advanced Usage
• Configuration
• Security
• Troubleshooting
• Development
• Contributing

Features

🎹 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).
• 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 to help improve it.

🎼 Example patterns

18 example patterns ship in patterns/examples/, grouped by genre:

• 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 is a JSON file with pattern code, BPM, key, and a description. See 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

This project was renamed from @williamzujkowski/strudel-mcp-server to @williamzujkowski/live-coding-music-mcp to make the unofficial fan-project status unambiguous (see #97). The old package is deprecated on npm.

If you were using the old package:

bashCopy code
# Remove old
npm uninstall -g @williamzujkowski/strudel-mcp-server

# Install new
npm install -g @williamzujkowski/live-coding-music-mcp

Update your MCP client config. The bin name changed from strudel-mcp to live-coding-music-mcp:

jsoncCopy code
// BEFORE
{
  "mcpServers": {
    "strudel": { "command": "strudel-mcp" }
  }
}

// AFTER
{
  "mcpServers": {
    "live-coding-music": { "command": "live-coding-music-mcp" }
  }
}

The MCP server's internal identity string also changed from strudel-mcp-enhanced to live-coding-music-mcp. If you have a client that keys on that string (logs, allowlists, permission policies), update it accordingly.

All tool names and schemas are unchanged.

Installation

Prerequisites

Optional: Docker for containerized deployment.

From npm

bashCopy code
npm install -g @williamzujkowski/live-coding-music-mcp

# Install browser (required once)
npx playwright install chromium

From Source

bashCopy code
# Clone repository
git clone https://github.com/williamzujkowski/live-coding-music-mcp.git
cd live-coding-music-mcp

# Install dependencies
npm install

# Install Chromium for browser automation
npx playwright install chromium

# Build the project
npm run build

Quick Reference

Common commands for immediate use:

The legacy single-verb tools (play, stop, save, undo, write, generate_pattern, ...) still work in v3.0 as deprecated aliases. They forward to the consolidated tools and will be removed in v3.1 (#178).

One-shot workflow:

Copy code
compose with style: "dnb", key: "Am", bpm: 174, auto_play: true

Quick Start

1. Add to Claude

bashCopy code
# If installed globally
claude mcp add strudel live-coding-music-mcp

# If built from source
claude mcp add strudel node /path/to/live-coding-music-mcp/dist/index.js

2. Start Using

bashCopy code
claude chat

Then ask Claude:

• "Initialize Strudel and create a techno beat"
• "Generate a jazz chord progression in F major"
• "Create a drum & bass pattern at 174 BPM"

Available Tools

84 tools across 15 categories:

Auto-generated from source. 84 tools registered.

Usage Examples

Basic Pattern Creation

Create a Simple Beat

Copy code
You: Initialize Strudel and create a simple techno beat

Claude: [Initializes browser]
        [Generates and writes pattern]
        [Starts playback]

Pattern created:
setcpm(130)
stack(
  s("bd*4"),
  s("~ cp ~ cp"),
  s("hh*8").gain(0.4)
).gain(0.8)

Generate a Bassline

Copy code
You: Add a techno bassline in C

Claude: [Generates bassline]
        [Appends to current pattern]

Added: note("c2 c2 c2 c2").s("sawtooth").cutoff(800)

Advanced Music Generation

Jazz Composition

Copy code
You: Create a jazz progression in F major with a walking bass

Claude: Generated progression: "Gm7" "C7" "Fmaj7"

Pattern:
stack(
  note("Gm7" "C7" "Fmaj7").struct("1 ~ ~ ~").s("piano"),
  note("g2 c2 f2").s("sine").gain(0.7)
)

Drum & Bass Track

Copy code
You: Generate a complete drum & bass track at 174 BPM

Claude: [Creates multi-layer pattern with drums, bass, and pads]

// dnb pattern in C at 174 BPM
setcpm(174)
stack(
  // Drums
  s("bd ~ ~ [bd bd] ~ ~ bd ~, ~ ~ cp ~ ~ cp ~ ~").fast(2),

  // Bass
  note("c1 ~ ~ c2 ~ c1 ~ ~").s("square").cutoff(400),

  // Pads (atmospheric)
  note("c3 eb3 g3 bb3").s("sawtooth")
    .attack(2).release(4).room(0.8).gain(0.6)
)

Real-Time Manipulation

Live Audio Analysis

Copy code
You: Analyze what's playing and show me the frequency breakdown

Claude: Audio Analysis Results:
{
  "connected": true,
  "features": {
    "average": 78.5,
    "peak": 180,
    "peakFrequency": 120,
    "bass": 145,
    "mid": 82,
    "treble": 45,
    "isPlaying": true,
    "brightness": "balanced"
  }
}

Strong bass presence detected - typical for techno/house patterns.

Pattern Variations

Copy code
You: Create a glitchy variation of the current pattern

Claude: [Applies glitch transformation]

Added: .sometimes(x => x.chop(8).rev).rarely(x => x.speed(-1))

Multi-Track Composition

Layered Ambient Track

Copy code
You: Create an ambient soundscape with multiple layers

Claude: [Generates complex multi-layer pattern]

setcpm(90)
stack(
  // Deep bass drone
  note("c1").s("sine").attack(4).release(8).gain(0.5),

  // Texture pad
  note("c3 eb3 g3").s("sawtooth")
    .attack(2).release(6).room(0.9).gain(0.4),

  // Sparse percussion
  s("bd ~ ~ ~, ~ ~ ~ hh:8").room(0.9).gain(0.3),

  // Melodic sparkles
  note("c5 g5 eb5 bb5").struct("~ 1 ~ 1 ~ ~ 1 ~")
    .s("triangle").delay(0.5).room(0.8).gain(0.3)
)

Session Management

Save and Load Patterns

Copy code
You: Save this pattern as "techno-groove-1" with tags "techno" and "experimental"

Claude: Pattern saved as "techno-groove-1"

---

You: List all my techno patterns

Claude: Saved patterns with tag "techno":
• techno-groove-1 [techno, experimental] - 2025-10-23T19:30:00.000Z
• acid-bassline [techno, acid] - 2025-10-23T18:15:00.000Z

---

You: Load "acid-bassline"

Claude: Loaded pattern "acid-bassline"
[Pattern written to editor]

Music Theory Applications

Generate Euclidean Rhythms

Copy code
You: Create a 5/8 euclidean rhythm with kick drum

Claude: Generated Euclidean rhythm (5/8)

Pattern: s("bd").struct("1 ~ 1 ~ 1 1 ~ 1")

Complex Polyrhythms

Copy code
You: Generate a polyrhythm with kick (4/16), snare (7/16), and hi-hat (3/16)

Claude: Generated polyrhythm

stack(
  s("bd").euclid(4, 16),
  s("cp").euclid(7, 16),
  s("hh").euclid(3, 16)
)

Integration with LLM Agents

AI-Assisted Composition

Copy code
You: Analyze the mood of my current pattern and suggest complementary elements

Claude: [Analyzes pattern structure and audio features]

Your pattern has:
- Energetic rhythm (130 BPM)
- Strong bass presence
- Minimal melodic content

Suggestions:
1. Add arpeggiated synth for movement
2. Include occasional breaks/fills
3. Layer atmospheric pad for depth

Would you like me to add any of these?

You: Add an arpeggiated synth in C minor

Claude: [Generates and adds]

note("c4 eb4 g4 bb4 c5").struct("1 1 1 1 1 1 1 1")
  .s("triangle").delay(0.25).room(0.3).gain(0.5)

Testing

All tools have been tested with real Strudel.cc interaction:

bashCopy code
# Run integration tests
npm run test:integration

# Run browser tests
node tests/strudel-integration.js

# Run npm test to see current pass/fail/skip counts

Configuration

config.json

jsonCopy code
{
  "headless": false,        // Set true for background operation
  "strudel_url": "https://strudel.cc/",
  "patterns_dir": "./patterns",
  "audio_analysis": {
    "fft_size": 2048,
    "smoothing": 0.8
  }
}

Architecture

System Overview

The Strudel MCP Server is built with a modular architecture that separates concerns and enables robust music generation:

Copy code
┌─────────────────────────────────────────────────────────────┐
│                       Claude AI                              │
│                  (MCP Client)                                │
└───────────────────────┬─────────────────────────────────────┘
                        │ MCP Protocol (stdio)
                        │
┌───────────────────────▼─────────────────────────────────────┐
│              StrudelMCPServer                          │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Tool Request Handler                                  │ │
│  │  - Validates inputs                                    │ │
│  │  - Routes to appropriate service                       │ │
│  │  - Handles errors gracefully                           │ │
│  └────────────────────────────────────────────────────────┘ │
└───────┬────────────┬────────────┬───────────┬──────────────┘
        │            │            │           │
   ┌────▼────┐  ┌───▼────┐  ┌───▼────┐  ┌──▼──────┐
   │ Strudel │  │ Music  │  │Pattern │  │ Pattern │
   │Controller│  │ Theory │  │Generator│  │  Store  │
   └────┬────┘  └────────┘  └────────┘  └─────────┘
        │
   ┌────▼────────────────────────────┐
   │   Playwright Browser            │
   │  ┌──────────────────────────┐   │
   │  │   Strudel.cc Website     │   │
   │  │  ┌────────────────────┐  │   │
   │  │  │  CodeMirror Editor │  │   │
   │  │  └────────────────────┘  │   │
   │  │  ┌────────────────────┐  │   │
   │  │  │  Audio Context     │  │   │
   │  │  │  + Web Audio API   │  │   │
   │  │  └────────┬───────────┘  │   │
   │  └───────────┼──────────────┘   │
   └──────────────┼──────────────────┘
                  │
          ┌───────▼────────┐
          │ Audio Analyzer │
          │  - FFT Analysis│
          │  - Frequency   │
          │  - Spectral    │
          └────────────────┘

Core Components

1. StrudelMCPServer (src/server/server.ts, ~510 lines)

Thin MCP dispatcher that:

• Aggregates 84 tool definitions from the per-domain modules in src/server/tools/ (84 = 26 consolidated tools + 58 deprecated aliases; -58 once #178 lands)
• 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:

typescriptCopy code
- Pattern caching before browser init
- Undo/redo stack management
- Session history tracking
- Generated pattern storage
- Safe fallback mechanisms

2. StrudelController (src/StrudelController.ts)

Browser automation layer using Playwright:

• Browser Management: Chromium instance lifecycle
• Editor Control: CodeMirror manipulation via DOM
• Playback Control: Keyboard shortcuts for play/stop
• Performance Optimizations:
  • Editor content caching (100ms TTL)
  • Direct CodeMirror API access
  • Resource blocking (images, fonts)
  • Fast DOM content loading

typescriptCopy code
// Example: Optimized pattern writing
async writePattern(pattern: string) {
  await this.page.evaluate((newPattern) => {
    const editor = document.querySelector('.cm-content');
    const view = editor.__view;
    view.dispatch({
      changes: { from: 0, to: view.state.doc.length, insert: newPattern }
    });
  }, pattern);
}

3. AudioAnalyzer (src/AudioAnalyzer.ts)

Real-time audio analysis via Web Audio API injection:

• FFT Analysis: 1024-point FFT for spectral data
• Frequency Bands: Bass, low-mid, mid, high-mid, treble
• Analysis Caching: 50ms TTL for performance
• Features Extracted:
  • Average amplitude
  • Peak frequency
  • Spectral centroid
  • Playing state detection
  • Frequency distribution

typescriptCopy code
Features provided:
- average: Overall amplitude (0-255)
- peak: Maximum amplitude
- peakFrequency: Dominant frequency in Hz
- bass/mid/treble: Band-specific amplitudes
- brightness: Timbral classification
- isPlaying: Boolean playback state

4. MusicTheory (src/services/MusicTheory.ts)

Music theory engine providing:

• 15+ Scales: Major, minor, modes, pentatonic, blues, whole-tone
• Chord Progressions: Pop, jazz, blues, rock, folk, EDM
• Euclidean Rhythms: Mathematical rhythm generation
• Arpeggio Generation: Multiple patterns (up, down, random)
• Note Transposition: Semitone-based pitch shifting

Supported scales:

typescriptCopy code
major, minor, dorian, phrygian, lydian, mixolydian,
aeolian, locrian, pentatonic, blues, chromatic,
wholetone, harmonic_minor, melodic_minor

5. PatternGenerator (src/services/PatternGenerator.ts)

AI-powered pattern creation:

• Genre Templates: Techno, house, DnB, trap, ambient, jazz, intelligent_dnb, trip_hop, boom_bap
• Drum Patterns: 4 complexity levels per genre
• Basslines: 8 different styles
• Melody Generation: Scale-based with musical intervals
• Variations: Subtle, moderate, extreme, glitch, evolving
• Fills: 1-4 bar drum fills

Example generation:

typescriptCopy code
generateCompletePattern('techno', 'C', 130)
→ Multi-layer pattern with drums, bass, chords, melody

6. PatternStore (src/PatternStore.ts)

Persistent pattern storage:

• JSON-based: Simple file storage
• Metadata: Name, tags, timestamp, audio features
• Tag Filtering: Organize by genre, mood, project
• Sorted Retrieval: Most recent first

Directory Structure

Copy code
live-coding-music-mcp/
├── src/
│   ├── 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                # 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
│   │   ├── 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
├── 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

1. Tool Invocation

   Copy code
   Claude → MCP Protocol → StrudelMCPServer
   

2. Pattern Generation (without browser)

   Copy code
   Server → PatternGenerator → MusicTheory → Pattern String
   

3. Pattern Execution (with browser)

   Copy code
   Server → StrudelController → Playwright → Strudel.cc
   

4. Audio Analysis

   Copy code
   Strudel.cc → Web Audio API → AudioAnalyzer → Feature Data
   

Performance Characteristics

Optimization Strategies

1. Caching

   • Editor content: 100ms TTL
   • Audio analysis: 50ms TTL
   • Generated patterns: Until browser init

2. Resource Blocking

   • Images, fonts, media blocked
   • Only load essential JavaScript/CSS

3. Direct API Access

   • CodeMirror view manipulation
   • Keyboard shortcuts over button clicks

4. Lazy Loading

   • Browser starts only when needed
   • Services initialized on-demand

Pattern Examples

Minimal Techno (Verified Working)

javascriptCopy code
setcpm(130)
stack(
  s("bd*4").gain(0.9),
  s("~ cp ~ cp").room(0.2),
  s("hh*16").gain(0.4).pan(sine.range(-0.5, 0.5)),
  note("c2 c2 eb2 c2").s("sawtooth").cutoff(800)
).swing(0.05)

Drum & Bass (Verified Working)

javascriptCopy code
setcpm(174)
stack(
  s("bd ~ ~ [bd bd] ~ ~ bd ~, ~ ~ sn:3 ~ ~ sn:3 ~ ~").fast(2),
  s("hh*16").gain(0.5),
  note("e1 ~ ~ e2 ~ e1 ~ ~").s("sine:2").lpf(200)
)

Generated Jazz Progression

javascriptCopy code
// Jazz ii-V-I in F
stack(
  note("Gm7" "C7" "Fmaj7").struct("1 ~ ~ ~").s("piano"),
  note("g2 c2 f2").s("sine").gain(0.7)
)

Docker Support

bashCopy code
# Build image
docker build -t live-coding-music-mcp .

# Run container
docker run -it --rm live-coding-music-mcp

# Or use docker-compose
docker-compose up

Development

Setup Development Environment

bashCopy code
# Clone the repository
git clone https://github.com/williamzujkowski/live-coding-music-mcp.git
cd live-coding-music-mcp

# Install dependencies
npm install

# Install Playwright browsers
npx playwright install chromium

# Build the project
npm run build

Available Scripts

bashCopy code
# Development mode with hot reload
npm run dev

# Build TypeScript to dist/
npm run build

# Start production server
npm start

# Run all tests
npm test

# Run integration tests with real browser
npm run test:integration

# Run browser-specific tests
npm run test:browser

# Validate MCP protocol compliance
npm run validate

# Lint code
npm run lint

# Format code
npm run format

# Clean build artifacts
npm clean

Publishing to npm

See NPM_PUBLISHING.md for complete publishing instructions.

Quick publish via GitHub Release:

bashCopy code
npm version patch  # or minor, major
git push && git push --tags
gh release create v$(node -p "require('./package.json').version") --generate-notes

The package uses OIDC trusted publishing with provenance attestation for supply chain security.

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:

   typescriptCopy code
   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. Add the case to the module's execute() switch:

   typescriptCopy code
   case 'my_new_tool':
     return await ctx.getController(args.session_id).doSomething(args.param1);
   

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.

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:

   bashCopy code
   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

1. Unit Tests

bashCopy code
# Run with Jest
npm test

# Watch mode
npm run test:watch

2. Integration Tests

bashCopy code
# Full integration with real browser
npm run test:integration

# This tests:
# - Browser initialization
# - Pattern generation
# - Audio analysis
# - Pattern storage
# - All 84 registered tools

3. Manual Testing

bashCopy code
# Development mode
npm run dev

# In another terminal
claude mcp add strudel-dev node $(pwd)/dist/index.js
claude chat

# Then interact with Claude

Code Quality

TypeScript Configuration

jsonCopy code
// tsconfig.json
{
  "compilerOptions": {
    "strict": true,           // Strict type checking
    "esModuleInterop": true,  // Better module compatibility
    "target": "ES2020",       // Modern JavaScript
    "module": "ES2020",       // ES modules
    "moduleResolution": "node"
  }
}

Linting & Formatting

bashCopy code
# ESLint
npm run lint

# Prettier
npm run format

# Pre-commit hooks recommended

Debugging

Enable Debug Logging

bashCopy code
# Set DEBUG environment variable
DEBUG=strudel:* npm start

# Or specific modules
DEBUG=strudel:controller npm start
DEBUG=strudel:audio npm start

VS Code Launch Configuration

jsonCopy code
{
  "type": "node",
  "request": "launch",
  "name": "Debug MCP Server",
  "program": "${workspaceFolder}/dist/index.js",
  "preLaunchTask": "npm: build",
  "console": "integratedTerminal",
  "env": {
    "DEBUG": "strudel:*"
  }
}

Playwright Debugging

typescriptCopy code
// In StrudelController.ts
this.browser = await chromium.launch({
  headless: false,  // See the browser
  devtools: true,   // Open DevTools
  slowMo: 100       // Slow down actions
});

Performance Monitoring

The server includes built-in performance monitoring:

typescriptCopy code
// Access performance metrics
You: Show me performance metrics

Claude: Performance Report:
{
  "averageLatency": {
    "init": "3.2s",
    "write": "52ms",
    "play": "105ms",
    "analyze": "18ms"
  },
  "cacheHitRate": "85%",
  "totalOperations": 1247,
  "bottlenecks": [
    {"tool": "init", "avgTime": 3200, "calls": 1},
    {"tool": "write", "avgTime": 52, "calls": 156}
  ]
}

Contributing Guidelines

1. Fork the repository

   bashCopy code
   git clone https://github.com/YOUR_USERNAME/live-coding-music-mcp.git
   

2. Create a feature branch

   bashCopy code
   git checkout -b feature/my-new-feature
   

3. Make your changes

   • Follow existing code style
   • Add tests for new features
   • Update documentation
   • Ensure all tests pass

4. Commit with meaningful messages

   bashCopy code
   git commit -m "feat: Add support for custom scale generation"
   

   Follow Conventional Commits:

   • feat: New feature
   • fix: Bug fix
   • docs: Documentation changes
   • refactor: Code refactoring
   • test: Adding tests
   • chore: Maintenance tasks

5. Push and create PR

   bashCopy code
   git push origin feature/my-new-feature
   

   Then create a Pull Request on GitHub with:

   • Clear description of changes
   • Link to related issues
   • Screenshots/examples if relevant

Release Process

bashCopy code
# 1. Update version in package.json
npm version patch  # or minor/major

# 2. Update CHANGELOG.md
# Add entry for new version

# 3. Build and test
npm run build
npm test
npm run test:integration

# 4. Commit version bump
git add .
git commit -m "chore: Bump version to X.Y.Z"

# 5. Create git tag
git tag vX.Y.Z

# 6. Push to GitHub
git push origin main --tags

# 7. Publish to npm (if you have access)
npm publish --access public

# 8. Create GitHub release
gh release create vX.Y.Z --generate-notes

Docker Development

bashCopy code
# Build development image
docker build -t live-coding-music-mcp:dev .

# Run with volume mount for hot reload
docker run -it --rm \
  -v $(pwd)/src:/app/src \
  -v $(pwd)/patterns:/app/patterns \
  live-coding-music-mcp:dev

# Run tests in container
docker run -it --rm live-coding-music-mcp:dev npm test

Environment Variables

bashCopy code
# Logging level
LOG_LEVEL=debug        # debug, info, warn, error

# Performance monitoring
ENABLE_PERF_MONITORING=true

# Pattern storage
PATTERNS_DIR=./patterns

# Browser configuration
HEADLESS=false
BROWSER_TIMEOUT=15000

# Audio analysis
FFT_SIZE=1024
SMOOTHING=0.8

Performance

Measured against the current StrudelController cache + Strudel.cc on a developer machine:

Advanced Usage

Custom Music Theory

Create Custom Scales

typescriptCopy code
// The MusicTheory service supports 15+ built-in scales
// You can request any combination:

You: Generate a lydian scale starting on D

Claude: D lydian scale: D, E, F#, G#, A, B, C#

Complex Chord Progressions

typescriptCopy code
You: Create a jazz ii-V-I progression in Bb with extended voicings

Claude: Generated jazz progression in Bb: "Cm7" "F7" "Bbmaj7"

Pattern:
note("Cm7" "F7" "Bbmaj7")
  .struct("1 ~ ~ ~")
  .s("sawtooth")
  .add(note("7"))  // Add 7th extensions
  .room(0.4)

Advanced Rhythm Techniques

Euclidean Patterns

Copy code
You: Create a complex polyrhythm using euclidean patterns:
     - Bass drum: 7 hits in 16 steps
     - Snare: 5 hits in 16 steps
     - Hi-hat: 11 hits in 16 steps

Claude: [Generates mathematically perfect polyrhythm]

stack(
  s("bd").euclid(7, 16),
  s("cp").euclid(5, 16),
  s("hh").euclid(11, 16)
)

Generative Variations

Copy code
You: Create 3 variations of my current pattern: subtle, moderate, and glitchy

Claude: [Generates three variants]

Version 1 (subtle):
original.sometimes(x => x.fast(2))

Version 2 (moderate):
original.every(4, x => x.rev).sometimes(x => x.fast(2))

Version 3 (glitchy):
original.sometimes(x => x.chop(8).rev).rarely(x => x.speed(-1))

Performance Optimization Tips

Pattern Caching

Copy code
// The server caches patterns intelligently:
// - Generated patterns stored before browser init
// - Editor content cached for 100ms
// - Audio analysis cached for 50ms

// For fastest performance:
1. Generate patterns before initializing browser
2. Initialize once and reuse the session
3. Batch multiple changes together

Headless Mode

jsonCopy code
// In config.json:
{
  "headless": true,  // Faster, no GUI
  "strudel_url": "https://strudel.cc/",
  "patterns_dir": "./patterns"
}

Integration Patterns

Workflow Automation

Copy code
You: Create a complete track:
     1. Start with techno drums at 130 BPM
     2. Add acid bassline in E
     3. Layer ambient pads
     4. Save as "track-001" with tags "techno", "acid", "experimental"

Claude: [Executes full workflow]
        [Initializes browser]
        [Generates drum pattern]
        [Adds bassline]
        [Layers pads]
        [Saves with metadata]

Complete! Pattern saved as "track-001"

Audio-Reactive Composition

Copy code
You: Monitor the audio and suggest adjustments based on frequency balance

Claude: [Analyzes current playback]

Analysis shows:
- Bass: 180 (strong)
- Mid: 45 (weak)
- Treble: 30 (weak)

Recommendations:
1. Reduce bass gain by 20%
2. Add mid-range melodic content
3. Include hi-hat pattern for treble

Apply changes? [Yes/No]

Advanced Pattern Manipulation

Dynamic Transformations

Copy code
You: Apply these transformations in sequence:
     1. Transpose up 3 semitones
     2. Add 10% humanization
     3. Apply reverb with 0.6 room size
     4. Every 4th cycle, reverse the pattern

Claude: [Applies transformations]

Final pattern:
[original]
  .transpose(3)
  .nudge(rand.range(-0.1, 0.1))
  .room(0.6)
  .every(4, x => x.rev)

Conditional Logic

Copy code
You: Create a pattern that evolves:
     - Bars 1-4: Simple kick pattern
     - Bars 5-8: Add snare
     - Bars 9-16: Add full drum kit
     - Then loop with variations

Claude: [Generates evolving pattern]

s("bd*4")
  .struct("1 ~ ~ ~")
  .mask("<1 1 1 1 0 0 0 0>/4")  // First 4 bars
  .stack(
    s("~ cp ~ cp")
      .mask("<0 0 0 0 1 1 1 1>/8")  // Bars 5-8
  )
  // Full complexity from bar 9
  .every(8, x => x.sometimes(y => y.fast(2)))

🔒 Security

Pattern Validation

All patterns are validated before execution:

• Dangerous gain levels (>2.0) are flagged
• Eval blocks are rejected
• Path traversal attacks are blocked in PatternStore

Browser Sandboxing

• Playwright runs Chromium in sandbox mode
• No access to local filesystem from browser context
• Resource blocking prevents loading external content

Known Limitations

• No authentication: The MCP server trusts all incoming requests
• Local only: Designed for local development, not network deployment
• Pattern execution: Patterns execute in browser context with audio access

Reporting Security Issues

Found a vulnerability? Please open a security issue or email the maintainer directly. Do not disclose publicly until patched.

🐛 Troubleshooting

Common Issues

Browser doesn't open

Symptom: Error: Browser not initialized or Chromium launch fails

Solutions:

bashCopy code
# Install Chromium for Playwright
npx playwright install chromium

# If that fails, try installing all browsers
npx playwright install

# Check Playwright installation
npx playwright --version

# For Linux, install dependencies
sudo npx playwright install-deps chromium

Audio analysis returns "not connected"

Symptom: Audio analysis shows connected: false

Solutions:

1. Ensure pattern is playing first:

   Copy code
   You: Play the pattern, wait 2 seconds, then analyze
   

2. Reinitialize the browser:

   Copy code
   You: Stop, close the browser, reinitialize, and try again
   

3. Check audio context activation:

   • Audio contexts require user interaction on some systems
   • The browser window must be visible (not headless) for first run

Pattern syntax errors

Symptom: Pattern doesn't play or shows errors in console

Solutions:

Copy code
Common issues:
1. Missing quotes: s(bd*4) → s("bd*4")
2. Unmatched parentheses: stack(s("bd")) → stack(s("bd")))
3. Invalid note names: note("h2") → note("c2")

Test with minimal pattern first:
s("bd*4")

Then build complexity gradually.

MCP connection issues

Symptom: Claude can't find the server or tools

Solutions:

bashCopy code
# Verify server is built
npm run build

# Check if server responds
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

# Should return JSON with 84 tools (post-v3.0; ~26 after #178 alias removal)

# Reinstall MCP server in Claude
claude mcp remove strudel
claude mcp add strudel node $(pwd)/dist/index.js

# Restart Claude
claude chat

Performance issues / Slow response

Symptom: Operations take longer than expected

Solutions:

1. Enable caching (default, but verify):

   • Editor caching: 100ms TTL
   • Audio analysis: 50ms TTL

2. Use headless mode for faster operation:

   jsonCopy code
   // config.json
   { "headless": true }
   

3. Batch operations:

   Copy code
   Instead of:
   - Add drums
   - Add bass
   - Add melody
   
   Do:
   - Generate complete pattern with drums, bass, and melody
   

4. Reduce browser overhead:

   • Close other browser instances
   • Disable browser DevTools
   • Use resource blocking (enabled by default)

Patterns not saving

Symptom: save command fails or patterns don't persist

Solutions:

bashCopy code
# Check patterns directory exists
ls -la ./patterns

# Create manually if needed
mkdir -p ./patterns

# Verify write permissions
touch ./patterns/test.json
rm ./patterns/test.json

# Check for invalid pattern names
# Valid: "techno-beat-1", "my_pattern", "track001"
# Invalid: "pattern/with/slashes", "name:with:colons"

Platform-Specific Issues

macOS

bashCopy code
# Keyboard shortcut uses Meta (Cmd) key
# Already handled by ControlOrMeta

# If Chromium crashes on M1/M2:
npx playwright install chromium --with-deps

Linux

bashCopy code
# Install system dependencies
sudo npx playwright install-deps chromium

# If running in Docker/headless environment:
# Ensure config.json has headless: true

Windows

bashCopy code
# Use PowerShell or Git Bash
# Paths should use forward slashes in config.json

# If Chromium doesn't launch:
npx playwright install chromium

Debugging Tips

Enable Verbose Logging

bashCopy code
# Set environment variable
DEBUG=* node dist/index.js

# Or in Claude:
You: Enable detailed logging for the next operation

Check Browser State

Copy code
You: Show me the current browser initialization state
     and any cached patterns

Claude: Browser state:
- Initialized: true
- Cached patterns: 2
- Undo stack depth: 5
- Last operation: write_pattern (2.5s ago)

Validate Pattern Syntax

Copy code
You: Before playing, validate this pattern syntax:
     s("bd*4, ~ cp ~ cp")

Claude: [Checks syntax]
Valid Strudel pattern.
Ready to play.

Getting Help

If you encounter issues not covered here:

1. Check existing issues: GitHub Issues
2. Run integration tests: npm run test:integration
3. Enable debug mode: DEBUG=* npm start
4. Consult Strudel docs: Strudel.cc documentation
5. Create new issue: Include error messages, OS, Node version, and steps to reproduce

🤝 Contributing

We need your help! This project is actively developed and welcomes contributions of all kinds:

Ways to Contribute

• Report Bugs: Found an issue? Open a bug report
• Suggest Features: Have ideas? Create a feature request
• Improve Docs: Fix typos, add examples, clarify confusing sections
• Write Tests: Help us improve test coverage
• Fix Issues: Check open issues for bugs to fix
• Add Features: Implement new tools or improve existing ones

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Ensure tests pass (npm test)
5. Commit with clear messages (git commit -m 'fix: resolve audio analysis bug')
6. Push to your fork (git push origin feature/amazing-feature)
7. Open a Pull Request

First time contributor? Look for issues labeled good-first-issue or help-wanted.

Feedback Welcome

• Questions? Open a Discussion
• Found something confusing? Tell us!
• Have a use case we haven't considered? Share it!

We review PRs promptly and welcome contributors of all skill levels. See DEVELOPMENT.md for detailed setup instructions.

📄 License

AGPL-3.0-or-later — see LICENSE for the full text.

This project depends on @strudel/core, @strudel/mini, @strudel/tonal, and @strudel/transpiler, which are AGPL-3.0 licensed by the upstream Strudel project. Since we import from those packages and redistribute the combined work via npm, this project must be distributed under the same copyleft terms. If you fork or redistribute, you must keep the AGPL license and provide source access to any network-accessible users (AGPL §13).

Earlier versions of this package (including @williamzujkowski/strudel-mcp-server prior to deprecation) shipped with an MIT declaration — that was incorrect given the AGPL dependencies. v2.0.0 of @williamzujkowski/live-coding-music-mcp corrects the license to AGPL-3.0-or-later. v1.0.0 of this package is deprecated; install v2.0.0 or later.

🙏 Acknowledgments

• Strudel.cc - Amazing live coding environment
• TidalCycles - Pattern language inspiration
• Anthropic - Claude AI and MCP protocol
• Playwright - Reliable browser automation

v3.0.0 — Open source, AGPL-3.0-or-later, experimental | Report issues | Contribute

This project is under active development. Core features work, but expect bugs and breaking changes. Not recommended for production use.