mcp-hydrocoder-image 1.1.1 → 1.2.1

package/dist/server/mcpServer.js

@@ -1,201 +1,240 @@
 /**
  * MCP Server implementation
- * Simplified architecture with direct Gemini integration
+ * Supports multiple image providers with Gemini prompt enhancement when applicable
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-// API clients
 import { createGeminiClient } from '../api/geminiClient.js';
 import { createGeminiTextClient } from '../api/geminiTextClient.js';
-// Business logic
+import { createVolcengineClient } from '../api/volcengineClient.js';
 import { createFileManager } from '../business/fileManager.js';
-import { validateGenerateImageParams } from '../business/inputValidator.js';
+import { validateGenerateImageParams, validatePrompt } from '../business/inputValidator.js';
+import { buildIndependentImagePrompt, extractExplicitImageRequests, normalizeMultiImageParams, prepareGenerateMultiImageParams, } from '../business/multiImagePrompt.js';
+import { resolveRequestedProvider } from '../business/providerResolver.js';
 import { createResponseBuilder } from '../business/responseBuilder.js';
 import { createStructuredPromptGenerator, } from '../business/structuredPromptGenerator.js';
-// Utilities
 import { getConfig } from '../utils/config.js';
 import { Logger } from '../utils/logger.js';
 import { SecurityManager } from '../utils/security.js';
 import { ErrorHandler } from './errorHandler.js';
-/**
- * Default MCP server configuration
- */
 const DEFAULT_CONFIG = {
     name: 'mcp-image-server',
     version: '0.1.0',
     defaultOutputDir: './output',
 };
-/**
- * Simplified MCP server
- */
+function createInputSchema(multiOnly = false) {
+    return {
+        type: 'object',
+        properties: {
+            prompt: {
+                type: 'string',
+                description: multiOnly
+                    ? 'Shared prompt or overall requirements for a multi-image generation task. Use this tool when the user wants one grouped result containing multiple images. Keep common constraints here and prefer outputCount or imageRequests over multiple tool calls.'
+                    : 'Shared prompt or overall requirements for single-image generation or editing. If the user wants multiple images in one request, prefer generate_multi_image instead. English recommended for prompt enhancement.',
+            },
+            provider: {
+                type: 'string',
+                description: 'Optional provider override. Defaults to IMAGE_PROVIDER when omitted. If the user explicitly asks for Volcengine, Seedream, 豆包, or 火山引擎, set this to `volcengine`. If they explicitly ask for Gemini, Google Gemini, or Nano Banana, set this to `gemini`. Do not probe shell environment variables before calling the tool.',
+                enum: ['gemini', 'volcengine'],
+            },
+            fileName: {
+                type: 'string',
+                description: 'Custom file name for the output image. Auto-generated if not specified.',
+            },
+            inputImagePath: {
+                type: 'string',
+                description: 'Optional absolute path to a source image. If the user provides a local image path, pass it here directly instead of summarizing image contents in the prompt. Supported by Gemini and Volcengine reference-image workflows.',
+            },
+            inputImage: {
+                type: 'string',
+                description: 'Optional base64 encoded image data for image-to-image generation. Gemini accepts raw base64; Volcengine sends this as `data:image/<format>;base64,<data>` and requires `inputImageMimeType` for correct formatting.',
+            },
+            inputImageMimeType: {
+                type: 'string',
+                description: 'MIME type of the input image provided via inputImage. Required when inputImage is provided for accurate processing',
+                enum: ['image/jpeg', 'image/png', 'image/webp', 'image/gif', 'image/bmp'],
+            },
+            inputImages: {
+                type: 'array',
+                description: 'Multiple input images for multi-image composition. Supported by Gemini and by Volcengine when mapped to reference-image arrays.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        data: {
+                            type: 'string',
+                            description: 'Base64 encoded image data. Raw base64 is accepted; for Volcengine it will be sent as `data:image/<format>;base64,<data>` using the paired `mimeType`.',
+                        },
+                        mimeType: {
+                            type: 'string',
+                            description: 'MIME type of the image',
+                            enum: ['image/jpeg', 'image/png', 'image/webp', 'image/gif', 'image/bmp'],
+                        },
+                    },
+                    required: ['data', 'mimeType'],
+                },
+            },
+            inputImagePaths: {
+                type: 'array',
+                description: 'Multiple absolute local image paths for multi-image composition. If the user provides two or more local image paths, pass them here directly instead of summarizing the images in the prompt.',
+                items: {
+                    type: 'string',
+                    description: 'Absolute path to an image file',
+                },
+            },
+            returnBase64: {
+                type: 'boolean',
+                description: 'Return the generated image as base64 data in the response. The image is always saved to disk regardless of this setting. Default: false',
+            },
+            blendImages: {
+                type: 'boolean',
+                description: 'Enable multi-image blending for combining multiple visual elements naturally. Use when prompt mentions multiple subjects or composite scenes',
+            },
+            maintainCharacterConsistency: {
+                type: 'boolean',
+                description: 'Maintain character appearance consistency. Enable when generating same character in different poses/scenes',
+            },
+            useWorldKnowledge: {
+                type: 'boolean',
+                description: 'Use real-world knowledge for accurate context. Enable for historical figures, landmarks, or factual scenarios',
+            },
+            useGoogleSearch: {
+                type: 'boolean',
+                description: 'Enable Google Search grounding for Gemini. Ignored by providers that do not support it.',
+            },
+            aspectRatio: {
+                type: 'string',
+                description: 'Aspect ratio for the generated image. When omitted, the server defaults to 16:9 for Gemini and Volcengine.',
+                enum: ['1:1', '1:4', '1:8', '2:3', '3:2', '3:4', '4:1', '4:3', '4:5', '5:4', '8:1', '9:16', '16:9', '21:9'],
+            },
+            imageSize: {
+                type: 'string',
+                description: 'Image resolution for high-quality output. Specify "1K", "2K", or "4K" when you need specific resolution. When omitted, the server defaults to 4K for Gemini and Volcengine. Volcengine also normalizes the final size into the provider legal pixel range.',
+                enum: ['1K', '2K', '4K'],
+            },
+            purpose: {
+                type: 'string',
+                description: 'Intended use for the image (e.g., cookbook cover, social media post, presentation slide). Influences lighting, composition, and detail level to match the context.',
+            },
+            quality: {
+                type: 'string',
+                description: 'Quality preset controlling speed/fidelity tradeoff. "fast": drafts, "balanced": better detail, "quality": highest fidelity.',
+                enum: ['fast', 'balanced', 'quality'],
+            },
+            outputFormat: {
+                type: 'string',
+                description: 'Output image format if supported by the provider. Some provider endpoints may ignore or reject format overrides.',
+                enum: ['png', 'jpeg', 'webp'],
+            },
+            outputCount: {
+                type: 'integer',
+                description: multiOnly
+                    ? 'Target number of images to generate in one grouped multi-image call. Prefer values greater than 1. If omitted, the server will try to infer the count from prompts like "4张图" or "4 images".'
+                    : 'Backward-compatible grouped output count for generate_image. For new multi-image requests, prefer generate_multi_image instead. Currently wired for Volcengine, but final image count still depends on provider behavior.',
+            },
+            imageRequests: {
+                type: 'array',
+                description: multiOnly
+                    ? 'Per-image prompts for one grouped multi-image call. Use this when the user wants multiple distinct images at once. The server rewrites them into explicit 第1张/第2张/... instructions and infers outputCount from the array length when omitted.'
+                    : 'Backward-compatible per-image prompts for generate_image. For new grouped multi-image requests, prefer generate_multi_image instead.',
+                items: {
+                    type: 'string',
+                },
+            },
+            skipPromptEnhancement: {
+                type: 'boolean',
+                description: 'Skip prompt enhancement and use the prompt as-is. Enable when your prompt already contains exact instructions.',
+            },
+        },
+        required: ['prompt'],
+    };
+}
+function createOutputSchema() {
+    return {
+        type: 'object',
+        properties: {
+            type: {
+                type: 'string',
+                const: 'image_result',
+            },
+            files: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        uri: { type: 'string' },
+                        name: { type: 'string' },
+                        title: { type: 'string' },
+                        mimeType: { type: 'string' },
+                        description: { type: 'string' },
+                    },
+                    required: ['uri', 'name', 'mimeType'],
+                },
+            },
+            base64Included: {
+                type: 'boolean',
+            },
+            metadata: {
+                type: 'object',
+                properties: {
+                    model: { type: 'string' },
+                    processingTime: { type: 'number' },
+                    contextMethod: { type: 'string' },
+                    timestamp: { type: 'string' },
+                    imageCount: { type: 'integer' },
+                },
+                required: ['model', 'processingTime', 'contextMethod', 'timestamp', 'imageCount'],
+            },
+        },
+        required: ['type', 'files', 'metadata'],
+    };
+}
 export class MCPServerImpl {
     constructor(config = {}) {
         this.server = null;
         this.structuredPromptGenerator = null;
         this.geminiTextClient = null;
         this.geminiClient = null;
+        this.volcengineClient = null;
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.logger = new Logger();
         this.fileManager = createFileManager();
         this.responseBuilder = createResponseBuilder();
         this.securityManager = new SecurityManager();
     }
-    /**
-     * Get server info
-     */
     getServerInfo() {
         return {
             name: this.config.name,
             version: this.config.version,
         };
     }
-    /**
-     * Get list of registered tools
-     */
     getToolsList() {
         return {
             tools: [
                 {
                     name: 'generate_image',
-                    description: 'Generate, edit, blend, or merge images using AI. Supports text-to-image generation, single image editing, and multi-image composition/blending. Use inputImagePaths for merging multiple images from file paths, or inputImages for base64 encoded images.',
-                    inputSchema: {
-                        type: 'object',
-                        properties: {
-                            prompt: {
-                                type: 'string',
-                                description: 'The prompt for image generation (English recommended for optimal structured prompt enhancement)',
-                            },
-                            fileName: {
-                                type: 'string',
-                                description: 'Custom file name for the output image. Auto-generated if not specified.',
-                            },
-                            inputImagePath: {
-                                type: 'string',
-                                description: 'Optional absolute path to source image for image-to-image generation. Use when generating variations, style transfers, or similar images based on an existing image (must be an absolute path)',
-                            },
-                            inputImage: {
-                                type: 'string',
-                                description: 'Optional base64 encoded image data for image-to-image generation. Alternative to inputImagePath when image data is already in memory. Do not include data URI prefix (e.g., "data:image/png;base64,")',
-                            },
-                            inputImageMimeType: {
-                                type: 'string',
-                                description: 'MIME type of the input image provided via inputImage. Required when inputImage is provided for accurate processing',
-                                enum: [
-                                    'image/jpeg',
-                                    'image/png',
-                                    'image/webp',
-                                    'image/gif',
-                                    'image/bmp',
-                                ],
-                            },
-                            inputImages: {
-                                type: 'array',
-                                description: 'Multiple input images for multi-image composition. Cannot be used together with inputImage or inputImagePath. Each item requires base64 data and MIME type.',
-                                items: {
-                                    type: 'object',
-                                    properties: {
-                                        data: {
-                                            type: 'string',
-                                            description: 'Base64 encoded image data. Do not include data URI prefix.',
-                                        },
-                                        mimeType: {
-                                            type: 'string',
-                                            description: 'MIME type of the image',
-                                            enum: [
-                                                'image/jpeg',
-                                                'image/png',
-                                                'image/webp',
-                                                'image/gif',
-                                                'image/bmp',
-                                            ],
-                                        },
-                                    },
-                                    required: ['data', 'mimeType'],
-                                },
-                            },
-                            inputImagePaths: {
-                                type: 'array',
-                                description: 'Multiple input image file paths for multi-image composition. Cannot be used together with inputImage, inputImagePath, or inputImages. Each path must be absolute.',
-                                items: {
-                                    type: 'string',
-                                    description: 'Absolute path to an image file',
-                                },
-                            },
-                            returnBase64: {
-                                type: 'boolean',
-                                description: 'Return the generated image as base64 data in the response. The image is always saved to disk regardless of this setting. Default: false',
-                            },
-                            blendImages: {
-                                type: 'boolean',
-                                description: 'Enable multi-image blending for combining multiple visual elements naturally. Use when prompt mentions multiple subjects or composite scenes',
-                            },
-                            maintainCharacterConsistency: {
-                                type: 'boolean',
-                                description: 'Maintain character appearance consistency. Enable when generating same character in different poses/scenes',
-                            },
-                            useWorldKnowledge: {
-                                type: 'boolean',
-                                description: 'Use real-world knowledge for accurate context. Enable for historical figures, landmarks, or factual scenarios',
-                            },
-                            useGoogleSearch: {
-                                type: 'boolean',
-                                description: "Enable Google Search grounding to access real-time web information for factually accurate image generation. Use when prompt requires current or time-sensitive data that may have changed since the model's knowledge cutoff. Leave disabled for creative, fictional, historical, or timeless content.",
-                            },
-                            aspectRatio: {
-                                type: 'string',
-                                description: 'Aspect ratio for the generated image',
-                                enum: [
-                                    '1:1',
-                                    '1:4',
-                                    '1:8',
-                                    '2:3',
-                                    '3:2',
-                                    '3:4',
-                                    '4:1',
-                                    '4:3',
-                                    '4:5',
-                                    '5:4',
-                                    '8:1',
-                                    '9:16',
-                                    '16:9',
-                                    '21:9',
-                                ],
-                            },
-                            imageSize: {
-                                type: 'string',
-                                description: 'Image resolution for high-quality output. Specify "1K", "2K", or "4K" when you need specific resolution. Leave unspecified for standard quality.',
-                                enum: ['1K', '2K', '4K'],
-                            },
-                            purpose: {
-                                type: 'string',
-                                description: 'Intended use for the image (e.g., cookbook cover, social media post, presentation slide). Influences lighting, composition, and detail level to match the context.',
-                            },
-                            quality: {
-                                type: 'string',
-                                description: 'Quality preset controlling speed/fidelity tradeoff. Only specify when the user explicitly requests a specific quality level; omit to use the server\'s configured default. "fast": best for drafts and rapid iteration. "balanced": better detail and coherence, moderate latency. "quality": highest fidelity, use for final deliverables where quality matters most.',
-                                enum: ['fast', 'balanced', 'quality'],
-                            },
-                            skipPromptEnhancement: {
-                                type: 'boolean',
-                                description: 'Skip prompt enhancement and use the prompt as-is. Enable when your prompt already contains exact instructions (e.g., multi-image blending) that should not be rewritten. Default: false',
-                            },
-                        },
-                        required: ['prompt'],
-                    },
+                    description: 'Generate, edit, blend, or merge a single image using AI. Use this tool for standard single-image generation and image editing. If the user wants multiple images in one grouped request, prefer generate_multi_image. When the user provides local image file paths, those paths must be passed through inputImagePath or inputImagePaths instead of being summarized by the model. If the user explicitly asks for Volcengine, Seedream, 豆包, or 火山引擎, pass `provider="volcengine"`. If they explicitly ask for Gemini, Google Gemini, or Nano Banana, pass `provider="gemini"`. Do not use shell checks for provider env vars before calling this tool. Gemini handles prompt enhancement; Volcengine supports text-to-image and reference-image workflows through its OpenAI-compatible image API.',
+                    inputSchema: createInputSchema(false),
+                    outputSchema: createOutputSchema(),
+                },
+                {
+                    name: 'generate_multi_image',
+                    description: 'Generate multiple images in a single grouped tool call. Use this tool when the user wants a set of images, multiple product shots, multiple scenes, or several variations at once. This tool is preferred for Notebook planners that might otherwise split one request into multiple generate_image calls. If the user explicitly asks for Volcengine, Seedream, 豆包, or 火山引擎, pass `provider="volcengine"`. If they explicitly ask for Gemini, Google Gemini, or Nano Banana, pass `provider="gemini"`. The server will infer outputCount from phrases like "4张图" when possible and will rewrite prompts into explicit 第1张/第2张/... instructions.',
+                    inputSchema: createInputSchema(true),
+                    outputSchema: createOutputSchema(),
                 },
             ],
         };
     }
-    /**
-     * Tool execution
-     */
     async callTool(name, args) {
         try {
             if (name === 'generate_image') {
                 return await this.handleGenerateImage(args);
             }
+            if (name === 'generate_multi_image') {
+                return await this.handleGenerateMultiImage(args);
+            }
             throw new Error(`Unknown tool: ${name}`);
         }
         catch (error) {
@@ -203,17 +242,13 @@ export class MCPServerImpl {
             return ErrorHandler.handleError(error);
         }
     }
-    /**
-     * Initialize Gemini clients lazily
-     */
-    async initializeClients() {
+    async initializeGeminiSupport() {
         if (this.structuredPromptGenerator && this.geminiClient)
             return;
         const configResult = getConfig();
         if (!configResult.success) {
             throw configResult.error;
         }
-        // Initialize Gemini Text Client for prompt generation
         if (!this.geminiTextClient) {
             const textClientResult = createGeminiTextClient(configResult.data);
             if (!textClientResult.success) {
@@ -221,11 +256,9 @@ export class MCPServerImpl {
             }
             this.geminiTextClient = textClientResult.data;
         }
-        // Initialize Structured Prompt Generator
         if (!this.structuredPromptGenerator) {
             this.structuredPromptGenerator = createStructuredPromptGenerator(this.geminiTextClient);
         }
-        // Initialize Gemini Client for image generation
         if (!this.geminiClient) {
             const clientResult = createGeminiClient(configResult.data);
             if (!clientResult.success) {
@@ -233,160 +266,278 @@ export class MCPServerImpl {
             }
             this.geminiClient = clientResult.data;
         }
-        this.logger.info('mcp-server', 'Gemini clients initialized');
     }
-    /**
-     * Simplified image generation handler
-     */
-    async handleGenerateImage(params) {
-        const result = await ErrorHandler.wrapWithResultType(async () => {
-            // Validate input
-            const validationResult = validateGenerateImageParams(params);
-            if (!validationResult.success) {
-                throw validationResult.error;
-            }
-            // Get configuration
-            const configResult = getConfig();
-            if (!configResult.success) {
-                throw configResult.error;
+    async initializeVolcengineSupport() {
+        if (this.volcengineClient)
+            return;
+        const configResult = getConfig();
+        if (!configResult.success) {
+            throw configResult.error;
+        }
+        const clientResult = createVolcengineClient(configResult.data);
+        if (!clientResult.success) {
+            throw clientResult.error;
+        }
+        this.volcengineClient = clientResult.data;
+    }
+    getProviderClient(provider) {
+        if (provider === 'gemini') {
+            if (!this.geminiClient) {
+                throw new Error('Gemini client not initialized');
             }
-            // Initialize clients
-            await this.initializeClients();
-            // Handle input image if provided
-            let inputImageData;
-            let inputImageMimeType;
-            let inputImagesData;
-            if (params.inputImagePaths && params.inputImagePaths.length > 0) {
-                // Multi-image from file paths: read each file and derive mimeType from extension
-                const extToMime = {
-                    '.jpg': 'image/jpeg',
-                    '.jpeg': 'image/jpeg',
-                    '.png': 'image/png',
-                    '.webp': 'image/webp',
-                    '.gif': 'image/gif',
-                    '.bmp': 'image/bmp',
+            return this.geminiClient;
+        }
+        if (!this.volcengineClient) {
+            throw new Error('Volcengine client not initialized');
+        }
+        return this.volcengineClient;
+    }
+    async prepareInputImages(params) {
+        let inputImageData;
+        let inputImageMimeType;
+        let inputImagesData;
+        const extToMime = {
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.png': 'image/png',
+            '.webp': 'image/webp',
+            '.gif': 'image/gif',
+            '.bmp': 'image/bmp',
+        };
+        if (params.inputImagePaths && params.inputImagePaths.length > 0) {
+            inputImagesData = await Promise.all(params.inputImagePaths.map(async (filePath) => {
+                const buffer = await fs.readFile(filePath);
+                const ext = path.extname(filePath).toLowerCase();
+                return {
+                    data: buffer.toString('base64'),
+                    mimeType: extToMime[ext] || 'image/jpeg',
                 };
-                inputImagesData = await Promise.all(params.inputImagePaths.map(async (filePath) => {
-                    const buffer = await fs.readFile(filePath);
-                    const ext = path.extname(filePath).toLowerCase();
-                    return {
-                        data: buffer.toString('base64'),
-                        mimeType: extToMime[ext] || 'image/jpeg',
-                    };
-                }));
-                inputImageData = inputImagesData[0]?.data;
-                inputImageMimeType = inputImagesData[0]?.mimeType;
-            }
-            else if (params.inputImages && params.inputImages.length > 0) {
-                // Multi-image: strip data URI prefix from each image
-                inputImagesData = params.inputImages.map((img) => ({
-                    data: img.data.replace(/^data:image\/[a-z]+;base64,/, ''),
-                    mimeType: img.mimeType,
-                }));
-                // Use first image for prompt enhancement context
-                inputImageData = inputImagesData[0]?.data;
-                inputImageMimeType = inputImagesData[0]?.mimeType;
-            }
-            else if (params.inputImagePath) {
-                const imageBuffer = await fs.readFile(params.inputImagePath);
-                inputImageData = imageBuffer.toString('base64');
-            }
-            else if (params.inputImage) {
-                // Use base64 input directly, stripping data URI prefix if present
-                inputImageData = params.inputImage.replace(/^data:image\/[a-z]+;base64,/, '');
-                inputImageMimeType = params.inputImageMimeType;
-            }
-            // Generate structured prompt (unless skipped)
-            let structuredPrompt = params.prompt;
-            const shouldSkipEnhancement = params.skipPromptEnhancement ?? configResult.data.skipPromptEnhancement;
-            if (!shouldSkipEnhancement && this.structuredPromptGenerator) {
-                const features = {};
-                if (params.maintainCharacterConsistency !== undefined) {
-                    features.maintainCharacterConsistency = params.maintainCharacterConsistency;
-                }
-                if (params.blendImages !== undefined) {
-                    features.blendImages = params.blendImages;
-                }
-                if (params.useWorldKnowledge !== undefined) {
-                    features.useWorldKnowledge = params.useWorldKnowledge;
-                }
-                if (params.useGoogleSearch !== undefined) {
-                    features.useGoogleSearch = params.useGoogleSearch;
-                }
-                const promptResult = await this.structuredPromptGenerator.generateStructuredPrompt(params.prompt, features, inputImageData, // Pass image data for context-aware prompt generation
-                params.purpose // Pass intended use for purpose-aware prompt generation
-                );
-                if (promptResult.success) {
-                    structuredPrompt = promptResult.data.structuredPrompt;
-                    this.logger.info('mcp-server', 'Structured prompt generated', {
-                        originalLength: params.prompt.length,
-                        structuredLength: structuredPrompt.length,
-                        selectedPractices: promptResult.data.selectedPractices,
-                    });
-                }
-                else {
-                    this.logger.warn('mcp-server', 'Using original prompt', {
-                        error: promptResult.error.message,
-                    });
-                }
-            }
-            else if (shouldSkipEnhancement) {
+            }));
+            inputImageData = inputImagesData[0]?.data;
+            inputImageMimeType = inputImagesData[0]?.mimeType;
+        }
+        else if (params.inputImages && params.inputImages.length > 0) {
+            inputImagesData = params.inputImages.map((img) => ({
+                data: img.data.replace(/^data:image\/[a-z0-9.+-]+;base64,/i, ''),
+                mimeType: img.mimeType,
+            }));
+            inputImageData = inputImagesData[0]?.data;
+            inputImageMimeType = inputImagesData[0]?.mimeType;
+        }
+        else if (params.inputImagePath) {
+            const imageBuffer = await fs.readFile(params.inputImagePath);
+            const ext = path.extname(params.inputImagePath).toLowerCase();
+            inputImageData = imageBuffer.toString('base64');
+            inputImageMimeType = extToMime[ext] || 'image/jpeg';
+        }
+        else if (params.inputImage) {
+            inputImageData = params.inputImage.replace(/^data:image\/[a-z0-9.+-]+;base64,/i, '');
+            inputImageMimeType = params.inputImageMimeType;
+        }
+        return { inputImageData, inputImageMimeType, inputImagesData };
+    }
+    async maybeEnhancePrompt(provider, params, inputImageData) {
+        const configResult = getConfig();
+        if (!configResult.success) {
+            throw configResult.error;
+        }
+        const shouldSkipEnhancement = params.skipPromptEnhancement ?? configResult.data.skipPromptEnhancement;
+        if (provider !== 'gemini' || shouldSkipEnhancement || !this.structuredPromptGenerator) {
+            if (shouldSkipEnhancement) {
                 this.logger.info('mcp-server', 'Prompt enhancement skipped (SKIP_PROMPT_ENHANCEMENT=true)');
             }
-            // Generate image using Gemini API
-            if (!this.geminiClient) {
-                throw new Error('Gemini client not initialized');
-            }
-            const generationResult = await this.geminiClient.generateImage({
-                prompt: structuredPrompt,
-                ...(inputImagesData && { inputImages: inputImagesData }),
-                ...(!inputImagesData && inputImageData && { inputImage: inputImageData }),
-                ...(!inputImagesData && inputImageMimeType && { inputImageMimeType }),
-                ...(params.aspectRatio && { aspectRatio: params.aspectRatio }),
-                ...(params.imageSize && { imageSize: params.imageSize }),
-                ...(params.useGoogleSearch !== undefined && { useGoogleSearch: params.useGoogleSearch }),
-                ...(params.quality !== undefined && { quality: params.quality }),
+            return params.prompt;
+        }
+        const features = {};
+        if (params.maintainCharacterConsistency !== undefined) {
+            features.maintainCharacterConsistency = params.maintainCharacterConsistency;
+        }
+        if (params.blendImages !== undefined) {
+            features.blendImages = params.blendImages;
+        }
+        if (params.useWorldKnowledge !== undefined) {
+            features.useWorldKnowledge = params.useWorldKnowledge;
+        }
+        if (params.useGoogleSearch !== undefined) {
+            features.useGoogleSearch = params.useGoogleSearch;
+        }
+        const promptResult = await this.structuredPromptGenerator.generateStructuredPrompt(params.prompt, features, inputImageData, params.purpose);
+        if (!promptResult.success) {
+            this.logger.warn('mcp-server', 'Using original prompt', {
+                error: promptResult.error.message,
             });
-            if (!generationResult.success) {
-                throw generationResult.error;
+            return params.prompt;
+        }
+        this.logger.info('mcp-server', 'Structured prompt generated', {
+            originalLength: params.prompt.length,
+            structuredLength: promptResult.data.structuredPrompt.length,
+            selectedPractices: promptResult.data.selectedPractices,
+        });
+        return promptResult.data.structuredPrompt;
+    }
+    buildSuccessResponse(params, generationResult, savedPaths) {
+        if (params.returnBase64) {
+            return this.responseBuilder.buildBase64SuccessResponse(generationResult, savedPaths);
+        }
+        return savedPaths.length > 1
+            ? this.responseBuilder.buildMultiSuccessResponse(generationResult, savedPaths)
+            : this.responseBuilder.buildSuccessResponse(generationResult, savedPaths[0]);
+    }
+    getGeneratedVariants(generationResult) {
+        return generationResult.images?.length
+            ? generationResult.images
+            : [{ imageData: generationResult.imageData, mimeType: generationResult.metadata.mimeType }];
+    }
+    async generateAndSave(params) {
+        const validationResult = validateGenerateImageParams(params);
+        if (!validationResult.success) {
+            throw validationResult.error;
+        }
+        const normalizedParams = normalizeMultiImageParams(validationResult.data);
+        const normalizedPromptResult = validatePrompt(normalizedParams.prompt);
+        if (!normalizedPromptResult.success) {
+            throw normalizedPromptResult.error;
+        }
+        const configResult = getConfig();
+        if (!configResult.success) {
+            throw configResult.error;
+        }
+        const provider = resolveRequestedProvider(normalizedParams.provider, normalizedParams.prompt, configResult.data.imageProvider);
+        if (provider === 'gemini') {
+            await this.initializeGeminiSupport();
+        }
+        else {
+            await this.initializeVolcengineSupport();
+        }
+        const { inputImageData, inputImageMimeType, inputImagesData } = await this.prepareInputImages(normalizedParams);
+        const prompt = await this.maybeEnhancePrompt(provider, normalizedParams, inputImageData);
+        const client = this.getProviderClient(provider);
+        const generationResult = await client.generateImage({
+            ...normalizedParams,
+            provider,
+            prompt,
+            ...(inputImagesData && { inputImages: inputImagesData }),
+            ...(!inputImagesData && inputImageData && { inputImage: inputImageData }),
+            ...(!inputImagesData && inputImageMimeType && { inputImageMimeType }),
+        });
+        if (!generationResult.success) {
+            throw generationResult.error;
+        }
+        const saveTargets = generationResult.data.images?.length
+            ? generationResult.data.images
+            : [{ imageData: generationResult.data.imageData, mimeType: generationResult.data.metadata.mimeType }];
+        const savedPaths = [];
+        for (let index = 0; index < saveTargets.length; index++) {
+            const target = saveTargets[index];
+            if (!target) {
+                continue;
             }
-            // Save image file
-            let fileName = params.fileName || this.fileManager.generateFileName();
-            // Auto-append extension if user-provided fileName has no extension
-            if (params.fileName && !path.extname(fileName)) {
-                const mimeToExt = {
+            let currentFileName = normalizedParams.fileName || this.fileManager.generateFileName();
+            if (normalizedParams.fileName) {
+                const ext = path.extname(currentFileName);
+                const baseName = ext ? currentFileName.slice(0, -ext.length) : currentFileName;
+                const finalExt = ext || ({
                     'image/png': '.png',
                     'image/jpeg': '.jpg',
                     'image/webp': '.webp',
                     'image/gif': '.gif',
                     'image/bmp': '.bmp',
-                };
-                fileName += mimeToExt[generationResult.data.metadata.mimeType] || '.png';
+                }[target.mimeType] || '.png');
+                currentFileName = saveTargets.length > 1 ? `${baseName}-${index + 1}${finalExt}` : `${baseName}${finalExt}`;
             }
-            const outputPath = path.join(configResult.data.imageOutputDir, fileName);
+            else if (saveTargets.length > 1) {
+                const ext = path.extname(currentFileName);
+                const baseName = currentFileName.slice(0, -ext.length);
+                currentFileName = `${baseName}-${index + 1}${ext}`;
+            }
+            const outputPath = path.join(configResult.data.imageOutputDir, currentFileName);
             const sanitizedPath = this.securityManager.sanitizeFilePath(outputPath);
             if (!sanitizedPath.success) {
                 throw sanitizedPath.error;
             }
-            const saveResult = await this.fileManager.saveImage(generationResult.data.imageData, sanitizedPath.data);
+            const saveResult = await this.fileManager.saveImage(target.imageData, sanitizedPath.data);
             if (!saveResult.success) {
                 throw saveResult.error;
             }
-            // Build response
-            if (params.returnBase64) {
-                const base64Data = generationResult.data.imageData.toString('base64');
-                return this.responseBuilder.buildBase64SuccessResponse(generationResult.data, saveResult.data, base64Data);
+            savedPaths.push(saveResult.data);
+        }
+        return {
+            generationResult: generationResult.data,
+            savedPaths,
+            normalizedParams,
+        };
+    }
+    async handleGenerateMultiImage(params) {
+        const result = await ErrorHandler.wrapWithResultType(async () => {
+            const preparedParamsResult = prepareGenerateMultiImageParams(params);
+            if (!preparedParamsResult.success) {
+                throw preparedParamsResult.error;
+            }
+            const preparedParams = preparedParamsResult.data;
+            const explicitRequests = preparedParams.imageRequests?.length
+                ? { sharedPrompt: preparedParams.prompt, imageRequests: preparedParams.imageRequests }
+                : extractExplicitImageRequests(preparedParams.prompt);
+            if (!explicitRequests.imageRequests.length) {
+                const singleRun = await this.generateAndSave(preparedParams);
+                return this.buildSuccessResponse(singleRun.normalizedParams, singleRun.generationResult, singleRun.savedPaths);
+            }
+            const aggregatedPaths = [];
+            const aggregatedImages = [];
+            let firstGenerationResult;
+            for (let index = 0; index < explicitRequests.imageRequests.length; index++) {
+                const imageRequest = explicitRequests.imageRequests[index];
+                const singleParams = {
+                    ...preparedParams,
+                    prompt: buildIndependentImagePrompt(explicitRequests.sharedPrompt, imageRequest),
+                    skipPromptEnhancement: true,
+                };
+                delete singleParams.outputCount;
+                delete singleParams.imageRequests;
+                if (preparedParams.fileName !== undefined) {
+                    singleParams.fileName = `${preparedParams.fileName.replace(/(\.[^.]+)?$/, '')}-${index + 1}`;
+                }
+                else {
+                    delete singleParams.fileName;
+                }
+                const singleRun = await this.generateAndSave(singleParams);
+                firstGenerationResult ?? (firstGenerationResult = singleRun.generationResult);
+                aggregatedPaths.push(...singleRun.savedPaths);
+                aggregatedImages.push(...this.getGeneratedVariants(singleRun.generationResult));
             }
-            return this.responseBuilder.buildSuccessResponse(generationResult.data, saveResult.data);
+            const combinedResult = {
+                imageData: aggregatedImages[0].imageData,
+                images: aggregatedImages,
+                metadata: {
+                    ...(firstGenerationResult?.metadata ?? {
+                        provider: 'gemini',
+                        model: 'unknown',
+                        prompt: preparedParams.prompt,
+                        mimeType: aggregatedImages[0]?.mimeType ?? 'image/png',
+                        timestamp: new Date(),
+                        inputImageProvided: false,
+                    }),
+                    prompt: preparedParams.prompt,
+                    timestamp: new Date(),
+                    mimeType: aggregatedImages[0]?.mimeType ?? firstGenerationResult?.metadata.mimeType ?? 'image/png',
+                },
+            };
+            return this.buildSuccessResponse(preparedParams, combinedResult, aggregatedPaths);
+        }, 'image-generation');
+        if (result.ok) {
+            return result.value;
+        }
+        return this.responseBuilder.buildErrorResponse(result.error);
+    }
+    async handleGenerateImage(params) {
+        const result = await ErrorHandler.wrapWithResultType(async () => {
+            const execution = await this.generateAndSave(params);
+            return this.buildSuccessResponse(execution.normalizedParams, execution.generationResult, execution.savedPaths);
         }, 'image-generation');
         if (result.ok) {
             return result.value;
         }
         return this.responseBuilder.buildErrorResponse(result.error);
     }
-    /**
-     * Initialize MCP server with tool handlers
-     */
     initialize() {
         this.server = new Server({
             name: this.config.name,
@@ -396,22 +547,16 @@ export class MCPServerImpl {
                 tools: {},
             },
         });
-        // Setup tool handlers
         this.setupHandlers();
         return this.server;
     }
-    /**
-     * Setup MCP protocol handlers
-     */
     setupHandlers() {
         if (!this.server) {
             throw new Error('Server not initialized');
         }
-        // Register tool list handler
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
             return this.getToolsList();
         });
-        // Register tool call handler
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
             const result = await this.callTool(name, args);
@@ -425,9 +570,6 @@ export class MCPServerImpl {
         });
     }
 }
-/**
- * Factory function to create MCP server
- */
 export function createMCPServer(config = {}) {
     return new MCPServerImpl(config);
 }