create_drum_pattern

Instructions

Implementation Reference

• src/reaper_mcp/midi_tools.py:184-233 (handler)

  The create_drum_pattern function that implements the tool logic. It reads a step-sequencer pattern string, maps characters to GM drum MIDI notes via DRUM_MAPPINGS, and creates a MIDI item with drum notes on channel 9.

  @mcp.tool()
  def create_drum_pattern(
      track_index: int,
      pattern: str,
      start_position: float,
      beats: int = 4,
      repeats: int = 1,
  ) -> dict:
      """
      Create a drum pattern on a track using a step-sequencer string.
      Each character = one step. Characters: k=kick, s=snare, h=hihat(closed),
      o=hihat(open), t=tom(low), m=tom(mid), f=tom(high), c=crash, r=ride, .=rest.
      Example 4/4 rock beat (16 steps): "k...h...s...h..."
      All drum notes are placed on MIDI channel 9 (GM standard).
      """
      try:
          project = get_project()
          track = project.tracks[track_index]
          seconds_per_beat = 60.0 / project.bpm
          pattern_length = seconds_per_beat * beats
          total_length = pattern_length * repeats
  
          item = track.add_midi_item(start_position, start_position + total_length)
          take = item.active_take
          time_per_step = pattern_length / len(pattern)
  
          for repeat in range(repeats):
              offset = repeat * pattern_length
              for i, char in enumerate(pattern):
                  if char in DRUM_MAPPINGS:
                      note_start = offset + i * time_per_step
                      take.add_note(
                          start=note_start,
                          end=note_start + time_per_step * 0.5,
                          pitch=DRUM_MAPPINGS[char],
                          velocity=100,
                          channel=9,
                      )
  
          return {
              "success": True,
              "item_id": item.id,
              "pattern": pattern,
              "repeats": repeats,
              "start_position": start_position,
              "total_length": total_length,
          }
      except Exception as e:
          logger.error(f"create_drum_pattern failed: {e}")
          return {"success": False, "error": str(e)}

• src/reaper_mcp/midi_tools.py:10-21 (schema)

  DRUM_MAPPINGS constant that defines the mapping from step-sequencer characters to GM standard drum MIDI note numbers. This acts as the schema/validation for which characters are valid in the pattern string.

  # GM standard drum MIDI notes
  DRUM_MAPPINGS = {
      "k": 36,  # kick  - C1
      "s": 38,  # snare - D1
      "h": 42,  # hihat closed - F#1
      "o": 46,  # hihat open   - A#1
      "t": 41,  # tom low  - F1
      "m": 45,  # tom mid  - A1
      "f": 48,  # tom high - C2
      "c": 49,  # crash - C#2
      "r": 51,  # ride  - D#2
  }

• src/reaper_mcp/midi_tools.py:61-63 (registration)

  The register_tools function wraps all tool definitions with @mcp.tool() decorator. When called from server.py, it registers create_drum_pattern (and the other MIDI tools) with the MCP server.

  def register_tools(mcp):
  
      @mcp.tool()

• src/reaper_mcp/server.py:10-22 (registration)

  The server.py imports register_tools from midi_tools and calls it to register all MIDI tools including create_drum_pattern with the MCP server.

  from reaper_mcp.project_tools import register_tools as _reg_project
  from reaper_mcp.track_tools import register_tools as _reg_track
  from reaper_mcp.midi_tools import register_tools as _reg_midi
  from reaper_mcp.fx_tools import register_tools as _reg_fx
  from reaper_mcp.audio_tools import register_tools as _reg_audio
  from reaper_mcp.mixing_tools import register_tools as _reg_mixing
  from reaper_mcp.render_tools import register_tools as _reg_render
  from reaper_mcp.mastering_tools import register_tools as _reg_mastering
  from reaper_mcp.analysis_tools import register_tools as _reg_analysis
  
  _reg_project(mcp)
  _reg_track(mcp)
  _reg_midi(mcp)

• src/reaper_mcp/connection.py:27-29 (helper)

  The get_project helper used by create_drum_pattern to obtain a reference to the current REAPER project.

  def get_project() -> reapy.Project:
      ensure_connected()
      return reapy.Project()