Filopastry
AI-powered live coding music generation through Strudel.cc
An MCP (Model Context Protocol) server that enables AI agents to generate, manipulate, and perform algorithmic music using Strudel.cc — a web-based live coding environment inspired by TidalCycles.
Overview
Filopastry bridges the gap between AI and live-coded music. It provides 46+ tools for pattern generation, music theory operations, audio analysis, and AI-powered composition — all accessible through the Model Context Protocol.
The server automates a headless Chromium browser running Strudel.cc, allowing AI agents to write patterns, control playback, analyze audio in real-time, and generate music across multiple genres.
Key Capabilities
- Pattern Generation: Create complete tracks in techno, house, drum & bass, ambient, trap, jungle, jazz, and experimental styles
- Music Theory Engine: Generate scales, chord progressions, Euclidean rhythms, and polyrhythms
- Real-time Audio Analysis: FFT spectrum analysis, tempo detection, key detection
- AI Integration: Natural language pattern generation via DeepSeek API (optional)
- Session Management: Save, load, and organize patterns with tags
- Undo/Redo: Full editing history for pattern manipulation
Prerequisites
- Node.js 18.0.0 or higher
- npm 9.0.0 or higher
- Chromium (installed automatically by Playwright)
Installation
# Clone the repository
git clone https://github.com/youwenshao/filopastry.git
cd filopastry
# Install dependencies
npm install
# Install Playwright browsers
npx playwright install chromium
# Build the project
npm run build
Configuration
config.json
The server reads configuration from config.json in the project root:
{
"headless": false,
"strudel_url": "https://strudel.cc/",
"patterns_dir": "./patterns",
"audio_analysis": {
"fft_size": 2048,
"smoothing": 0.8
},
"deepseek": {
"model": "deepseek-chat",
"max_tokens": 2048,
"temperature": 0.7,
"base_url": "https://api.deepseek.com"
}
}
| Option | Description | Default |
|---|---|---|
headless | Run browser without GUI (set true for servers) | false |
strudel_url | Strudel.cc instance URL | https://strudel.cc/ |
patterns_dir | Directory for saved patterns | ./patterns |
audio_analysis.fft_size | FFT window size for audio analysis | 2048 |
audio_analysis.smoothing | Spectrum smoothing factor (0-1) | 0.8 |
DeepSeek API (Optional)
For AI-powered pattern generation, set the DEEPSEEK_API_KEY environment variable:
export DEEPSEEK_API_KEY="your-api-key-here"
Get an API key from the DeepSeek Platform.
When the API key is not configured, AI tools fall back to static pattern generation using the built-in PatternGenerator.
Usage
Running the MCP Server
# Start the server
npm start
# Or run in development mode with hot reload
npm run dev
Validating the Server
Test that the MCP protocol is working:
npm run validate
This sends a tools/list request and displays the available tools.
Integration with Cursor IDE
Add Filopastry to your Cursor MCP configuration:
macOS/Linux: ~/.cursor/mcp.json
Windows: %APPDATA%\Cursor\mcp.json
{
"mcpServers": {
"filopastry": {
"command": "node",
"args": ["/path/to/filopastry/dist/index.js"],
"env": {
"DEEPSEEK_API_KEY": "your-api-key-here"
}
}
}
}
Restart Cursor after updating the configuration.
Tool Reference
Filopastry provides 46+ tools organized into categories:
Core Control (10 tools)
| Tool | Description |
|---|---|
init | Initialize Strudel in browser |
write | Write pattern to editor |
append | Append code to current pattern |
insert | Insert code at specific line |
replace | Replace pattern section |
play | Start playing pattern |
pause | Pause playback |
stop | Stop playback |
clear | Clear the editor |
get_pattern | Get current pattern code |
Pattern Generation (10 tools)
| Tool | Description |
|---|---|
generate_pattern | Generate complete pattern from style (techno, house, dnb, ambient, trap, jungle, jazz) |
generate_drums | Generate drum pattern |
generate_bassline | Generate bassline |
generate_melody | Generate melody from scale |
generate_scale | Generate scale notes |
generate_chord_progression | Generate chord progression |
generate_euclidean | Generate Euclidean rhythm |
generate_polyrhythm | Generate polyrhythm |
generate_fill | Generate drum fill |
generate_variation | Create pattern variations |
Pattern Manipulation (6 tools)
| Tool | Description |
|---|---|
transpose | Transpose notes by semitones |
reverse | Reverse pattern |
stretch | Time stretch pattern |
quantize | Quantize to grid |
humanize | Add human timing variation |
apply_scale | Apply scale to notes |
Effects & Processing (5 tools)
| Tool | Description |
|---|---|
add_effect | Add effect to pattern |
remove_effect | Remove effect |
set_tempo | Set BPM |
add_swing | Add swing to pattern |
validate_pattern_runtime | Validate pattern with runtime error checking |
Audio Analysis (5 tools)
| Tool | Description |
|---|---|
analyze | Complete audio analysis |
analyze_spectrum | FFT spectrum analysis |
analyze_rhythm | Rhythm analysis |
detect_tempo | BPM detection |
detect_key | Key detection |
Session Management (5 tools)
| Tool | Description |
|---|---|
save | Save pattern with metadata |
load | Load saved pattern |
list | List saved patterns |
undo | Undo last action |
redo | Redo action |
AI-Powered Tools (7 tools)
Requires DEEPSEEK_API_KEY environment variable for full functionality.
| Tool | Description |
|---|---|
ai_generate_pattern | Generate pattern from natural language description |
ai_enhance_pattern | Enhance or modify current pattern |
ai_explain_pattern | Get explanation of what current pattern does |
ai_analyze_pattern | Get style detection, complexity assessment, suggestions |
ai_suggest_variations | Generate AI-suggested variations |
ai_status | Check if DeepSeek AI is configured |
ai_test_connection | Test DeepSeek API connection |
Performance Monitoring (2 tools)
| Tool | Description |
|---|---|
performance_report | Get performance metrics and bottlenecks |
memory_usage | Get current memory usage statistics |
Architecture
┌─────────────────────────────────────────────────────────────┐
│ MCP Protocol Layer │
│ EnhancedMCPServerFixed (46+ tools) │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MusicTheory │ │PatternGenerator │ │ DeepSeekService │
│ (scales, │ │ (genres, drums │ │ (AI patterns, │
│ chords) │ │ bass, melody) │ │ enhancement) │
└───────────────┘ └─────────────────┘ └─────────────────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌─────────────────┐ ┌─────────────────┐
│StrudelController│ │ AudioAnalyzer │ │ PatternStore │
│ (Playwright, │ │ (FFT, tempo, │ │ (JSON storage, │
│ browser) │ │ key detect) │ │ tags, cache) │
└───────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Strudel.cc │
│ (Web Audio, Live Coding) │
└─────────────────────────────────────────────────────────────┘
Component Overview
| Component | Purpose |
|---|---|
| EnhancedMCPServerFixed | MCP protocol handling, tool registration and routing |
| StrudelController | Browser automation via Playwright, editor manipulation |
| AudioAnalyzer | Real-time FFT analysis, tempo/key detection algorithms |
| MusicTheory | Scale generation, chord progressions, music theory calculations |
| PatternGenerator | Genre-specific pattern generation, Euclidean rhythms |
| DeepSeekService | AI integration for natural language pattern generation |
| PatternStore | JSON-based pattern persistence with tagging |
Troubleshooting
Browser won't launch
# Install Playwright browsers
npx playwright install chromium
Build fails
# Clean and rebuild
npm run clean
npm run build
"Browser not initialized" errors
Always run the init tool before using browser-dependent tools:
Use the init tool first, then generate_pattern, then play.
Audio analysis not working
- Ensure audio is actually playing (
playtool) - Wait a moment for the audio context to connect
- Try
analyzetool to verify connection
DeepSeek API errors
- Verify API key is set: check
ai_statustool output - Test connection: use
ai_test_connectiontool - Check API key validity at DeepSeek Platform
Pattern validation errors
The server includes safety checks for dangerous patterns (extreme gain values, eval blocks). Use validate_pattern_runtime to test patterns before playing.
Performance issues
Use performance_report to identify bottlenecks. Common optimizations:
- Set
headless: truein config.json for faster operation - Patterns are cached with 100ms TTL to reduce browser calls
Example Patterns
The patterns/examples/ directory contains genre-specific pattern templates:
patterns/examples/
├── ambient/
│ ├── dark-ambient.json
│ └── drone.json
├── dnb/
│ ├── liquid-dnb.json
│ └── neurofunk.json
├── house/
│ ├── deep-house.json
│ └── tech-house.json
├── jazz/
│ ├── bebop.json
│ └── modal-jazz.json
├── jungle/
│ ├── classic-jungle.json
│ └── ragga-jungle.json
├── techno/
│ ├── hard-techno.json
│ └── minimal-techno.json
└── trap/
├── cloud-trap.json
└── modern-trap.json
Performance
| Operation | Typical Latency |
|---|---|
| Browser initialization | 1.5-2s |
| Pattern write | 50-80ms |
| Pattern read (cached) | 10-15ms |
| Play/Stop | 100-150ms |
| Audio analysis | 10-15ms |
| Tempo detection | <100ms |
| Key detection | <100ms |
| AI pattern generation | 2-5s (network dependent) |
Author
Youwen Shao
- GitHub: @youwenshao
- Email: youwenshao@gmail.com
Acknowledgments
- Strudel.cc — The live coding music platform that makes this possible
- TidalCycles — The inspiration behind Strudel's pattern language
- Model Context Protocol — The protocol enabling AI agent integration
- DeepSeek — AI capabilities for natural language pattern generation
