@michelabboud/visual-forge-mcp 0.7.0 → 0.9.0

package/docs/guides/comprehensive-guide.md

@@ -0,0 +1,1552 @@
+# Visual Forge MCP - Comprehensive Guide
+
+**Version:** 0.9.0
+**Last Updated:** 2026-01-16
+
+---
+
+## Table of Contents
+
+1. [Description](#description)
+2. [Installation](#installation)
+3. [Architecture & How It Works](#architecture--how-it-works)
+4. [Environment Variables](#environment-variables)
+5. [Provider & Model System](#provider--model-system)
+6. [Usage Workflows](#usage-workflows)
+7. [MCP Tools Reference](#mcp-tools-reference)
+8. [Testing](#testing)
+9. [Troubleshooting](#troubleshooting)
+10. [Advanced Topics](#advanced-topics)
+
+---
+
+## Description
+
+**Visual Forge MCP** is a Model Context Protocol (MCP) server that automates AI-powered image generation for technical documentation. It provides a comprehensive solution for generating, optimizing, and managing images across multiple AI providers.
+
+### Key Features
+
+- **Multi-Provider Support**: 8 AI providers with automatic fallback
+  - OpenAI (GPT Image)
+  - Google Gemini (Nano Banana)
+  - Stability AI (SDXL)
+  - Replicate (FLUX models)
+  - Leonardo AI (Phoenix)
+  - HuggingFace (SDXL, FLUX)
+  - xAI (Grok 2 Image)
+  - Z.ai (GLM-Image) - **NEW** ✨
+
+- **Multi-Model Architecture**: Each provider can offer multiple models with different capabilities and pricing
+
+- **Model Testing & Comparison** - **NEW v0.9.0** ✨:
+  - Standard automated quality tests
+  - Custom prompt testing with real use cases
+  - Side-by-side multi-provider comparison
+  - Quality scoring (sharpness, brightness, text rendering, color accuracy)
+  - Intelligent recommendations based on test results
+  - Cost-aware permission flow for paid models
+
+- **Professional Image Pipeline**:
+  - Automatic image optimization (WebP, JPEG, PNG)
+  - Quality inspection (sharpness, brightness, dimensions)
+  - Watermarking support
+  - Auto-regeneration on quality failures
+
+- **State Management**:
+  - Persistent state across sessions
+  - Resumable workflows
+  - Cost tracking by provider/file/type
+  - Backup/restore system
+
+- **Workflow Modes**:
+  - **Interactive**: One-by-one generation with approval
+  - **Batch**: Generate N images, then approve batch
+  - **Bulk**: Parallel generation with concurrency control
+
+- **Quality Features**:
+  - Image quality validation (sharpness, brightness, OCR)
+  - Automatic regeneration on failures (configurable)
+  - Multi-format optimization
+  - Comprehensive metadata tracking
+
+### Use Cases
+
+- **Technical Documentation**: Generate diagrams, flowcharts, and architecture illustrations
+- **Educational Content**: Create instructional images and infographics
+- **API Documentation**: Visualize API endpoints and data flows
+- **System Architecture**: Illustrate cloud infrastructure and system designs
+- **Process Documentation**: Create visual workflows and decision trees
+
+---
+
+## Installation
+
+### Prerequisites
+
+- **Node.js**: v18+ or v20+
+- **npm**: v9+ or v10+
+- **Operating System**: Linux, macOS, or Windows with WSL2
+
+### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/michelabboud/visual-forge-mcp.git
+cd visual-forge-mcp
+```
+
+### Step 2: Install Dependencies
+
+```bash
+npm install
+```
+
+### Step 3: Build the Project
+
+```bash
+npm run build
+```
+
+This compiles TypeScript to JavaScript in the `dist/` directory.
+
+### Step 4: Configure Environment Variables
+
+Create a `.env` file in the project root:
+
+```bash
+# Copy example environment file
+cp .env.example .env
+
+# Edit with your API keys
+nano .env
+```
+
+**Minimum configuration** (at least one provider required):
+
+```env
+# Free option (recommended for testing)
+GOOGLE_API_KEY=AIza...
+
+# Or paid options
+OPENAI_API_KEY=sk-...
+ZAI_API_KEY=zai-...
+```
+
+See [Environment Variables](#environment-variables) section for complete list.
+
+### Step 5: Verify Installation
+
+```bash
+# Run tests
+npm test
+
+# Check provider availability
+npx tsx scripts/check-providers.ts
+```
+
+### Step 6: Configure MCP Client
+
+Add to your MCP client configuration (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "visual-forge": {
+      "command": "node",
+      "args": ["/path/to/visual-forge-mcp/dist/index.js"],
+      "env": {
+        "GOOGLE_API_KEY": "AIza...",
+        "ZAI_API_KEY": "zai-...",
+        "IMAGE_GEN_OUTPUT_DIR": "./generated-images",
+        "IMAGE_GEN_LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Architecture & How It Works
+
+### System Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    MCP Client                           │
+│             (Claude Desktop, Continue, etc.)            │
+└───────────────────────┬─────────────────────────────────┘
+                        │ MCP Protocol (stdio)
+                        │
+┌───────────────────────▼─────────────────────────────────┐
+│              Visual Forge MCP Server                    │
+│  ┌────────────────────────────────────────────────┐    │
+│  │  13+ MCP Tools (parse, generate, configure)    │    │
+│  └────────────────────┬────────────────────────────┘    │
+│                       │                                  │
+│  ┌────────────────────▼────────────────────────────┐    │
+│  │         Provider Factory                        │    │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐     │    │
+│  │  │ OpenAI   │  │  Gemini  │  │   Z.ai   │  ...│    │
+│  │  └──────────┘  └──────────┘  └──────────┘     │    │
+│  └─────────────────────────────────────────────────┘    │
+│                                                          │
+│  ┌─────────────────────────────────────────────────┐    │
+│  │         State Manager                           │    │
+│  │  • Session tracking                             │    │
+│  │  • Cost tracking                                │    │
+│  │  • Workflow orchestration                       │    │
+│  │  • Backup/restore                               │    │
+│  └─────────────────────────────────────────────────┘    │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Core Components
+
+#### 1. MCP Server (`src/server/mcp-server.ts`)
+
+Entry point for MCP protocol communication:
+- Exposes 13+ MCP tools via stdio transport
+- Handles tool calls and responses
+- Manages configuration via ConfigManager
+- Coordinates all system components
+
+#### 2. Provider System (`src/providers/`)
+
+**Provider vs Model Architecture** (v0.8.0):
+- **Provider**: Service/company (OpenAI, Google, Z.ai)
+- **Model**: Specific AI implementation (GPT Image 1, Gemini Flash, GLM-Image)
+- One provider can offer multiple models with different pricing/capabilities
+
+**Components**:
+- **ProviderFactory** (`index.ts`): Singleton managing all providers
+- **BaseProvider** (`base-provider.ts`): Abstract base with shared functionality
+- **Provider Implementations**: 8 providers extending BaseProvider
+
+**Features**:
+- Automatic provider initialization from env vars or ConfigManager
+- Multi-model support per provider
+- Automatic fallback on provider failure
+- Rate limiting per provider
+- Quality inspection post-generation
+
+#### 3. State Management (`src/state/state-manager.ts`)
+
+Persistent state in `~/.visual-forge-mcp/state.json`:
+- **Atomic writes**: Temp file + rename for crash safety
+- **Tracks**: sessions, images, jobs, costs
+- **Enables**: resumable workflows across restarts
+
+#### 4. Workflow Orchestrator (`src/workflow/workflow-orchestrator.ts`)
+
+Three workflow modes:
+- **Interactive**: Sequential one-at-a-time (simulated approval in MCP)
+- **Batch**: Generate N images → approve batch
+- **Bulk**: Parallel with concurrency limit (default: 3)
+
+#### 5. Quality Inspector (`src/quality/quality-inspector.ts`)
+
+Post-generation validation:
+- **Sharpness**: Laplacian variance analysis
+- **Brightness**: 0-255 scale validation
+- **Dimensions**: Size verification
+- **File size**: 10KB - 10MB range
+- **OCR** (optional): Text detection
+
+#### 6. Markdown Parser (`src/parser/markdown-parser.ts`)
+
+Extracts image specifications from markdown:
+```markdown
+\`\`\`image
+type: diagram
+aspectRatio: 16:9
+prompt: AWS architecture with VPC, EC2, and RDS
+\`\`\`
+```
+
+Merges global context with per-image prompts for consistency.
+
+---
+
+## Environment Variables
+
+### Provider API Keys (Required - at least one)
+
+```env
+# Google Gemini (FREE, recommended for testing)
+GOOGLE_API_KEY=AIza...
+
+# Z.ai GLM-Image (NEW - excellent for text-heavy diagrams)
+ZAI_API_KEY=zai-...
+
+# OpenAI GPT Image
+OPENAI_API_KEY=sk-...
+
+# Stability AI
+STABILITY_API_KEY=sk-...
+
+# Replicate (FLUX models - cheapest paid option)
+REPLICATE_API_TOKEN=r8_...
+
+# Leonardo AI
+LEONARDO_API_KEY=...
+
+# HuggingFace
+HUGGINGFACE_API_KEY=hf_...
+
+# xAI Grok
+XAI_API_KEY=xai-...
+```
+
+### Configuration (Optional)
+
+```env
+# Output directory for generated images
+IMAGE_GEN_OUTPUT_DIR=./generated-images
+
+# State persistence directory
+IMAGE_GEN_STATE_DIR=~/.visual-forge-mcp
+
+# Logging level: debug | info | warn | error
+IMAGE_GEN_LOG_LEVEL=info
+
+# Default provider selection
+IMAGE_GEN_DEFAULT_PROVIDER=gemini
+
+# Quality validation (default: true)
+VF_QUALITY_VALIDATION=true
+
+# Auto-regeneration on quality failures (default: true)
+VF_AUTO_REGENERATE=true
+
+# Maximum regeneration attempts (default: 3)
+VF_MAX_RETRIES=3
+
+# Image format generation
+VF_GENERATE_PNG=false      # Generate optimized PNG (default: false)
+VF_PNG_QUALITY=85          # PNG quality 0-100 (default: 85)
+VF_PNG_PALETTE=true        # Use palette for PNG (default: true)
+VF_PNG_COLORS=256          # Color palette size (default: 256)
+VF_PNG_DITHER=1.0          # Dithering level 0-1 (default: 1.0)
+```
+
+### Provider-Specific Environment Variables
+
+```env
+# OpenAI specific
+OPENAI_ORG_ID=org-...              # Optional: Organization ID
+OPENAI_PROJECT_ID=proj_...         # Optional: Project ID
+
+# Stability AI specific
+STABILITY_ORGANIZATION=org-...     # Optional: Organization ID
+
+# HuggingFace specific
+HUGGINGFACE_MODEL=stabilityai/stable-diffusion-xl-base-1.0  # Default model
+```
+
+---
+
+## Provider & Model System
+
+### Provider Overview
+
+| Provider | Models | Cost Range | Best For | Free Tier |
+|----------|--------|------------|----------|-----------|
+| **Replicate** | FLUX Schnell, Dev, Pro | $0.003-$0.055 | General images, fast | ❌ |
+| **Z.ai** | GLM-Image | $0.015 | Text-heavy diagrams | ❌ |
+| **Gemini** | 2.5 Flash, 2.5 Flash Pro | $0 | Testing, prototypes | ✅ |
+| **HuggingFace** | SDXL, FLUX.1 Dev | $0 | Testing, community models | ✅ |
+| **Leonardo** | Phoenix 1.0 | $0.02 | Artistic images | ❌ |
+| **OpenAI** | GPT Image 1, GPT Image 1 HD | $0.04-$0.12 | Professional images | ❌ |
+| **Stability AI** | SDXL 1.0 | $0.04 | Stable Diffusion | ❌ |
+| **xAI** | Grok 2 Image | $0.07 | Grok integration | ❌ |
+
+### Model Selection
+
+Providers with multiple models:
+- **OpenAI**: `gpt-image-1` (standard), `gpt-image-1-hd` (high-def)
+- **Gemini**: `gemini-2.5-flash-image` (2K), `gemini-2.5-flash-image-pro` (4K)
+- **Replicate**: `flux-schnell` (fast), `flux-dev` (quality), `flux-pro` (professional)
+- **HuggingFace**: `stabilityai/stable-diffusion-xl-base-1.0`, `black-forest-labs/FLUX.1-dev`
+
+**Select model during generation**:
+```typescript
+// MCP tool call
+{
+  "tool": "generate_image",
+  "parameters": {
+    "imageId": "doc-img-01",
+    "provider": "openai",
+    "options": {
+      "model": "gpt-image-1-hd",  // Specify model
+      "quality": "hd"
+    }
+  }
+}
+```
+
+### Provider Priority Order
+
+When no provider is specified, Visual Forge selects based on:
+
+1. **Environment variable**: `IMAGE_GEN_DEFAULT_PROVIDER`
+2. **Cost priority** (if no env var):
+   - `replicate` (cheapest: $0.003)
+   - `zai` (2nd cheapest: $0.015)
+   - `gemini` (free)
+   - `huggingface` (free)
+   - `openai`, `stability`, `leonardo`, `xai`
+
+### Provider Capabilities
+
+Each provider reports capabilities via `getCapabilities()`:
+
+```typescript
+interface ProviderCapabilities {
+  maxDimensions: { width: number; height: number };
+  supportedAspectRatios: string[];
+  supportedFormats: Array<'png' | 'jpg' | 'webp'>;
+  supportsHD: boolean;
+  supportsMultilingual: boolean;
+  supportsImageEditing: boolean;
+  supportsStyleTransfer: boolean;
+  averageGenerationTime: number;  // seconds
+}
+```
+
+**Example** (Z.ai GLM-Image):
+```json
+{
+  "maxDimensions": { "width": 2048, "height": 2048 },
+  "supportedAspectRatios": ["1:1", "16:9", "4:3", "9:16", "3:2", "21:9"],
+  "supportedFormats": ["png"],
+  "supportsHD": true,
+  "supportsMultilingual": true,
+  "supportsImageEditing": true,
+  "supportsStyleTransfer": true,
+  "averageGenerationTime": 15
+}
+```
+
+### Provider Configuration via MCP
+
+Runtime configuration without restart:
+
+```bash
+# Set API key for Z.ai
+mcp-tool configure_provider \
+  --provider zai \
+  --apiKey "zai-..."
+
+# Check which providers are configured
+mcp-tool get_provider_status
+
+# Test API key validity
+mcp-tool test_provider_connection --provider zai
+
+# Remove provider
+mcp-tool remove_provider --provider zai
+```
+
+Configuration stored in `~/.visual-forge-mcp/config.json`.
+
+---
+
+## Usage Workflows
+
+### Basic Workflow: Generate Images from Markdown
+
+**Step 1: Create markdown with image specifications**
+
+```markdown
+# My Technical Documentation
+
+## Architecture Overview
+
+\`\`\`image
+type: architecture
+aspectRatio: 16:9
+prompt: AWS cloud architecture showing VPC with public/private subnets,
+EC2 instances, RDS database, and load balancer. Professional diagram style.
+\`\`\`
+
+## Data Flow
+
+\`\`\`image
+type: flowchart
+aspectRatio: 4:3
+prompt: Data processing pipeline flowchart showing ingestion,
+transformation, storage, and analytics stages with arrows.
+\`\`\`
+```
+
+**Step 2: Parse markdown to extract specifications**
+
+```typescript
+// MCP tool call
+{
+  "tool": "parse_markdown",
+  "parameters": {
+    "filePaths": ["docs/architecture.md"]
+  }
+}
+```
+
+**Step 3: Start generation workflow**
+
+```typescript
+// Bulk mode (parallel, fire-and-forget)
+{
+  "tool": "start_workflow",
+  "parameters": {
+    "mode": "bulk",
+    "provider": "gemini",
+    "concurrency": 3
+  }
+}
+```
+
+**Step 4: Monitor progress**
+
+```typescript
+{
+  "tool": "get_status"
+}
+```
+
+**Response**:
+```json
+{
+  "mode": "bulk",
+  "status": "running",
+  "currentImage": "docs-img-02",
+  "totalImages": 5,
+  "completed": 2,
+  "failed": 0,
+  "provider": "gemini"
+}
+```
+
+**Step 5: Get cost summary**
+
+```typescript
+{
+  "tool": "get_cost_summary"
+}
+```
+
+**Response**:
+```json
+{
+  "totalCost": 0.075,
+  "byProvider": {
+    "gemini": 0.0,
+    "zai": 0.045,
+    "openai": 0.03
+  },
+  "byFile": {
+    "docs/architecture.md": 0.075
+  },
+  "byType": {
+    "architecture": 0.03,
+    "flowchart": 0.045
+  },
+  "imageCount": 5
+}
+```
+
+### Advanced Workflow: Global Context
+
+For consistent styling across multiple images:
+
+**Step 1: Parse with global context**
+
+```typescript
+{
+  "tool": "parse_markdown",
+  "parameters": {
+    "filePaths": ["docs/*.md"],
+    "globalContext": {
+      "prePrompt": "Professional technical documentation style",
+      "documentVibe": "Modern, clean, and professional",
+      "style": {
+        "visualStyle": "Flat design with subtle isometric perspective",
+        "mood": "Professional and informative",
+        "colorPalette": ["#1a365d", "#0891b2", "#7c3aed"]
+      },
+      "postPrompt": "High quality, clear labels, no watermarks"
+    }
+  }
+}
+```
+
+This context is prepended to every image prompt automatically.
+
+### Workflow Mode Comparison
+
+| Mode | Use Case | Concurrency | Approval | Speed |
+|------|----------|-------------|----------|-------|
+| **Interactive** | Few images, manual control | 1 | Per-image | Slowest |
+| **Batch** | Medium batch, review before approval | N images | Per-batch | Medium |
+| **Bulk** | Large batch, fire-and-forget | 3 (configurable) | None | Fastest |
+
+**Interactive Mode**:
+```typescript
+{
+  "tool": "start_workflow",
+  "parameters": {
+    "mode": "interactive",
+    "imageIds": ["img-01", "img-02", "img-03"]
+  }
+}
+```
+
+**Batch Mode**:
+```typescript
+{
+  "tool": "start_workflow",
+  "parameters": {
+    "mode": "batch",
+    "imageIds": ["img-01", "img-02", "img-03"],
+    "batchSize": 10  // Generate 10 at a time
+  }
+}
+```
+
+**Bulk Mode**:
+```typescript
+{
+  "tool": "start_workflow",
+  "parameters": {
+    "mode": "bulk",
+    "concurrency": 5  // 5 parallel generations
+  }
+}
+```
+
+### Workflow Control
+
+**Pause workflow**:
+```typescript
+{
+  "tool": "pause_workflow"
+}
+```
+
+**Resume workflow**:
+```typescript
+{
+  "tool": "resume_workflow"
+}
+```
+
+**Generate single image**:
+```typescript
+{
+  "tool": "generate_image",
+  "parameters": {
+    "imageId": "doc-img-01",
+    "provider": "zai"  // Optional, uses default if omitted
+  }
+}
+```
+
+---
+
+## MCP Tools Reference
+
+### Configuration Tools
+
+#### `configure_provider`
+Set API key for a provider at runtime.
+
+**Parameters**:
+- `provider` (string): Provider type (`openai`, `gemini`, `zai`, etc.)
+- `apiKey` (string): API key
+
+**Example**:
+```json
+{
+  "tool": "configure_provider",
+  "parameters": {
+    "provider": "zai",
+    "apiKey": "zai-..."
+  }
+}
+```
+
+#### `get_provider_status`
+Check which providers are configured.
+
+**Parameters**: None
+
+**Response**:
+```json
+{
+  "configured": ["openai", "gemini", "zai"],
+  "unconfigured": ["stability", "replicate", "leonardo", "huggingface", "xai"]
+}
+```
+
+#### `test_provider_connection`
+Verify API key validity.
+
+**Parameters**:
+- `provider` (string): Provider to test
+
+**Response**:
+```json
+{
+  "success": true,
+  "message": "Z.ai API connected (245ms)",
+  "latency": 245
+}
+```
+
+#### `remove_provider`
+Remove API key for a provider.
+
+**Parameters**:
+- `provider` (string): Provider to remove
+
+### Model Selection & Testing Tools ✨ NEW v0.9.0
+
+#### `set_default_model`
+Set the default model for a provider.
+
+**Parameters**:
+- `provider` (string): Provider to configure
+- `modelId` (string): Model ID to set as default
+
+**Example**:
+```json
+{
+  "tool": "set_default_model",
+  "parameters": {
+    "provider": "zai",
+    "modelId": "glm-image"
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "provider": "zai",
+  "modelId": "glm-image",
+  "modelName": "GLM-Image",
+  "message": "Default model set to 'GLM-Image' for Z.ai GLM-Image..."
+}
+```
+
+#### `get_model_info`
+Get detailed information about a specific model.
+
+**Parameters**:
+- `provider` (string): Provider that offers the model
+- `modelId` (string): Model ID to get information about
+
+**Response**:
+```json
+{
+  "success": true,
+  "provider": "gemini",
+  "providerName": "Google Gemini 2.5 Flash Image",
+  "model": {
+    "id": "gemini-2.5-flash-image",
+    "name": "Gemini 2.5 Flash Image",
+    "costPerImage": 0.0,
+    "description": "Fast, free-tier image generation",
+    "capabilities": {
+      "maxResolution": "2048x2048",
+      "supportedAspectRatios": ["1:1", "16:9", "4:3", "9:16"]
+    }
+  },
+  "testResult": {
+    "testedAt": "2026-01-16T10:30:00.000Z",
+    "qualityScore": 85.5,
+    "passed": true
+  }
+}
+```
+
+#### `test_model`
+Test a model with standard or custom prompt.
+
+**Parameters**:
+- `provider` (string): Provider to test
+- `modelId` (string): Model ID to test
+- `useStandardTest` (boolean, optional): Use standard test prompt
+- `prompt` (string, optional): Custom prompt for testing
+- `aspectRatio` (string, optional): Aspect ratio (default: "16:9")
+- `skipPermission` (boolean, optional): Skip cost confirmation (default: false)
+
+**Example (Standard Test)**:
+```json
+{
+  "tool": "test_model",
+  "parameters": {
+    "provider": "zai",
+    "modelId": "glm-image",
+    "useStandardTest": true
+  }
+}
+```
+
+**Example (Custom Prompt)**:
+```json
+{
+  "tool": "test_model",
+  "parameters": {
+    "provider": "gemini",
+    "modelId": "gemini-2.5-flash-image",
+    "prompt": "AWS VPC architecture diagram with public/private subnets"
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "provider": "zai",
+  "providerName": "Z.ai GLM-Image",
+  "model": "GLM-Image",
+  "testImage": {
+    "filepath": "generated-images/tests/zai-glm-image-test.png",
+    "generationTime": 12000,
+    "actualCost": 0.015
+  },
+  "qualityScore": {
+    "overall": 87.5,
+    "sharpness": 89.2,
+    "brightness": 145,
+    "textRendering": 85.0,
+    "colorAccuracy": 90.0,
+    "passed": true
+  }
+}
+```
+
+**Quality Metrics**:
+- **Sharpness (30%)**: Laplacian variance analysis
+- **Brightness (20%)**: Average brightness (30-240 range)
+- **Text Rendering (40%)**: OCR accuracy estimation
+- **Color Accuracy (10%)**: Heuristic validation
+- **Pass Threshold**: 60/100 overall score
+
+#### `compare_models`
+Compare multiple providers/models side-by-side.
+
+**Parameters**:
+- `prompt` (string): Prompt to test across all models
+- `providers` (array): Array of {provider, model} objects
+- `aspectRatio` (string, optional): Aspect ratio (default: "16:9")
+- `skipPermission` (boolean, optional): Skip cost confirmation
+
+**Example**:
+```json
+{
+  "tool": "compare_models",
+  "parameters": {
+    "prompt": "Technical diagram showing microservices architecture",
+    "providers": [
+      { "provider": "gemini", "model": "gemini-2.5-flash-image" },
+      { "provider": "zai", "model": "glm-image" },
+      { "provider": "huggingface", "model": "black-forest-labs/FLUX.1-dev" }
+    ]
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "totalCost": 0.015,
+  "totalTime": 35000,
+  "results": [
+    {
+      "provider": "zai",
+      "model": "GLM-Image",
+      "qualityScore": { "overall": 92.1 },
+      "rank": 1
+    },
+    {
+      "provider": "gemini",
+      "model": "Gemini Flash Image",
+      "qualityScore": { "overall": 85.5 },
+      "rank": 2
+    }
+  ],
+  "recommendation": {
+    "provider": "zai",
+    "model": "glm-image",
+    "reason": "Highest overall quality (92.1/100)..."
+  }
+}
+```
+
+### Image Generation Tools
+
+#### `parse_markdown`
+Extract image specifications from markdown files.
+
+**Parameters**:
+- `filePaths` (string[]): Array of markdown file paths
+- `globalContext` (object, optional): Global styling context
+
+**Response**:
+```json
+{
+  "images": [
+    {
+      "id": "docs-img-01",
+      "file": "docs/architecture.md",
+      "type": "architecture",
+      "aspectRatio": "16:9",
+      "prompt": "AWS cloud architecture...",
+      "estimatedCost": 0.015
+    }
+  ],
+  "totalImages": 5,
+  "totalEstimatedCost": 0.075
+}
+```
+
+#### `list_providers`
+List available providers and their models.
+
+**Parameters**: None
+
+**Response**:
+```json
+{
+  "providers": [
+    {
+      "name": "zai",
+      "displayName": "Z.ai GLM-Image",
+      "isAvailable": true,
+      "models": [
+        {
+          "id": "glm-image",
+          "name": "GLM-Image",
+          "costPerImage": 0.015,
+          "description": "16B hybrid model for text-heavy diagrams"
+        }
+      ],
+      "defaultModel": "glm-image",
+      "capabilities": { ... }
+    }
+  ]
+}
+```
+
+#### `generate_image`
+Generate a single image.
+
+**Parameters**:
+- `imageId` (string): Image specification ID
+- `provider` (string, optional): Provider to use
+- `options` (object, optional):
+  - `model` (string): Specific model ID
+  - `quality` (`'standard'` | `'hd'`)
+  - `style` (string): Custom style
+
+**Response**:
+```json
+{
+  "id": "doc-img-01",
+  "filepath": "generated-images/zai/doc-img-01.webp",
+  "provider": "zai",
+  "metadata": {
+    "model": "glm-image",
+    "actualCost": 0.015,
+    "generationTime": 12500,
+    "dimensions": { "width": 1792, "height": 1024 },
+    "fileSize": 145234,
+    "format": "webp",
+    "quality": {
+      "sharpness": 87.3,
+      "brightness": 142,
+      "passed": true
+    }
+  },
+  "generatedAt": "2026-01-16T06:30:00.000Z"
+}
+```
+
+#### `start_workflow`
+Start image generation workflow.
+
+**Parameters**:
+- `mode` (`'interactive'` | `'batch'` | `'bulk'`): Workflow mode
+- `imageIds` (string[], optional): Specific images to generate
+- `provider` (string, optional): Default provider
+- `concurrency` (number, optional): Parallel generations (bulk mode only)
+
+**Response**:
+```json
+{
+  "workflowId": "wf-1234",
+  "mode": "bulk",
+  "status": "started",
+  "totalImages": 10,
+  "provider": "gemini"
+}
+```
+
+#### `get_status`
+Get workflow progress.
+
+**Parameters**: None
+
+**Response**:
+```json
+{
+  "mode": "bulk",
+  "status": "running",
+  "currentImage": "docs-img-05",
+  "totalImages": 10,
+  "completed": 4,
+  "failed": 0,
+  "pending": 6,
+  "provider": "gemini",
+  "estimatedTimeRemaining": 45
+}
+```
+
+#### `pause_workflow` / `resume_workflow`
+Control workflow execution.
+
+**Parameters**: None
+
+#### `list_images`
+List parsed image specifications.
+
+**Parameters**:
+- `filter` (string, optional): Filter by type (`architecture`, `flowchart`, etc.)
+
+**Response**:
+```json
+{
+  "images": [
+    {
+      "id": "docs-img-01",
+      "file": "docs/architecture.md",
+      "type": "architecture",
+      "status": "generated",
+      "filepath": "generated-images/zai/docs-img-01.webp"
+    }
+  ],
+  "total": 10,
+  "byStatus": {
+    "pending": 3,
+    "generated": 6,
+    "failed": 1
+  }
+}
+```
+
+### Cost Tracking Tools
+
+#### `get_cost_summary`
+Get cost breakdown.
+
+**Parameters**: None
+
+**Response**:
+```json
+{
+  "totalCost": 0.225,
+  "byProvider": {
+    "gemini": 0.0,
+    "zai": 0.105,
+    "openai": 0.12
+  },
+  "byFile": {
+    "docs/architecture.md": 0.075,
+    "docs/api.md": 0.15
+  },
+  "byType": {
+    "architecture": 0.09,
+    "flowchart": 0.075,
+    "diagram": 0.06
+  },
+  "imageCount": 15,
+  "averageCostPerImage": 0.015
+}
+```
+
+---
+
+## Testing
+
+### Test Infrastructure
+
+Visual Forge uses **Jest** with full TypeScript and ES modules support.
+
+**Test coverage**: 77 tests across 4 test suites
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run with coverage report
+npm test -- --coverage
+
+# Run specific test file
+npm test -- provider-factory.test.ts
+```
+
+### Test Structure
+
+```
+test/
+├── helpers/                    # Test utilities and mocks
+│   ├── test-utils.ts          # createMockImageSpec(), etc.
+│   └── mock-providers.ts      # MockSuccessProvider, MockFailureProvider
+├── providers/                  # Provider system tests
+│   └── provider-factory.test.ts  # 21 test cases
+├── state/                      # State management tests
+├── workflow/                   # Workflow orchestration tests
+└── README.md                   # Test documentation
+```
+
+### Manual Provider Testing
+
+```bash
+# Check all providers
+npx tsx scripts/check-providers.ts
+
+# Test Z.ai specifically
+ZAI_API_KEY=zai-... npx tsx scripts/test-zai.ts
+
+# Compare all providers
+npx tsx scripts/generate-all-providers.ts
+
+# Test versioning
+npx tsx scripts/generate-solo-theme-test.ts
+```
+
+### Test Helpers
+
+Use these when writing tests:
+
+```typescript
+import {
+  createMockImageSpec,
+  createMockProviderConfig,
+  setTestEnv,
+  clearTestEnv
+} from '../helpers/test-utils.js';
+
+// Create mock image spec
+const spec = createMockImageSpec({
+  id: 'test-img-01',
+  type: 'architecture',
+  aspectRatio: '16:9'
+});
+
+// Set test environment
+setTestEnv({
+  'GOOGLE_API_KEY': 'AIza-test-key-1234567890',
+  'ZAI_API_KEY': 'zai-test-key-1234567890'
+});
+
+// Clean up
+clearTestEnv(['GOOGLE_API_KEY', 'ZAI_API_KEY']);
+```
+
+### Writing Tests
+
+Follow AAA pattern:
+```typescript
+describe('ProviderFactory', () => {
+  beforeEach(() => {
+    // Arrange: Setup
+    jest.clearAllMocks();
+    clearTestEnv(['GOOGLE_API_KEY']);
+  });
+
+  it('should initialize Gemini provider when API key is set', () => {
+    // Arrange
+    setTestEnv({ 'GOOGLE_API_KEY': 'AIza-test-key-1234567890' });
+    const factory = new ProviderFactory();
+
+    // Act
+    factory.initialize();
+
+    // Assert
+    expect(factory.isProviderAvailable('gemini')).toBe(true);
+  });
+});
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. "No providers configured" error
+
+**Problem**: No API keys set
+
+**Solution**:
+```bash
+# Check environment variables
+echo $GOOGLE_API_KEY
+echo $ZAI_API_KEY
+
+# Set at least one provider
+export GOOGLE_API_KEY=AIza...
+
+# Or use runtime configuration
+mcp-tool configure_provider --provider gemini --apiKey AIza...
+```
+
+#### 2. Rate limit errors
+
+**Problem**: Too many requests to provider API
+
+**Solution**:
+- Reduce concurrency: `"concurrency": 2` (instead of 3)
+- Wait between requests (automatic with rate limiter)
+- Check provider-specific rate limits in `config/pricing.json`
+
+#### 3. Quality validation failures
+
+**Problem**: Generated images fail quality checks
+
+**Solution**:
+```env
+# Disable quality validation temporarily
+VF_QUALITY_VALIDATION=false
+
+# Or adjust thresholds (in code: quality-inspector.ts)
+minSharpness: 40  # Instead of 50
+minQualityScore: 50  # Instead of 60
+```
+
+#### 4. Build errors
+
+**Problem**: TypeScript compilation fails
+
+**Solution**:
+```bash
+# Clean build artifacts
+npm run clean
+
+# Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
+
+# Rebuild
+npm run build
+```
+
+#### 5. Provider initialization warnings
+
+**Problem**: "Failed to initialize X provider"
+
+**Causes**:
+- Invalid API key format
+- Missing environment variable
+- Network connectivity issues
+
+**Debug**:
+```bash
+# Check provider status
+npx tsx scripts/check-providers.ts
+
+# Test specific provider connection
+mcp-tool test_provider_connection --provider zai
+
+# Enable debug logging
+export IMAGE_GEN_LOG_LEVEL=debug
+npm start
+```
+
+### Debug Mode
+
+Enable detailed logging:
+
+```env
+IMAGE_GEN_LOG_LEVEL=debug
+```
+
+Log output includes:
+- Provider initialization details
+- Model selection logic
+- API request/response details
+- Quality inspection results
+- Cost calculations
+
+### State Corruption
+
+If state becomes corrupted:
+
+```bash
+# Backup current state
+cp ~/.visual-forge-mcp/state.json ~/.visual-forge-mcp/state.json.backup
+
+# Reset state
+rm ~/.visual-forge-mcp/state.json
+
+# Restart MCP server
+```
+
+---
+
+## Advanced Topics
+
+### Custom Provider Implementation
+
+Create a new provider by extending `BaseProvider`:
+
+```typescript
+import { BaseProvider } from '../base-provider.js';
+import { ProviderType, ProviderConfig, ... } from '../../types/index.js';
+
+export class MyCustomProvider extends BaseProvider {
+  readonly name: ProviderType = 'mycustom';
+  readonly displayName = 'My Custom Provider';
+
+  constructor(config: ProviderConfig) {
+    super(config);
+    this.client.setHeader('Authorization', `Bearer ${config.apiKey}`);
+    this.init();
+  }
+
+  protected async generateImage(
+    spec: ImageSpec,
+    options?: GenerationOptions
+  ): Promise<GeneratedImage> {
+    // Implementation
+  }
+
+  adaptPrompt(prompt: string, context?: GlobalContext): string {
+    // Customize prompt for your provider
+  }
+
+  getCapabilities(): ProviderCapabilities {
+    // Return provider capabilities
+  }
+
+  async testConnection(): Promise<{ success: boolean; message: string; latency?: number }> {
+    // Test API connectivity
+  }
+}
+```
+
+Register in `ProviderFactory`:
+
+```typescript
+// src/providers/index.ts
+import { MyCustomProvider } from './mycustom/mycustom-provider.js';
+
+// In initialize()
+if (process.env.MYCUSTOM_API_KEY) {
+  const provider = new MyCustomProvider({
+    type: 'mycustom',
+    apiKey: process.env.MYCUSTOM_API_KEY,
+    endpoint: 'https://api.mycustom.com',
+    models: [
+      {
+        id: 'my-model-1',
+        name: 'My Model 1',
+        costPerImage: 0.01
+      }
+    ],
+    defaultModel: 'my-model-1',
+    costPerImage: 0.01,
+    rateLimit: 10,
+    timeout: 60000
+  });
+  this.providers.set('mycustom', provider);
+}
+```
+
+### Pricing Configuration
+
+Centralized pricing in `config/pricing.json`:
+
+```json
+{
+  "version": "2.1.0",
+  "lastUpdated": "2026-01-16",
+  "providers": {
+    "zai": {
+      "name": "Z.ai (Zhipu AI)",
+      "pricingUrl": "https://docs.z.ai/guides/overview/pricing",
+      "defaultModel": "glm-image",
+      "models": {
+        "glm-image": {
+          "name": "GLM-Image",
+          "costPerImage": 0.015,
+          "rateLimit": 15,
+          "timeout": 90000,
+          "maxDimensions": { "width": 2048, "height": 2048 },
+          "notes": "Excellent for text-heavy diagrams"
+        }
+      }
+    }
+  },
+  "costComparison": {
+    "recommended": {
+      "provider": "zai",
+      "model": "glm-image",
+      "reason": "Best for technical documentation"
+    }
+  }
+}
+```
+
+### Backup and Restore
+
+Visual Forge includes automatic backup system:
+
+**Create backup before generation**:
+```typescript
+{
+  "tool": "create_backup",
+  "parameters": {
+    "files": ["docs/architecture.md"],
+    "description": "Before architecture diagram generation"
+  }
+}
+```
+
+**List backups**:
+```typescript
+{
+  "tool": "list_backups"
+}
+```
+
+**Restore from backup**:
+```typescript
+{
+  "tool": "restore_from_backup",
+  "parameters": {
+    "backupId": "backup-20260116-063000"
+  }
+}
+```
+
+**Approve changes** (delete backups):
+```typescript
+{
+  "tool": "approve_changes"
+}
+```
+
+See [Backup System Guide](./backup-system.md) for details.
+
+### Multi-Format Optimization
+
+Generated images are automatically optimized to multiple formats:
+
+**Default formats**:
+- **WebP**: Primary format (best compression, wide support)
+- **JPEG**: Fallback for older browsers (90% quality)
+- **PNG**: Optional (disabled by default, use for transparency)
+
+**Configuration**:
+```env
+VF_GENERATE_PNG=true       # Enable PNG generation
+VF_PNG_QUALITY=85          # PNG quality 0-100
+VF_PNG_PALETTE=true        # Use palette compression
+VF_PNG_COLORS=256          # Palette colors
+VF_PNG_DITHER=1.0          # Dithering level
+```
+
+**Output structure**:
+```
+generated-images/
+└── 001-architecture-md/
+    └── zai/
+        ├── original/
+        │   └── doc-img-01.png          # Original PNG
+        ├── doc-img-01.webp              # Optimized WebP (primary)
+        ├── doc-img-01.jpg               # Optimized JPEG (fallback)
+        └── doc-img-01-optimized.png     # Optimized PNG (optional)
+```
+
+### State Persistence
+
+State file: `~/.visual-forge-mcp/state.json`
+
+**Structure**:
+```json
+{
+  "version": "1.0",
+  "session": {
+    "id": "session-20260116",
+    "createdAt": "2026-01-16T06:00:00.000Z"
+  },
+  "parsedImages": [
+    {
+      "id": "doc-img-01",
+      "file": "docs/architecture.md",
+      "type": "architecture",
+      "status": "generated"
+    }
+  ],
+  "generatedImages": [
+    {
+      "id": "doc-img-01",
+      "filepath": "generated-images/zai/doc-img-01.webp",
+      "provider": "zai",
+      "cost": 0.015
+    }
+  ],
+  "jobs": {
+    "pending": [],
+    "inProgress": [],
+    "completed": ["doc-img-01"]
+  },
+  "costs": {
+    "total": 0.015,
+    "byProvider": { "zai": 0.015 },
+    "byFile": { "docs/architecture.md": 0.015 }
+  },
+  "workflow": {
+    "mode": "bulk",
+    "status": "completed"
+  }
+}
+```
+
+**Atomic writes**: Uses temp file + rename to prevent corruption on crash.
+
+---
+
+## Next Steps
+
+1. **Explore Examples**: See [Usage Examples](./usage-examples.md)
+2. **Test Providers**: Run `npx tsx scripts/check-providers.ts`
+3. **Generate Your First Image**: Follow [Quick Start](../../README.md#quick-start)
+4. **Configure Backups**: Read [Backup System Guide](./backup-system.md)
+5. **Integrate with n8n**: See [n8n Integration](../integrations/n8n.md)
+
+---
+
+## Support & Resources
+
+- **GitHub**: https://github.com/michelabboud/visual-forge-mcp
+- **Issues**: https://github.com/michelabboud/visual-forge-mcp/issues
+- **Changelog**: [CHANGELOG.md](../../CHANGELOG.md)
+- **Architecture**: [MCP Server Architecture](../development/mcp-server-architecture.md)
+
+---
+
+**Version:** 0.7.0
+**Last Updated:** 2026-01-16
+**License:** MIT