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 (play tool)
Wait a moment for the audio context to connect
Try analyze tool to verify connection

DeepSeek API errors

Verify API key is set: check ai_status tool output
Test connection: use ai_test_connection tool
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