MCPollinations Multimodal MCP Server

Instructions

Implementation Reference

• src/services/imageService.js:377-514 (handler)

  The core handler function that takes a prompt and reference image URL(s), constructs a Pollinations API URL for image-to-image generation, fetches the image, encodes it as base64, saves it to a file in outputPath, and returns the image data with metadata.

  export async function generateImageFromReference(prompt, imageUrl, model = 'kontext', seed = Math.floor(Math.random() * 1000000), width = 1024, height = 1024, enhance = true, safe = false, outputPath = './mcpollinations-output', fileName = '', format = 'png', authConfig = null) {
    if (!prompt || typeof prompt !== 'string') {
      throw new Error('Prompt is required and must be a string');
    }
  
    if (!imageUrl || (typeof imageUrl !== 'string' && !Array.isArray(imageUrl))) {
      throw new Error('Reference image URL(s) are required and must be a string or array of strings');
    }
  
    const imageList = Array.isArray(imageUrl)
      ? imageUrl.filter(Boolean)
      : (typeof imageUrl === 'string' && imageUrl.includes(','))
        ? imageUrl.split(',').map(s => s.trim()).filter(Boolean)
        : [imageUrl];
  
    // Build the query parameters
    const queryParams = new URLSearchParams();
    queryParams.append('model', model);
    for (const u of imageList) {
      queryParams.append('image', u);
    }
    if (seed !== undefined) queryParams.append('seed', seed);
    if (width !== 1024) queryParams.append('width', width);
    if (height !== 1024) queryParams.append('height', height);
  
    // Add enhance parameter if true
    if (enhance) queryParams.append('enhance', 'true');
  
    // Add parameters
    queryParams.append('nologo', 'true'); // Always set nologo to true
    queryParams.append('private', 'true'); // Always set private to true)
    queryParams.append('safe', safe.toString()); // Use the customizable safe parameter
  
    // Construct the URL
    const encodedPrompt = encodeURIComponent(prompt);
    const baseUrl = 'https://image.pollinations.ai';
    let url = `${baseUrl}/prompt/${encodedPrompt}`;
  
    // Add query parameters
    const queryString = queryParams.toString();
    url += `?${queryString}`;
  
    try {
      // Prepare fetch options with optional auth headers
      const fetchOptions = {};
      if (authConfig) {
        fetchOptions.headers = {};
        if (authConfig.token) {
          fetchOptions.headers['Authorization'] = `Bearer ${authConfig.token}`;
        }
        if (authConfig.referrer) {
          fetchOptions.headers['Referer'] = authConfig.referrer;
        }
      }
  
      // Fetch the image from the URL
      const response = await fetch(url, fetchOptions);
  
      if (!response.ok) {
        throw new Error(`Failed to generate image from reference: ${response.statusText}`);
      }
  
      // Get the image data as an ArrayBuffer
      const imageBuffer = await response.arrayBuffer();
  
      // Convert the ArrayBuffer to a base64 string
      const base64Data = Buffer.from(imageBuffer).toString('base64');
  
      // Determine the mime type from the response headers or default to image/jpeg
      const contentType = response.headers.get('content-type') || 'image/jpeg';
  
      // Prepare the result object
      const result = {
        data: base64Data,
        mimeType: contentType,
        metadata: {
          prompt,
          referenceImageUrl: imageUrl,
          width,
          height,
          model,
          seed,
          enhance,
          private: true,
          nologo: true,
          safe
        }
      };
  
      // Always save the image to a file
      // Import required modules
      const fs = await import('fs');
      const path = await import('path');
  
      // Create the output directory if it doesn't exist
      if (!fs.existsSync(outputPath)) {
        fs.mkdirSync(outputPath, { recursive: true });
      }
  
      // Generate a filename if not provided
      let finalFileName = fileName;
      if (!finalFileName) {
        // Create a filename from the prompt (first 20 characters) and timestamp
        const sanitizedPrompt = prompt.replace(/[^a-zA-Z0-9]/g, '_').substring(0, 20);
        const timestamp = Date.now();
        const randomSuffix = Math.floor(Math.random() * 1000);
        finalFileName = `reference_${sanitizedPrompt}_${timestamp}_${randomSuffix}`;
      }
  
      // Ensure the filename has the correct extension
      const extension = format.toLowerCase();
      if (!finalFileName.endsWith(`.${extension}`)) {
        finalFileName += `.${extension}`;
      }
  
      // Check if file already exists and add a number suffix if needed
      let finalFilePath = path.join(outputPath, finalFileName);
      let counter = 1;
      while (fs.existsSync(finalFilePath)) {
        const nameWithoutExt = finalFileName.replace(`.${extension}`, '');
        const numberedFileName = `${nameWithoutExt}_${counter}.${extension}`;
        finalFilePath = path.join(outputPath, numberedFileName);
        counter++;
      }
  
      // Write the image data to the file
      fs.writeFileSync(finalFilePath, Buffer.from(base64Data, 'base64'));
  
      // Add the file path to the result
      result.filePath = finalFilePath;
  
      return result;
  
    } catch (error) {
      log('Error generating image from reference:', error);
      throw error;
    }
  }

• src/services/imageSchema.js:177-233 (schema)

  JSON schema defining the input parameters and validation for the generateImageFromReference tool.

  export const generateImageFromReferenceSchema = {
    name: 'generateImageFromReference',
    description: 'Generate a new image using an existing image as reference. User-configured settings in MCP config will be used as defaults unless specifically overridden.',
    inputSchema: {
      type: 'object',
      properties: {
        prompt: {
          type: 'string',
          description: 'The text description of what to generate based on the reference image (e.g., "create a cartoon version", "make it look like a painting")'
        },
        imageUrl: {
          oneOf: [
            { type: 'string' },
            { type: 'array', items: { type: 'string' } }
          ],
          description: 'Public HTTP(S) URL(s) of reference images. Accepts a string or an array for multi-reference. Local file paths, file uploads, or base64/data URLs are not supported.'
        },
        model: {
          type: 'string',
          description: 'Model name to use for generation (default: user config or "kontext"). Available: "kontext", "nanobanana", "seedream"'
        },
        seed: {
          type: 'number',
          description: 'Seed for reproducible results (default: random)'
        },
        width: {
          type: 'number',
          description: 'Width of the generated image (default: 1024)'
        },
        height: {
          type: 'number',
          description: 'Height of the generated image (default: 1024)'
        },
        enhance: {
          type: 'boolean',
          description: 'Whether to enhance the prompt using an LLM before generating (default: true)'
        },
        safe: {
          type: 'boolean',
          description: 'Whether to apply content filtering (default: false)'
        },
        outputPath: {
          type: 'string',
          description: 'Directory path where to save the image (default: user config or "./mcpollinations-output")'
        },
        fileName: {
          type: 'string',
          description: 'Name of the file to save (without extension, default: generated from prompt)'
        },
        format: {
          type: 'string',
          description: 'Image format to save as (png, jpeg, jpg, webp - default: png)'
        }
      },
      required: ['prompt', 'imageUrl']
    }
  };

• pollinations-mcp-server.js:400-436 (registration)

  MCP server tool call dispatcher that handles calls to 'generateImageFromReference', extracts arguments with defaults, invokes the handler function, and formats the response as MCP content with image and text describing the result and file path.

  } else if (name === 'generateImageFromReference') {
    try {
      const { prompt, imageUrl, model = 'kontext', seed, width = defaultConfig.image.width, height = defaultConfig.image.height, enhance = defaultConfig.image.enhance, safe = defaultConfig.image.safe, outputPath = defaultConfig.resources.output_dir, fileName = '', format = 'png' } = args;
      const result = await generateImageFromReference(prompt, imageUrl, model, seed, width, height, enhance, safe, outputPath, fileName, format, finalAuthConfig);
  
      // Prepare the response content
      const content = [
        {
          type: 'image',
          data: result.data,
          mimeType: result.mimeType
        }
      ];
  
      // Prepare the response text
      let responseText = `Generated image from reference: "${prompt}"\nReference image: ${imageUrl}\n\nImage metadata: ${JSON.stringify(result.metadata, null, 2)}`;
  
      // Add file path information if the image was saved to a file
      if (result.filePath) {
        responseText += `\n\nImage saved to: ${result.filePath}`;
      }
  
      content.push({
        type: 'text',
        text: responseText
      });
  
      return { content };
    } catch (error) {
      return {
        content: [
          { type: 'text', text: `Error generating image from reference: ${error.message}` }
        ],
        isError: true
      };
    }