Strudel MCP - Model Context Protocol Integration for Strudel

This project provides an MCP (Model Context Protocol) server that enables LLMs to interact with Strudel - a JavaScript port of the Tidal Cycles pattern language for live coding music.

Overview

Strudel MCP allows Large Language Models (LLMs) to:

• Execute Strudel patterns via natural language commands
• Retrieve current pattern states
• Get Strudel documentation through Context7 integration
• Access browser development tools for debugging

Architecture

┌─────────────┐    MCP     ┌──────────────┐    WebSocket    ┌─────────────┐
│   LLM       │ ◄──────► │ strudel-mcp  │ ◄─────────────► │  Strudel    │
│  (Qwen/     │  Protocol │   Server     │   Communication│  REPL/      │
│  etc.)      │           │ (Node.js ✨) │                │  Frontend   │
└─────────────┘           └──────────────┘                └─────────────┘

Server Options

Node.js Server

cd server-node
npm install
npm run dev

Components

• strudel-mcp (Node.js): MCP server with WebSocket communication
• WebSocket Server: Handles bidirectional communication between MCP and Strudel
• Frontend: Web-based Strudel interface with synchronization capabilities
• Context7 Integration: External documentation service for Strudel docs

Original Strudel Project

This project is based on and inspired by the original Strudel project:

• Original Repository: https://github.com/tidalcycles/strudel
• Primary Source: https://codeberg.org/uzu/strudel (Codeberg mirror)
• Official Website: https://strudel.cc
• Documentation: https://strudel.cc/docs

Note:

• The source_of_strudel/ directory was cloned from https://codeberg.org/uzu/strudel on 2025-10-12 for development reference.
• Both directories were local development references and are not included in this GitHub repository.

License

This project follows the AGPL-3.0 license, consistent with the original Strudel project. See LICENSE file for details.

Features

MCP Tools

• execute_strudel_code - Execute Strudel patterns
• get_current_pattern - Get current active pattern
• get_strudel_knowledge - Built-in Strudel documentation and knowledge base

Synchronization Features

• BroadcastChannel API: Cross-tab pattern synchronization
• Real-time Updates: Immediate pattern changes across multiple tabs/windows
• Error Handling: Robust error recovery and fallback mechanisms

Quick Start

Prerequisites

• Bun (>=1.0) - Recommended runtime
• Modern browser with WebSocket and Web Audio API support

Note: This project is optimized for Bun. While it works with Node.js, we strongly recommend using Bun for better performance and developer experience.

Installation

1. Clone the repository:

   git clone https://github.com/utenadev/strudel-mcp.git
   cd strudel-mcp
   

2. Install server dependencies:

   cd server-node
   bun install
   cd ..
   

3. Install frontend dependencies:

   cd frontend
   bun install
   cd ..
   

4. Start the servers:

   # Terminal 1: Start MCP + WebSocket server
   cd server-node
   bun run dev
   
   # Terminal 2: Start frontend
   cd frontend
   bun run dev
   

5. Run tests:

   cd frontend
   bun run test  # 23 tests
   

Usage with LLM

Qwen3-Coder + Qwen-code (MCP Configuration Required)

Create .qwen/settings.json in your project root:

Production (built version):

{
  "mcpServers": {
    "strudel-mcp": {
      "command": "node",
      "args": ["server-node/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Development (npm dev):

{
  "mcpServers": {
    "strudel-mcp": {
      "command": "npm", 
      "args": ["run", "dev"],
      "cwd": "server-node",
      "env": {
        "NODE_ENV": "development",
        "DEBUG": "true"
      }
    }
  }
}

Pre-built settings provided in this repository:

• .qwen/settings.json - Production ready
• .qwen/settings.dev.json - Development mode

Build first for production: cd server-node && npm run build

Gemini CLI (MCP Configuration Required)

Configure ~/.gemini/settings.json:

{
  "selectedAuthType": "gemini-api-key",
  "theme": "Dracula",
  "mcpServers": {
    "strudel-mcp": {
      "command": "node",
      "args": ["/path/to/strudel-mcp/server-node/dist/index.js"],
      "cwd": "/path/to/strudel-mcp/server-node"
    }
  }
}

Build first: cd server-node && npm run build

Verify with /mcp command in Gemini CLI

Claude Desktop (MCP Configuration Required)

Configure Claude Desktop settings:

1. Open Claude Desktop → Settings → Developer → Edit Config
2. Add to mcpServers:

{
  "mcpServers": {
    "strudel-mcp": {
      "command": "node",
      "args": ["/path/to/strudel-mcp/server-node/dist/index.js"],
      "cwd": "/path/to/strudel-mcp/server-node"
    }
  }
}

3. Restart Claude Desktop
4. Verify tools are available in new chat

GitHub Copilot (MCP Configuration Required)

In VS Code with GitHub Copilot (v1.99+):

1. Open Settings → Extensions → GitHub Copilot
2. Enable "MCP servers in Copilot" policy
3. Use GitHub MCP Registry or manual configuration

{
  "mcpServers": {
    "strudel-mcp": {
      "command": "node",
      "args": ["/path/to/strudel-mcp/server-node/dist/index.js"],
      "cwd": "/path/to/strudel-mcp/server-node"
    }
  }
}

Note: Replace /path/to/strudel-mcp with your actual repository path

Development

Project Structure

strudel-mcp/
├── server-node/               # Node.js MCP server
│   ├── src/
│   │   ├── index.ts          # Main server entry
│   │   ├── mcp/              # MCP protocol handlers
│   │   ├── websocket/        # WebSocket manager
│   │   └── utils/            # Utilities (logger, config)
│   ├── test/                 # Server tests
│   ├── package.json          # Dependencies
│   └── tsconfig.json         # TypeScript config
├── frontend/                  # React-based Strudel interface
│   ├── src/
│   │   ├── App.tsx           # Main application component
│   │   ├── hooks/            # React hooks (useStrudel, useWebSocket)
│   │   ├── presets/          # Genre-based pattern presets
│   │   ├── types/            # TypeScript type declarations
│   │   └── test/             # Frontend tests
│   ├── package.json          # Dependencies
│   └── vitest.config.ts      # Test configuration
├── docs/                      # Documentation
├── source_of_strudel/         # Strudel source reference (git submodule)
└── images/                    # Screenshots and assets

Key Technologies

• Runtime: Bun (recommended)
• Backend: TypeScript + Express + @modelcontextprotocol/sdk
• Frontend: React + TypeScript + Vite
• Audio: Strudel packages (@strudel/core, @strudel/webaudio, @strudel/transpiler)
• Communication: WebSocket protocol
• Testing: Vitest + React Testing Library

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style and conventions
• Add appropriate error handling
• Update documentation for new features
• Test cross-browser compatibility

Roadmap

• [ ] Enhanced pattern synchronization across multiple tabs
• [ ] Improved error handling and recovery
• [ ] Additional LLM tools for advanced pattern manipulation
• [ ] Performance optimizations
• [ ] Mobile browser support
• [ ] Plugin system for extensions

API Reference

WebSocket Endpoints

• ws://localhost:8081/ws?type=mcp - MCP client connection
• ws://localhost:8081/ws?type=strudel - Strudel frontend connection

MCP Tool Reference

execute_strudel_code

Execute Strudel pattern code

{
  "name": "execute_strudel_code",
  "arguments": {
    "code": "s('bd hh sd oh').fast(2)"
  }
}

get_current_pattern

Get currently executing pattern

{
  "name": "get_current_pattern",
  "arguments": {}
}

get_strudel_knowledge

Built-in Strudel documentation

{
  "name": "get_strudel_knowledge",
  "arguments": {
    "topic": "basics",
    "query": "drum patterns"
  }
}

Available topics: basics, patterns, effects, troubleshooting

Troubleshooting

Common Issues

1. WebSocket Connection Failed

   • Ensure port 8081 is available
   • Check firewall settings
   • Verify server and frontend are running

2. Audio Not Playing

   • Check browser audio permissions
   • Ensure user interaction initiated audio context
   • Verify Web Audio API support

3. MCP Connection Issues

   • Verify MCP server is running
   • Check LLM client configuration
   • Ensure stdio communication is working

Logging

• Server logs: Console output
• Frontend logs: Browser developer console
• WebSocket logs: Server console with verbose mode

Acknowledgments

• Original Strudel Team: For creating an amazing live coding environment
• TidalCycles Community: For the pattern language inspiration
• MCP Contributors: For the Model Context Protocol standard

License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details, consistent with the original Strudel project.

---

Note: This is an independent implementation inspired by Strudel. For the official Strudel project, please visit strudel.cc.