# 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