Decent-Sampler Drums MCP Server

Instructions

Implementation Reference

• src/round-robin.ts:32-104 (handler)

  Core implementation of the configure_round_robin tool. Validates round-robin mode, sequence positions, checks sample file existence in the directory, and constructs an AdvancedDrumKitConfig object used for generating the XML groups structure.
  export function configureRoundRobin(directory: string, config: RoundRobinConfig): AdvancedDrumKitConfig { // If mode is not 'always', ensure seqPosition is provided at some level if (config.mode !== 'always') { for (const group of config.groups) { const hasGroupSeqPos = group.settings?.seqPosition !== undefined; for (const sample of group.samples) { if (!hasGroupSeqPos && !sample.seqPosition && !sample.settings?.seqPosition) { throw new Error( `Sample ${sample.path} needs a seqPosition when mode is ${config.mode}. ` + 'Provide it at sample, group, or global level.' ); } } } } // If length is provided, validate sequence positions if (config.length !== undefined) { for (const group of config.groups) { for (const sample of group.samples) { const seqPos = sample.seqPosition || sample.settings?.seqPosition || group.settings?.seqPosition; if (seqPos !== undefined && (seqPos < 1 || seqPos > config.length)) { throw new Error( `Invalid sequence position ${seqPos} for sample ${sample.path}. ` + `Must be between 1 and ${config.length}` ); } } } } // Verify all files exist for (const group of config.groups) { for (const sample of group.samples) { const fullPath = path.join(directory, sample.path); if (!fs.existsSync(fullPath)) { throw new Error(`Sample file not found: ${sample.path}`); } } } // Create the drum kit configuration return { globalSettings: { roundRobin: { mode: config.mode, ...(config.length !== undefined && { length: config.length }) } }, drumPieces: config.groups.map(group => ({ name: group.name, rootNote: group.rootNote || 60, ...(group.settings && { seqMode: group.settings.mode, ...(group.settings.length !== undefined && { seqLength: group.settings.length }), ...(group.settings.seqPosition !== undefined && { seqPosition: group.settings.seqPosition }) }), samples: group.samples.map(sample => ({ path: sample.path, ...(sample.seqPosition !== undefined && { seqPosition: sample.seqPosition }), ...(sample.settings && { seqMode: sample.settings.mode, ...(sample.settings.length !== undefined && { seqLength: sample.settings.length }), ...(sample.settings.seqPosition !== undefined && { seqPosition: sample.settings.seqPosition }) }) })) })) }; }
• src/index.ts:190-246 (registration)

  Registration of the configure_round_robin tool in the MCP server, including detailed description and input schema for validation.
  { name: "configure_round_robin", description: `Configure round robin sample playback for a set of samples. This tool will: - Validate sequence positions - Verify sample files exist - Generate proper XML structure for round robin playback Error Handling: - Checks if sample files exist at specified paths - Validates sequence positions are unique and sequential - Ensures mode is one of: round_robin, random, true_random, always - Returns specific error messages for missing files or invalid sequences Success Response: Returns XML structure with: - Configured playback mode - Sample sequence assignments - Proper group organization for round robin playback`, inputSchema: { type: "object", properties: { directory: { type: "string", description: "Absolute path to the directory containing samples" }, mode: { type: "string", enum: ["round_robin", "random", "true_random", "always"], description: "Round robin playback mode" }, length: { type: "number", description: "Number of round robin variations" }, samples: { type: "array", items: { type: "object", properties: { path: { type: "string", description: "Path to sample file (relative to directory)" }, seqPosition: { type: "number", description: "Position in the round robin sequence (1 to length)" } }, required: ["path", "seqPosition"] } } }, required: ["directory", "mode", "length", "samples"] } },
• src/index.ts:551-598 (handler)

  MCP server request handler for the configure_round_robin tool call. Performs initial argument validation, invokes the configureRoundRobin function, generates XML, and handles errors.
  case "configure_round_robin": { const args = request.params.arguments; if (!args || typeof args !== 'object' || typeof args.directory !== 'string' || typeof args.mode !== 'string' || typeof args.length !== 'number' || !Array.isArray(args.samples)) { throw new McpError( ErrorCode.InvalidParams, "Invalid arguments: expected object with directory, mode, length, and samples" ); } if (!['round_robin', 'random', 'true_random', 'always'].includes(args.mode)) { throw new McpError( ErrorCode.InvalidParams, "Invalid mode: must be one of 'round_robin', 'random', 'true_random', 'always'" ); } try { const config = configureRoundRobin(args.directory, { mode: args.mode as "round_robin" | "random" | "true_random" | "always", length: args.length, groups: [{ name: "Samples", samples: args.samples.map(s => ({ path: String(s.path), seqPosition: Number(s.seqPosition) })) }] }); 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 round robin: ${message}` ); } }
• src/index.ts:210-244 (schema)

  JSON schema defining the input parameters for the configure_round_robin tool, including directory, mode, length, and samples array.
  inputSchema: { type: "object", properties: { directory: { type: "string", description: "Absolute path to the directory containing samples" }, mode: { type: "string", enum: ["round_robin", "random", "true_random", "always"], description: "Round robin playback mode" }, length: { type: "number", description: "Number of round robin variations" }, samples: { type: "array", items: { type: "object", properties: { path: { type: "string", description: "Path to sample file (relative to directory)" }, seqPosition: { type: "number", description: "Position in the round robin sequence (1 to length)" } }, required: ["path", "seqPosition"] } } }, required: ["directory", "mode", "length", "samples"]