JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 95
  • Score
    100M100P100Q55079F
  • License SEE LICENSE IN LICENSE

MCP server for AI image generation from markdown and HTML with multi-provider support

Package Exports

  • @michelabboud/visual-forge-mcp
  • @michelabboud/visual-forge-mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@michelabboud/visual-forge-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Visual Forge MCP ๐ŸŽจ

AI-powered image generation for technical documentation with multi-provider support

Visual Forge MCP Hero Banner

An MCP (Model Context Protocol) server that automates AI image generation for technical documentation. Parse markdown files containing image prompts and generate professional images using multiple AI providers.

npm version Version License Node.js


๐ŸŒŸ Features

  • ๐Ÿ“ Multi-Format Support: Extract image specifications from Markdown (.md) and HTML (.html) files
  • ๐Ÿ”Œ Multi-Provider Support: 7 AI providers with automatic fallback
    • OpenAI GPT Image
    • Google Gemini 2.5 Flash Image (Nano Banana)
    • Stability AI SDXL
    • Replicate FLUX Schnell
    • Leonardo Phoenix
    • HuggingFace Inference
    • xAI Grok 2 Image
  • ๐ŸŽจ Detailed Global Context โœจ NEW: Comprehensive styling system with hex colors, typography, layout rules, and audience targeting for dramatically better, more consistent images
  • ๐Ÿ’ฐ Cost-Effective: Options from $0.00 to $0.12/image
  • โšก Flexible Workflows: Interactive, Batch, and Bulk generation modes
  • ๐Ÿ”„ State Persistence: Resume interrupted sessions without losing progress
  • ๐Ÿ“Š Cost Tracking: Real-time cost monitoring and estimates per provider
  • ๐ŸŽฏ Smart Rate Limiting: Token bucket algorithm prevents API bans
  • โœจ Quality Inspection: Automated quality analysis with sharpness and brightness metrics
  • ๐Ÿ”’ Automatic Backups: File backup system with approve/restore workflow (optional, enabled by default)
  • ๐ŸŒ Universal MCP Support: Compatible with 24+ MCP clients (tested with Claude Code, Claude Desktop, Zed)

๐Ÿ“ฆ Installation

Prerequisites

  • Node.js 24+ (recommended for optimal performance)
  • At least one AI provider API key (see Provider Setup)

Option 1: Install from NPM

npm install -g @michelabboud/visual-forge-mcp

Option 2: Install from Source (Current)

# Clone the repository
git clone https://github.com/michelabboud/visual-forge-mcp.git
cd visual-forge-mcp

# Install dependencies
npm install

# Build the project
npm run build

# (Optional) Link globally for CLI usage
npm link

โš™๏ธ Configuration

1. Provider Setup

Create a .env file in the project root with at least one provider API key:

# === AI PROVIDER API KEYS ===
# Choose at least one provider below

# Google Gemini 2.5 Flash Image ($0.039/image)
GOOGLE_API_KEY=AIza...

# Replicate FLUX Schnell ($0.003/image) - Most cost-effective
REPLICATE_API_TOKEN=r8_...

# Stability AI SDXL ($0.04/image)
STABILITY_API_KEY=sk-...

# OpenAI GPT Image ($0.04-0.12/image)
OPENAI_API_KEY=sk-...

# xAI Grok 2 Image ($0.07/image)
XAI_API_KEY=xai-...

# Leonardo Phoenix ($0.02/image)
LEONARDO_API_KEY=...

# HuggingFace Inference (no-cost models available)
HUGGINGFACE_API_KEY=hf_...

# === OPTIONAL CONFIGURATION ===
IMAGE_GEN_OUTPUT_DIR=./generated-images
IMAGE_GEN_STATE_DIR=~/.visual-forge-mcp
IMAGE_GEN_LOG_LEVEL=info
IMAGE_GEN_DEFAULT_PROVIDER=gemini

Get API Keys:

2. MCP Server Configuration

Add Visual Forge MCP to your MCP client configuration.

Two configuration options:

  • Option A (npm package): Use npx to run the published npm package - no local install needed
  • Option B (local source): Use absolute path to your cloned repository

๐Ÿงช Tested Clients

These configurations have been tested and verified:

Claude Code

Edit ~/.claude/settings.json:

Option A: Using npm package (recommended)

{
  "mcpServers": {
    "visual-forge": {
      "command": "npx",
      "args": ["-y", "@michelabboud/visual-forge-mcp"],
      "env": {
        "GOOGLE_API_KEY": "${GOOGLE_API_KEY}",
        "REPLICATE_API_TOKEN": "${REPLICATE_API_TOKEN}",
        "STABILITY_API_KEY": "${STABILITY_API_KEY}",
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "XAI_API_KEY": "${XAI_API_KEY}"
      }
    }
  }
}

Option B: Using local source

{
  "mcpServers": {
    "visual-forge": {
      "command": "node",
      "args": ["/path/to/visual-forge-mcp/dist/index.js"],
      "env": {
        "GOOGLE_API_KEY": "${GOOGLE_API_KEY}",
        "REPLICATE_API_TOKEN": "${REPLICATE_API_TOKEN}",
        "STABILITY_API_KEY": "${STABILITY_API_KEY}",
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "XAI_API_KEY": "${XAI_API_KEY}"
      }
    }
  }
}
Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Option A: Using npm package (recommended)

{
  "mcpServers": {
    "visual-forge": {
      "command": "npx",
      "args": ["-y", "@michelabboud/visual-forge-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-key-here",
        "REPLICATE_API_TOKEN": "your-token-here"
      }
    }
  }
}

Option B: Using local source

{
  "mcpServers": {
    "visual-forge": {
      "command": "node",
      "args": ["/path/to/visual-forge-mcp/dist/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your-key-here",
        "REPLICATE_API_TOKEN": "your-token-here"
      }
    }
  }
}
Zed

Edit ~/.config/zed/settings.json:

Option A: Using npm package (recommended)

{
  "context_servers": {
    "visual-forge": {
      "command": {
        "path": "npx",
        "args": ["-y", "@michelabboud/visual-forge-mcp"]
      }
    }
  }
}

Option B: Using local source

{
  "context_servers": {
    "visual-forge": {
      "command": {
        "path": "node",
        "args": ["/path/to/visual-forge-mcp/dist/index.js"]
      }
    }
  }
}

๐Ÿš€ MCP-Compatible Clients

These clients support MCP protocol and should work with Visual Forge. Configuration formats may vary slightly:

Cursor

Settings โ†’ Features โ†’ MCP:

Option A: Using npm package (recommended)

{
  "visual-forge": {
    "command": "npx",
    "args": ["-y", "@michelabboud/visual-forge-mcp"]
  }
}

Option B: Using local source

{
  "visual-forge": {
    "command": "node",
    "args": ["/path/to/visual-forge-mcp/dist/index.js"]
  }
}
Windsurf

Edit ~/.windsurf/settings.json:

Option A: Using npm package (recommended)

{
  "mcpServers": {
    "visual-forge": {
      "command": "npx",
      "args": ["-y", "@michelabboud/visual-forge-mcp"]
    }
  }
}

Option B: Using local source

{
  "mcpServers": {
    "visual-forge": {
      "command": "node",
      "args": ["/path/to/visual-forge-mcp/dist/index.js"]
    }
  }
}
Cline (VS Code Extension)

Edit ~/.continue/config.json or use Cline's settings UI:

Option A: Using npm package (recommended)

{
  "experimental": {
    "mcpServers": {
      "visual-forge": {
        "command": "npx",
        "args": ["-y", "@michelabboud/visual-forge-mcp"]
      }
    }
  }
}

Option B: Using local source

{
  "experimental": {
    "mcpServers": {
      "visual-forge": {
        "command": "node",
        "args": ["/path/to/visual-forge-mcp/dist/index.js"]
      }
    }
  }
}
Continue (VS Code Extension)

Edit ~/.continue/config.json:

Option A: Using npm package (recommended)

{
  "experimental": {
    "mcpServers": {
      "visual-forge": {
        "command": "npx",
        "args": ["-y", "@michelabboud/visual-forge-mcp"]
      }
    }
  }
}

Option B: Using local source

{
  "experimental": {
    "mcpServers": {
      "visual-forge": {
        "command": "node",
        "args": ["/path/to/visual-forge-mcp/dist/index.js"]
      }
    }
  }
}
Roo Code (VS Code Extension)

Same as Continue (Roo Code is a fork):

Option A: Using npm package (recommended)

{
  "experimental": {
    "mcpServers": {
      "visual-forge": {
        "command": "npx",
        "args": ["-y", "@michelabboud/visual-forge-mcp"]
      }
    }
  }
}

Option B: Using local source

{
  "experimental": {
    "mcpServers": {
      "visual-forge": {
        "command": "node",
        "args": ["/path/to/visual-forge-mcp/dist/index.js"]
      }
    }
  }
}
Copilot (GitHub Copilot with MCP support)

Configuration via VS Code settings or copilot config file. Consult GitHub Copilot documentation for MCP integration.

Qodo Gen (IDE Extension)

Follow Qodo Gen's MCP integration docs. Typically similar to VS Code extension format.

JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.)

Install MCP plugin, then add to IDE settings or .idea/mcp-servers.json:

Option A: Using npm package (recommended)

{
  "mcpServers": {
    "visual-forge": {
      "command": "npx",
      "args": ["-y", "@michelabboud/visual-forge-mcp"]
    }
  }
}

Option B: Using local source

{
  "mcpServers": {
    "visual-forge": {
      "command": "node",
      "args": ["/path/to/visual-forge-mcp/dist/index.js"]
    }
  }
}

๐Ÿ–ฅ๏ธ Terminal & CLI Clients

Aider

Option A: Using npm package (recommended)

aider --mcp-server "npx -y @michelabboud/visual-forge-mcp"

Or add to ~/.aider.conf.yml:

mcp-servers:
  - name: visual-forge
    command: npx
    args:
      - -y
      - @michelabboud/visual-forge-mcp

Option B: Using local source

aider --mcp-server "node /path/to/visual-forge-mcp/dist/index.js"

Or add to ~/.aider.conf.yml:

mcp-servers:
  - name: visual-forge
    command: node
    args:
      - /path/to/visual-forge-mcp/dist/index.js
Goose

Create ~/.config/goose/config.yaml:

Option A: Using npm package (recommended)

mcp_servers:
  visual-forge:
    command: npx
    args:
      - -y
      - @michelabboud/visual-forge-mcp

Option B: Using local source

mcp_servers:
  visual-forge:
    command: node
    args:
      - /path/to/visual-forge-mcp/dist/index.js
Warp Terminal

Settings โ†’ MCP Servers โ†’ Add Server:

Option A: Using npm package (recommended)

{
  "name": "visual-forge",
  "command": "npx",
  "args": ["-y", "@michelabboud/visual-forge-mcp"]
}

Option B: Using local source

{
  "name": "visual-forge",
  "command": "node",
  "args": ["/path/to/visual-forge-mcp/dist/index.js"]
}
Gemini CLI (Google)

Configuration via CLI flags or config file. Consult Google's Gemini CLI documentation.

opencode

Add to opencode config (typically ~/.opencode/config.json):

Option A: Using npm package (recommended)

{
  "mcpServers": {
    "visual-forge": {
      "command": "npx",
      "args": ["-y", "@michelabboud/visual-forge-mcp"]
    }
  }
}

Option B: Using local source

{
  "mcpServers": {
    "visual-forge": {
      "command": "node",
      "args": ["/path/to/visual-forge-mcp/dist/index.js"]
    }
  }
}
Codex (OpenAI)

Follow OpenAI Codex documentation for MCP server integration.


๐ŸŽจ Specialized Platforms

Amp (Sourcegraph)

Add to workspace settings or Amp configuration file.

LM Studio

Tools โ†’ MCP Servers โ†’ Add Server:

Option A: Using npm package (recommended)

{
  "visual-forge": {
    "command": "npx",
    "args": ["-y", "@michelabboud/visual-forge-mcp"]
  }
}

Option B: Using local source

{
  "visual-forge": {
    "command": "node",
    "args": ["/path/to/visual-forge-mcp/dist/index.js"]
  }
}
OpenHands (All Hands AI)

Edit OpenHands config file:

Option A: Using npm package (recommended)

mcp_servers:
  - name: visual-forge
    command: npx
    args:
      - -y
      - @michelabboud/visual-forge-mcp

Option B: Using local source

mcp_servers:
  - name: visual-forge
    command: node
    args:
      - /path/to/visual-forge-mcp/dist/index.js
Factory

Add via Factory's MCP integration settings.

Kiro (AWS)

Add via Kiro IDE settings โ†’ MCP Servers.


๐Ÿ“ Text Editors

Neovim

Install MCP plugin (e.g., mcp.nvim), then add to init.lua:

Option A: Using npm package (recommended)

require('mcp').setup({
  servers = {
    ['visual-forge'] = {
      command = 'npx',
      args = { '-y', '@michelabboud/visual-forge-mcp' }
    }
  }
})

Option B: Using local source

require('mcp').setup({
  servers = {
    ['visual-forge'] = {
      command = 'node',
      args = { '/path/to/visual-forge-mcp/dist/index.js' }
    }
  }
})

๐Ÿ“– General MCP Setup Pattern:

Most MCP clients follow this pattern. Choose either npm package or local source:

Option A: Using npm package (recommended)

{
  "mcpServers": {
    "visual-forge": {
      "command": "npx",
      "args": ["-y", "@michelabboud/visual-forge-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-key-here"
      }
    }
  }
}

Option B: Using local source

{
  "mcpServers": {
    "visual-forge": {
      "command": "node",
      "args": ["/absolute/path/to/visual-forge-mcp/dist/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your-key-here"
      }
    }
  }
}

If your client isn't listed, consult its MCP integration documentation


๐Ÿ“– Detailed Setup Guides

For popular AI coding assistants, we provide comprehensive setup guides:

๐ŸŽฏ Cursor

Complete Cursor Setup Guide โ†’

Features covered:

  • Step-by-step configuration
  • MCP settings (UI and manual)
  • Usage examples with Cursor's context system
  • Composer mode integration
  • Troubleshooting common issues

๐Ÿ”„ Continue (VS Code)

Complete Continue Setup Guide โ†’

Features covered:

  • VS Code extension setup
  • config.json configuration
  • Slash commands with Visual Forge
  • Multi-file operations
  • Custom prompts and workflows

Other clients: Follow the general MCP configuration pattern shown in the Configuration section above.


๐Ÿ”— n8n Workflow Automation Integration

Visual Forge MCP can be integrated with n8n for automated image generation workflows.

Quick Start with n8n

  1. Start HTTP API Server:
cd visual-forge-mcp
npm run dev:http  # Runs on http://localhost:3000
  1. Choose Integration Method:
    • HTTP API: Use n8n HTTP Request nodes (works immediately)
    • Custom Node: Install n8n-nodes-visual-forge community node (drag-and-drop)
    • Example Workflows: Import pre-built workflow JSON files

Integration Options

Option 1: HTTP API (Immediate)

Use n8n's HTTP Request nodes to call Visual Forge endpoints:

Webhook โ†’ HTTP: Start Session โ†’ HTTP: Process Files โ†’ HTTP: Generate Images โ†’ HTTP: Finalize Session

API Endpoints:

  • POST /api/vf/start-session - Create workflow session
  • POST /api/vf/process-files - Add placeholders and parse
  • POST /api/vf/generate-session - Generate all images
  • POST /api/vf/finalize-session - Commit and create PR
  • GET /api/vf/sessions - List all sessions

Option 2: Custom n8n Node (Drag-and-Drop)

Install the Visual Forge community node:

  1. In n8n: Settings > Community Nodes > Install
  2. Enter: n8n-nodes-visual-forge
  3. Restart n8n

Then drag Visual Forge nodes into your workflows with built-in UI for all operations.

Option 3: Example Workflows (Templates)

Import pre-built workflows from n8n-workflows/:

  • 01-simple-image-generation.json - Basic webhook-triggered generation
  • 02-batch-processing-with-cdn.json - Scheduled batch with S3/CDN upload
  • 03-webhook-triggered-generation.json - Advanced conditional generation

Documentation

Use Cases

  • Automated Documentation: Nightly regeneration of all doc images
  • CI/CD Integration: Generate images on markdown file changes
  • Webhook Triggers: External systems trigger image generation
  • CDN Deployment: Generate and upload to S3/CloudFront
  • Slack Notifications: Alert team when images are generated

โœ… Compatibility & Testing Status

Tested & Verified

  • โœ… Claude Code - Full functionality tested
  • โœ… Claude Desktop - Full functionality tested
  • โœ… Zed - Full functionality tested

Should Work (MCP Standard Compliant)

All clients implementing the MCP protocol should work with Visual Forge. The server uses the official @modelcontextprotocol/sdk and follows the MCP specification.

Reported Working: Cursor, Windsurf, Continue, Cline, Aider, Goose

Not Yet Tested: Amp, Copilot, Factory, Gemini CLI, Kiro, LM Studio, opencode, OpenHands, Qodo Gen, Warp, JetBrains IDEs, Neovim, Roo Code, Codex

If you test Visual Forge with any client, please report your results via GitHub Issues!


๐Ÿš€ Quick Start

Workflow Diagram - Generation Modes

Once the MCP server is added to your client, you can configure providers directly through MCP tools:

User: "Configure Gemini provider with my API key"
Claude: [Uses configure_provider tool]

User: "Check which providers are configured"
Claude: [Uses get_provider_status tool]

User: "Test if my Gemini connection works"
Claude: [Uses test_provider_connection tool]

Available Configuration Tools:

  • configure_provider - Set API key for a provider
  • get_provider_status - Check which providers have API keys set
  • test_provider_connection - Verify API key works
  • remove_provider - Remove a provider's API key

Option 2: Manual .env Configuration

Create a .env file in the project root:

GOOGLE_API_KEY=AIza...
REPLICATE_API_TOKEN=r8_...

Standalone CLI Usage

# Check available providers
npx tsx scripts/check-providers.ts

# Generate with all providers (comparison)
npx tsx scripts/generate-all-providers.ts

# Generate with specific provider
npx tsx scripts/generate-with-xai.ts

# Generate with custom theme and versioning
npx tsx scripts/generate-solo-theme-test.ts

MCP Tool Usage (via MCP Client)

Once configured, interact with Visual Forge through your MCP client:

User: "Generate a professional image of a DevOps engineer working on cloud infrastructure"

Claude: [Uses visual-forge MCP tools to generate the image]

๐Ÿ› ๏ธ MCP Tools Reference

MCP Tools Architecture

Visual Forge provides the following MCP tools for use through your MCP client:

Configuration Tools

configure_provider

Set API key for an image generation provider.

{
  "provider": "gemini",
  "apiKey": "AIza..."
}

Example: "Configure my Replicate API key: r8_abc123..."

get_provider_status

Check which providers have API keys configured.

{}

Example: "Show me which providers are configured"

Returns:

{
  "success": true,
  "providers": [
    {
      "provider": "gemini",
      "displayName": "Google Gemini",
      "configured": true,
      "keyPreview": "AIza****abc123"
    },
    {
      "provider": "openai",
      "displayName": "OpenAI",
      "configured": false
    }
  ]
}

test_provider_connection

Test if a provider API key is valid by checking availability.

{
  "provider": "gemini"
}

Example: "Test my Gemini connection"

remove_provider

Remove API key for a provider.

{
  "provider": "gemini"
}

Example: "Remove my OpenAI API key"

Image Generation Tools

parse_markdown

Parse markdown files to extract image specifications.

{
  "filePaths": ["./docs/guide.md"]
}

list_providers

List all available image generation providers and their capabilities.

{}

generate_image

Generate a single image from specification.

{
  "imageId": "chapter-01-img-01",
  "provider": "gemini"
}

list_images

List all parsed image specifications.

{
  "filter": "diagram"
}

Workflow Tools

start_workflow

Start image generation workflow with specified mode.

{
  "mode": "interactive",
  "provider": "gemini",
  "imageIds": ["img-01", "img-02"]
}

Modes: interactive, batch, bulk

get_status

Get current workflow status and progress.

{}

pause_workflow / resume_workflow

Control workflow execution.

{}

Cost Tracking Tools

get_cost_summary

Get cost summary for all generated images by provider.

{}

๐Ÿ“– Usage Examples

Example 1: Generate Single Image with Specific Provider

// generate-example.ts
import { providerFactory } from './src/providers/index.js';
import { ImageSpec } from './src/types/index.js';

providerFactory.initialize();
const provider = providerFactory.getProvider('gemini');

const spec: ImageSpec = {
  id: 'my-image-01',
  prompt: 'A modern cloud architecture diagram showing microservices...',
  aspectRatio: '16:9',
  // ... other fields
};

const result = await provider.generate(spec);
console.log(`Generated: ${result.filepath}`);

Example 2: Generate with Multiple Versions

# Generate 2 versions of each image for comparison
npx tsx generate-solo-theme-test.ts

Example 3: Cost Estimation

const gemini = providerFactory.getProvider('gemini');
const estimatedCost = gemini.estimateCost(spec);
console.log(`Estimated cost: $${estimatedCost}`);

๐ŸŽจ Supported Providers

AI Provider Comparison

Provider Model Cost/Image Speed Quality Status
Google Gemini 2.5 Flash Image $0.00 โšกโšกโšก Fast Excellent โœ… Tested
Replicate FLUX Schnell $0.003 โšกโšกโšก Fast Excellent โญ Recommended
Leonardo Phoenix $0.02 โšกโšก Medium Excellent โœ… Ready
Stability AI SDXL 1.0 $0.04 โšกโšก Medium Excellent โœ… Tested
OpenAI GPT Image 1 $0.04-0.12 โšก Medium Best โœ… Fixed
xAI Grok 2 Image $0.07 โšกโšก Fast Good โš ๏ธ Preview
HuggingFace Various $0.00 โšก Slow Varies ๐Ÿ”ง Beta

Cost Comparison (151 images)

Provider Total Cost Savings vs OpenAI HD
Replicate FLUX $0.45 96% cheaper โญ
Leonardo $3.02 75% cheaper
Gemini $5.89 51% cheaper
Stability AI $6.04 50% cheaper
OpenAI Standard $6.04 Baseline
xAI Grok $10.57 12% cheaper
OpenAI HD $12.08 Baseline premium

๐Ÿ—๏ธ Project Structure

Visual Forge MCP Architecture

visual-forge-mcp/
โ”œโ”€โ”€ src/                    # Source code
โ”‚   โ”œโ”€โ”€ providers/          # AI provider implementations
โ”‚   โ”‚   โ”œโ”€โ”€ openai/         # OpenAI GPT Image
โ”‚   โ”‚   โ”œโ”€โ”€ gemini/         # Google Gemini 2.5 Flash
โ”‚   โ”‚   โ”œโ”€โ”€ stability/      # Stability AI SDXL
โ”‚   โ”‚   โ”œโ”€โ”€ replicate/      # Replicate FLUX
โ”‚   โ”‚   โ”œโ”€โ”€ leonardo/       # Leonardo Phoenix
โ”‚   โ”‚   โ”œโ”€โ”€ huggingface/    # HuggingFace Inference
โ”‚   โ”‚   โ”œโ”€โ”€ xai/            # xAI Grok 2 Image
โ”‚   โ”‚   โ””โ”€โ”€ base-provider.ts
โ”‚   โ”œโ”€โ”€ quality/            # Quality inspection module
โ”‚   โ”œโ”€โ”€ state/              # State management
โ”‚   โ”œโ”€โ”€ types/              # TypeScript definitions
โ”‚   โ””โ”€โ”€ utils/              # Utilities (logger, rate limiter)
โ”‚
โ”œโ”€โ”€ scripts/                # Example & test scripts
โ”‚   โ”œโ”€โ”€ check-providers.ts  # Provider status checker
โ”‚   โ”œโ”€โ”€ generate-with-*.ts  # Provider-specific generators
โ”‚   โ”œโ”€โ”€ generate-all-providers.ts  # Multi-provider comparison
โ”‚   โ””โ”€โ”€ generate-solo-theme-test.ts  # Versioning test
โ”‚
โ”œโ”€โ”€ docs/                   # Documentation
โ”‚   โ”œโ”€โ”€ VISUAL_MCP_SERVER.md  # Server specification
โ”‚   โ”œโ”€โ”€ IMPLEMENTATION-PLAN.md  # Architecture plan
โ”‚   โ”œโ”€โ”€ SESSION_SUMMARY.md  # Development notes
โ”‚   โ””โ”€โ”€ example.md          # Example prompts
โ”‚
โ”œโ”€โ”€ test/                   # Test files
โ”‚   โ””โ”€โ”€ test-run.ts
โ”‚
โ”œโ”€โ”€ dist/                   # Build output (gitignored)
โ”œโ”€โ”€ generated-images/       # Generated images (gitignored)
โ”‚   โ”œโ”€โ”€ gemini/             # Gemini generated images
โ”‚   โ”œโ”€โ”€ openai/             # OpenAI generated images
โ”‚   โ”œโ”€โ”€ stability/          # Stability AI generated images
โ”‚   โ””โ”€โ”€ ...                 # Other providers
โ”‚
โ”œโ”€โ”€ package.json            # NPM package configuration
โ”œโ”€โ”€ tsconfig.json           # TypeScript configuration
โ”œโ”€โ”€ README.md               # This file
โ”œโ”€โ”€ CHANGELOG.md            # Version history
โ””โ”€โ”€ .env.example            # Environment variables template

๐Ÿ”ง Development

Build

npm run build

Development Mode

npm run dev

Linting

npm run lint

Testing

npm test
npm run test:watch

๐Ÿ“Š Features in Detail

Quality Inspection

Automatically analyzes generated images for:

  • Sharpness: Laplacian variance algorithm
  • Brightness: 0-255 scale with warnings for extremes
  • File size: Validation (10KB - 10MB)
  • Dimensions: Aspect ratio verification
  • Format: Image encoding validation

Rate Limiting

Token bucket algorithm per provider:

  • OpenAI: 5 images/minute
  • Gemini: 20 images/minute
  • Stability AI: 10 images/minute
  • Replicate: 20 images/minute
  • xAI: 10 images/minute

Cost Tracking

Real-time tracking:

  • Per-image cost
  • Provider totals
  • Session costs
  • Estimates before generation

๐Ÿ› Troubleshooting

Provider Not Available

โŒ Gemini provider not available! Check GOOGLE_API_KEY in .env

Solution: Verify API key is set in .env file and restart the server.

Out of Credits (Stability AI)

โŒ insufficient_balance: Your organization does not have enough balance

Solution: Add credits to your Stability AI account at https://platform.stability.ai

Rate Limit Errors

โŒ Rate limit exceeded for provider openai

Solution: The rate limiter will automatically retry after cooldown. Reduce concurrency in workflow config.


๐Ÿค Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

๐Ÿ“ License

Personal Use Only - This software is free for personal, educational, and research purposes only.

Commercial use is NOT permitted without a commercial license.

See LICENSE file for complete terms and conditions.

For commercial licensing inquiries, please contact the author.


๐Ÿ™ Acknowledgments

  • Built with MCP SDK
  • Powered by multiple AI image generation providers
  • Special thanks to the open-source community

๐Ÿ“š Resources

Documentation

Setup Guides

n8n Integration



โšก Generate professional images for your documentation in seconds!

Made with โค๏ธ for the developer community