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"
  }
}

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)

Pattern Generation (10 tools)

Pattern Manipulation (6 tools)

Effects & Processing (5 tools)

Audio Analysis (5 tools)

Session Management (5 tools)

AI-Powered Tools (7 tools)

Requires DEEPSEEK_API_KEY environment variable for full functionality.

Performance Monitoring (2 tools)

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

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

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