MiniMax MCP JS

Instructions

Implementation Reference

• src/api/voice-design.ts:16-73 (handler)

  Core handler implementing the voice_design tool logic: validates inputs, calls MiniMax /v1/voice_design API, decodes hex audio response, saves MP3 preview file, returns voiceId and outputFile.

  async voiceDesign(request: VoiceDesignRequest): Promise<any> {
    // Validate required parameters
    if (!request.prompt || request.prompt.trim() === '') {
      throw new MinimaxRequestError(ERROR_PROMPT_REQUIRED);
    }
    if (!request.previewText || request.previewText.trim() === '') {
      throw new MinimaxRequestError(ERROR_PREVIEW_TEXT_REQUIRED);
    }
  
    // Process output file
    const textPrefix = request.prompt.substring(0, 20).replace(/[^\w]/g, '_');
    const fileName = `voice_design_${textPrefix}_${Date.now()}`;
    const outputFile = buildOutputFile(fileName, request.outputDirectory, 'mp3');
  
    // Prepare request data
    const requestData: Record<string, any> = {
      prompt: request.prompt,
      preview_text: request.previewText,
      voice_id: request.voiceId,
    };
  
    try {
      // Send request
      const response = await this.api.post<any>('/v1/voice_design', requestData);
  
      // Process response
      const trialAudioData = response?.trial_audio;
      const voiceId = response?.voice_id;
  
      if (!trialAudioData) {
        throw new MinimaxRequestError('Could not get audio data from response');
      }
  
      // decode and save file
      try {
        // Convert hex string to binary
        const audioBuffer = Buffer.from(trialAudioData, 'hex');
  
        // Ensure output directory exists
        const outputDir = path.dirname(outputFile);
        if (!fs.existsSync(outputDir)) {
          fs.mkdirSync(outputDir, { recursive: true });
        }
  
        // Write to file
        fs.writeFileSync(outputFile, audioBuffer);
  
        return {
          voiceId,
          outputFile,
        };
      } catch (error) {
        throw new MinimaxRequestError(`Failed to save audio file: ${String(error)}`);
      }
    } catch (err) {
      throw err;
    }
  }

• src/mcp-server.ts:775-829 (registration)

  Registers the 'voice_design' MCP tool with name, description, Zod input schema (prompt, previewText, voiceId?, outputDirectory?), and async handler that calls VoiceDesignAPI and formats response.

  private registerVoiceDesignTool(): void {
    this.server.tool(
      'voice_design',
      'Generate a voice based on description prompts.\n\nNote: This tool calls MiniMax API and may incur costs. Use only when explicitly requested by the user.',
      {
        prompt: z
          .string()
          .describe('The prompt to generate the voice from'),
        previewText: z
          .string()
          .describe('The text to preview the voice'),
        voiceId: z
          .string()
          .optional()
          .describe('The id of the voice to use. For example, "male-qn-qingse"/"audiobook_female_1"/"cute_boy"/"Charming_Lady"...'),
        outputDirectory: COMMON_PARAMETERS_SCHEMA.outputDirectory,
      },
      async (params) => {
        try {
          // No need to update configuration from request parameters in stdio mode
          const { voiceId, outputFile } = await this.voiceDesignApi.voiceDesign(params);
  
          // Handle different output formats
          if (this.config.resourceMode === RESOURCE_MODE_URL) {
            return {
              content: [
                {
                  type: 'text',
                  text: `Success. Voice ID: ${voiceId}. Voice URL: ${outputFile}`,
                },
              ],
            };
          } else {
            return {
              content: [
                {
                  type: 'text',
                  text: `Success. Voice ID: ${voiceId}. Voice saved as: ${outputFile}`,
                },
              ],
            };
          }
        } catch (error) {
          return {  
            content: [
              {
                type: 'text',
                text: `Failed to design voice: ${error instanceof Error ? error.message : String(error)}`,
              },
            ],
          };
        }
      },
    );
  }

• src/types/index.ts:79-83 (schema)

  TypeScript interface defining the structure of VoiceDesignRequest: prompt (required), previewText (required), voiceId (optional), inherits outputDirectory from BaseToolRequest.

  export interface VoiceDesignRequest extends BaseToolRequest {
    prompt: string;
    previewText: string;
    voiceId?: string;
  }

• src/services/media-service.ts:244-251 (helper)

  Thin wrapper in MediaService that initializes and delegates to VoiceDesignAPI.voiceDesign, used by REST server handler.

  public async designVoice(params: any): Promise<any> {
    this.checkInitialized();
    try {
      return await this.voiceDesignApi.voiceDesign(params);
    } catch (error) {
      throw this.wrapError('Failed to design voice', error);
    }
  } 

• src/mcp-rest-server.ts:401-419 (registration)

  Tool definition/schema for 'voice_design' in REST server's listTools handler, including arguments and inputSchema for protocol compliance.

    name: 'voice_design',
    description: 'Generate a voice based on description prompts',
    arguments: [
      { name: 'prompt', description: 'The prompt to generate the voice from', required: true },
      { name: 'previewText', description: 'The text to preview the voice', required: true },
      { name: 'voiceId', description: 'The id of the voice to use', required: false },
      { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false }
    ],
    inputSchema: {
      type: 'object',
      properties: {
        prompt: { type: 'string' },
        previewText: { type: 'string' },
        voiceId: { type: 'string' },
        outputDirectory: { type: 'string' }
      },
      required: ['prompt', 'previewText']
    }
  }