configure_drum_controls

Instructions

Implementation Reference

• src/drum-controls.ts:129-153 (handler)

  The core handler function that validates and configures drum controls (pitch and envelope) for each drum, producing an AdvancedDrumKitConfig object.

  export function configureDrumControls(config: DrumControlsConfig): AdvancedDrumKitConfig {
    // Validate all drum configurations
    for (const drum of config.drums) {
      validatePitchSettings(drum);
      validateEnvelopeSettings(drum);
    }
  
    // Create the drum kit configuration
    return {
      globalSettings: {
        drumControls: config.drums.reduce((acc, drum) => ({
          ...acc,
          [drum.name]: {
            ...(drum.pitch && { pitch: drum.pitch }),
            ...(drum.envelope && { envelope: drum.envelope })
          }
        }), {})
      },
      drumPieces: config.drums.map(drum => ({
        name: drum.name,
        rootNote: drum.rootNote,
        samples: [] // Let caller provide samples
      }))
    };
  }

• src/index.ts:103-189 (registration)

  MCP tool registration in ListToolsRequestHandler, defining the tool name, description, and JSON input schema for validation.

        {
          name: "configure_drum_controls",
          description: `Configure global pitch and envelope controls for each drum type.
  
  This tool will:
  - Add per-drum pitch controls with customizable ranges
  - Configure ADSR envelope settings for natural decay control
  - Generate proper XML structure for global drum controls
  
  Error Handling:
  - Validates pitch range values (min/max must be valid numbers)
  - Ensures envelope times are positive values
  - Verifies curve values are within -100 to 100 range
  - Returns detailed error messages for invalid configurations
  
  Success Response:
  Returns XML structure containing:
  - Global controls for each drum type
  - MIDI CC mappings for real-time control
  - Properly formatted parameter bindings`,
          inputSchema: {
            type: "object",
            properties: {
              drumControls: {
                type: "object",
                additionalProperties: {
                  type: "object",
                  properties: {
                    pitch: {
                      type: "object",
                      properties: {
                        default: { 
                          type: "number",
                          description: "Default pitch in semitones (0 = no change)"
                        },
                        min: { 
                          type: "number",
                          description: "Minimum pitch adjustment (e.g. -12 semitones)"
                        },
                        max: { 
                          type: "number",
                          description: "Maximum pitch adjustment (e.g. +12 semitones)"
                        }
                      },
                      required: ["default"]
                    },
                    envelope: {
                      type: "object",
                      properties: {
                        attack: { 
                          type: "number",
                          description: "Attack time in seconds"
                        },
                        decay: { 
                          type: "number",
                          description: "Decay time in seconds"
                        },
                        sustain: { 
                          type: "number",
                          description: "Sustain level (0-1)"
                        },
                        release: { 
                          type: "number",
                          description: "Release time in seconds"
                        },
                        attackCurve: { 
                          type: "number",
                          description: "-100 to 100, Default: -100 (logarithmic)"
                        },
                        decayCurve: { 
                          type: "number",
                          description: "-100 to 100, Default: 100 (exponential)"
                        },
                        releaseCurve: { 
                          type: "number",
                          description: "-100 to 100, Default: 100 (exponential)"
                        }
                      },
                      required: ["attack", "decay", "sustain", "release"]
                    }
                  }
                }
              }
            },
            required: ["drumControls"]
          }
        },

• src/drum-controls.ts:34-60 (schema)

  TypeScript interfaces defining the schema for DrumControlsConfig, DrumConfig, DrumPitchConfig, and DrumEnvelopeConfig used by the handler.

  export interface DrumPitchConfig {
    default: number;
    min?: number;
    max?: number;
  }
  
  export interface DrumEnvelopeConfig {
    attack: number;
    decay: number;
    sustain: number;
    release: number;
    attackCurve?: number;
    decayCurve?: number;
    releaseCurve?: number;
  }
  
  export interface DrumConfig {
    name: string;
    rootNote: number;  // Required instead of defaulting
    pitch?: DrumPitchConfig;
    envelope?: DrumEnvelopeConfig;
  }
  
  export interface DrumControlsConfig {
    drums: DrumConfig[];
  }

• src/index.ts:715-752 (handler)

  MCP CallToolRequestHandler case for 'configure_drum_controls' that validates input, converts format, calls the core handler, generates XML output, and handles errors.

  case "configure_drum_controls": {
    const args = request.params.arguments;
    if (!args || typeof args !== 'object' || !args.drumControls) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Invalid arguments: expected object with drumControls"
      );
    }
  
    try {
      // Convert the input format to our DrumControlsConfig format
      const drumControlsConfig: DrumControlsConfig = {
        drums: Object.entries(args.drumControls).map(([name, controls]) => ({
          name,
          ...(controls as any)
        }))
      };
  
      // Configure and validate the drum controls
      const config = configureDrumControls(drumControlsConfig);
  
      // Generate XML with the validated configuration
      const xml = generateGroupsXml(config);
      return {
        content: [{
          type: "text",
          text: xml
        }]
      };
    } catch (error: unknown) {
      if (error instanceof McpError) throw error;
      const message = error instanceof Error ? error.message : String(error);
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to configure drum controls: ${message}`
      );
    }
  }

• src/drum-controls.ts:61-128 (helper)

  Helper validation functions for pitch and envelope settings used by the configureDrumControls handler to ensure valid configurations.

  function validatePitchSettings(drum: DrumConfig): void {
    if (!drum.pitch) return;
  
    const { default: defaultPitch, min, max } = drum.pitch;
  
    // Validate min/max if provided
    if (min !== undefined && max !== undefined && min > max) {
      throw new Error(
        `Invalid pitch range for drum "${drum.name}": min (${min}) cannot be greater than max (${max})`
      );
    }
  
    // Validate default is within range
    if (min !== undefined && defaultPitch < min) {
      throw new Error(
        `Invalid default pitch for drum "${drum.name}": ${defaultPitch} is below minimum ${min}`
      );
    }
    if (max !== undefined && defaultPitch > max) {
      throw new Error(
        `Invalid default pitch for drum "${drum.name}": ${defaultPitch} is above maximum ${max}`
      );
    }
  }
  
  function validateEnvelopeSettings(drum: DrumConfig): void {
    if (!drum.envelope) return;
  
    const env = drum.envelope;
  
    // Validate time values are positive
    if (env.attack < 0) {
      throw new Error(
        `Invalid attack time for drum "${drum.name}": ${env.attack}. Must be >= 0`
      );
    }
    if (env.decay < 0) {
      throw new Error(
        `Invalid decay time for drum "${drum.name}": ${env.decay}. Must be >= 0`
      );
    }
    if (env.release < 0) {
      throw new Error(
        `Invalid release time for drum "${drum.name}": ${env.release}. Must be >= 0`
      );
    }
  
    // Validate sustain level is between 0 and 1
    if (env.sustain < 0 || env.sustain > 1) {
      throw new Error(
        `Invalid sustain level for drum "${drum.name}": ${env.sustain}. Must be between 0 and 1`
      );
    }
  
    // Validate curve values if provided
    const validateCurve = (value: number | undefined, name: string) => {
      if (value !== undefined && (value < -100 || value > 100)) {
        throw new Error(
          `Invalid ${name} curve for drum "${drum.name}": ${value}. Must be between -100 and 100`
        );
      }
    };
  
    validateCurve(env.attackCurve, 'attack');
    validateCurve(env.decayCurve, 'decay');
    validateCurve(env.releaseCurve, 'release');
  }