bfxr2-mcp

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

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

ID	Name	Description
0	Square	Classic square wave, good for retro game sounds
1	Saw	Sawtooth wave, raspy and buzzy
2	Sin	Pure sine wave, clean and simple
3	White	White noise, good for explosions and static
4	Triangle	Triangle wave, softer than square
5	Rasp	Periodic 1-bit noise, digital buzz
6	Tan	Tangent wave, potentially crazy/distorted
7	Whistle	Sin with overtone, breathy/hollow
8	Breaker	Quadratic wave, smooth and slick
9	Bitnoise	Periodic 1-bit white noise, glitchy
10	FMSyn	FM synthesis, dense and breathy
11	Voice	Digital voice sample

Named Presets

Pre-configured sounds with carefully tuned parameters:

Name	Wave Type	Description
cry	Voice	A crying/whimpering voice sound
pluck	Voice	A plucked string instrument sound
splash	Sin	A water splash effect
droplet	Whistle	A water droplet sound
rip	Voice	A tearing/ripping sound
woof	Square	A dog bark/woof sound
pushrock	White	A heavy object pushing/scraping sound
glass	Whistle	A glass breaking/tinkling sound
bark	Rasp	A sharp bark sound
powerdown	White	A power-down/shutdown sound
smallbark	Rasp	A small/quiet bark sound
bounce	FMSyn	A bouncy/springy sound

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.