EverArt Forge MCP Server

Instructions

Implementation Reference

• src/index.ts:365-418 (registration)

  Registration of the 'generate_image' tool in the ListToolsRequestSchema handler, including name, description, and detailed inputSchema for parameters like prompt, model, format, paths, etc.

  {
    name: "generate_image",
    description:
      "Generate images using EverArt Models, optimized for web development. " +
      "Supports web project paths, responsive formats, and inline preview. " +
      "Available models:\n" +
      "- 5000:FLUX1.1: Standard quality\n" +
      "- 9000:FLUX1.1-ultra: Ultra high quality\n" +
      "- 6000:SD3.5: Stable Diffusion 3.5\n" +
      "- 7000:Recraft-Real: Photorealistic style\n" +
      "- 8000:Recraft-Vector: Vector art style (SVG format)",
    inputSchema: {
      type: "object",
      properties: {
        prompt: {
          type: "string",
          description: "Text description of desired image",
        },
        model: {
          type: "string",
          description:
            "Model ID (5000:FLUX1.1, 9000:FLUX1.1-ultra, 6000:SD3.5, 7000:Recraft-Real, 8000:Recraft-Vector)",
          default: "5000",
        },
        format: {
          type: "string",
          description: "Output format (svg, png, jpg, webp). Note: Vector format (svg) is only available with Recraft-Vector (8000) model.",
          default: "svg"
        },
        output_path: {
          type: "string",
          description: "Optional: Custom output path for the generated image. If not provided, image will be saved in the default storage directory.",
        },
        web_project_path: {
          type: "string",
          description: "Path to web project root folder for storing images in appropriate asset directories.",
        },
        project_type: {
          type: "string",
          description: "Web project type to determine appropriate asset directory structure (e.g., 'react', 'vue', 'html', 'next').",
        },
        asset_path: {
          type: "string",
          description: "Optional subdirectory within the web project's asset structure for storing generated images.",
        },
        image_count: {
          type: "number",
          description: "Number of images to generate",
          default: 1,
        },
      },
      required: ["prompt"],
    },
  },

• src/index.ts:522-734 (handler)

  Main handler logic for 'generate_image': validates inputs, creates generation via EverArt client API, polls for completion, saves image using saveImage helper, opens in viewer, and returns formatted success response with inline details.

  case "generate_image": {
    try {
      const args = request.params.arguments as any;
      
      // Validate required parameters
      if (!args.prompt || typeof args.prompt !== 'string' || args.prompt.trim() === '') {
        return errorResponse({
          type: EverArtErrorType.VALIDATION_ERROR,
          message: "Prompt is required and must be a non-empty string."
        });
      }
      
      const prompt = args.prompt;
      // Use 'let' instead of 'const' for model since we might need to modify it
      let modelInput = args.model || "5000";
      const image_count = args.image_count || 1;
      const output_path = args.output_path;
      const web_project_path = args.web_project_path;
      const project_type = args.project_type;
      const asset_path = args.asset_path;
      
      // Enhanced validation
      if (image_count < 1 || image_count > 10) {
        return errorResponse({
          type: EverArtErrorType.VALIDATION_ERROR,
          message: "image_count must be between 1 and 10"
        });
      }
      
      // Validate model - extract the numeric ID if a combined format was provided
      const validModels = ["5000", "6000", "7000", "8000", "9000"];
      
      // Handle model IDs in the format "8000:Recraft-Vector"
      if (modelInput.includes(":")) {
        const originalModel = modelInput;
        modelInput = modelInput.split(":")[0];
        console.log(`Received combined model ID format: ${originalModel}, using base ID: ${modelInput}`);
      }
      
      if (!validModels.includes(modelInput)) {
        return errorResponse({
          type: EverArtErrorType.VALIDATION_ERROR,
          message: `Invalid model ID: ${modelInput}. Valid models are: ${validModels.join(", ")}`
        });
      }
      
      // Now we have the validated model ID
      const format = args.format || (modelInput === "8000" ? "svg" : "png");
      
      // Validate format
      const supportedFormats = ["svg", "png", "jpg", "jpeg", "webp"];
      if (!supportedFormats.includes(format.toLowerCase())) {
        return errorResponse({
          type: EverArtErrorType.VALIDATION_ERROR,
          message: `Unsupported format: ${format}. Supported formats are: ${supportedFormats.join(", ")}`
        });
      }
      
      // Validate model/format compatibility
      if (!validateModelFormatCompatibility(modelInput, format)) {
        return errorResponse({
          type: EverArtErrorType.VALIDATION_ERROR,
          message: `Format '${format}' is not compatible with model '${modelInput}'. SVG format is only available with Recraft-Vector (8000) model.`
        });
      }
      
      // Generate image with retry logic
      let generation;
      let retryCount = 0;
      
      while (retryCount < MAX_RETRIES) {
        try {
          generation = await client.v1.generations.create(
            modelInput,
            prompt,
            "txt2img",
            {
              imageCount: image_count,
              height: 1024,
              width: 1024,
              // Add extra fields for specific models if needed
              ...(modelInput === "8000" ? { variant: "vector" } : {}),
            },
          );
          break;
        } catch (error) {
          if (retryCount >= MAX_RETRIES - 1) throw error;
          
          // Exponential backoff
          const delay = INITIAL_RETRY_DELAY * Math.pow(2, retryCount);
          await new Promise(r => setTimeout(r, delay));
          retryCount++;
        }
      }
      
      if (!generation) {
        throw new Error("Failed to create generation after multiple attempts");
      }
  
      // Enhanced polling with better timeout handling
      const completedGen = await client.v1.generations.fetchWithPolling(
        generation[0].id,
        { 
          maxAttempts: 30,  // Increased from default
          interval: 3000    // Check every 3 seconds
        }
      );
  
      const imgUrl = completedGen.image_url;
      if (!imgUrl) {
        throw new Error("No image URL in the completed generation");
      }
  
      // Save image locally with specified format and path
      const filepath = await saveImage(
        imgUrl, 
        prompt, 
        modelInput, 
        format, 
        output_path, 
        web_project_path, 
        project_type, 
        asset_path
      );
  
      // Open in default viewer
      try {
        await open(filepath);
      } catch (openError) {
        console.warn("Could not open the image in default viewer:", openError);
        // Continue without throwing - this is a non-critical error
      }
  
      // Model name mapping for user-friendly display
      const modelNames: Record<string, string> = {
        "5000": "FLUX1.1 (Standard quality)",
        "9000": "FLUX1.1-ultra (Ultra high quality)",
        "6000": "Stable Diffusion 3.5",
        "7000": "Recraft-Real (Photorealistic)",
        "8000": "Recraft-Vector (Vector art)"
      };
  
      // Read the image file for inline display
      let imageData: string | undefined;
      try {
        const imageContent = await fs.readFile(filepath);
        imageData = imageContent.toString('base64');
      } catch (error) {
        console.warn("Unable to read image for inline display:", error);
        // Continue without inline display if reading fails
      }
  
      // Calculate relative web path if applicable
      let webRelativePath: string | undefined;
      if (web_project_path && filepath.startsWith(web_project_path)) {
        webRelativePath = filepath.slice(web_project_path.length);
        if (!webRelativePath.startsWith('/')) webRelativePath = '/' + webRelativePath;
      }
  
      return {
        content: [
          {
            type: "text", 
            text: `✅ Image generated and saved successfully!\n\n` +
                 `Generation details:\n` +
                 `• Model: ${modelNames[modelInput] || modelInput}\n` +
                 `• Prompt: "${prompt}"\n` +
                 `• Format: ${format.toUpperCase()}\n` +
                 `• Saved to: ${filepath}` +
                 (webRelativePath ? `\n• Web relative path: ${webRelativePath}` : ``)
          },
          {
            type: "text",
            text: `View the image at: file://${filepath}`
          }
        ],
      };
    } catch (error: unknown) {
      console.error("Detailed error:", error);
      
      // Categorize errors for better user feedback
      if (error instanceof Error) {
        if (error.message.includes("SVG format")) {
          return errorResponse({
            type: EverArtErrorType.FORMAT_ERROR,
            message: error.message
          });
        } else if (error.message.includes("Failed to fetch image")) {
          return errorResponse({
            type: EverArtErrorType.NETWORK_ERROR,
            message: "Failed to download the generated image. Please check your internet connection and try again."
          });
        } else if (error.message.includes("rate limit")) {
          return errorResponse({
            type: EverArtErrorType.API_ERROR,
            message: "EverArt API rate limit reached. Please try again later."
          });
        } else if (error.message.includes("unauthorized") || error.message.includes("authentication")) {
          return errorResponse({
            type: EverArtErrorType.AUTHENTICATION_ERROR,
            message: "API authentication failed. Please check your EverArt API key."
          });
        }
      }
      
      // Generic error handling
      const errorMessage = error instanceof Error ? error.message : "Unknown error";
      return errorResponse({
        type: EverArtErrorType.UNKNOWN_ERROR,
        message: errorMessage
      });
    }
  }

• src/index.ts:181-307 (helper)

  Key helper function saveImage: fetches image from URL, handles format-specific processing (SVG optimization, raster conversion with sharp), supports web project paths, retries on fetch errors, and saves to filesystem.

  async function saveImage(imageUrl: string, prompt: string, model: string, format: string = "svg", outputPath?: string, webProjectPath?: string, projectType?: string, assetPath?: string): Promise<string> {
    // Validate format
    format = format.toLowerCase();
    const supportedFormats = ['svg', 'png', 'jpg', 'jpeg', 'webp'];
    if (!supportedFormats.includes(format)) {
      throw new Error(`Unsupported format: ${format}. Supported formats are: ${supportedFormats.join(', ')}`);
    }
    
    // Validate model/format compatibility
    if (!validateModelFormatCompatibility(model, format)) {
      throw new Error(`Format '${format}' is not compatible with model '${model}'. SVG format is only available with Recraft-Vector (8000) model.`);
    }
    
    let filepath: string;
    
    try {
      // Handle web project paths if specified
      let projectBasePath: string | undefined;
      if (webProjectPath) {
        projectBasePath = await processWebProjectPath(webProjectPath, projectType, assetPath);
      }
      
      // Generate a standardized file name for web assets
      const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
      const sanitizedPrompt = prompt.slice(0, 20).replace(/[^a-zA-Z0-9]/g, "_").toLowerCase();
      const filename = `${sanitizedPrompt}_${model}.${format}`;
      
      if (outputPath) {
        // If outputPath is provided, ensure it has the correct extension
        const ext = path.extname(outputPath);
        if (!ext) {
          // If no extension provided, append the format
          filepath = `${outputPath}.${format}`;
        } else if (ext.slice(1).toLowerCase() !== format.toLowerCase()) {
          // If extension doesn't match format, warn but use the specified format
          console.warn(`Warning: File extension ${ext} doesn't match specified format ${format}`);
          filepath = outputPath.slice(0, -ext.length) + `.${format}`;
        } else {
          filepath = outputPath;
        }
        
        // Ensure the directory exists
        await fs.mkdir(path.dirname(filepath), { recursive: true });
      } else if (projectBasePath) {
        // Web project path takes precedence over default
        filepath = path.join(projectBasePath, filename);
      } else {
        // Default behavior: save to STORAGE_DIR with timestamp
        filepath = path.join(STORAGE_DIR, `${timestamp}_${model}_${sanitizedPrompt}.${format}`);
      }
  
      // Fetch the image with retries
      let response;
      let retryCount = 0;
      
      while (retryCount < MAX_RETRIES) {
        try {
          // @ts-ignore - node-fetch doesn't support timeout in RequestInit, but this works at runtime
          response = await fetch(imageUrl, { timeout: 30000 });
          if (response.ok) break;
          
          // If we got a 429 (rate limit), wait longer before retrying
          if (response.status === 429) {
            const retryAfter = parseInt(response.headers.get('retry-after') || '5', 10);
            await new Promise(r => setTimeout(r, retryAfter * 1000));
          } else {
            throw new Error(`Failed to fetch image: ${response.statusText} (${response.status})`);
          }
        } catch (error) {
          if (retryCount >= MAX_RETRIES - 1) throw error;
          
          // Exponential backoff
          const delay = INITIAL_RETRY_DELAY * Math.pow(2, retryCount);
          await new Promise(r => setTimeout(r, delay));
        }
        
        retryCount++;
      }
      
      if (!response || !response.ok) {
        throw new Error(`Failed to fetch image after ${MAX_RETRIES} attempts`);
      }
  
      const buffer = await response.arrayBuffer();
      const content = Buffer.from(buffer);
  
      if (format === "svg") {
        // For SVG, optimize and save
        const svgString = content.toString('utf-8');
        const result = optimize(svgString, {
          multipass: true,
          plugins: [
            'preset-default',
            'removeDimensions',
            'removeViewBox',
            'cleanupIds',
          ],
        });
        await fs.writeFile(filepath, result.data);
      } else {
        // For raster formats, convert using sharp with better error handling
        try {
          const image = sharp(content);
          switch (format.toLowerCase()) {
            case "png":
              await image.png({ quality: 90 }).toFile(filepath);
              break;
            case "jpg":
            case "jpeg":
              await image.jpeg({ quality: 90 }).toFile(filepath);
              break;
            case "webp":
              await image.webp({ quality: 90 }).toFile(filepath);
              break;
            default:
              throw new Error(`Unsupported format: ${format}`);
          }
        } catch (error) {
          throw new Error(`Image processing failed: ${(error as Error).message}`);
        }
      }
  
      return filepath;
    } catch (error) {
      throw new Error(`Failed to save image: ${(error as Error).message}`);
    }
  }

• src/index.ts:131-137 (helper)

  Helper function to validate model-format compatibility, specifically restricting SVG to Recraft-Vector model (8000).

  function validateModelFormatCompatibility(model: string, format: string): boolean {
    // SVG is only supported by Recraft-Vector (8000)
    if (format.toLowerCase() === 'svg' && model !== '8000') {
      return false;
    }
    return true;
  }

• src/index.ts:377-416 (schema)

  Input schema definition for generate_image tool, specifying properties, descriptions, defaults, and required fields.

  type: "object",
  properties: {
    prompt: {
      type: "string",
      description: "Text description of desired image",
    },
    model: {
      type: "string",
      description:
        "Model ID (5000:FLUX1.1, 9000:FLUX1.1-ultra, 6000:SD3.5, 7000:Recraft-Real, 8000:Recraft-Vector)",
      default: "5000",
    },
    format: {
      type: "string",
      description: "Output format (svg, png, jpg, webp). Note: Vector format (svg) is only available with Recraft-Vector (8000) model.",
      default: "svg"
    },
    output_path: {
      type: "string",
      description: "Optional: Custom output path for the generated image. If not provided, image will be saved in the default storage directory.",
    },
    web_project_path: {
      type: "string",
      description: "Path to web project root folder for storing images in appropriate asset directories.",
    },
    project_type: {
      type: "string",
      description: "Web project type to determine appropriate asset directory structure (e.g., 'react', 'vue', 'html', 'next').",
    },
    asset_path: {
      type: "string",
      description: "Optional subdirectory within the web project's asset structure for storing generated images.",
    },
    image_count: {
      type: "number",
      description: "Number of images to generate",
      default: 1,
    },
  },
  required: ["prompt"],