GPT Image 1 MCP

Implementation Reference

• src/index.ts:174-361 (handler)

  The async handler function that implements the 'create_image' tool logic: calls OpenAI's images.generate API with gpt-image-1 model, processes the base64 response, saves images to disk using saveImageToDisk, handles detailed errors, and returns a rich formatted response with text summary and image contents.

    async (args: CreateImageArgs, extra: any) => {
      try {
        // Use the OpenAI SDK's createImage method with detailed error handling
        let apiResponse;
        try {
          apiResponse = await openai.images.generate({
            model: "gpt-image-1",
            prompt: args.prompt,
            size: args.size || "1024x1024",
            quality: args.quality || "high",
            n: args.n || 1
          });
  
          // Check if the response contains an error field (shouldn't happen with SDK but just in case)
          if (apiResponse && 'error' in apiResponse) {
            const error = (apiResponse as any).error;
            throw {
              message: error.message || 'Unknown API error',
              type: error.type || 'api_error',
              code: error.code || 'unknown',
              response: { data: { error } }
            };
          }
        } catch (apiError: any) {
          // Enhance the error with more details if possible
          console.error("OpenAI API Error:", apiError);
  
          // Rethrow with enhanced information
          throw apiError;
        }
  
        // Create a Response-like object with a json() method for compatibility with the built-in tool
        const response = {
          json: () => Promise.resolve(apiResponse)
        };
  
        const responseData = apiResponse;
        const format = args.output_format || "png";
  
        // Save images to disk and create response with file paths
        const savedImages = [];
        const imageContents = [];
  
        if (responseData.data && responseData.data.length > 0) {
          for (const item of responseData.data) {
            if (item.b64_json) {
              // Save the image to disk
              const imagePath = saveImageToDisk(item.b64_json, format);
  
              // Add the saved image info to our response
              savedImages.push({
                path: imagePath,
                format: format
              });
  
              // Also include the image content for compatibility
              imageContents.push({
                type: "image" as const,
                data: item.b64_json,
                mimeType: `image/${format}`
              });
            } else if (item.url) {
              console.error(`Image URL: ${item.url}`);
              console.error("The gpt-image-1 model returned a URL instead of base64 data.");
              console.error("To view the image, open the URL in your browser.");
  
              // Add the URL info to our response
              savedImages.push({
                url: item.url,
                format: format
              });
  
              // Include a text message about the URL in the content
              imageContents.push({
                type: "text" as const,
                text: `Image available at URL: ${item.url}`
              });
            }
          }
        }
  
        // Create a beautifully formatted response with emojis and details
        const formatSize = (size: string | undefined) => size || "1024x1024";
        const formatQuality = (quality: string | undefined) => quality || "high";
  
        // Create a beautiful formatted message
        const formattedMessage = `
  🎨 **Image Generation Complete!** 🎨
  
  ✨ **Prompt**: "${args.prompt}"
  
  📊 **Generation Parameters**:
     • Size: ${formatSize(args.size)}
     • Quality: ${formatQuality(args.quality)}
     • Number of Images: ${args.n || 1}
     ${args.background ? `• Background: ${args.background}` : ''}
     ${args.output_format ? `• Format: ${args.output_format}` : ''}
     ${args.output_compression ? `• Compression: ${args.output_compression}%` : ''}
     ${args.moderation ? `• Moderation: ${args.moderation}` : ''}
  
  📁 **Generated ${savedImages.length} Image${savedImages.length > 1 ? 's' : ''}**:
  ${savedImages.map((img, index) => `   ${index + 1}. ${img.path || img.url}`).join('\n')}
  
  ${responseData.usage ? `⚡ **Token Usage**:
     • Total Tokens: ${responseData.usage.total_tokens}
     • Input Tokens: ${responseData.usage.input_tokens}
     • Output Tokens: ${responseData.usage.output_tokens}` : ''}
  
  🔍 You can find your image${savedImages.length > 1 ? 's' : ''} at the path${savedImages.length > 1 ? 's' : ''} above!
  `;
  
        // Return both the image content and the saved file paths with the beautiful message
        return {
          content: [
            {
              type: "text" as const,
              text: formattedMessage
            },
            ...imageContents
          ],
          ...(responseData.usage && {
            _meta: {
              usage: responseData.usage,
              savedImages: savedImages
            }
          })
        };
      } catch (error: any) {
        // Log the full error for debugging
        console.error("Error generating image:", error);
  
        // Extract detailed error information
        const errorCode = error.status || error.code || 'Unknown';
        const errorType = error.type || 'Error';
        const errorMessage = error.message || 'An unknown error occurred';
  
        // Check for specific OpenAI API errors
        let detailedError = '';
  
        if (error.response) {
          // If we have a response object from OpenAI, extract more details
          try {
            const responseData = error.response.data || {};
            if (responseData.error) {
              detailedError = `\n📋 **Details**: ${responseData.error.message || 'No additional details available'}`;
  
              // Add parameter errors if available
              if (responseData.error.param) {
                detailedError += `\n🔍 **Parameter**: ${responseData.error.param}`;
              }
  
              // Add code if available
              if (responseData.error.code) {
                detailedError += `\n🔢 **Error Code**: ${responseData.error.code}`;
              }
  
              // Add type if available
              if (responseData.error.type) {
                detailedError += `\n📝 **Error Type**: ${responseData.error.type}`;
              }
            }
          } catch (parseError) {
            // If we can't parse the response, just use what we have
            detailedError = '\n📋 **Details**: Could not parse error details from API response';
          }
        }
  
        // Construct a comprehensive error message
        const fullErrorMessage = `❌ **Image Generation Failed**\n\n⚠️ **Error ${errorCode}**: ${errorType} - ${errorMessage}${detailedError}\n\n🔄 Please try again with a different prompt or parameters.`;
  
        // Return the detailed error to the client
        return {
          content: [{
            type: "text",
            text: fullErrorMessage
          }],
          isError: true,
          _meta: {
            error: {
              code: errorCode,
              type: errorType,
              message: errorMessage,
              raw: JSON.stringify(error, Object.getOwnPropertyNames(error))
            }
          }
        };
      }
    }

• src/index.ts:155-166 (schema)

  Zod schema defining the input parameters for the create_image tool, including prompt, size, quality, etc., with validation rules.

  const createImageSchema = z.object({
    prompt: z.string().max(32000, "Prompt exceeds maximum length for gpt-image-1."),
    background: z.enum(["transparent", "opaque", "auto"]).optional(),
    n: z.number().int().min(1).max(10).optional(),
    output_compression: z.number().int().min(0).max(100).optional(),
    output_format: z.enum(["png", "jpeg", "webp"]).optional(),
    quality: z.enum(["high", "medium", "low", "auto"]).optional(),
    size: z.enum(["1024x1024", "1536x1024", "1024x1536", "auto"]).optional(),
    user: z.string().optional(),
    moderation: z.enum(["low", "auto"]).optional()
  });
  type CreateImageArgs = z.infer<typeof createImageSchema>;

• src/index.ts:168-173 (registration)

  Registers the 'create_image' tool with the MCP server using server.tool(), specifying the name, input schema, metadata title, and handler function.

  server.tool(
    "create_image",
    createImageSchema.shape,
    {
      title: "Generate new images using OpenAI's gpt-image-1 model"
    },

• src/index.ts:87-110 (helper)

  Helper utility to save base64-encoded image data to a file in the configured output directory, used by the create_image handler to persist generated images.

  function saveImageToDisk(base64Data: string, format: string = 'png'): string {
    // Create a dedicated folder for generated images if we're using the workspace root
    // This keeps the workspace organized while still saving in the current directory
    const imagesFolder = path.join(outputDir, 'gpt-images');
  
    // Create the images folder if it doesn't exist
    if (!fs.existsSync(imagesFolder)) {
      fs.mkdirSync(imagesFolder, { recursive: true });
      console.error(`Created images folder: ${imagesFolder}`);
    }
  
    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
    const filename = `image-${timestamp}.${format}`;
    const outputPath = path.join(imagesFolder, filename);
  
    // Remove the data URL prefix if present
    const base64Image = base64Data.replace(/^data:image\/\w+;base64,/, '');
  
    // Write the image to disk
    fs.writeFileSync(outputPath, Buffer.from(base64Image, 'base64'));
    console.error(`Image saved to: ${outputPath}`);
  
    return outputPath;
  }