MiniMax MCP JS

Instructions

Implementation Reference

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

  Registers the text_to_image MCP tool, defines the input schema using Zod, and provides the execution handler that calls ImageAPI.generateImage to perform the generation and handles the response based on resource mode.

  private registerTextToImageTool(): void {
    this.server.tool(
      'text_to_image',
      'Generate images based on text prompts.\n\nNote: This tool calls MiniMax API and may incur costs. Use only when explicitly requested by the user.',
      {
        model: z.string().optional().default(DEFAULT_T2I_MODEL).describe('Model to use'),
        prompt: z.string().describe('Text prompt for image generation'),
        aspectRatio: z
          .string()
          .optional()
          .default('1:1')
          .describe('Image aspect ratio, values: ["1:1", "16:9","4:3", "3:2", "2:3", "3:4", "9:16", "21:9"]'),
        n: z.number().min(1).max(9).optional().default(1).describe('Number of images to generate'),
        promptOptimizer: z.boolean().optional().default(true).describe('Whether to optimize the prompt'),
        outputDirectory: COMMON_PARAMETERS_SCHEMA.outputDirectory,
        outputFile: z
          .string()
          .optional()
          .describe('Path to save the generated image file, automatically generated if not provided'),
      },
      async (params) => {
        try {
          // No need to update configuration from request parameters in stdio mode
  
          // If no output filename is provided, generate one automatically
          if (!params.outputFile) {
            const promptPrefix = params.prompt.substring(0, 20).replace(/[^\w]/g, '_');
            params.outputFile = `image_${promptPrefix}_${Date.now()}`;
          }
  
          const outputFiles = await this.imageApi.generateImage(params);
  
          // Handle different output formats
          if (this.config.resourceMode === RESOURCE_MODE_URL) {
            return {
              content: [
                {
                  type: 'text',
                  text: `Success. Image URL(s): ${outputFiles.join(', ')}`,
                },
              ],
            };
          } else {
            return {
              content: [
                {
                  type: 'text',
                  text: `Image(s) saved: ${outputFiles.join(', ')}`,
                },
              ],
            };
          }
        } catch (error) {
          return {
            content: [
              {
                type: 'text',
                text: `Failed to generate image: ${error instanceof Error ? error.message : String(error)}`,
              },
            ],
          };
        }
      },
    );
  }

• src/api/image.ts:17-96 (handler)

  Core handler function in ImageAPI that validates input, prepares request to MiniMax /v1/image_generation endpoint, handles response URLs, downloads and saves images to local files if not in URL mode, returns file paths or URLs.

  async generateImage(request: ImageGenerationRequest): Promise<string[]> {
    // Validate required parameters
    if (!request.prompt || request.prompt.trim() === '') {
      throw new MinimaxRequestError(ERROR_PROMPT_REQUIRED);
    }
  
    // Validate model
    const model = this.ensureValidModel(request.model);
  
    // Prepare request data
    const requestData: Record<string, any> = {
      model: model,
      prompt: request.prompt,
      aspect_ratio: request.aspectRatio || '1:1',
      n: request.n || 1,
      prompt_optimizer: request.promptOptimizer !== undefined ? request.promptOptimizer : true
    };
  
    // Only add subject reference if provided
    if (request.subjectReference) {
      // Check if it's a URL
      if (!request.subjectReference.startsWith(('http://')) &&
          !request.subjectReference.startsWith(('https://')) &&
          !request.subjectReference.startsWith(('data:'))) {
        // If it's a local file, process it as a data URL
        if (!fs.existsSync(request.subjectReference)) {
          throw new MinimaxRequestError(`Reference image file does not exist: ${request.subjectReference}`);
        }
  
        const imageData = fs.readFileSync(request.subjectReference);
        const base64Image = imageData.toString('base64');
        requestData.subject_reference = `data:image/jpeg;base64,${base64Image}`;
      } else {
        requestData.subject_reference = request.subjectReference;
      }
    }
  
    // Send request
    const response = await this.api.post<any>('/v1/image_generation', requestData);
  
    // Check response structure
    const imageUrls = response?.data?.image_urls;
    if (!imageUrls || !Array.isArray(imageUrls) || imageUrls.length === 0) {
      throw new MinimaxRequestError('Unable to get image URLs from response');
    }
  
    // If URL mode, return URLs directly
    const resourceMode = this.api.getResourceMode();
    if (resourceMode === RESOURCE_MODE_URL) {
      return imageUrls;
    }
  
    // Process output files
    const outputFiles: string[] = [];
    const outputDir = request.outputDirectory;
  
    for (let i = 0; i < imageUrls.length; i++) {
      // Generate output filename - similar to Python version
      const outputFileName = buildOutputFile(`image_${i}_${request.prompt.substring(0, 20)}`, outputDir, 'jpg', true);
  
      try {
        // Download image
        const imageResponse = await requests.default.get(imageUrls[i], { responseType: 'arraybuffer' });
  
        // Ensure directory exists
        const dirPath = path.dirname(outputFileName);
        if (!fs.existsSync(dirPath)) {
          fs.mkdirSync(dirPath, { recursive: true });
        }
  
        // Save file
        fs.writeFileSync(outputFileName, Buffer.from(imageResponse.data));
        outputFiles.push(outputFileName);
      } catch (error) {
        throw new MinimaxRequestError(`Failed to download or save image: ${String(error)}`);
      }
    }
  
    return outputFiles;
  }

• src/mcp-server.ts:406-419 (schema)

  Zod schema defining input parameters for text_to_image tool including prompt, model, aspect ratio, number of images, etc.

  model: z.string().optional().default(DEFAULT_T2I_MODEL).describe('Model to use'),
  prompt: z.string().describe('Text prompt for image generation'),
  aspectRatio: z
    .string()
    .optional()
    .default('1:1')
    .describe('Image aspect ratio, values: ["1:1", "16:9","4:3", "3:2", "2:3", "3:4", "9:16", "21:9"]'),
  n: z.number().min(1).max(9).optional().default(1).describe('Number of images to generate'),
  promptOptimizer: z.boolean().optional().default(true).describe('Whether to optimize the prompt'),
  outputDirectory: COMMON_PARAMETERS_SCHEMA.outputDirectory,
  outputFile: z
    .string()
    .optional()
    .describe('Path to save the generated image file, automatically generated if not provided'),

• src/mcp-rest-server.ts:277-300 (registration)

  Static registration of text_to_image tool schema in REST server's listTools handler.

  name: 'text_to_image',
  description: 'Generate image based on text prompt',
  arguments: [
    { name: 'prompt', description: 'Text prompt for image generation', required: true },
    { name: 'model', description: 'Model to use', required: false },
    { name: 'aspectRatio', description: 'Image aspect ratio, values: ["1:1", "16:9","4:3", "3:2", "2:3", "3:4", "9:16", "21:9"]', required: false },
    { name: 'n', description: 'Number of images to generate (1-9)', required: false },
    { name: 'promptOptimizer', description: 'Whether to optimize prompt', required: false },
    { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false },
    { name: 'outputFile', description: 'Output file path, auto-generated if not provided', required: false }
  ],
  inputSchema: {
    type: 'object',
    properties: {
      prompt: { type: 'string' },
      model: { type: 'string' },
      aspectRatio: { type: 'string' },
      n: { type: 'number' },
      promptOptimizer: { type: 'boolean' },
      outputDirectory: { type: 'string' },
      outputFile: { type: 'string' }
    },
    required: ['prompt']
  }

• src/mcp-rest-server.ts:546-559 (helper)

  Handler in REST server that delegates text_to_image execution to MediaService with retry logic.

  private async handleTextToImage(args: any, api: MiniMaxAPI, mediaService: MediaService, attempt = 1): Promise<any> {
    try {
      // Call media service to handle request
      const result = await mediaService.generateImage(args);
      return result;
    } catch (error) {
      if (attempt < MAX_RETRY_ATTEMPTS) {
        // console.warn(`[${new Date().toISOString()}] Failed to generate image, attempting retry (${attempt}/${MAX_RETRY_ATTEMPTS})`, error);
        // Delay retry
        await new Promise(resolve => setTimeout(resolve, RETRY_DELAY * Math.pow(2, attempt - 1)));
        return this.handleTextToImage(args, api, mediaService, attempt + 1);
      }
      throw this.wrapError('Failed to generate image', error);
    }