Skip to main content
Glama
xDarkzx

ReaperMCP

by xDarkzx
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

scan_audio_folder

Scan audio folders to extract BPM, key, and role from filenames. Returns loop metadata and summaries to help select loops matching target criteria.

Instructions

Walk a folder for audio loops and parse metadata from filenames.

Returns every audio file (.wav, .mp3, .flac, .aif, .aiff, .ogg, .m4a) with BPM, musical key, and role (kick / bass / pad / lead / fx / …) extracted from the filename. Plus a summary of distributions so the AI can quickly decide on a target BPM / key before picking loops.

For a large library (thousands of files), don't scan the whole thing blindly: call list_audio_subfolders first to see its shape, point path at the specific subfolder that matters, and use the filters below to narrow further.

Args: path: Absolute folder path (e.g., D:/Music Production/Chillstep Express). recursive: Walk subfolders too. Default True. max_files: With no filters, stop after this many files visited. With any filter below active, stop after this many MATCHES instead (the walk looks past non-matching files to find them, up to an internal safety ceiling). Default 500; max 5000. query: Space-separated terms, ALL must match (AND) against the full path, case-insensitive — covers genre/style words ("techno") and specific naming ("laugh") since these usually appear literally in folder or file names. min_bpm: Only files whose parsed BPM is >= this. 0 = no filter. max_bpm: Only files whose parsed BPM is <= this. 0 = no filter. role: Exact match (case-insensitive) against the parsed role (kick/snare/hat/ride/perc/bass/pad/lead/vocal/fx/drums). Empty = no filter. key: Root note + optional accidental, e.g. "D", "F#", "Bb". Matches any quality (major/minor) unless you specify one ("Dm"). Empty = no filter.

Returns a structure with:

  • folder: resolved absolute path

  • total_files: how many matched

  • truncated: True if max_files hit before end

  • summary: BPM / key / role distributions + parse-failure counts

  • loops: list of { path, filename, duration_sec, size_mb, parsed: { bpm, key, role } }

  • hint: a one-line suggestion for the AI's next call

Files without parseable metadata are still listed when no filter needs that field; a min_bpm/max_bpm/role/key filter excludes files where that specific field didn't parse. Pair with transport_set_bpm + load_loops to turn the selection into a working REAPER session.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
keyNo
pathYes
roleNo
queryNo
max_bpmNo
min_bpmNo
max_filesNo
recursiveNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.7.0
    • addedInput schema / properties / key
      Added value: +{
+  "default": "",
+  "title": "Key",
+  "type": "string"
+}
    • addedInput schema / properties / max_bpm
      Added value: +{
+  "default": 0,
+  "title": "Max Bpm",
+  "type": "integer"
+}
    • addedInput schema / properties / min_bpm
      Added value: +{
+  "default": 0,
+  "title": "Min Bpm",
+  "type": "integer"
+}
    • addedInput schema / properties / query
      Added value: +{
+  "default": "",
+  "title": "Query",
+  "type": "string"
+}
    • addedInput schema / properties / role
      Added value: +{
+  "default": "",
+  "title": "Role",
+  "type": "string"
+}
  2. First observedv0.3.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses filtering semantics (a min_bpm/max_bpm/role/key filter excludes files where that field didn't parse, while unfiltered results still list them), truncation via max_files with a distinct 'matches vs visited' rule and an internal safety ceiling, and a truncated flag. That is well beyond annotation-level safety hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with a front-loaded purpose, an Args block, and a Returns block; every sentence carries information. It is long, but the length is justified by 8 filter parameters and a non-trivial return shape. Slightly dense, so not a perfect 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so spelling out the return structure (folder, total_files, truncated, summary, loops[], hint) is warranted and present, and all 8 parameters plus edge-case behavior are covered. Nothing an agent needs to call this correctly or consume its result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate and it fully does: path (absolute, with example), recursive (default), max_files (default 500, max 5000, and the matches-vs-visited nuance), query (space-separated AND, case-insensitive, covers path/name), min_bpm/max_bpm (0 = no filter), role (exact case-insensitive match against the parsed role with an enumerated list), and key (root+accidental, any-quality unless specified). Every parameter's semantics are clarified beyond the bare schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Walk a folder for audio loops and parse metadata from filenames,' and enumerates exactly what it extracts (BPM, key, role). It also names the siblings it relates to (list_audio_subfolders for orientation, transport_set_bpm + load_loops downstream), so an agent can place it in the workflow without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when NOT to scan blindly ('For a large library... don't scan the whole thing blindly'), names the alternative (list_audio_subfolders) and the condition that selects it, and gives the follow-up condition for narrowing with filters. This is exactly the when/when-not/alternatives pattern.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools