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); }