# 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](https://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
```bash
# 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:
```json
{
"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:
```bash
export DEEPSEEK_API_KEY="your-api-key-here"
```
Get an API key from the [DeepSeek Platform](https://platform.deepseek.com/api_keys).
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
```bash
# 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:
```bash
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`
```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
```bash
# Install Playwright browsers
npx playwright install chromium
```
### Build fails
```bash
# 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](https://platform.deepseek.com/)
### 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](https://github.com/youwenshao)
- Email: youwenshao@gmail.com
---
## Acknowledgments
- [Strudel.cc](https://strudel.cc/) — The live coding music platform that makes this possible
- [TidalCycles](https://tidalcycles.org/) — The inspiration behind Strudel's pattern language
- [Model Context Protocol](https://modelcontextprotocol.io/) — The protocol enabling AI agent integration
- [DeepSeek](https://deepseek.com/) — AI capabilities for natural language pattern generation
