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

1. Ensure audio is actually playing (play tool)
2. Wait a moment for the audio context to connect
3. Try analyze tool to verify connection

DeepSeek API errors

1. Verify API key is set: check ai_status tool output
2. Test connection: use ai_test_connection tool
3. 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: true in 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