Content
# Strudel MCP Server
> 🎵 Open source MCP server for AI-powered music generation with Strudel.cc
>
> **Status:** Actively developed | Experimental | Contributions welcome
<a href="https://glama.ai/mcp/servers/@williamzujkowski/strudel-mcp-server">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@williamzujkowski/strudel-mcp-server/badge" alt="Strudel Server MCP server" />
</a>
[](https://github.com/williamzujkowski/strudel-mcp-server/actions)
[](https://www.npmjs.com/package/@williamzujkowski/strudel-mcp-server)
[]()
[](LICENSE)
An 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.
**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.
## Table of Contents
- [Features](#-features)
- [Installation](#-installation)
- [Quick Reference](#-quick-reference)
- [Quick Start](#-quick-start)
- [Available Tools](#-available-tools-65)
- [Usage Examples](#-usage-examples)
- [Architecture](#-architecture)
- [Advanced Usage](#-advanced-usage)
- [Configuration](#-configuration)
- [Security](#-security)
- [Troubleshooting](#-troubleshooting)
- [Development](#-development)
- [Contributing](#-contributing)
## ✨ 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**: 1470 tests passing (1521 total, 51 skipped)
- ✅ **Code Coverage**: 78% statement coverage (goal: 80%)
- ✅ **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
**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
Explore 17 curated example patterns across 10 genres in [`patterns/examples/`](patterns/examples/):
- **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
Each example includes pattern code, BPM, key, and description. See [`patterns/examples/README.md`](patterns/examples/README.md) for details.
## 📦 Installation
### Prerequisites
| Requirement | Version | Notes |
|-------------|---------|-------|
| Node.js | 18.x or 20.x | LTS versions recommended |
| npm | 9+ | Comes with Node.js |
| Chromium | Latest | Auto-installed by Playwright |
| Audio output | Any | Required for playback (speakers/headphones) |
**Optional:** Docker for containerized deployment.
### From npm
```bash
npm install -g @williamzujkowski/strudel-mcp-server
# Install browser (required once)
npx playwright install chromium
```
### From Source
```bash
# Clone repository
git clone https://github.com/williamzujkowski/strudel-mcp-server.git
cd strudel-mcp-server
# 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:
| Action | Command |
|--------|---------|
| Initialize browser | `init` |
| Create techno beat | `generate_pattern` with `style: "techno"` |
| Play pattern | `play` |
| Stop playback | `stop` |
| Get current pattern | `get_pattern` |
| Analyze audio | `analyze` |
| Save pattern | `save` with `name: "my-pattern"` |
| Undo last change | `undo` |
**One-shot workflow:**
```
compose with style: "dnb", key: "Am", bpm: 174, auto_play: true
```
## 🎯 Quick Start
### 1. Add to Claude
```bash
# If installed globally
claude mcp add strudel strudel-mcp
# If built from source
claude mcp add strudel node /path/to/strudel-mcp-server/dist/index.js
```
### 2. Start Using
```bash
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 (65)
### Core Control (10 tools)
| Tool | Description | Example |
|------|-------------|---------|
| `init` | Initialize Strudel in browser | "Initialize Strudel" |
| `write` | Write pattern to editor | "Write pattern: s('bd*4')" |
| `play` | Start playback | "Play the pattern" |
| `stop` | Stop playback | "Stop playing" |
| `clear` | Clear editor | "Clear the editor" |
| `get_pattern` | Get current pattern | "Show current pattern" |
| `append` | Add to pattern | "Add hi-hats" |
| `insert` | Insert at line | "Insert at line 2" |
| `replace` | Replace text | "Replace bd with sn" |
| `pause` | Pause playback | "Pause" |
### Pattern Generation & Manipulation (10 tools)
| Tool | Description | Options |
|------|-------------|---------|
| `generate_pattern` | Complete patterns | techno, house, dnb, ambient, trap, jungle, jazz, intelligent_dnb, trip_hop, boom_bap |
| `generate_drums` | Drum patterns | All styles + complexity (0-1) |
| `generate_bassline` | Bass patterns | techno, house, dnb, acid, dub, funk, jazz, intelligent_dnb, trip_hop, boom_bap |
| `generate_melody` | Melodic lines | Any scale, custom length |
| `generate_variation` | Pattern variations | subtle, moderate, extreme, glitch |
| `transpose` | Transpose notes | ±12 semitones |
| `reverse` | Reverse pattern | - |
| `stretch` | Time stretch | Factor 0.1-10 |
| `quantize` | Quantize to grid | 1/4, 1/8, 1/16, etc. |
| `humanize` | Add timing variation | Amount 0-1 |
### Music Theory (6 tools)
| Tool | Description | Options |
|------|-------------|---------|
| `generate_scale` | Generate scales | major, minor, modes, pentatonic, blues |
| `generate_chord_progression` | Chord progressions | pop, jazz, blues, rock, folk |
| `generate_euclidean` | Euclidean rhythms | hits/steps/sound |
| `generate_polyrhythm` | Polyrhythms | Multiple patterns |
| `generate_fill` | Generate drum fills | All styles, 1-4 bars |
| `apply_scale` | Apply scale to notes | Any scale |
### Effects (4 tools)
| Tool | Description |
|------|-------------|
| `add_effect` | Add audio effect (reverb, delay, etc.) |
| `remove_effect` | Remove an effect from the chain |
| `set_tempo` | Set BPM (60-200) |
| `add_swing` | Add swing feel (0-1 amount) |
### Session Management (5 tools)
| Tool | Description |
|------|-------------|
| `save` | Save pattern with tags |
| `load` | Load saved pattern |
| `list` | List all patterns |
| `undo` | Undo last action |
| `redo` | Redo action |
### Pattern History (3 tools)
| Tool | Description |
|------|-------------|
| `list_history` | Browse pattern history with timestamps and previews |
| `restore_history` | Restore a previous pattern by ID |
| `compare_patterns` | Compare two patterns showing line-by-line differences |
### Audio Analysis (6 tools)
| Tool | Description |
|------|-------------|
| `analyze` | Basic audio analysis (frequency, playing state) |
| `analyze_spectrum` | FFT spectral analysis |
| `analyze_rhythm` | Rhythm complexity analysis |
| `detect_tempo` | BPM detection |
| `detect_key` | Musical key detection |
| `validate_pattern_runtime` | Validate pattern with browser error checking |
### UX & Browser Control (6 tools)
| Tool | Description |
|------|-------------|
| `compose` | One-shot pattern generation with auto-play |
| `status` | Get current browser/playback state |
| `diagnostics` | Detailed system diagnostics |
| `show_browser` | Bring browser window to foreground |
| `screenshot` | Capture browser screenshot |
| `show_errors` | Display captured console errors |
### Performance (2 tools)
| Tool | Description |
|------|-------------|
| `performance_report` | Timing metrics and bottleneck analysis |
| `memory_usage` | Memory consumption statistics |
### AI Feedback (1 tool)
| Tool | Description | Options |
|------|-------------|---------|
| `get_pattern_feedback` | AI-powered creative feedback via Gemini | `includeAudio`: analyze audio (default: false), `style`: hint for context |
> **Note:** Requires `GEMINI_API_KEY` environment variable. Returns pattern complexity, estimated style, strengths, and suggestions.
## 🎵 Usage Examples
### Basic Pattern Creation
**Create a Simple Beat**
```
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**
```
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**
```
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**
```
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**
```
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**
```
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**
```
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**
```
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**
```
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**
```
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**
```
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:
```bash
# Run integration tests
npm run test:integration
# Run browser tests
node tests/strudel-integration.js
# Test results: 1470/1521 tests passing (96.6%), 51 skipped (browser tests in CI)
```
## ⚙️ Configuration
### config.json
```json
{
"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:
```
┌─────────────────────────────────────────────────────────────┐
│ Claude AI │
│ (MCP Client) │
└───────────────────────┬─────────────────────────────────────┘
│ MCP Protocol (stdio)
│
┌───────────────────────▼─────────────────────────────────────┐
│ EnhancedMCPServerFixed │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 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. **EnhancedMCPServerFixed** (`src/server/EnhancedMCPServerFixed.ts`)
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
Key Features:
```typescript
- 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
```typescript
// 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
```typescript
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:
```typescript
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:
```typescript
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
```
strudel-mcp-server/
├── src/
│ ├── server/
│ │ ├── EnhancedMCPServer.ts # Original implementation
│ │ └── EnhancedMCPServerFixed.ts # Production version
│ ├── services/
│ │ ├── MusicTheory.ts # Theory engine
│ │ └── PatternGenerator.ts # Pattern creation
│ ├── utils/
│ │ └── Logger.ts # Logging utility
│ ├── types/
│ │ └── index.ts # TypeScript types
│ ├── StrudelController.ts # Browser automation
│ ├── AudioAnalyzer.ts # Audio analysis
│ ├── PatternStore.ts # 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
```
### Data Flow
1. **Tool Invocation**
```
Claude → MCP Protocol → EnhancedMCPServerFixed
```
2. **Pattern Generation** (without browser)
```
Server → PatternGenerator → MusicTheory → Pattern String
```
3. **Pattern Execution** (with browser)
```
Server → StrudelController → Playwright → Strudel.cc
```
4. **Audio Analysis**
```
Strudel.cc → Web Audio API → AudioAnalyzer → Feature Data
```
### Performance Characteristics
| Operation | Latency | Notes |
|-----------|---------|-------|
| Pattern Generation | <100ms | Pure computation |
| Browser Init | ~3s | One-time cost |
| Pattern Write | ~50ms | With caching |
| Play/Stop | ~100ms | Keyboard shortcuts |
| Audio Analysis | ~20ms | With 50ms cache |
| Pattern Save | ~10ms | File I/O |
### 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)
```javascript
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)
```javascript
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
```javascript
// 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
```bash
# Build image
docker build -t strudel-mcp .
# Run container
docker run -it --rm strudel-mcp
# Or use docker-compose
docker-compose up
```
## 🔧 Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/williamzujkowski/strudel-mcp-server.git
cd strudel-mcp-server
# Install dependencies
npm install
# Install Playwright browsers
npx playwright install chromium
# Build the project
npm run build
```
### Available Scripts
```bash
# 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](NPM_PUBLISHING.md) for complete publishing instructions.
**Quick publish via GitHub Release:**
```bash
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.
### Project Structure
```
src/
├── server/
│ ├── EnhancedMCPServer.ts # Original implementation
│ └── EnhancedMCPServerFixed.ts # Production version with caching
│
├── 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']
}
}
```
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);
```
3. **Add necessary service methods** if needed:
```typescript
// In appropriate service file
async doSomething(param1: string, param2?: number): Promise<string> {
// Implementation
return `Result: ${param1}`;
}
```
4. **Test the tool**:
```bash
# Build
npm run build
# Test via MCP
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
```bash
# Run with Jest
npm test
# Watch mode
npm run test:watch
```
#### 2. Integration Tests
```bash
# Full integration with real browser
npm run test:integration
# This tests:
# - Browser initialization
# - Pattern generation
# - Audio analysis
# - Pattern storage
# - All 65 tools
```
#### 3. Manual Testing
```bash
# 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**
```json
// 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**
```bash
# ESLint
npm run lint
# Prettier
npm run format
# Pre-commit hooks recommended
```
### Debugging
**Enable Debug Logging**
```bash
# 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**
```json
{
"type": "node",
"request": "launch",
"name": "Debug MCP Server",
"program": "${workspaceFolder}/dist/index.js",
"preLaunchTask": "npm: build",
"console": "integratedTerminal",
"env": {
"DEBUG": "strudel:*"
}
}
```
**Playwright Debugging**
```typescript
// 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:
```typescript
// 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**
```bash
git clone https://github.com/YOUR_USERNAME/strudel-mcp-server.git
```
2. **Create a feature branch**
```bash
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**
```bash
git commit -m "feat: Add support for custom scale generation"
```
Follow [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation changes
- `refactor:` Code refactoring
- `test:` Adding tests
- `chore:` Maintenance tasks
5. **Push and create PR**
```bash
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
```bash
# 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
```bash
# Build development image
docker build -t strudel-mcp:dev .
# Run with volume mount for hot reload
docker run -it --rm \
-v $(pwd)/src:/app/src \
-v $(pwd)/patterns:/app/patterns \
strudel-mcp:dev
# Run tests in container
docker run -it --rm strudel-mcp:dev npm test
```
### Environment Variables
```bash
# 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
- **Pattern Generation**: <100ms
- **Browser Initialization**: ~3 seconds
- **Pattern Writing**: Instant
- **Playback Start**: ~500ms
- **Audio Analysis**: Real-time
- **Memory Usage**: <150MB
## 🎓 Advanced Usage
### Custom Music Theory
**Create Custom Scales**
```typescript
// 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**
```typescript
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**
```
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**
```
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**
```
// 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**
```json
// In config.json:
{
"headless": true, // Faster, no GUI
"strudel_url": "https://strudel.cc/",
"patterns_dir": "./patterns"
}
```
### Integration Patterns
**Workflow Automation**
```
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**
```
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**
```
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**
```
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](https://github.com/williamzujkowski/strudel-mcp-server/security/advisories/new) 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**:
```bash
# 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:
```
You: Play the pattern, wait 2 seconds, then analyze
```
2. Reinitialize the browser:
```
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**:
```
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**:
```bash
# 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 65 tools
# 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:
```json
// config.json
{ "headless": true }
```
3. **Batch operations**:
```
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**:
```bash
# 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
```bash
# Keyboard shortcut uses Meta (Cmd) key
# Already handled by ControlOrMeta
# If Chromium crashes on M1/M2:
npx playwright install chromium --with-deps
```
#### Linux
```bash
# Install system dependencies
sudo npx playwright install-deps chromium
# If running in Docker/headless environment:
# Ensure config.json has headless: true
```
#### Windows
```bash
# 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**
```bash
# Set environment variable
DEBUG=* node dist/index.js
# Or in Claude:
You: Enable detailed logging for the next operation
```
**Check Browser State**
```
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**
```
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](https://github.com/williamzujkowski/strudel-mcp-server/issues)
2. **Run integration tests**: `npm run test:integration`
3. **Enable debug mode**: `DEBUG=* npm start`
4. **Consult Strudel docs**: [Strudel.cc documentation](https://strudel.cc/learn)
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](https://github.com/williamzujkowski/strudel-mcp-server/issues/new)
- **Suggest Features**: Have ideas? [Create a feature request](https://github.com/williamzujkowski/strudel-mcp-server/issues/new)
- **Improve Docs**: Fix typos, add examples, clarify confusing sections
- **Write Tests**: Help us reach 80% coverage (currently 78%)
- **Fix Issues**: Check [open issues](https://github.com/williamzujkowski/strudel-mcp-server/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](https://github.com/williamzujkowski/strudel-mcp-server/discussions)
- 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](DEVELOPMENT.md) for detailed setup instructions.
## 📄 License
MIT License - see [LICENSE](LICENSE) file
## 🙏 Acknowledgments
- [Strudel.cc](https://strudel.cc) - Amazing live coding environment
- [TidalCycles](https://tidalcycles.org) - Pattern language inspiration
- [Anthropic](https://anthropic.com) - Claude AI and MCP protocol
- [Playwright](https://playwright.dev) - Reliable browser automation
---
**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)
*This project is under active development. Core features work, but expect bugs and breaking changes. Not recommended for production use.*
