Bfxr2 MCP Server

A Model Context Protocol (MCP) server that provides music and sound effect generation tools using the existing Bfxr2 codebase.

Table of Contents

• Features

• Installation

• MCP Server Configuration

• Usage

• Architecture

• Contributing

• Changelog

• License

Related MCP server: SuperCollider MCP Server

Features

• Sound Effect Generation: Create preset sound effects (pickup, laser, explosion, etc.)

• Custom Sound Creation: Full parameter control for custom sounds

• Random Generation: Generate random sounds with optional seeding

• WAV Export: Export generated sounds as WAV files (base64 or data URI)

• Parameter Inspection: View and modify sound parameters

• Zero Code Duplication: Uses existing Bfxr2 JavaScript files directly

Installation

cd mcp
npm install

MCP Server Configuration

To use the bfxr2 MCP server with Cline or other MCP clients, add this configuration:

{
  "mcpServers": {
    "bfxr2-music-generator": {
      "autoApprove": [
        "list_presets",
        "get_parameters",
        "generate_sound_effect",
        "randomize_sound"
      ],
      "disabled": false,
      "timeout": 30,
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/your/bfxr2/mcp/src/server.js"
      ]
    }
  }
}

Note: Update the path in args to match your actual bfxr2 installation directory.

Usage

Start the MCP Server

npm start

Available Tools

1. generate_sound_effect

   • Generate preset sound effects

   • Types: pickup, laser, explosion, powerup, hit, jump, blip

   • Optional custom parameter overrides

2. generate_named_sound

   • Generate sounds from precomputed named presets

   • Presets: cry, pluck, splash, droplet, rip, woof, pushrock, glass, bark, powerdown, smallbark, bounce

   • Each preset has carefully tuned parameters for specific sound characters

3. create_custom_sound

   • Full control over all sound parameters

   • Specify waveType, frequency, envelope, effects, etc.

4. create_sound_with_wave

   • Create sounds using wave type by name

   • Wave types: Square, Saw, Sin, White, Triangle, Rasp, Tan, Whistle, Breaker, Bitnoise, FMSyn, Voice

5. randomize_sound

   • Generate completely random sounds

   • Optional seed for reproducible results

6. mutate_sound

   • Create variations of the last generated sound

   • Slightly randomizes parameters while maintaining general character

7. export_wav

   • Export last generated sound as WAV

   • Formats: base64 or data URI

8. get_parameters

   • View current sound parameters

9. list_presets

   • List available generator presets (pickup, laser, etc.)

10. list_named_presets

    • List available named presets with descriptions (cry, bark, splash, etc.)

11. list_wave_types

    • List all available wave types with descriptions

Example Tool Calls

{
  "name": "generate_sound_effect",
  "arguments": {
    "type": "laser",
    "customParams": {
      "frequency_start": 0.7,
      "attackTime": 0.1
    }
  }
}

{
  "name": "create_custom_sound",
  "arguments": {
    "parameters": {
      "waveType": 2,
      "frequency_start": 0.5,
      "sustainTime": 0.3,
      "vibratoDepth": 0.2
    }
  }
}

{
  "name": "generate_named_sound",
  "arguments": {
    "preset": "bark",
    "filepath": "/tmp/bark.wav"
  }
}

{
  "name": "create_sound_with_wave",
  "arguments": {
    "waveType": "Whistle",
    "parameters": {
      "frequency_start": 0.6,
      "sustainTime": 0.4
    },
    "filepath": "/tmp/whistle.wav"
  }
}

{
  "name": "mutate_sound",
  "arguments": {
    "filepath": "/tmp/mutated.wav"
  }
}

Architecture

The MCP server uses a lightweight wrapper approach:

• bfxr-wrapper.js: Provides minimal browser API mocks and loads existing Bfxr2 files

• server.js: MCP server implementation with tool handlers

• No code duplication: Directly imports from ../js/ directory

Wave Types

Named Presets

Pre-configured sounds with carefully tuned parameters:

Sound Parameters

Key parameters you can control:

• waveType: Wave shape (0-11)

• frequency_start: Base frequency (0-1)

• frequency_slide: Frequency sweep (-0.5 to 0.5)

• attackTime: Volume envelope attack (0-1)

• sustainTime: Volume envelope sustain (0-1)

• decayTime: Volume envelope decay (0.03-1)

• vibratoDepth: Vibrato strength (0-1)

• vibratoSpeed: Vibrato speed (0-1)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to get started.

Changelog

See CHANGELOG.md for a list of changes in each version.

License

This project is licensed under the MIT License - see the LICENSE file for details.