pixel-surgeon-mcp 1.0.0 → 1.1.1

package/README.md

@@ -6,13 +6,14 @@
 
 <p align="center">
   <strong>MCP server for AI image &amp; video generation, editing, and transplant-grade region repair</strong><br/>
-  Powered by Gemini 3.1 Flash Image, OpenAI GPT Image 2, and Veo 3
+  Powered by Gemini 3.1 Flash Image, OpenAI GPT Image 2, Grok Imagine, and Veo 3
 </p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/MCP-stdio-blue" alt="MCP stdio" />
   <img src="https://img.shields.io/badge/Gemini_3.1-Flash_Image-4285F4?logo=google" alt="Gemini" />
   <img src="https://img.shields.io/badge/GPT_Image_2-OpenAI-412991?logo=openai&logoColor=white" alt="OpenAI" />
+  <img src="https://img.shields.io/badge/Grok_Imagine-xAI-000000?logo=x&logoColor=white" alt="Grok" />
   <img src="https://img.shields.io/badge/Veo_3-Video-34A853?logo=google" alt="Veo 3" />
   <img src="https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
 </p>
@@ -23,15 +24,19 @@ An [MCP](https://modelcontextprotocol.io) server that gives Claude (or any MCP c
 
 ## How it works
 
-pixel-surgeon-mcp is a **multi-provider** image generation server. You can use either or both providers, and switch between them per-request:
+pixel-surgeon-mcp is a **multi-provider** image generation server. You can use any combination of providers and switch between them per-request:
 
-### Gemini (Google)
+### Gemini (Google) — balanced
 
-Google's image generation pipeline uses a two-stage approach: **Gemini 3.1 Pro** reasons about your prompt, then **Gemini 3.1 Flash Image** renders the pixels. Supports 9 aspect ratios at 512/1K/2K/4K resolution.
+Google's image generation pipeline uses a two-stage approach: **Gemini 3.1 Pro** reasons about your prompt, then **Gemini 3.1 Flash Image** renders the pixels. Supports 9 aspect ratios at 512/1K/2K/4K resolution. Best price/performance ratio, with a free tier available.
 
-### OpenAI GPT Image 2
+### OpenAI GPT Image 2 — highest quality
 
-OpenAI's latest image model with dramatically improved text rendering and visual fidelity. Supports flexible resolutions — pixel-surgeon maps your chosen size and aspect ratio to the optimal pixel dimensions automatically. Quality levels: `medium` (fast) and `high` (print-ready). **Excellent for infographics, diagrams, and text-heavy images** where Gemini models struggle.
+OpenAI's latest image model with dramatically improved text rendering and visual fidelity. Supports flexible resolutions — pixel-surgeon maps your chosen size and aspect ratio to the optimal pixel dimensions automatically. Quality levels: `medium` (fast) and `high` (print-ready). **Excellent for infographics, diagrams, and text-heavy images** where other models struggle. Slower and more expensive.
+
+### Grok Imagine (xAI) — fastest
+
+xAI's Aurora-powered image model. Fastest generation speed and lowest cost. Supports 7 aspect ratios at fixed resolutions (~1K). Good for rapid prototyping and iteration.
 
 ### Veo 3 (Video)
 
@@ -64,6 +69,7 @@ AI image models struggle with text-heavy images. The fix tools solve this by sen
 | `gemini-2.5-flash-image` | Google | 1K max (free tier) | Quick drafts, prototyping |
 | `gpt-image-2` | OpenAI | Flexible (up to 4K) | Text-heavy images, infographics, diagrams, typography |
 | `gpt-image-1` | OpenAI | 3 fixed sizes | Legacy support |
+| `grok-imagine` | xAI | Fixed (~1K per ratio) | Fast iteration, lowest cost |
 
 Force a specific model per-call via the `model` tool parameter, or set `DEFAULT_IMAGE_MODEL` env var.
 
@@ -80,10 +86,10 @@ Magazine editorial, bold typography, halftone textures. Cream, black, and terrac
 
 <img src="assets/style-neo-brutalist.png" alt="neo-brutalist style example" width="400" />
 
-### `neo-retro-futurism`
-1960s Space Age meets 1980s arcade. Cathode blue, amber, and salmon palette.
+### `duval-software-infographic`
+Duval Software's signature retro-futurist infographic style. 1960s Space Age meets 1980s arcade. Cathode blue, amber, and salmon palette. Great for diagrams and system overviews.
 
-<img src="assets/style-neo-retro-futurism.png" alt="neo-retro-futurism style example" width="400" />
+<img src="assets/style-neo-retro-futurism.png" alt="duval-software-infographic style example" width="400" />
 
 ### `fractal-arcade`
 Dithered fractals, Sierpinski patterns, low-poly. CRT retro, Amiga/EGA palette.
@@ -99,7 +105,7 @@ Technical diagrams, system flows, data pipelines. Dark navy, cyan, and electric
 
 ### Get your API key(s)
 
-You need at least one provider API key. You can use both for maximum flexibility.
+You need at least one provider API key. You can use any combination for maximum flexibility.
 
 #### Google (Gemini + Veo 3)
 
@@ -118,45 +124,59 @@ You need at least one provider API key. You can use both for maximum flexibility
 
 > GPT Image 2 excels at text rendering, infographics, and diagrams. If you primarily need text-heavy images, this is the provider to use.
 
-### Prerequisites
+#### xAI (Grok Imagine)
+
+1. Go to [xAI Console](https://console.x.ai/)
+2. Sign in or create an account
+3. Create an API key and copy it
+
+> Grok Imagine is the fastest and cheapest provider. Great for rapid iteration and prototyping. Fixed output resolutions (~1K) with no size control.
 
-- Node.js 18+
+### Quick start (npx)
 
-### Install
+No install needed — run directly with npx. Pass whichever API keys you have:
 
 ```bash
-git clone https://github.com/j-east/pixel-surgeon-mcp.git
-cd pixel-surgeon-mcp
-npm install
-npm run build
+npx pixel-surgeon-mcp
 ```
 
-### Configure your MCP client
+#### Claude Code CLI
 
-Add to your Claude Code or Claude Desktop config. Include whichever API keys you have:
+```bash
+claude mcp add pixel-surgeon \
+  -e GOOGLE_API_KEY=your-google-key \
+  -e OPENAI_API_KEY=your-openai-key \
+  -e XAI_API_KEY=your-xai-key \
+  -- npx pixel-surgeon-mcp
+```
+
+#### Claude Desktop / MCP client config
 
 ```json
 {
   "mcpServers": {
     "pixel-surgeon": {
-      "command": "node",
-      "args": ["/path/to/pixel-surgeon-mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["pixel-surgeon-mcp"],
       "env": {
         "GOOGLE_API_KEY": "your-google-api-key",
-        "OPENAI_API_KEY": "your-openai-api-key"
+        "OPENAI_API_KEY": "your-openai-api-key",
+        "XAI_API_KEY": "your-xai-api-key"
       }
     }
   }
 }
 ```
 
-Or via the Claude Code CLI:
+### Install from source
+
+If you prefer a local clone:
 
 ```bash
-claude mcp add pixel-surgeon \
-  -e GOOGLE_API_KEY=your-google-key \
-  -e OPENAI_API_KEY=your-openai-key \
-  -- node /path/to/pixel-surgeon-mcp/dist/index.js
+git clone https://github.com/j-east/pixel-surgeon-mcp.git
+cd pixel-surgeon-mcp
+npm install
+npm run build
 ```
 
 ### Image output
@@ -192,7 +212,7 @@ Add entries to the `STYLE_PRESETS` object in `src/index.ts`. Your PR should incl
 
 ### Model adapters
 
-The server currently supports Gemini, OpenAI, and Veo 3. We'd love adapters for other image/video generation APIs — Stable Diffusion, Flux, etc. If you're interested in adding one, open an issue first so we can align on the interface.
+The server currently supports Gemini, OpenAI, Grok Imagine, and Veo 3. We'd love adapters for other image/video generation APIs — Stable Diffusion, Flux, etc. If you're interested in adding one, open an issue first so we can align on the interface.
 
 ## Built by Duval Software
 

package/dist/index.js

@@ -39,15 +39,16 @@ function loadKeysFromClaudeConfig() {
         const configPath = join(homedir(), ".claude.json");
         const config = JSON.parse(readFileSync(configPath, "utf-8"));
         const env = config?.mcpServers?.["pixel-surgeon"]?.env ?? {};
-        return { google: env.GOOGLE_API_KEY ?? "", openai: env.OPENAI_API_KEY ?? "" };
+        return { google: env.GOOGLE_API_KEY ?? "", openai: env.OPENAI_API_KEY ?? "", xai: env.XAI_API_KEY ?? "" };
     }
     catch {
-        return { google: "", openai: "" };
+        return { google: "", openai: "", xai: "" };
     }
 }
-const _claudeKeys = (!process.env.GOOGLE_API_KEY && !process.env.OPENAI_API_KEY) ? loadKeysFromClaudeConfig() : { google: "", openai: "" };
+const _claudeKeys = (!process.env.GOOGLE_API_KEY && !process.env.OPENAI_API_KEY && !process.env.XAI_API_KEY) ? loadKeysFromClaudeConfig() : { google: "", openai: "", xai: "" };
 const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || _claudeKeys.google;
 const OPENAI_API_KEY = process.env.OPENAI_API_KEY || _claudeKeys.openai;
+const XAI_API_KEY = process.env.XAI_API_KEY || _claudeKeys.xai;
 const MODELS = {
     "gemini-3.1-flash-image": {
         id: "gemini-3.1-flash-image-preview",
@@ -73,6 +74,12 @@ const MODELS = {
         provider: "openai",
         tier: "paid",
     },
+    "grok-imagine": {
+        id: "grok-imagine-image-quality",
+        label: "Grok Imagine (xAI)",
+        provider: "xai",
+        tier: "paid",
+    },
 };
 const MODEL_KEYS = Object.keys(MODELS);
 const GEMINI_DEFAULT = "gemini-3.1-flash-image";
@@ -99,7 +106,7 @@ function getProvider(modelKey) {
         throw new Error(`Unknown model "${key}". Available: ${MODEL_KEYS.join(", ")}`);
     const provider = providers[entry.provider];
     if (!provider) {
-        const envHint = entry.provider === "gemini" ? "GOOGLE_API_KEY" : "OPENAI_API_KEY";
+        const envHint = entry.provider === "gemini" ? "GOOGLE_API_KEY" : entry.provider === "xai" ? "XAI_API_KEY" : "OPENAI_API_KEY";
         throw new Error(`Provider "${entry.provider}" not available. Set ${envHint} env var.`);
     }
     return { provider, modelId: entry.id, modelKey: key };
@@ -1433,6 +1440,104 @@ class OpenAIProvider {
         return { imageBase64, text: "", modelUsed: req.modelId };
     }
 }
+const GROK_ASPECT_MAP = {
+    "1:1": "1:1", "16:9": "16:9", "9:16": "9:16",
+    "3:4": "3:4", "4:3": "4:3", "2:3": "2:3", "3:2": "3:2",
+    "4:5": "3:4", "5:4": "4:3",
+};
+function grokAspect(aspectRatio) {
+    return GROK_ASPECT_MAP[aspectRatio] ?? "1:1";
+}
+class GrokProvider {
+    name = "xai";
+    async generate(req) {
+        const aspect = grokAspect(req.aspectRatio);
+        const t0 = Date.now();
+        log(`  Calling xAI ${req.modelId} generate (aspect=${aspect})...`);
+        let res;
+        try {
+            res = await fetch("https://api.x.ai/v1/images/generations", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${XAI_API_KEY}`,
+                },
+                body: JSON.stringify({
+                    model: req.modelId,
+                    prompt: req.prompt,
+                    n: 1,
+                    aspect_ratio: aspect,
+                    response_format: "b64_json",
+                }),
+            });
+        }
+        catch (fetchErr) {
+            throw new Error(`Network error calling xAI API: ${fetchErr instanceof Error ? fetchErr.message : String(fetchErr)}`);
+        }
+        const elapsed = Date.now() - t0;
+        log(`  xAI responded HTTP ${res.status} in ${(elapsed / 1000).toFixed(1)}s`);
+        const rawBody = await res.text();
+        let data;
+        try {
+            data = JSON.parse(rawBody);
+        }
+        catch {
+            throw new Error(`xAI API returned non-JSON (HTTP ${res.status}). Raw body: ${rawBody.slice(0, 2000)}`);
+        }
+        if (!res.ok || data.error) {
+            throw new Error(`xAI API HTTP ${res.status}: ${data.error?.message ?? rawBody.slice(0, 2000)}`);
+        }
+        const imageBase64 = data.data?.[0]?.b64_json;
+        if (!imageBase64) {
+            throw new Error(`xAI returned no image data. Response: ${rawBody.slice(0, 2000)}`);
+        }
+        log(`  Got image: ${(imageBase64.length / 1024).toFixed(0)}KB base64 from ${req.modelId}`);
+        return { imageBase64, text: "", modelUsed: req.modelId };
+    }
+    async edit(req) {
+        const t0 = Date.now();
+        log(`  Calling xAI ${req.modelId} edit...`);
+        let res;
+        try {
+            res = await fetch("https://api.x.ai/v1/images/edits", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${XAI_API_KEY}`,
+                },
+                body: JSON.stringify({
+                    model: req.modelId,
+                    prompt: req.prompt,
+                    image: { url: `data:${req.imageMime};base64,${req.imageBase64}`, type: "image_url" },
+                    n: 1,
+                    response_format: "b64_json",
+                }),
+            });
+        }
+        catch (fetchErr) {
+            throw new Error(`Network error calling xAI edit API: ${fetchErr instanceof Error ? fetchErr.message : String(fetchErr)}`);
+        }
+        const elapsed = Date.now() - t0;
+        log(`  xAI edit responded HTTP ${res.status} in ${(elapsed / 1000).toFixed(1)}s`);
+        const rawBody = await res.text();
+        let data;
+        try {
+            data = JSON.parse(rawBody);
+        }
+        catch {
+            throw new Error(`xAI edit API returned non-JSON (HTTP ${res.status}). Raw body: ${rawBody.slice(0, 2000)}`);
+        }
+        if (!res.ok || data.error) {
+            throw new Error(`xAI edit API HTTP ${res.status}: ${data.error?.message ?? rawBody.slice(0, 2000)}`);
+        }
+        const imageBase64 = data.data?.[0]?.b64_json;
+        if (!imageBase64) {
+            throw new Error(`xAI edit returned no image data. Response: ${rawBody.slice(0, 2000)}`);
+        }
+        log(`  Got image: ${(imageBase64.length / 1024).toFixed(0)}KB base64 from ${req.modelId} edit`);
+        return { imageBase64, text: "", modelUsed: req.modelId };
+    }
+}
 // --- Veo API ---
 async function callVeo(prompt, aspectRatio, durationSeconds) {
     const t0 = Date.now();
@@ -1555,7 +1660,8 @@ const EXPLICIT_FREE_NOTICE = `\u2139\uFE0F Generated with ${MODEL_FALLBACK} (Gem
     `For higher-quality image generation, pass model='${GEMINI_DEFAULT}' — this requires prepaid credits on your Google AI account.`;
 const MODEL_PARAM_DESCRIPTION = `Model to use. Available: ${MODEL_KEYS.map(k => `'${k}' (${MODELS[k].label})`).join(", ")}. ` +
     `Default: '${getDefaultModelKey()}'. Set DEFAULT_IMAGE_MODEL env var to change the default. ` +
-    `Gemini models fall back to free tier on billing errors. OpenAI requires OPENAI_API_KEY.`;
+    `Provider tradeoffs: grok-imagine is fastest and cheapest; gemini is mid-quality with the best price/performance ratio (free tier available); gpt-image-2 is highest quality but slower and more expensive. ` +
+    `Gemini models fall back to free tier on billing errors. OpenAI requires OPENAI_API_KEY. Grok requires XAI_API_KEY.`;
 function noticeFor(modelUsed, explicitModelKey) {
     if (explicitModelKey && MODELS[explicitModelKey]?.provider !== "gemini")
         return "";
@@ -1583,8 +1689,8 @@ const STYLE_PRESETS = {
         promptPrefix: "Neo-brutalist minimalist design. Magazine editorial style layout. Off-white / cream background with bold black typography in a heavy-weight grotesque sans-serif font, slightly overlapping and breaking the grid. Accent color: muted burnt orange or terracotta used sparingly as stripe or block elements. Raw, unpolished aesthetic — visible grid lines, asymmetric layout, oversized type that bleeds off edges. Subtle halftone texture overlay. Monospaced subtext in lowercase. No gradients, no glossy effects, no heavy saturation. Clean but edgy, restrained but bold.",
         defaultAspectRatio: "4:5",
     },
-    "duval-software-infographic": {
-        description: "Duval Software's signature retro-futurist infographic style. 1960s Space Age optimism meets 1980s arcade aesthetics. Cathode blue, warm amber, salmon red, warm green palette. CRT scanlines, atomic-age geometry, pixel-grid accents. Great for diagrams, system overviews, and technical illustrations.",
+    "retro-futuristic-arcade": {
+        description: "Retro-futurist infographic style. 1960s Space Age optimism meets 1980s arcade aesthetics. Cathode blue, warm amber, salmon red, warm green palette. CRT scanlines, atomic-age geometry, pixel-grid accents. Great for diagrams, system overviews, and technical illustrations.",
         promptPrefix: "Neo-retro-futurism style. Blend of 1960s Space Age futurism and 1980s video game aesthetics with a modern neo-retro sensibility. Color palette: deep cathode-ray blue (#1a3a5c to #4a9eff glowing CRT blue), warm amber (#d4a017 to #ffcc44), salmon red (#e8735a to #ff6b6b), and warm muted greens (#5a8a5c to #8bbd7b). Dark background evoking a CRT monitor with subtle scanline texture and faint phosphor glow. Typography: mix of retrofuturist geometric sans-serif (like Eurostile, Microgramma, or Bank Gothic) with pixel-grid or bitmap-style secondary text. Design elements: atomic-age starbursts, orbital ellipses, rounded-rectangle pods, jet-age swooshes, and subtle 8-bit pixel patterns along borders or dividers. Faint CRT curvature vignette at edges. Thin vector grid lines receding to a vanishing point. Icons and illustrations should feel like arcade cabinet art meets Googie architecture meets NASA mission patches. Warm analog glow on all light sources — no harsh pure whites, everything filtered through amber or blue phosphor. The overall mood is optimistic, adventurous, and slightly nostalgic — a future that never was, rendered through a cathode ray tube.",
         defaultAspectRatio: "4:5",
     },
@@ -1593,8 +1699,8 @@ const STYLE_PRESETS = {
         promptPrefix: "Geometric dithered illustration style. All shading done through dithering patterns, halftone dots, and geometric cross-hatch grids — NO smooth gradients anywhere. Every surface rendered with visible pixel-level dithering like a 16-color EGA/VGA palette pushed through ordered Bayer matrix dithering. Fractal geometric patterns in the background — Sierpinski triangles, hexagonal tessellations, recursive diamond grids. Color palette: deep cathode-ray blue (#1a3a5c to #4a9eff), warm amber (#d4a017 to #ffcc44), salmon red (#e8735a), warm muted greens (#5a8a5c). Subjects built from clean geometric shapes — triangular facets, polygonal planes, like a low-poly render but flat and 2D with dithered color fills instead of smooth shading. Think: Saul Bass designed a character select screen for an Amiga game. Geometric line-art icons. Chunky retrofuturist typeface for headers, smaller geometric caps for subtitles. Horizontal scanline overlay. No photorealism, no soft shadows, no AI-gradient smoothness. Every color transition is a hard dither pattern. Clean, precise, geometric, but retro-cool.",
         defaultAspectRatio: "4:5",
     },
-    "clean-tech-infographic": {
-        description: "Clean technical infographic for architecture diagrams, system flows, and data pipelines. Dark navy background, cyan/electric blue glowing connection lines, geometric nodes, professional and precise.",
+    "duval-software-infographic": {
+        description: "Duval Software's clean technical infographic for architecture diagrams, system flows, and data pipelines. Dark navy background, cyan/electric blue glowing connection lines, geometric nodes, professional and precise.",
         promptPrefix: "Clean, professional technical infographic on a dark navy (#0a1628) background with subtle grid lines. Use cyan (#00d4ff) and electric blue (#4a9eff) glowing connection lines between components. White and light gray text only — no bright colors for text. Components rendered as clean geometric shapes: rounded rectangles, hexagons, circles with thin borders and subtle inner glow. Icons are minimal line-art style (server racks, phones, browsers, databases, cloud services). Typography: modern sans-serif (like Inter or SF Pro) — bold for titles, regular weight for labels, monospace for technical details (ports, protocols, versions). Layout follows clear left-to-right or top-to-bottom data flow with labeled arrows showing protocols and data formats. No decorative illustrations, no clip art, no logos, no random embellishments. Include a thin tech stack bar at the bottom. The overall feel is a polished engineering diagram you'd present to a CTO — precise, minimal, and authoritative.",
         defaultAspectRatio: "16:9",
     },
@@ -2529,17 +2635,21 @@ async function main() {
         providers["openai"] = new OpenAIProvider();
         log("OpenAI provider available");
     }
+    if (XAI_API_KEY) {
+        providers["xai"] = new GrokProvider();
+        log("xAI/Grok provider available");
+    }
     if (process.argv.includes("--viewer")) {
-        if (!GOOGLE_API_KEY && !OPENAI_API_KEY) {
-            console.log("Note: No API keys set — viewer is read-only (respin disabled). Set GOOGLE_API_KEY or OPENAI_API_KEY to enable generation.");
+        if (!GOOGLE_API_KEY && !OPENAI_API_KEY && !XAI_API_KEY) {
+            console.log("Note: No API keys set — viewer is read-only (respin disabled). Set GOOGLE_API_KEY, OPENAI_API_KEY, or XAI_API_KEY to enable generation.");
         }
         viewerPort = await startViewer();
         console.log(`pixel-surgeon-mcp viewer running at http://localhost:${viewerPort}`);
         openExternal(`http://localhost:${viewerPort}`);
         return;
     }
-    if (!GOOGLE_API_KEY && !OPENAI_API_KEY) {
-        log("WARNING: Neither GOOGLE_API_KEY nor OPENAI_API_KEY is set. No image providers available.");
+    if (!GOOGLE_API_KEY && !OPENAI_API_KEY && !XAI_API_KEY) {
+        log("WARNING: No API keys set (GOOGLE_API_KEY, OPENAI_API_KEY, XAI_API_KEY). No image providers available.");
     }
     log(`Default model: ${getDefaultModelKey()}`);
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixel-surgeon-mcp",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "mcpName": "io.github.j-east/pixel-surgeon",
   "main": "dist/index.js",
   "type": "module",