Files
mcp-img-gen/server.mjs
T

637 lines
23 KiB
JavaScript

#!/usr/bin/env node
/**
* MCP image-gen server (thin custom wrapper around OpenRouter).
*
* Tools:
* - generate_image(prompt, model, aspect) -> opaque PNG
* - generate_image_transparent(prompt, model, aspect) -> PNG with alpha channel
* - list_image_models() -> 35 image-capable models (1h cache)
*
* Auth: Bearer token in Authorization header (token from env MCP_TOKEN).
*
* Routing:
* - sourceful/riverflow-* -> /api/v1/images (provider requires it)
* - recraft/recraft-v* -> /api/v1/images (transparent_background flag)
* - openai/gpt-image-* -> /chat/completions + image_config (background=transparent)
* - everything else -> /chat/completions + modalities:[image,text]
*
* Design notes (from mcp-image-generation skill, validated 2026-07):
* - Stateful StreamableHTTPServerTransport (sessionIdGenerator: crypto.randomUUID)
* - try/catch around fetch AND transport.handleRequest
* - AbortSignal.timeout(120_000) on upstream
* - process.stderr.write on every request/response (SDK swallows errors)
* - MODEL_CACHE 1h TTL
*/
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import {
ListToolsRequestSchema,
CallToolRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import http from 'node:http';
import crypto from 'node:crypto';
import fs from 'node:fs/promises';
import path from 'node:path';
const API_KEY = process.env.OPENROUTER_API_KEY;
const MCP_TOKEN = process.env.MCP_TOKEN;
if (!API_KEY) {
console.error('FATAL: OPENROUTER_API_KEY env not set');
process.exit(1);
}
if (!MCP_TOKEN) {
console.error('FATAL: MCP_TOKEN env not set (required to protect the endpoint)');
process.exit(1);
}
const PORT = Number(process.env.PORT || 8935);
const OUTPUT_DIR = process.env.IMAGE_MCP_OUTPUT_DIR || '/app/generated-images';
// ---------- Models that support transparent background ----------
// Recraft (v3 confirmed via OpenRouter /api/v1/images endpoint, accepts background param)
// GPT-Image (1/2/5-image) via /chat/completions with image_config.background=transparent
//
// Order matters: riverflow check first because regex is more specific.
const TRANSPARENT_MODELS = [
'recraft/recraft-v3',
'openai/gpt-image-1',
'openai/gpt-image-1-mini',
'openai/gpt-image-2',
'openai/gpt-5-image',
'openai/gpt-5-image-mini',
];
// ---------- Models known to accept image references (image-to-image / style refs) ----------
// Order matters: more specific first.
const IMAGE_REF_MODELS = new Set([
// OpenAI
'openai/gpt-image-1',
'openai/gpt-image-1-mini',
'openai/gpt-image-2',
'openai/gpt-5-image',
'openai/gpt-5-image-mini',
'openai/gpt-5.4-image-2',
// Google Gemini
'google/gemini-2.5-flash-image',
'google/gemini-3-pro-image',
'google/gemini-3.1-flash-image',
'google/gemini-3.1-flash-lite-image',
'google/gemini-3.1-flash-image-preview',
'google/gemini-3-pro-image-preview',
// ByteDance Seedream (style ref supported via seed image)
'bytedance-seed/seedream-4.5',
// FLUX 2 (in editing variants)
'black-forest-labs/flux.2-flex',
'black-forest-labs/flux.2-pro',
'black-forest-labs/flux.2-max',
]);
function isRiverflow(modelId) {
return /^sourceful\/riverflow/i.test(modelId);
}
function isRecraft(modelId) {
return /^recraft\//i.test(modelId);
}
function isGptImage(modelId) {
return /^openai\/gpt-image-/i.test(modelId) || /^openai\/gpt-5-image/i.test(modelId);
}
function isTransparentCapable(modelId) {
return TRANSPARENT_MODELS.includes(modelId);
}
// ---------- OpenRouter model catalog (cached 1h) ----------
let MODEL_CACHE = null;
let MODEL_CACHE_TIME = 0;
const MODEL_TTL_MS = 3600_000;
async function getImageModels() {
if (MODEL_CACHE && Date.now() - MODEL_CACHE_TIME < MODEL_TTL_MS) {
return MODEL_CACHE;
}
const r = await fetch(
'https://openrouter.ai/api/v1/models?output_modalities=image',
{ headers: { Authorization: `Bearer ${API_KEY}` } },
);
if (!r.ok) throw new Error(`OpenRouter /models ${r.status}`);
const data = await r.json();
MODEL_CACHE = data.data.map((m) => m.id);
MODEL_CACHE_TIME = Date.now();
process.stderr.write(`[cache] refreshed: ${MODEL_CACHE.length} image models\n`);
return MODEL_CACHE;
}
function aspectToOpenRouter(ar) {
if (ar === 'square') return '1:1';
if (ar === 'landscape') return '16:9';
if (ar === 'portrait') return '9:16';
return ar;
}
// ---------- API call router ----------
async function callOpenRouter({ prompt, model, aspect, transparent = false, imageUrls = [] }) {
if (isRiverflow(model)) return await callRiverflowImages({ prompt, model, aspect, imageUrls });
if (isRecraft(model)) return await callImagesEndpoint({ prompt, model, aspect, transparent, kind: 'recraft', imageUrls });
if (isGptImage(model)) return await callImagesEndpoint({ prompt, model, aspect, transparent, kind: 'gpt-image', imageUrls });
return await callChatCompletions({ prompt, model, aspect, imageUrls });
}
// Helper: validate that an image reference is acceptable.
// Accepts http(s) URLs and data:image/... URLs. Anything else -> warn and drop.
function normalizeImageUrls(rawUrls) {
if (!Array.isArray(rawUrls)) return [];
const out = [];
for (const u of rawUrls) {
if (typeof u !== 'string' || !u) continue;
if (/^https?:\/\//i.test(u)) { out.push(u); continue; }
if (/^data:image\//i.test(u)) { out.push(u); continue; }
process.stderr.write(`[ref] skipping unsupported ref URL: ${u.slice(0, 80)}\n`);
}
return out;
}
// Build a multimodal user message for chat completions:
// { role: 'user', content: [
// { type: 'text', text: <prompt + aspect suffix> },
// { type: 'image_url', image_url: { url: <ref> } }, ...
// ] }
function buildChatMessages({ prompt, aspect, imageUrls }) {
const ar = aspectToOpenRouter(aspect);
const text = ar ? `${prompt} (aspect ratio ${ar})` : prompt;
const content = [{ type: 'text', text }];
for (const url of imageUrls) {
content.push({ type: 'image_url', image_url: { url } });
}
return [{ role: 'user', content }];
}
async function callChatCompletions({ prompt, model, aspect, imageUrls = [] }) {
const resp = await fetch('https://openrouter.ai/api/v1/chat/completions', {
method: 'POST',
headers: {
Authorization: `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model,
messages: buildChatMessages({ prompt, aspect, imageUrls }),
modalities: ['image', 'text'],
}),
signal: AbortSignal.timeout(120_000),
});
if (!resp.ok) {
const body = await resp.text();
throw new Error(`OpenRouter chat ${resp.status}: ${body.slice(0, 600)}`);
}
const data = await resp.json();
const images = data.choices?.[0]?.message?.images;
if (!images?.length) {
const text = data.choices?.[0]?.message?.content;
throw new Error(`No images returned. Text content: ${JSON.stringify(text).slice(0, 300)}`);
}
const imgEntry = images.find((e) => e?.image_url?.url?.startsWith('data:image/'));
if (!imgEntry) throw new Error('images[] has no data: URLs (unsupported shape)');
return {
dataUrl: imgEntry.image_url.url,
provider: 'chat_completions',
mime: 'image/png',
};
}
async function callImagesEndpoint({ prompt, model, aspect, transparent, kind, imageUrls = [] }) {
// Same endpoint shape for Recraft and GPT-Image inside OpenRouter:
// POST /api/v1/images
// body: { model, prompt, size, n, background?, image? }
//
// image (single) / image[] (multiple refs) are routed by OpenRouter to models
// that accept them. Recraft v3 supports 1 image ref. GPT-Image (chat completions
// path) prefers the messages[] multimodal format — but OpenRouter also routes
// a single `image` field for some providers. We pass the image_urls through
// in BOTH places when supported to maximize compatibility — providers that
// ignore the unused field will still receive the prompt.
const sizeMap = {
square: '1024x1024',
landscape: '1536x1024',
portrait: '1024x1536',
};
const body = {
model,
prompt,
size: sizeMap[aspect] || '1024x1024',
n: 1,
};
if (transparent) {
// OpenAI Images API standard: "background": "transparent" (also accepts "opaque")
body.background = 'transparent';
}
if (imageUrls.length > 0) {
// OpenRouter accepts an array of reference image URLs via this top-level key.
// Each provider may map it to its native convention (seed image, style ref, etc).
body.image = imageUrls.length === 1 ? imageUrls[0] : imageUrls;
}
const resp = await fetch('https://openrouter.ai/api/v1/images', {
method: 'POST',
headers: {
Authorization: `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
signal: AbortSignal.timeout(120_000),
});
if (!resp.ok) {
const errBody = await resp.text();
throw new Error(
`OpenRouter /api/v1/images (${kind}) ${resp.status}: ${errBody.slice(0, 600)}`,
);
}
const data = await resp.json();
const item = data?.data?.[0];
if (!item) {
throw new Error(`${kind} returned empty data[]: ${JSON.stringify(data).slice(0, 300)}`);
}
// OpenRouter may return either b64_json directly, a data URL, or a hosted URL.
// For GPT-Image and Recraft, b64_json is most common.
let dataUrl = null;
let mime = 'image/png';
if (item.b64_json) {
dataUrl = `data:${mime};base64,${item.b64_json}`;
} else if (item.url?.startsWith('data:')) {
dataUrl = item.url;
mime = item.url.match(/^data:([^;]+);/)?.[1] || 'image/png';
} else if (item.url) {
// Hosted URL — fetch and inline-base64
const fetched = await fetch(item.url, { signal: AbortSignal.timeout(60_000) });
if (!fetched.ok) throw new Error(`${kind} URL fetch ${fetched.status}`);
const ct = fetched.headers.get('content-type') || 'image/png';
mime = ct.split(';')[0].trim();
const buf = Buffer.from(await fetched.arrayBuffer());
dataUrl = `data:${mime};base64,${buf.toString('base64')}`;
} else {
throw new Error(`${kind} response has no url or b64_json`);
}
return { dataUrl, provider: `images_ep/${kind}`, mime };
}
async function callRiverflowImages({ prompt, model, aspect, imageUrls = [] }) {
// Sourceful Riverflow lives on /api/v1/images (not chat completions).
// Riverflow accepts up to N reference images via `image_input` /
// `image_inputs` array depending on the upstream. We pass both keys for safety.
const sizeMap = {
square: '1024x1024',
landscape: '1536x1024',
portrait: '1024x1536',
};
const body = {
model,
prompt,
size: sizeMap[aspect] || '1024x1024',
n: 1,
};
if (imageUrls.length > 0) {
body.image_input = imageUrls;
body.image_inputs = imageUrls;
}
const resp = await fetch('https://openrouter.ai/api/v1/images', {
method: 'POST',
headers: {
Authorization: `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
signal: AbortSignal.timeout(120_000),
});
if (!resp.ok) {
const errBody = await resp.text();
throw new Error(
`OpenRouter /api/v1/images (riverflow) ${resp.status}: ${errBody.slice(0, 600)}`,
);
}
const data = await resp.json();
const item = data?.data?.[0];
if (!item) throw new Error('Riverflow returned empty data[]');
if (item.b64_json) {
return {
dataUrl: `data:image/png;base64,${item.b64_json}`,
provider: 'images_ep/riverflow',
mime: 'image/png',
};
}
if (item.url) {
const fetched = await fetch(item.url, { signal: AbortSignal.timeout(60_000) });
if (!fetched.ok) throw new Error(`Riverflow URL fetch ${fetched.status}`);
const buf = Buffer.from(await fetched.arrayBuffer());
return {
dataUrl: `data:image/png;base64,${buf.toString('base64')}`,
provider: 'images_ep/riverflow',
mime: 'image/png',
};
}
throw new Error('Riverflow response has no url or b64_json');
}
// ---------- Save helper ----------
async function saveImage({ dataUrl, model, prefix }) {
const base64 = dataUrl.replace(/^data:image\/\w+;base64,/, '');
const bytes = Buffer.from(base64, 'base64');
await fs.mkdir(OUTPUT_DIR, { recursive: true });
const safeModel = model.replace(/[/:]/g, '_');
const filename = `${prefix}-${safeModel}-${Date.now()}.png`;
const filepath = path.join(OUTPUT_DIR, filename);
await fs.writeFile(filepath, bytes);
return { filepath, filename, bytes: bytes.length };
}
// ---------- MCP server ----------
const server = new Server(
{ name: 'mcp-img-gen', version: '1.2.0' },
{ capabilities: { tools: {} } },
);
server.setRequestHandler(ListToolsRequestSchema, async () => {
const models = await getImageModels();
return {
tools: [
{
name: 'generate_image',
description:
'Generate an opaque (background filled) image via OpenRouter. ' +
'Aspect: square|landscape|portrait. ' +
'Optional: image_urls — list of HTTP(S) or data: URLs of reference images ' +
'(style ref, seed, i2i) — works with Gemini, GPT-Image, FLUX 2, Seedream. ' +
'Returns {model,filepath,bytes,provider,latency_ms}.',
inputSchema: {
type: 'object',
properties: {
prompt: { type: 'string', description: 'Text prompt' },
model: {
type: 'string',
enum: models,
default: 'google/gemini-2.5-flash-image',
},
aspect: {
type: 'string',
enum: ['square', 'landscape', 'portrait'],
default: 'square',
},
image_urls: {
type: 'array',
items: { type: 'string' },
description:
'Optional reference images. Each item is an http(s):// URL OR ' +
'a data:image/... URL. Up to ~4 references recommended for best ' +
'compatibility. Empty array = no refs.',
default: [],
},
},
required: ['prompt'],
},
},
{
name: 'generate_image_transparent',
description:
'Generate an image with a TRANSPARENT background (alpha channel PNG). ' +
'Only works with models that support background removal natively: ' +
'recraft/recraft-v3, openai/gpt-image-1, openai/gpt-image-1-mini, ' +
'openai/gpt-image-2, openai/gpt-5-image, openai/gpt-5-image-mini. ' +
'Other models will return an error from the upstream. ' +
'Aspect: square|landscape|portrait. ' +
'Optional image_urls — use to apply style from reference images while ' +
'keeping transparent background.',
inputSchema: {
type: 'object',
properties: {
prompt: { type: 'string', description: 'Text prompt (mention "isolated on transparent background" for best results)' },
model: {
type: 'string',
enum: TRANSPARENT_MODELS,
default: 'recraft/recraft-v3',
},
aspect: {
type: 'string',
enum: ['square', 'landscape', 'portrait'],
default: 'square',
},
image_urls: {
type: 'array',
items: { type: 'string' },
description:
'Optional reference images. Each item is an http(s):// URL OR ' +
'a data:image/... URL. For Recraft v3: single reference. ' +
'For GPT-Image: up to ~4 references recommended.',
default: [],
},
},
required: ['prompt'],
},
},
{
name: 'list_image_models',
description: 'List 35 image-capable models on OpenRouter (cached 1h).',
inputSchema: { type: 'object', properties: {} },
},
{
name: 'get_image',
description:
'Read a previously generated image by filename. Returns multipart content: ' +
'one inline image (base64) + one text metadata block. Use this if you want ' +
'to re-fetch an image after a generate_image call (file persists across ' +
'the same container lifetime but is lost on container restart). ' +
'Filename is the value returned in the generate_image metadata.',
inputSchema: {
type: 'object',
properties: {
filename: {
type: 'string',
description:
'Filename as returned in `filename` field from generate_image / ' +
'generate_image_transparent output (e.g. ' +
'"opaque-google_gemini-2.5-flash-image-1783615606608.png").',
},
},
required: ['filename'],
},
},
],
};
});
server.setRequestHandler(CallToolRequestSchema, async (req) => {
const { name, arguments: args } = req.params;
try {
if (name === 'list_image_models') {
const list = (await getImageModels()).join('\n');
return {
content: [
{
type: 'text',
text: `# OpenRouter image models (${MODEL_CACHE.length})\n\n${list}`,
},
],
};
}
if (name === 'generate_image' || name === 'generate_image_transparent') {
const prompt = String(args?.prompt || '').trim();
if (!prompt) return errResp('prompt required');
const aspect = args?.aspect || 'square';
const imageUrls = normalizeImageUrls(args?.image_urls || []);
let model;
if (name === 'generate_image_transparent') {
model = args?.model || 'recraft/recraft-v3';
if (!isTransparentCapable(model)) {
return errResp(
`Model ${model} is not in the transparent-capable list. ` +
`Use one of: ${TRANSPARENT_MODELS.join(', ')}`,
);
}
} else {
model = args?.model || 'google/gemini-2.5-flash-image';
}
const transparent = name === 'generate_image_transparent';
if (imageUrls.length > 0 && !IMAGE_REF_MODELS.has(model)) {
process.stderr.write(
`[gen] WARN: ${imageUrls.length} image_ref(s) passed but model ${model} may not support refs. Will be forwarded anyway as chat-completions image_url parts or top-level image[] field.\n`,
);
}
process.stderr.write(
`[gen] req tool=${name} model=${model} aspect=${aspect} transparent=${transparent} refs=${imageUrls.length} prompt="${prompt.slice(0, 80)}"\n`,
);
const t0 = Date.now();
const { dataUrl, provider, mime } = await callOpenRouter({
prompt, model, aspect, transparent, imageUrls,
});
const { filepath, filename, bytes } = await saveImage({
dataUrl, model, prefix: transparent ? 'transparent' : 'opaque',
});
process.stderr.write(
`[gen] OK provider=${provider} mime=${mime} ${Date.now() - t0}ms ${filepath} ${bytes}b\n`,
);
// Return multipart content: image inline (base64) + text metadata.
// The image block lets MCP clients (Cursor, Claude Desktop, Figma) render
// the picture directly in the chat without an extra tool call.
// The text block exposes structured metadata for the agent / user.
const meta = {
tool: name,
model,
provider,
mime,
aspect,
transparent,
refs_used: imageUrls.length,
filepath,
filename,
bytes,
latency_ms: Date.now() - t0,
};
return {
content: [
{
type: 'image',
mimeType: mime,
data: bytes.toString('base64'),
},
{
type: 'text',
text: JSON.stringify(meta, null, 2),
},
],
};
}
if (name === 'get_image') {
const filename = String(args?.filename || '').trim();
if (!filename) return errResp('filename required');
// Security: prevent path escape — only flat filenames in OUTPUT_DIR.
if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
return errResp('filename must be a flat name (no path separators)');
}
const filepath = path.join(OUTPUT_DIR, filename);
let buf;
try {
buf = await fs.readFile(filepath);
} catch (e) {
return errResp(`Image not found: ${filename} (container may have restarted)`);
}
const mime = filename.endsWith('.png')
? 'image/png'
: filename.endsWith('.jpg') || filename.endsWith('.jpeg')
? 'image/jpeg'
: filename.endsWith('.webp')
? 'image/webp'
: 'application/octet-stream';
process.stderr.write(`[get] OK ${filename} ${buf.length}b\n`);
return {
content: [
{ type: 'image', mimeType: mime, data: buf.toString('base64') },
{
type: 'text',
text: JSON.stringify({ filename, filepath, bytes: buf.length, mime }, null, 2),
},
],
};
}
return errResp(`Unknown tool: ${name}`);
} catch (e) {
process.stderr.write(`[gen-ERR] ${e.stack || e}\n`);
return {
content: [{ type: 'text', text: `Error: ${e.message}` }],
isError: true,
};
}
});
function errResp(text) {
return { content: [{ type: 'text', text }], isError: true };
}
// ---------- HTTP transport w/ Bearer auth ----------
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => crypto.randomUUID(),
});
await server.connect(transport);
const httpServer = http.createServer(async (req, res) => {
if (!req.url.startsWith('/health')) {
const auth = req.headers.authorization || '';
const expected = `Bearer ${MCP_TOKEN}`;
if (auth !== expected) {
process.stderr.write(`[auth] denied ${req.method} ${req.url}\n`);
res.statusCode = 401;
res.setHeader('www-authenticate', 'Bearer');
res.setHeader('content-type', 'application/json');
res.end(JSON.stringify({ error: 'invalid or missing token' }));
return;
}
}
if (req.url === '/health') {
res.statusCode = 200;
res.setHeader('content-type', 'application/json');
res.end(JSON.stringify({ ok: true, version: '1.2.0', uptime: process.uptime() }));
return;
}
process.stderr.write(`[HTTP] ${req.method} ${req.url} -> incoming\n`);
try {
await transport.handleRequest(req, res);
process.stderr.write(`[HTTP] ${req.method} ${req.url} -> ${res.statusCode}\n`);
} catch (e) {
process.stderr.write(`[HTTP-ERR] ${e.stack || e}\n`);
if (!res.headersSent) {
res.statusCode = 500;
res.setHeader('content-type', 'application/json');
res.end(JSON.stringify({ error: e.message }));
}
}
});
httpServer.listen(PORT, '0.0.0.0', () => {
process.stderr.write(`mcp-img-gen listening on http://0.0.0.0:${PORT}\n`);
});