Image Generation MCP Server

Instructions

Implementation Reference

• src/imageService.ts:59-147 (handler)

  Core handler method of ImageGenerationService that implements the image generation logic: caching, calling Replicate API, downloading images, saving to disk, and error handling.
  async generateImages(params: ImageGenerationParams): Promise<ImageGenerationResponse> { const startTime = Date.now(); try { // Check cache first const cacheKey = this.generateCacheKey(params); const cached = this.cache.get(cacheKey); if (cached) { // Verify files still exist const allFilesExist = cached.response.image_paths.every(path => fs.existsSync(path)); if (allFilesExist) { return { ...cached.response, metadata: { ...cached.response.metadata, cache_hit: true } }; } // If files don't exist, remove from cache this.cache.delete(cacheKey); } // Prepare model input const modelInput = { prompt: params.prompt, go_fast: params.go_fast ?? false, megapixels: params.megapixels ?? "1", num_outputs: params.num_outputs ?? 1, aspect_ratio: params.aspect_ratio ?? "1:1", num_inference_steps: params.num_inference_steps ?? 4 }; // Call Replicate API const output = await this.replicate.run( this.MODEL, { input: modelInput } ) as string[]; // Download and save images const imagePaths = await this.saveImages( output, params.output_dir, params.output_format ?? 'webp', params.output_quality ?? 80, params.filename ); const endTime = Date.now(); const response: ImageGenerationResponse = { image_paths: imagePaths, metadata: { model: this.MODEL, inference_time_ms: endTime - startTime, cache_hit: false } }; // Cache the result this.cache.set(cacheKey, { response, timestamp: Date.now() }); return response; } catch (error: any) { if (error.response) { const apiError = new Error(error.message) as APIError; apiError.code = 'API_ERROR'; apiError.details = { message: error.message, status: error.response.status }; throw apiError; } const serverError = new Error('Server error occurred') as ServerError; serverError.code = 'SERVER_ERROR'; serverError.details = { message: 'Failed to generate or save images', system_error: error.message }; throw serverError; } }
• src/server.ts:18-52 (registration)

  MCP server tool registration for 'generate-image', including description, Zod input schema, and wrapper handler delegating to ImageGenerationService.
  // Register the image generation tool server.tool( "generate-image", "Generate an image based on a prompt", { prompt: z.string(), output_dir: z.string().describe("Full absolute path to output directory. For Windows, use double backslashes like 'C:\\\\Users\\\\name\\\\path'. For Unix/Mac use '/path/to/dir'. Always use the proper path otherwise you will get an error."), filename: z.string().optional().describe("Base filename to save the image(s) with"), go_fast: z.boolean().optional(), megapixels: z.enum(["1", "2", "4"]).optional(), num_outputs: z.number().min(1).max(4).optional(), aspect_ratio: z.enum(["1:1", "4:3", "16:9"]).optional(), output_format: z.enum(["webp", "png", "jpeg"]).optional(), output_quality: z.number().min(1).max(100).optional(), num_inference_steps: z.number().min(4).max(20).optional() }, async (params) => { try { const result = await imageService.generateImages(params); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } catch (error: any) { return { content: [{ type: "text", text: `Error: ${error.message}` }] }; } } );
• src/types.ts:1-12 (schema)

  TypeScript interface defining the input parameters for the generate-image tool, used by ImageGenerationService.
  export interface ImageGenerationParams { prompt: string; output_dir: string; filename?: string; go_fast?: boolean; megapixels?: "1" | "2" | "4"; num_outputs?: number; aspect_ratio?: "1:1" | "4:3" | "16:9"; output_format?: "webp" | "png" | "jpeg"; output_quality?: number; num_inference_steps?: number; }
• src/imageService.ts:168-219 (helper)

  Helper method to download images from URLs (with retries), save them to disk in batches with concurrency limit, and return file paths.
  private async saveImages( imageUrls: string[], outputDir: string, format: 'webp' | 'png' | 'jpeg', quality: number, baseFilename?: string ): Promise<string[]> { // Create output directory if it doesn't exist if (!fs.existsSync(outputDir)) { fs.mkdirSync(outputDir, { recursive: true }); } // Prepare download tasks const downloadTasks = imageUrls.map(async (imageUrl, i) => { const filename = baseFilename ? (imageUrls.length > 1 ? `${baseFilename}_${i + 1}.${format}` : `${baseFilename}.${format}`) : `output_${i}.${format}`; const filePath = path.join(outputDir, filename); try { // Download image with retry mechanism const buffer = await this.downloadWithRetry(imageUrl); // Save image atomically using temporary file const tempPath = `${filePath}.tmp`; fs.writeFileSync(tempPath, buffer); fs.renameSync(tempPath, filePath); return filePath; } catch (error: any) { const serverError = new Error('Failed to save image') as ServerError; serverError.code = 'SERVER_ERROR'; serverError.details = { message: `Failed to save image ${i}`, system_error: error.message }; throw serverError; } }); // Execute all downloads in parallel with a concurrency limit const CONCURRENCY_LIMIT = 3; const imagePaths: string[] = []; for (let i = 0; i < downloadTasks.length; i += CONCURRENCY_LIMIT) { const batch = downloadTasks.slice(i, i + CONCURRENCY_LIMIT); const results = await Promise.all(batch); imagePaths.push(...results); } return imagePaths; }