Strudel MCP Server

1# Strudel MCP Server
2 
3> 🎵 Open source MCP server for AI-powered music generation with Strudel.cc
4>
5> **Status:** Actively developed | Experimental | Contributions welcome
6 
7<a href="https://glama.ai/mcp/servers/@williamzujkowski/strudel-mcp-server">
8  <img width="380" height="200" src="https://glama.ai/mcp/servers/@williamzujkowski/strudel-mcp-server/badge" alt="Strudel Server MCP server" />
9</a>
10 
11[![CI](https://github.com/williamzujkowski/strudel-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/williamzujkowski/strudel-mcp-server/actions)
12[![npm version](https://img.shields.io/npm/v/@williamzujkowski/strudel-mcp-server.svg)](https://www.npmjs.com/package/@williamzujkowski/strudel-mcp-server)
13[![Tools](https://img.shields.io/badge/tools-65-green.svg)]()
14[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
15 
16An experimental Model Context Protocol (MCP) server that enables Claude to control [Strudel.cc](https://strudel.cc/) for AI-assisted music generation, live coding, and algorithmic composition.
17 
18**Current State:** Functional but under active development. Core features work reliably, but expect rough edges. Test coverage is at 78% with 1470 tests passing (1521 total, 51 skipped). See [open issues](https://github.com/williamzujkowski/strudel-mcp-server/issues) for known limitations.
19 
20## Table of Contents
21 
22- [Features](#-features)
23- [Installation](#-installation)
24- [Quick Reference](#-quick-reference)
25- [Quick Start](#-quick-start)
26- [Available Tools](#-available-tools-65)
27- [Usage Examples](#-usage-examples)
28- [Architecture](#-architecture)
29- [Advanced Usage](#-advanced-usage)
30- [Configuration](#-configuration)
31- [Security](#-security)
32- [Troubleshooting](#-troubleshooting)
33- [Development](#-development)
34- [Contributing](#-contributing)
35 
36## ✨ Features
37 
38### 🎹 Complete Music Control
39- **65 MCP Tools**: Comprehensive suite for music creation and manipulation
40- **Real Browser Automation**: Direct control of Strudel.cc through Playwright
41- **Live Audio Analysis**: Real-time frequency analysis via Web Audio API
42- **Pattern Generation**: AI-powered creation across 8+ music genres
43- **Music Theory Engine**: Scales, chords, progressions, euclidean rhythms
44- **Session Management**: Save, load, undo/redo with pattern storage
45 
46### 🔧 Testing & Development Status
47- ✅ **Test Suite**: 1470 tests passing (1521 total, 51 skipped)
48- ✅ **Code Coverage**: 78% statement coverage (goal: 80%)
49- ✅ **Browser Integration**: Works with live Strudel.cc website
50- ✅ **Audio Analysis**: Real-time FFT analysis functional
51- ✅ **Pattern Generation**: Core music generation features working
52- ✅ **OIDC Publishing**: Secure npm publishing with provenance attestation
53 
54**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.
55 
56### 🎼 Example Patterns
57 
58Explore 17 curated example patterns across 10 genres in [`patterns/examples/`](patterns/examples/):
59 
60- **Techno**: Hard techno, minimal techno
61- **House**: Deep house, tech house
62- **Drum & Bass**: Liquid, neurofunk
63- **Ambient**: Dark ambient, drone
64- **Trap**: Modern trap, cloud trap
65- **Jungle**: Classic jungle, ragga jungle
66- **Jazz**: Bebop, modal jazz
67- **Intelligent DnB**: Atmospheric, liquid, LTJ Bukem style
68- **Trip Hop**: Portishead, Massive Attack, Flying Lotus style
69- **Boom Bap**: DJ Premier, Alchemist, golden era hip hop
70 
71Each example includes pattern code, BPM, key, and description. See [`patterns/examples/README.md`](patterns/examples/README.md) for details.
72 
73## 📦 Installation
74 
75### Prerequisites
76 
77| Requirement | Version | Notes |
78|-------------|---------|-------|
79| Node.js | 18.x or 20.x | LTS versions recommended |
80| npm | 9+ | Comes with Node.js |
81| Chromium | Latest | Auto-installed by Playwright |
82| Audio output | Any | Required for playback (speakers/headphones) |
83 
84**Optional:** Docker for containerized deployment.
85 
86### From npm
87```bash
88npm install -g @williamzujkowski/strudel-mcp-server
89 
90# Install browser (required once)
91npx playwright install chromium
92```
93 
94### From Source
95```bash
96# Clone repository
97git clone https://github.com/williamzujkowski/strudel-mcp-server.git
98cd strudel-mcp-server
99 
100# Install dependencies
101npm install
102 
103# Install Chromium for browser automation
104npx playwright install chromium
105 
106# Build the project
107npm run build
108```
109 
110## 🚀 Quick Reference
111 
112Common commands for immediate use:
113 
114| Action | Command |
115|--------|---------|
116| Initialize browser | `init` |
117| Create techno beat | `generate_pattern` with `style: "techno"` |
118| Play pattern | `play` |
119| Stop playback | `stop` |
120| Get current pattern | `get_pattern` |
121| Analyze audio | `analyze` |
122| Save pattern | `save` with `name: "my-pattern"` |
123| Undo last change | `undo` |
124 
125**One-shot workflow:**
126```
127compose with style: "dnb", key: "Am", bpm: 174, auto_play: true
128```
129 
130## 🎯 Quick Start
131 
132### 1. Add to Claude
133```bash
134# If installed globally
135claude mcp add strudel strudel-mcp
136 
137# If built from source
138claude mcp add strudel node /path/to/strudel-mcp-server/dist/index.js
139```
140 
141### 2. Start Using
142```bash
143claude chat
144```
145 
146Then ask Claude:
147- "Initialize Strudel and create a techno beat"
148- "Generate a jazz chord progression in F major"
149- "Create a drum & bass pattern at 174 BPM"
150 
151## 🛠️ Available Tools (65)
152 
153### Core Control (10 tools)
154| Tool | Description | Example |
155|------|-------------|---------|
156| `init` | Initialize Strudel in browser | "Initialize Strudel" |
157| `write` | Write pattern to editor | "Write pattern: s('bd*4')" |
158| `play` | Start playback | "Play the pattern" |
159| `stop` | Stop playback | "Stop playing" |
160| `clear` | Clear editor | "Clear the editor" |
161| `get_pattern` | Get current pattern | "Show current pattern" |
162| `append` | Add to pattern | "Add hi-hats" |
163| `insert` | Insert at line | "Insert at line 2" |
164| `replace` | Replace text | "Replace bd with sn" |
165| `pause` | Pause playback | "Pause" |
166 
167### Pattern Generation & Manipulation (10 tools)
168| Tool | Description | Options |
169|------|-------------|---------|
170| `generate_pattern` | Complete patterns | techno, house, dnb, ambient, trap, jungle, jazz, intelligent_dnb, trip_hop, boom_bap |
171| `generate_drums` | Drum patterns | All styles + complexity (0-1) |
172| `generate_bassline` | Bass patterns | techno, house, dnb, acid, dub, funk, jazz, intelligent_dnb, trip_hop, boom_bap |
173| `generate_melody` | Melodic lines | Any scale, custom length |
174| `generate_variation` | Pattern variations | subtle, moderate, extreme, glitch |
175| `transpose` | Transpose notes | ±12 semitones |
176| `reverse` | Reverse pattern | - |
177| `stretch` | Time stretch | Factor 0.1-10 |
178| `quantize` | Quantize to grid | 1/4, 1/8, 1/16, etc. |
179| `humanize` | Add timing variation | Amount 0-1 |
180 
181### Music Theory (6 tools)
182| Tool | Description | Options |
183|------|-------------|---------|
184| `generate_scale` | Generate scales | major, minor, modes, pentatonic, blues |
185| `generate_chord_progression` | Chord progressions | pop, jazz, blues, rock, folk |
186| `generate_euclidean` | Euclidean rhythms | hits/steps/sound |
187| `generate_polyrhythm` | Polyrhythms | Multiple patterns |
188| `generate_fill` | Generate drum fills | All styles, 1-4 bars |
189| `apply_scale` | Apply scale to notes | Any scale |
190 
191### Effects (4 tools)
192| Tool | Description |
193|------|-------------|
194| `add_effect` | Add audio effect (reverb, delay, etc.) |
195| `remove_effect` | Remove an effect from the chain |
196| `set_tempo` | Set BPM (60-200) |
197| `add_swing` | Add swing feel (0-1 amount) |
198 
199### Session Management (5 tools)
200| Tool | Description |
201|------|-------------|
202| `save` | Save pattern with tags |
203| `load` | Load saved pattern |
204| `list` | List all patterns |
205| `undo` | Undo last action |
206| `redo` | Redo action |
207 
208### Pattern History (3 tools)
209| Tool | Description |
210|------|-------------|
211| `list_history` | Browse pattern history with timestamps and previews |
212| `restore_history` | Restore a previous pattern by ID |
213| `compare_patterns` | Compare two patterns showing line-by-line differences |
214 
215### Audio Analysis (6 tools)
216| Tool | Description |
217|------|-------------|
218| `analyze` | Basic audio analysis (frequency, playing state) |
219| `analyze_spectrum` | FFT spectral analysis |
220| `analyze_rhythm` | Rhythm complexity analysis |
221| `detect_tempo` | BPM detection |
222| `detect_key` | Musical key detection |
223| `validate_pattern_runtime` | Validate pattern with browser error checking |
224 
225### UX & Browser Control (6 tools)
226| Tool | Description |
227|------|-------------|
228| `compose` | One-shot pattern generation with auto-play |
229| `status` | Get current browser/playback state |
230| `diagnostics` | Detailed system diagnostics |
231| `show_browser` | Bring browser window to foreground |
232| `screenshot` | Capture browser screenshot |
233| `show_errors` | Display captured console errors |
234 
235### Performance (2 tools)
236| Tool | Description |
237|------|-------------|
238| `performance_report` | Timing metrics and bottleneck analysis |
239| `memory_usage` | Memory consumption statistics |
240 
241### AI Feedback (1 tool)
242| Tool | Description | Options |
243|------|-------------|---------|
244| `get_pattern_feedback` | AI-powered creative feedback via Gemini | `includeAudio`: analyze audio (default: false), `style`: hint for context |
245 
246> **Note:** Requires `GEMINI_API_KEY` environment variable. Returns pattern complexity, estimated style, strengths, and suggestions.
247 
248## 🎵 Usage Examples
249 
250### Basic Pattern Creation
251 
252**Create a Simple Beat**
253```
254You: Initialize Strudel and create a simple techno beat
255 
256Claude: [Initializes browser]
257        [Generates and writes pattern]
258        [Starts playback]
259 
260Pattern created:
261setcpm(130)
262stack(
263  s("bd*4"),
264  s("~ cp ~ cp"),
265  s("hh*8").gain(0.4)
266).gain(0.8)
267```
268 
269**Generate a Bassline**
270```
271You: Add a techno bassline in C
272 
273Claude: [Generates bassline]
274        [Appends to current pattern]
275 
276Added: note("c2 c2 c2 c2").s("sawtooth").cutoff(800)
277```
278 
279### Advanced Music Generation
280 
281**Jazz Composition**
282```
283You: Create a jazz progression in F major with a walking bass
284 
285Claude: Generated progression: "Gm7" "C7" "Fmaj7"
286 
287Pattern:
288stack(
289  note("Gm7" "C7" "Fmaj7").struct("1 ~ ~ ~").s("piano"),
290  note("g2 c2 f2").s("sine").gain(0.7)
291)
292```
293 
294**Drum & Bass Track**
295```
296You: Generate a complete drum & bass track at 174 BPM
297 
298Claude: [Creates multi-layer pattern with drums, bass, and pads]
299 
300// dnb pattern in C at 174 BPM
301setcpm(174)
302stack(
303  // Drums
304  s("bd ~ ~ [bd bd] ~ ~ bd ~, ~ ~ cp ~ ~ cp ~ ~").fast(2),
305 
306  // Bass
307  note("c1 ~ ~ c2 ~ c1 ~ ~").s("square").cutoff(400),
308 
309  // Pads (atmospheric)
310  note("c3 eb3 g3 bb3").s("sawtooth")
311    .attack(2).release(4).room(0.8).gain(0.6)
312)
313```
314 
315### Real-Time Manipulation
316 
317**Live Audio Analysis**
318```
319You: Analyze what's playing and show me the frequency breakdown
320 
321Claude: Audio Analysis Results:
322{
323  "connected": true,
324  "features": {
325    "average": 78.5,
326    "peak": 180,
327    "peakFrequency": 120,
328    "bass": 145,
329    "mid": 82,
330    "treble": 45,
331    "isPlaying": true,
332    "brightness": "balanced"
333  }
334}
335 
336Strong bass presence detected - typical for techno/house patterns.
337```
338 
339**Pattern Variations**
340```
341You: Create a glitchy variation of the current pattern
342 
343Claude: [Applies glitch transformation]
344 
345Added: .sometimes(x => x.chop(8).rev).rarely(x => x.speed(-1))
346```
347 
348### Multi-Track Composition
349 
350**Layered Ambient Track**
351```
352You: Create an ambient soundscape with multiple layers
353 
354Claude: [Generates complex multi-layer pattern]
355 
356setcpm(90)
357stack(
358  // Deep bass drone
359  note("c1").s("sine").attack(4).release(8).gain(0.5),
360 
361  // Texture pad
362  note("c3 eb3 g3").s("sawtooth")
363    .attack(2).release(6).room(0.9).gain(0.4),
364 
365  // Sparse percussion
366  s("bd ~ ~ ~, ~ ~ ~ hh:8").room(0.9).gain(0.3),
367 
368  // Melodic sparkles
369  note("c5 g5 eb5 bb5").struct("~ 1 ~ 1 ~ ~ 1 ~")
370    .s("triangle").delay(0.5).room(0.8).gain(0.3)
371)
372```
373 
374### Session Management
375 
376**Save and Load Patterns**
377```
378You: Save this pattern as "techno-groove-1" with tags "techno" and "experimental"
379 
380Claude: Pattern saved as "techno-groove-1"
381 
382---
383 
384You: List all my techno patterns
385 
386Claude: Saved patterns with tag "techno":
387• techno-groove-1 [techno, experimental] - 2025-10-23T19:30:00.000Z
388• acid-bassline [techno, acid] - 2025-10-23T18:15:00.000Z
389 
390---
391 
392You: Load "acid-bassline"
393 
394Claude: Loaded pattern "acid-bassline"
395[Pattern written to editor]
396```
397 
398### Music Theory Applications
399 
400**Generate Euclidean Rhythms**
401```
402You: Create a 5/8 euclidean rhythm with kick drum
403 
404Claude: Generated Euclidean rhythm (5/8)
405 
406Pattern: s("bd").struct("1 ~ 1 ~ 1 1 ~ 1")
407```
408 
409**Complex Polyrhythms**
410```
411You: Generate a polyrhythm with kick (4/16), snare (7/16), and hi-hat (3/16)
412 
413Claude: Generated polyrhythm
414 
415stack(
416  s("bd").euclid(4, 16),
417  s("cp").euclid(7, 16),
418  s("hh").euclid(3, 16)
419)
420```
421 
422### Integration with LLM Agents
423 
424**AI-Assisted Composition**
425```
426You: Analyze the mood of my current pattern and suggest complementary elements
427 
428Claude: [Analyzes pattern structure and audio features]
429 
430Your pattern has:
431- Energetic rhythm (130 BPM)
432- Strong bass presence
433- Minimal melodic content
434 
435Suggestions:
4361. Add arpeggiated synth for movement
4372. Include occasional breaks/fills
4383. Layer atmospheric pad for depth
439 
440Would you like me to add any of these?
441 
442You: Add an arpeggiated synth in C minor
443 
444Claude: [Generates and adds]
445 
446note("c4 eb4 g4 bb4 c5").struct("1 1 1 1 1 1 1 1")
447  .s("triangle").delay(0.25).room(0.3).gain(0.5)
448```
449 
450## 🧪 Testing
451 
452All tools have been tested with real Strudel.cc interaction:
453 
454```bash
455# Run integration tests
456npm run test:integration
457 
458# Run browser tests
459node tests/strudel-integration.js
460 
461# Test results: 1470/1521 tests passing (96.6%), 51 skipped (browser tests in CI)
462```
463 
464## ⚙️ Configuration
465 
466### config.json
467```json
468{
469  "headless": false,        // Set true for background operation
470  "strudel_url": "https://strudel.cc/",
471  "patterns_dir": "./patterns",
472  "audio_analysis": {
473    "fft_size": 2048,
474    "smoothing": 0.8
475  }
476}
477```
478 
479## 🏗️ Architecture
480 
481### System Overview
482 
483The Strudel MCP Server is built with a modular architecture that separates concerns and enables robust music generation:
484 
485```
486┌─────────────────────────────────────────────────────────────┐
487│                       Claude AI                              │
488│                  (MCP Client)                                │
489└───────────────────────┬─────────────────────────────────────┘
490                        │ MCP Protocol (stdio)
491                        │
492┌───────────────────────▼─────────────────────────────────────┐
493│              EnhancedMCPServerFixed                          │
494│  ┌────────────────────────────────────────────────────────┐ │
495│  │  Tool Request Handler                                  │ │
496│  │  - Validates inputs                                    │ │
497│  │  - Routes to appropriate service                       │ │
498│  │  - Handles errors gracefully                           │ │
499│  └────────────────────────────────────────────────────────┘ │
500└───────┬────────────┬────────────┬───────────┬──────────────┘
501        │            │            │           │
502   ┌────▼────┐  ┌───▼────┐  ┌───▼────┐  ┌──▼──────┐
503   │ Strudel │  │ Music  │  │Pattern │  │ Pattern │
504   │Controller│  │ Theory │  │Generator│  │  Store  │
505   └────┬────┘  └────────┘  └────────┘  └─────────┘
506        │
507   ┌────▼────────────────────────────┐
508   │   Playwright Browser            │
509   │  ┌──────────────────────────┐   │
510   │  │   Strudel.cc Website     │   │
511   │  │  ┌────────────────────┐  │   │
512   │  │  │  CodeMirror Editor │  │   │
513   │  │  └────────────────────┘  │   │
514   │  │  ┌────────────────────┐  │   │
515   │  │  │  Audio Context     │  │   │
516   │  │  │  + Web Audio API   │  │   │
517   │  │  └────────┬───────────┘  │   │
518   │  └───────────┼──────────────┘   │
519   └──────────────┼──────────────────┘
520                  │
521          ┌───────▼────────┐
522          │ Audio Analyzer │
523          │  - FFT Analysis│
524          │  - Frequency   │
525          │  - Spectral    │
526          └────────────────┘
527```
528 
529### Core Components
530 
531#### 1. **EnhancedMCPServerFixed** (`src/server/EnhancedMCPServerFixed.ts`)
532 
533Main MCP server implementation handling:
534- **65 Tool Definitions**: Complete API surface for music control
535- **Request Routing**: Directs tool calls to appropriate handlers
536- **State Management**: Tracks initialization, undo/redo stacks, pattern cache
537- **Error Handling**: Graceful degradation and informative error messages
538- **Lazy Initialization**: Browser starts only when needed
539 
540Key Features:
541```typescript
542- Pattern caching before browser init
543- Undo/redo stack management
544- Session history tracking
545- Generated pattern storage
546- Safe fallback mechanisms
547```
548 
549#### 2. **StrudelController** (`src/StrudelController.ts`)
550 
551Browser automation layer using Playwright:
552- **Browser Management**: Chromium instance lifecycle
553- **Editor Control**: CodeMirror manipulation via DOM
554- **Playback Control**: Keyboard shortcuts for play/stop
555- **Performance Optimizations**:
556  - Editor content caching (100ms TTL)
557  - Direct CodeMirror API access
558  - Resource blocking (images, fonts)
559  - Fast DOM content loading
560 
561```typescript
562// Example: Optimized pattern writing
563async writePattern(pattern: string) {
564  await this.page.evaluate((newPattern) => {
565    const editor = document.querySelector('.cm-content');
566    const view = editor.__view;
567    view.dispatch({
568      changes: { from: 0, to: view.state.doc.length, insert: newPattern }
569    });
570  }, pattern);
571}
572```
573 
574#### 3. **AudioAnalyzer** (`src/AudioAnalyzer.ts`)
575 
576Real-time audio analysis via Web Audio API injection:
577- **FFT Analysis**: 1024-point FFT for spectral data
578- **Frequency Bands**: Bass, low-mid, mid, high-mid, treble
579- **Analysis Caching**: 50ms TTL for performance
580- **Features Extracted**:
581  - Average amplitude
582  - Peak frequency
583  - Spectral centroid
584  - Playing state detection
585  - Frequency distribution
586 
587```typescript
588Features provided:
589- average: Overall amplitude (0-255)
590- peak: Maximum amplitude
591- peakFrequency: Dominant frequency in Hz
592- bass/mid/treble: Band-specific amplitudes
593- brightness: Timbral classification
594- isPlaying: Boolean playback state
595```
596 
597#### 4. **MusicTheory** (`src/services/MusicTheory.ts`)
598 
599Music theory engine providing:
600- **15+ Scales**: Major, minor, modes, pentatonic, blues, whole-tone
601- **Chord Progressions**: Pop, jazz, blues, rock, folk, EDM
602- **Euclidean Rhythms**: Mathematical rhythm generation
603- **Arpeggio Generation**: Multiple patterns (up, down, random)
604- **Note Transposition**: Semitone-based pitch shifting
605 
606Supported scales:
607```typescript
608major, minor, dorian, phrygian, lydian, mixolydian,
609aeolian, locrian, pentatonic, blues, chromatic,
610wholetone, harmonic_minor, melodic_minor
611```
612 
613#### 5. **PatternGenerator** (`src/services/PatternGenerator.ts`)
614 
615AI-powered pattern creation:
616- **Genre Templates**: Techno, house, DnB, trap, ambient, jazz, intelligent_dnb, trip_hop, boom_bap
617- **Drum Patterns**: 4 complexity levels per genre
618- **Basslines**: 8 different styles
619- **Melody Generation**: Scale-based with musical intervals
620- **Variations**: Subtle, moderate, extreme, glitch, evolving
621- **Fills**: 1-4 bar drum fills
622 
623Example generation:
624```typescript
625generateCompletePattern('techno', 'C', 130)
626→ Multi-layer pattern with drums, bass, chords, melody
627```
628 
629#### 6. **PatternStore** (`src/PatternStore.ts`)
630 
631Persistent pattern storage:
632- **JSON-based**: Simple file storage
633- **Metadata**: Name, tags, timestamp, audio features
634- **Tag Filtering**: Organize by genre, mood, project
635- **Sorted Retrieval**: Most recent first
636 
637### Directory Structure
638 
639```
640strudel-mcp-server/
641├── src/
642│   ├── server/
643│   │   ├── EnhancedMCPServer.ts          # Original implementation
644│   │   └── EnhancedMCPServerFixed.ts     # Production version
645│   ├── services/
646│   │   ├── MusicTheory.ts                # Theory engine
647│   │   └── PatternGenerator.ts           # Pattern creation
648│   ├── utils/
649│   │   └── Logger.ts                     # Logging utility
650│   ├── types/
651│   │   └── index.ts                      # TypeScript types
652│   ├── StrudelController.ts              # Browser automation
653│   ├── AudioAnalyzer.ts                  # Audio analysis
654│   ├── PatternStore.ts                   # Pattern persistence
655│   └── index.ts                          # Entry point
656├── tests/
657│   ├── browser-test.js                   # Browser integration
658│   ├── integration.test.js               # Integration tests
659│   ├── manual-test.js                    # Manual testing
660│   ├── mcp-tools.test.ts                 # MCP tool tests
661│   └── strudel-integration.js            # Full integration
662├── patterns/                             # Saved patterns
663├── config.json                           # Server configuration
664├── package.json                          # Dependencies
665└── tsconfig.json                         # TypeScript config
666```
667 
668### Data Flow
669 
6701. **Tool Invocation**
671   ```
672   Claude → MCP Protocol → EnhancedMCPServerFixed
673   ```
674 
6752. **Pattern Generation** (without browser)
676   ```
677   Server → PatternGenerator → MusicTheory → Pattern String
678   ```
679 
6803. **Pattern Execution** (with browser)
681   ```
682   Server → StrudelController → Playwright → Strudel.cc
683   ```
684 
6854. **Audio Analysis**
686   ```
687   Strudel.cc → Web Audio API → AudioAnalyzer → Feature Data
688   ```
689 
690### Performance Characteristics
691 
692| Operation | Latency | Notes |
693|-----------|---------|-------|
694| Pattern Generation | <100ms | Pure computation |
695| Browser Init | ~3s | One-time cost |
696| Pattern Write | ~50ms | With caching |
697| Play/Stop | ~100ms | Keyboard shortcuts |
698| Audio Analysis | ~20ms | With 50ms cache |
699| Pattern Save | ~10ms | File I/O |
700 
701### Optimization Strategies
702 
7031. **Caching**
704   - Editor content: 100ms TTL
705   - Audio analysis: 50ms TTL
706   - Generated patterns: Until browser init
707 
7082. **Resource Blocking**
709   - Images, fonts, media blocked
710   - Only load essential JavaScript/CSS
711 
7123. **Direct API Access**
713   - CodeMirror view manipulation
714   - Keyboard shortcuts over button clicks
715 
7164. **Lazy Loading**
717   - Browser starts only when needed
718   - Services initialized on-demand
719 
720## 🎹 Pattern Examples
721 
722### Minimal Techno (Verified Working)
723```javascript
724setcpm(130)
725stack(
726  s("bd*4").gain(0.9),
727  s("~ cp ~ cp").room(0.2),
728  s("hh*16").gain(0.4).pan(sine.range(-0.5, 0.5)),
729  note("c2 c2 eb2 c2").s("sawtooth").cutoff(800)
730).swing(0.05)
731```
732 
733### Drum & Bass (Verified Working)
734```javascript
735setcpm(174)
736stack(
737  s("bd ~ ~ [bd bd] ~ ~ bd ~, ~ ~ sn:3 ~ ~ sn:3 ~ ~").fast(2),
738  s("hh*16").gain(0.5),
739  note("e1 ~ ~ e2 ~ e1 ~ ~").s("sine:2").lpf(200)
740)
741```
742 
743### Generated Jazz Progression
744```javascript
745// Jazz ii-V-I in F
746stack(
747  note("Gm7" "C7" "Fmaj7").struct("1 ~ ~ ~").s("piano"),
748  note("g2 c2 f2").s("sine").gain(0.7)
749)
750```
751 
752## 🐳 Docker Support
753 
754```bash
755# Build image
756docker build -t strudel-mcp .
757 
758# Run container
759docker run -it --rm strudel-mcp
760 
761# Or use docker-compose
762docker-compose up
763```
764 
765## 🔧 Development
766 
767### Setup Development Environment
768 
769```bash
770# Clone the repository
771git clone https://github.com/williamzujkowski/strudel-mcp-server.git
772cd strudel-mcp-server
773 
774# Install dependencies
775npm install
776 
777# Install Playwright browsers
778npx playwright install chromium
779 
780# Build the project
781npm run build
782```
783 
784### Available Scripts
785 
786```bash
787# Development mode with hot reload
788npm run dev
789 
790# Build TypeScript to dist/
791npm run build
792 
793# Start production server
794npm start
795 
796# Run all tests
797npm test
798 
799# Run integration tests with real browser
800npm run test:integration
801 
802# Run browser-specific tests
803npm run test:browser
804 
805# Validate MCP protocol compliance
806npm run validate
807 
808# Lint code
809npm run lint
810 
811# Format code
812npm run format
813 
814# Clean build artifacts
815npm clean
816```
817 
818### Publishing to npm
819 
820See [NPM_PUBLISHING.md](NPM_PUBLISHING.md) for complete publishing instructions.
821 
822**Quick publish via GitHub Release:**
823```bash
824npm version patch  # or minor, major
825git push && git push --tags
826gh release create v$(node -p "require('./package.json').version") --generate-notes
827```
828 
829The package uses OIDC trusted publishing with provenance attestation for supply chain security.
830 
831### Project Structure
832 
833```
834src/
835├── server/
836│   ├── EnhancedMCPServer.ts          # Original implementation
837│   └── EnhancedMCPServerFixed.ts     # Production version with caching
838│
839├── services/
840│   ├── MusicTheory.ts                # Music theory engine
841│   │   - 15+ scales (major, minor, modes, etc.)
842│   │   - Chord progressions (jazz, pop, blues, etc.)
843│   │   - Euclidean rhythm generation
844│   │   - Arpeggio generation
845│   │
846│   └── PatternGenerator.ts           # Pattern creation service
847│       - Genre-specific drum patterns
848│       - Bassline generation
849│       - Melody composition
850│       - Pattern variations
851│       - Complete track generation
852│
853├── utils/
854│   ├── Logger.ts                     # Logging utility
855│   ├── PerformanceMonitor.ts         # Performance tracking
856│   ├── PatternValidator.ts           # Pattern syntax validation
857│   └── ErrorRecovery.ts              # Error handling & recovery
858│
859├── types/
860│   └── index.ts                      # TypeScript type definitions
861│
862├── StrudelController.ts              # Browser automation
863│   - Chromium management via Playwright
864│   - CodeMirror editor manipulation
865│   - Playback control
866│   - Pattern validation
867│   - Error recovery
868│
869├── AudioAnalyzer.ts                  # Real-time audio analysis
870│   - Web Audio API injection
871│   - FFT spectral analysis
872│   - Frequency band detection
873│   - Playing state monitoring
874│
875├── PatternStore.ts                   # Pattern persistence
876│   - JSON-based storage
877│   - Tag-based organization
878│   - Metadata tracking
879│   - List caching
880│
881└── index.ts                          # Application entry point
882```
883 
884### Adding New Tools
885 
886To add a new MCP tool:
887 
8881. **Define the tool** in `getTools()` method:
889```typescript
890{
891  name: 'my_new_tool',
892  description: 'Description of what it does',
893  inputSchema: {
894    type: 'object',
895    properties: {
896      param1: { type: 'string', description: 'Parameter description' },
897      param2: { type: 'number', description: 'Numeric parameter' }
898    },
899    required: ['param1']
900  }
901}
902```
903 
9042. **Implement the handler** in `executeTool()` switch statement:
905```typescript
906case 'my_new_tool':
907  // Your implementation here
908  return await this.someService.doSomething(args.param1, args.param2);
909```
910 
9113. **Add necessary service methods** if needed:
912```typescript
913// In appropriate service file
914async doSomething(param1: string, param2?: number): Promise<string> {
915  // Implementation
916  return `Result: ${param1}`;
917}
918```
919 
9204. **Test the tool**:
921```bash
922# Build
923npm run build
924 
925# Test via MCP
926echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"my_new_tool","arguments":{"param1":"test"}},"id":2}' | node dist/index.js
927```
928 
929### Testing Strategy
930 
931#### 1. Unit Tests
932```bash
933# Run with Jest
934npm test
935 
936# Watch mode
937npm run test:watch
938```
939 
940#### 2. Integration Tests
941```bash
942# Full integration with real browser
943npm run test:integration
944 
945# This tests:
946# - Browser initialization
947# - Pattern generation
948# - Audio analysis
949# - Pattern storage
950# - All 65 tools
951```
952 
953#### 3. Manual Testing
954```bash
955# Development mode
956npm run dev
957 
958# In another terminal
959claude mcp add strudel-dev node $(pwd)/dist/index.js
960claude chat
961 
962# Then interact with Claude
963```
964 
965### Code Quality
966 
967**TypeScript Configuration**
968```json
969// tsconfig.json
970{
971  "compilerOptions": {
972    "strict": true,           // Strict type checking
973    "esModuleInterop": true,  // Better module compatibility
974    "target": "ES2020",       // Modern JavaScript
975    "module": "ES2020",       // ES modules
976    "moduleResolution": "node"
977  }
978}
979```
980 
981**Linting & Formatting**
982```bash
983# ESLint
984npm run lint
985 
986# Prettier
987npm run format
988 
989# Pre-commit hooks recommended
990```
991 
992### Debugging
993 
994**Enable Debug Logging**
995```bash
996# Set DEBUG environment variable
997DEBUG=strudel:* npm start
998 
999# Or specific modules
1000DEBUG=strudel:controller npm start
1001DEBUG=strudel:audio npm start
1002```
1003 
1004**VS Code Launch Configuration**
1005```json
1006{
1007  "type": "node",
1008  "request": "launch",
1009  "name": "Debug MCP Server",
1010  "program": "${workspaceFolder}/dist/index.js",
1011  "preLaunchTask": "npm: build",
1012  "console": "integratedTerminal",
1013  "env": {
1014    "DEBUG": "strudel:*"
1015  }
1016}
1017```
1018 
1019**Playwright Debugging**
1020```typescript
1021// In StrudelController.ts
1022this.browser = await chromium.launch({
1023  headless: false,  // See the browser
1024  devtools: true,   // Open DevTools
1025  slowMo: 100       // Slow down actions
1026});
1027```
1028 
1029### Performance Monitoring
1030 
1031The server includes built-in performance monitoring:
1032 
1033```typescript
1034// Access performance metrics
1035You: Show me performance metrics
1036 
1037Claude: Performance Report:
1038{
1039  "averageLatency": {
1040    "init": "3.2s",
1041    "write": "52ms",
1042    "play": "105ms",
1043    "analyze": "18ms"
1044  },
1045  "cacheHitRate": "85%",
1046  "totalOperations": 1247,
1047  "bottlenecks": [
1048    {"tool": "init", "avgTime": 3200, "calls": 1},
1049    {"tool": "write", "avgTime": 52, "calls": 156}
1050  ]
1051}
1052```
1053 
1054### Contributing Guidelines
1055 
10561. **Fork the repository**
1057   ```bash
1058   git clone https://github.com/YOUR_USERNAME/strudel-mcp-server.git
1059   ```
1060 
10612. **Create a feature branch**
1062   ```bash
1063   git checkout -b feature/my-new-feature
1064   ```
1065 
10663. **Make your changes**
1067   - Follow existing code style
1068   - Add tests for new features
1069   - Update documentation
1070   - Ensure all tests pass
1071 
10724. **Commit with meaningful messages**
1073   ```bash
1074   git commit -m "feat: Add support for custom scale generation"
1075   ```
1076 
1077   Follow [Conventional Commits](https://www.conventionalcommits.org/):
1078   - `feat:` New feature
1079   - `fix:` Bug fix
1080   - `docs:` Documentation changes
1081   - `refactor:` Code refactoring
1082   - `test:` Adding tests
1083   - `chore:` Maintenance tasks
1084 
10855. **Push and create PR**
1086   ```bash
1087   git push origin feature/my-new-feature
1088   ```
1089 
1090   Then create a Pull Request on GitHub with:
1091   - Clear description of changes
1092   - Link to related issues
1093   - Screenshots/examples if relevant
1094 
1095### Release Process
1096 
1097```bash
1098# 1. Update version in package.json
1099npm version patch  # or minor/major
1100 
1101# 2. Update CHANGELOG.md
1102# Add entry for new version
1103 
1104# 3. Build and test
1105npm run build
1106npm test
1107npm run test:integration
1108 
1109# 4. Commit version bump
1110git add .
1111git commit -m "chore: Bump version to X.Y.Z"
1112 
1113# 5. Create git tag
1114git tag vX.Y.Z
1115 
1116# 6. Push to GitHub
1117git push origin main --tags
1118 
1119# 7. Publish to npm (if you have access)
1120npm publish --access public
1121 
1122# 8. Create GitHub release
1123gh release create vX.Y.Z --generate-notes
1124```
1125 
1126### Docker Development
1127 
1128```bash
1129# Build development image
1130docker build -t strudel-mcp:dev .
1131 
1132# Run with volume mount for hot reload
1133docker run -it --rm \
1134  -v $(pwd)/src:/app/src \
1135  -v $(pwd)/patterns:/app/patterns \
1136  strudel-mcp:dev
1137 
1138# Run tests in container
1139docker run -it --rm strudel-mcp:dev npm test
1140```
1141 
1142### Environment Variables
1143 
1144```bash
1145# Logging level
1146LOG_LEVEL=debug        # debug, info, warn, error
1147 
1148# Performance monitoring
1149ENABLE_PERF_MONITORING=true
1150 
1151# Pattern storage
1152PATTERNS_DIR=./patterns
1153 
1154# Browser configuration
1155HEADLESS=false
1156BROWSER_TIMEOUT=15000
1157 
1158# Audio analysis
1159FFT_SIZE=1024
1160SMOOTHING=0.8
1161```
1162 
1163## 📊 Performance
1164 
1165- **Pattern Generation**: <100ms
1166- **Browser Initialization**: ~3 seconds
1167- **Pattern Writing**: Instant
1168- **Playback Start**: ~500ms
1169- **Audio Analysis**: Real-time
1170- **Memory Usage**: <150MB
1171 
1172## 🎓 Advanced Usage
1173 
1174### Custom Music Theory
1175 
1176**Create Custom Scales**
1177```typescript
1178// The MusicTheory service supports 15+ built-in scales
1179// You can request any combination:
1180 
1181You: Generate a lydian scale starting on D
1182 
1183Claude: D lydian scale: D, E, F#, G#, A, B, C#
1184```
1185 
1186**Complex Chord Progressions**
1187```typescript
1188You: Create a jazz ii-V-I progression in Bb with extended voicings
1189 
1190Claude: Generated jazz progression in Bb: "Cm7" "F7" "Bbmaj7"
1191 
1192Pattern:
1193note("Cm7" "F7" "Bbmaj7")
1194  .struct("1 ~ ~ ~")
1195  .s("sawtooth")
1196  .add(note("7"))  // Add 7th extensions
1197  .room(0.4)
1198```
1199 
1200### Advanced Rhythm Techniques
1201 
1202**Euclidean Patterns**
1203```
1204You: Create a complex polyrhythm using euclidean patterns:
1205     - Bass drum: 7 hits in 16 steps
1206     - Snare: 5 hits in 16 steps
1207     - Hi-hat: 11 hits in 16 steps
1208 
1209Claude: [Generates mathematically perfect polyrhythm]
1210 
1211stack(
1212  s("bd").euclid(7, 16),
1213  s("cp").euclid(5, 16),
1214  s("hh").euclid(11, 16)
1215)
1216```
1217 
1218**Generative Variations**
1219```
1220You: Create 3 variations of my current pattern: subtle, moderate, and glitchy
1221 
1222Claude: [Generates three variants]
1223 
1224Version 1 (subtle):
1225original.sometimes(x => x.fast(2))
1226 
1227Version 2 (moderate):
1228original.every(4, x => x.rev).sometimes(x => x.fast(2))
1229 
1230Version 3 (glitchy):
1231original.sometimes(x => x.chop(8).rev).rarely(x => x.speed(-1))
1232```
1233 
1234### Performance Optimization Tips
1235 
1236**Pattern Caching**
1237```
1238// The server caches patterns intelligently:
1239// - Generated patterns stored before browser init
1240// - Editor content cached for 100ms
1241// - Audio analysis cached for 50ms
1242 
1243// For fastest performance:
12441. Generate patterns before initializing browser
12452. Initialize once and reuse the session
12463. Batch multiple changes together
1247```
1248 
1249**Headless Mode**
1250```json
1251// In config.json:
1252{
1253  "headless": true,  // Faster, no GUI
1254  "strudel_url": "https://strudel.cc/",
1255  "patterns_dir": "./patterns"
1256}
1257```
1258 
1259### Integration Patterns
1260 
1261**Workflow Automation**
1262```
1263You: Create a complete track:
1264     1. Start with techno drums at 130 BPM
1265     2. Add acid bassline in E
1266     3. Layer ambient pads
1267     4. Save as "track-001" with tags "techno", "acid", "experimental"
1268 
1269Claude: [Executes full workflow]
1270        [Initializes browser]
1271        [Generates drum pattern]
1272        [Adds bassline]
1273        [Layers pads]
1274        [Saves with metadata]
1275 
1276Complete! Pattern saved as "track-001"
1277```
1278 
1279**Audio-Reactive Composition**
1280```
1281You: Monitor the audio and suggest adjustments based on frequency balance
1282 
1283Claude: [Analyzes current playback]
1284 
1285Analysis shows:
1286- Bass: 180 (strong)
1287- Mid: 45 (weak)
1288- Treble: 30 (weak)
1289 
1290Recommendations:
12911. Reduce bass gain by 20%
12922. Add mid-range melodic content
12933. Include hi-hat pattern for treble
1294 
1295Apply changes? [Yes/No]
1296```
1297 
1298### Advanced Pattern Manipulation
1299 
1300**Dynamic Transformations**
1301```
1302You: Apply these transformations in sequence:
1303     1. Transpose up 3 semitones
1304     2. Add 10% humanization
1305     3. Apply reverb with 0.6 room size
1306     4. Every 4th cycle, reverse the pattern
1307 
1308Claude: [Applies transformations]
1309 
1310Final pattern:
1311[original]
1312  .transpose(3)
1313  .nudge(rand.range(-0.1, 0.1))
1314  .room(0.6)
1315  .every(4, x => x.rev)
1316```
1317 
1318**Conditional Logic**
1319```
1320You: Create a pattern that evolves:
1321     - Bars 1-4: Simple kick pattern
1322     - Bars 5-8: Add snare
1323     - Bars 9-16: Add full drum kit
1324     - Then loop with variations
1325 
1326Claude: [Generates evolving pattern]
1327 
1328s("bd*4")
1329  .struct("1 ~ ~ ~")
1330  .mask("<1 1 1 1 0 0 0 0>/4")  // First 4 bars
1331  .stack(
1332    s("~ cp ~ cp")
1333      .mask("<0 0 0 0 1 1 1 1>/8")  // Bars 5-8
1334  )
1335  // Full complexity from bar 9
1336  .every(8, x => x.sometimes(y => y.fast(2)))
1337```
1338 
1339## 🔒 Security
1340 
1341### Pattern Validation
1342 
1343All patterns are validated before execution:
1344- **Dangerous gain levels** (>2.0) are flagged
1345- **Eval blocks** are rejected
1346- **Path traversal** attacks are blocked in PatternStore
1347 
1348### Browser Sandboxing
1349 
1350- Playwright runs Chromium in sandbox mode
1351- No access to local filesystem from browser context
1352- Resource blocking prevents loading external content
1353 
1354### Known Limitations
1355 
1356- **No authentication**: The MCP server trusts all incoming requests
1357- **Local only**: Designed for local development, not network deployment
1358- **Pattern execution**: Patterns execute in browser context with audio access
1359 
1360### Reporting Security Issues
1361 
1362Found a vulnerability? Please [open a security issue](https://github.com/williamzujkowski/strudel-mcp-server/security/advisories/new) or email the maintainer directly. Do not disclose publicly until patched.
1363 
1364## 🐛 Troubleshooting
1365 
1366### Common Issues
1367 
1368#### Browser doesn't open
1369**Symptom**: `Error: Browser not initialized` or Chromium launch fails
1370 
1371**Solutions**:
1372```bash
1373# Install Chromium for Playwright
1374npx playwright install chromium
1375 
1376# If that fails, try installing all browsers
1377npx playwright install
1378 
1379# Check Playwright installation
1380npx playwright --version
1381 
1382# For Linux, install dependencies
1383sudo npx playwright install-deps chromium
1384```
1385 
1386#### Audio analysis returns "not connected"
1387**Symptom**: Audio analysis shows `connected: false`
1388 
1389**Solutions**:
13901. Ensure pattern is playing first:
1391   ```
1392   You: Play the pattern, wait 2 seconds, then analyze
1393   ```
1394 
13952. Reinitialize the browser:
1396   ```
1397   You: Stop, close the browser, reinitialize, and try again
1398   ```
1399 
14003. Check audio context activation:
1401   - Audio contexts require user interaction on some systems
1402   - The browser window must be visible (not headless) for first run
1403 
1404#### Pattern syntax errors
1405**Symptom**: Pattern doesn't play or shows errors in console
1406 
1407**Solutions**:
1408```
1409Common issues:
14101. Missing quotes: s(bd*4) → s("bd*4")
14112. Unmatched parentheses: stack(s("bd")) → stack(s("bd")))
14123. Invalid note names: note("h2") → note("c2")
1413 
1414Test with minimal pattern first:
1415s("bd*4")
1416 
1417Then build complexity gradually.
1418```
1419 
1420#### MCP connection issues
1421**Symptom**: Claude can't find the server or tools
1422 
1423**Solutions**:
1424```bash
1425# Verify server is built
1426npm run build
1427 
1428# Check if server responds
1429echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js
1430 
1431# Should return JSON with 65 tools
1432 
1433# Reinstall MCP server in Claude
1434claude mcp remove strudel
1435claude mcp add strudel node $(pwd)/dist/index.js
1436 
1437# Restart Claude
1438claude chat
1439```
1440 
1441#### Performance issues / Slow response
1442**Symptom**: Operations take longer than expected
1443 
1444**Solutions**:
14451. **Enable caching** (default, but verify):
1446   - Editor caching: 100ms TTL
1447   - Audio analysis: 50ms TTL
1448 
14492. **Use headless mode** for faster operation:
1450   ```json
1451   // config.json
1452   { "headless": true }
1453   ```
1454 
14553. **Batch operations**:
1456   ```
1457   Instead of:
1458   - Add drums
1459   - Add bass
1460   - Add melody
1461 
1462   Do:
1463   - Generate complete pattern with drums, bass, and melody
1464   ```
1465 
14664. **Reduce browser overhead**:
1467   - Close other browser instances
1468   - Disable browser DevTools
1469   - Use resource blocking (enabled by default)
1470 
1471#### Patterns not saving
1472**Symptom**: `save` command fails or patterns don't persist
1473 
1474**Solutions**:
1475```bash
1476# Check patterns directory exists
1477ls -la ./patterns
1478 
1479# Create manually if needed
1480mkdir -p ./patterns
1481 
1482# Verify write permissions
1483touch ./patterns/test.json
1484rm ./patterns/test.json
1485 
1486# Check for invalid pattern names
1487# Valid: "techno-beat-1", "my_pattern", "track001"
1488# Invalid: "pattern/with/slashes", "name:with:colons"
1489```
1490 
1491### Platform-Specific Issues
1492 
1493#### macOS
1494```bash
1495# Keyboard shortcut uses Meta (Cmd) key
1496# Already handled by ControlOrMeta
1497 
1498# If Chromium crashes on M1/M2:
1499npx playwright install chromium --with-deps
1500```
1501 
1502#### Linux
1503```bash
1504# Install system dependencies
1505sudo npx playwright install-deps chromium
1506 
1507# If running in Docker/headless environment:
1508# Ensure config.json has headless: true
1509```
1510 
1511#### Windows
1512```bash
1513# Use PowerShell or Git Bash
1514# Paths should use forward slashes in config.json
1515 
1516# If Chromium doesn't launch:
1517npx playwright install chromium
1518```
1519 
1520### Debugging Tips
1521 
1522**Enable Verbose Logging**
1523```bash
1524# Set environment variable
1525DEBUG=* node dist/index.js
1526 
1527# Or in Claude:
1528You: Enable detailed logging for the next operation
1529```
1530 
1531**Check Browser State**
1532```
1533You: Show me the current browser initialization state
1534     and any cached patterns
1535 
1536Claude: Browser state:
1537- Initialized: true
1538- Cached patterns: 2
1539- Undo stack depth: 5
1540- Last operation: write_pattern (2.5s ago)
1541```
1542 
1543**Validate Pattern Syntax**
1544```
1545You: Before playing, validate this pattern syntax:
1546     s("bd*4, ~ cp ~ cp")
1547 
1548Claude: [Checks syntax]
1549Valid Strudel pattern.
1550Ready to play.
1551```
1552 
1553### Getting Help
1554 
1555If you encounter issues not covered here:
1556 
15571. **Check existing issues**: [GitHub Issues](https://github.com/williamzujkowski/strudel-mcp-server/issues)
15582. **Run integration tests**: `npm run test:integration`
15593. **Enable debug mode**: `DEBUG=* npm start`
15604. **Consult Strudel docs**: [Strudel.cc documentation](https://strudel.cc/learn)
15615. **Create new issue**: Include error messages, OS, Node version, and steps to reproduce
1562 
1563## 🤝 Contributing
1564 
1565**We need your help!** This project is actively developed and welcomes contributions of all kinds:
1566 
1567### Ways to Contribute
1568- **Report Bugs**: Found an issue? [Open a bug report](https://github.com/williamzujkowski/strudel-mcp-server/issues/new)
1569- **Suggest Features**: Have ideas? [Create a feature request](https://github.com/williamzujkowski/strudel-mcp-server/issues/new)
1570- **Improve Docs**: Fix typos, add examples, clarify confusing sections
1571- **Write Tests**: Help us reach 80% coverage (currently 78%)
1572- **Fix Issues**: Check [open issues](https://github.com/williamzujkowski/strudel-mcp-server/issues) for bugs to fix
1573- **Add Features**: Implement new tools or improve existing ones
1574 
1575### Quick Start for Contributors
15761. Fork the repository
15772. Create a feature branch (`git checkout -b feature/amazing-feature`)
15783. Make your changes and add tests
15794. Ensure tests pass (`npm test`)
15805. Commit with clear messages (`git commit -m 'fix: resolve audio analysis bug'`)
15816. Push to your fork (`git push origin feature/amazing-feature`)
15827. Open a Pull Request
1583 
1584**First time contributor?** Look for issues labeled `good-first-issue` or `help-wanted`.
1585 
1586### Feedback Welcome
1587- Questions? Open a [Discussion](https://github.com/williamzujkowski/strudel-mcp-server/discussions)
1588- Found something confusing? Tell us!
1589- Have a use case we haven't considered? Share it!
1590 
1591We review PRs promptly and welcome contributors of all skill levels. See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed setup instructions.
1592 
1593## 📄 License
1594 
1595MIT License - see [LICENSE](LICENSE) file
1596 
1597## 🙏 Acknowledgments
1598 
1599- [Strudel.cc](https://strudel.cc) - Amazing live coding environment
1600- [TidalCycles](https://tidalcycles.org) - Pattern language inspiration
1601- [Anthropic](https://anthropic.com) - Claude AI and MCP protocol
1602- [Playwright](https://playwright.dev) - Reliable browser automation
1603 
1604---
1605 
1606**v2.4.0** - Open Source | Experimental | [Report Issues](https://github.com/williamzujkowski/strudel-mcp-server/issues) | [Contribute](https://github.com/williamzujkowski/strudel-mcp-server/pulls)
1607 
1608*This project is under active development. Core features work, but expect bugs and breaking changes. Not recommended for production use.*