configure_round_robin

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"]