image-proxy-mcp 1.0.0

package/.env.example

@@ -0,0 +1,35 @@
+# ============================================================
+# Image Proxy MCP - Environment Configuration
+# ============================================================
+# Copy this to .env and fill in your values.
+#
+# AUTHENTICATION
+# ==============
+# Two modes supported (per endpoint):
+#   1. Managed Identity (recommended) - leave API key blank, run az login
+#   2. API Key - set the key env var below
+#
+# If an API key is set, it takes priority. If blank, the server
+# uses DefaultAzureCredential (az login locally, system-assigned
+# MI on Azure). Same zero-secret approach as the main MCP server.
+#
+# Azure OpenAI (for gpt-image-1.5, dall-e-3, etc.)
+# ============================================================
+AZURE_OPENAI_ENDPOINT=https://aoai-sweden-csa.openai.azure.com/
+# AZURE_OPENAI_API_KEY=           # Leave blank for managed identity
+AZURE_OPENAI_API_VERSION=2024-02-01
+
+# ============================================================
+# Azure AI Services Serverless (for flux-kontext-pro, etc.)
+# The endpoint below is the serverless model endpoint, NOT the
+# resource-level endpoint. Find it in Azure AI Foundry under
+# the deployment's "Target URI".
+# ============================================================
+AZURE_AI_SERVICES_ENDPOINT=https://aoai-sweden-csa.services.ai.azure.com/
+# AZURE_AI_SERVICES_KEY=          # Leave blank for managed identity
+
+# ============================================================
+# Output directory for generated images
+# Default: ~/Documents/generated-images
+# ============================================================
+IMAGE_OUTPUT_DIR=~/Documents/generated-images

package/README.md

@@ -0,0 +1,114 @@
+# Image Proxy MCP Server
+
+Local MCP server (stdio transport) that proxies image generation to Azure endpoints, saves results to disk, and returns **only file paths** to Claude Desktop. This eliminates the base64 context window overflow problem entirely.
+
+## The Problem
+
+When Claude Desktop calls image generation through the remote multimodel MCP, the response includes base64-encoded image data (1-4MB of text per image). This consumes 30-60% of the available context window and frequently causes failures.
+
+## The Solution
+
+This local MCP server:
+1. Receives the image generation request from Claude Desktop
+2. Calls the Azure endpoint directly via HTTP
+3. Receives the base64 response server-side (never enters the context)
+4. Saves the image to a local directory
+5. Returns only a compact JSON with the file path (~200 bytes vs ~2MB)
+
+## Setup
+
+### 1. Install Dependencies
+
+```bash
+cd tools/image-proxy
+npm install
+```
+
+### 2. Configure Environment
+
+```bash
+cp .env.example .env
+# Edit .env with your Azure endpoints (keys are optional)
+```
+
+**Authentication** — two modes, per endpoint:
+
+| Mode | Setup | When to use |
+|------|-------|-------------|
+| **Managed Identity** (recommended) | Set endpoints only, leave keys blank. Run `az login` locally. | Zero secrets, same as main MCP server |
+| **API Key** | Set both endpoint + key env vars | Quick testing, no az login needed |
+
+If a key is set, it takes priority. If blank, the server uses `DefaultAzureCredential` (`az login` locally, system-assigned MI on Azure).
+
+You need endpoints for:
+- **Azure OpenAI** (for gpt-image-1.5, dall-e-3) — `cognitiveservices.azure.com`
+- **Azure AI Services** (for flux-kontext-pro) — `services.ai.azure.com`
+
+Both are in your Azure AI Foundry portal under each deployment.
+
+### 3. Test
+
+```bash
+node test.js
+```
+
+### 4. Add to Claude Desktop
+
+Add the `image-proxy` entry to your Claude Desktop config:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "image-proxy": {
+      "command": "node",
+      "args": ["/absolute/path/to/tools/image-proxy/index.js"],
+      "env": {
+        "AZURE_OPENAI_ENDPOINT": "https://your-resource.openai.azure.com",
+        "AZURE_AI_SERVICES_ENDPOINT": "https://your-resource.services.ai.azure.com",
+        "IMAGE_OUTPUT_DIR": "~/Documents/generated-images"
+      }
+    }
+  }
+}
+```
+
+With managed identity, only endpoints are needed — no keys. Run `az login` and the server authenticates automatically. To use API keys instead, add `AZURE_OPENAI_API_KEY` and/or `AZURE_AI_SERVICES_KEY` to the `env` block.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `generate_image` | Generate an image and save to disk. Returns only the file path. Models: gpt-image-1.5, dall-e-3, flux-kontext-pro |
+| `base64_to_file` | Convert a base64 string already in context to a file on disk |
+| `list_generated_images` | List all previously generated images with metadata |
+| `cleanup_images` | Remove old generated images (dry_run=true by default) |
+
+## Architecture
+
+```
+Claude Desktop
+    |
+    |-- (stdio) --> image-proxy MCP (LOCAL)
+    |                   |
+    |                   |-- (HTTPS) --> Azure OpenAI (gpt-image-1.5, dall-e-3)
+    |                   |-- (HTTPS) --> Azure AI Services (flux-kontext-pro)
+    |                   |
+    |                   v
+    |               ~/Documents/generated-images/
+    |                   |
+    |                   v
+    |               Returns: { filePath, model, size } (~200 bytes)
+    |
+    |-- (HTTP)  --> multimodel MCP (Azure, for non-image tasks)
+```
+
+## Context Window Savings
+
+| Scenario | Without Proxy | With Proxy |
+|----------|--------------|------------|
+| 1 image (1024x1024) | ~2-4 MB base64 in context | ~200 bytes path |
+| 3 images in conversation | Context overflow / failure | ~600 bytes |
+| Image + follow-up edits | Cascading failures | Works normally |

package/index.js

@@ -0,0 +1,875 @@
+#!/usr/bin/env node
+// ============================================================
+// Image Proxy MCP Server
+// ============================================================
+// Generates images via Azure endpoints, saves to local disk,
+// and returns only the file path to Claude Desktop. This keeps
+// base64 image data OUT of the context window entirely.
+//
+// Supported models:
+//   - gpt-image-1.5  (Azure OpenAI pattern)
+//   - flux-kontext-pro (Azure AI Services serverless pattern)
+//
+// Tools exposed:
+//   - generate_image: prompt -> file path
+//   - base64_to_file: base64 string -> file path (utility)
+//   - list_generated_images: lists all saved images
+//   - cleanup_images: remove old generated images
+// ============================================================
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { DefaultAzureCredential } from "@azure/identity";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Load .env if present (dotenv is optional - falls back to process.env)
+try {
+  const dotenv = await import("dotenv");
+  dotenv.config({ path: path.join(__dirname, ".env") });
+} catch {
+  // dotenv not installed - rely on process.env or Claude Desktop env block
+}
+
+const CONFIG = {
+  azureOpenAI: {
+    endpoint: process.env.AZURE_OPENAI_ENDPOINT || "",
+    apiKey: process.env.AZURE_OPENAI_API_KEY || "",
+    apiVersion: process.env.AZURE_OPENAI_API_VERSION || "2024-02-01",
+  },
+  azureAIServices: {
+    endpoint: process.env.AZURE_AI_SERVICES_ENDPOINT || "",
+    apiKey: process.env.AZURE_AI_SERVICES_KEY || "",
+  },
+  outputDir:
+    process.env.IMAGE_OUTPUT_DIR ||
+    path.join(process.env.HOME || "/tmp", "Documents", "generated-images"),
+};
+
+// ---------------------------------------------------------------------------
+// Authentication: Managed Identity (DefaultAzureCredential) or API keys
+// ---------------------------------------------------------------------------
+// Priority: API key env vars win if set; otherwise use managed identity
+// (az login locally, system-assigned MI on Azure).
+const USE_KEY_AUTH_OPENAI = !!CONFIG.azureOpenAI.apiKey;
+const USE_KEY_AUTH_AI_SERVICES = !!CONFIG.azureAIServices.apiKey;
+
+const credential =
+  !USE_KEY_AUTH_OPENAI || !USE_KEY_AUTH_AI_SERVICES
+    ? new DefaultAzureCredential()
+    : null;
+
+const COGNITIVE_SCOPE = "https://cognitiveservices.azure.com/.default";
+
+/** Get a Bearer token for Azure Cognitive Services. Cached internally by the SDK. */
+async function getBearerToken() {
+  try {
+    const tokenResponse = await credential.getToken(COGNITIVE_SCOPE);
+    return tokenResponse.token;
+  } catch (err) {
+    const isCredentialError =
+      err.name === "CredentialUnavailableError" ||
+      err.message?.includes("CredentialUnavailable") ||
+      err.message?.includes("DefaultAzureCredential") ||
+      err.message?.includes("Please run 'az login'");
+
+    if (isCredentialError) {
+      throw new Error(
+        "Azure authentication failed — no active login found.\n\n" +
+          "To fix this, open a terminal and run:\n\n" +
+          "  az login\n\n" +
+          "Then restart this MCP server in Claude Desktop.\n\n" +
+          "Alternatively, set API keys in your config:\n" +
+          "  AZURE_OPENAI_API_KEY and/or AZURE_AI_SERVICES_KEY"
+      );
+    }
+    throw err;
+  }
+}
+
+// Model -> deployment mapping and API pattern
+const MODEL_REGISTRY = {
+  "gpt-image-1.5": {
+    pattern: "azure-openai",
+    deployment: "gpt-image-1.5",
+    supportedSizes: ["1024x1024", "1024x1792", "1792x1024"],
+    defaultSize: "1024x1024",
+    supportsQuality: true,
+    supportsStyle: false,
+    maxN: 1,
+  },
+  "dall-e-3": {
+    pattern: "azure-openai",
+    deployment: "dall-e-3",
+    supportedSizes: ["1024x1024", "1024x1792", "1792x1024"],
+    defaultSize: "1024x1024",
+    supportsQuality: true,
+    supportsStyle: true,
+    maxN: 1,
+  },
+  "flux-kontext-pro": {
+    pattern: "azure-ai-services",
+    deployment: "FLUX.1-Kontext-pro",
+    supportedSizes: ["1024x1024", "768x1024", "1024x768"],
+    defaultSize: "1024x1024",
+    supportsQuality: false,
+    supportsStyle: false,
+    maxN: 1,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Ensure output directory exists
+// ---------------------------------------------------------------------------
+function ensureOutputDir() {
+  if (!fs.existsSync(CONFIG.outputDir)) {
+    fs.mkdirSync(CONFIG.outputDir, { recursive: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Generate a unique filename
+// ---------------------------------------------------------------------------
+function generateFilename(model, extension = "png") {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const shortId = crypto.randomBytes(4).toString("hex");
+  return `${model}_${timestamp}_${shortId}.${extension}`;
+}
+
+// ---------------------------------------------------------------------------
+// Save base64 image data to disk
+// ---------------------------------------------------------------------------
+function saveBase64ToFile(base64Data, filename) {
+  ensureOutputDir();
+  const filePath = path.join(CONFIG.outputDir, filename);
+  // Strip data URI prefix if present
+  const cleanBase64 = base64Data.replace(/^data:image\/[a-zA-Z]+;base64,/, "");
+  const buffer = Buffer.from(cleanBase64, "base64");
+  fs.writeFileSync(filePath, buffer);
+  return filePath;
+}
+
+// ---------------------------------------------------------------------------
+// Download image from URL and save to disk
+// ---------------------------------------------------------------------------
+async function downloadImageToFile(imageUrl, filename) {
+  ensureOutputDir();
+  const filePath = path.join(CONFIG.outputDir, filename);
+  const response = await fetch(imageUrl);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download image: ${response.status} ${response.statusText}`
+    );
+  }
+  const arrayBuffer = await response.arrayBuffer();
+  fs.writeFileSync(filePath, Buffer.from(arrayBuffer));
+  return filePath;
+}
+
+// ---------------------------------------------------------------------------
+// Azure OpenAI image generation
+// ---------------------------------------------------------------------------
+async function generateViaAzureOpenAI(model, prompt, options = {}) {
+  const modelConfig = MODEL_REGISTRY[model];
+  if (!modelConfig) {
+    throw new Error(`Unknown model: ${model}`);
+  }
+
+  const endpoint = CONFIG.azureOpenAI.endpoint.replace(/\/$/, "");
+  const url = `${endpoint}/openai/deployments/${modelConfig.deployment}/images/generations?api-version=${CONFIG.azureOpenAI.apiVersion}`;
+
+  const body = {
+    prompt: prompt,
+    n: 1,
+    size: options.size || modelConfig.defaultSize,
+    response_format: "b64_json",
+  };
+
+  if (modelConfig.supportsQuality && options.quality) {
+    body.quality = options.quality;
+  }
+  if (modelConfig.supportsStyle && options.style) {
+    body.style = options.style;
+  }
+
+  // Auth: API key header or Bearer token from managed identity
+  const headers = { "Content-Type": "application/json" };
+  if (USE_KEY_AUTH_OPENAI) {
+    headers["api-key"] = CONFIG.azureOpenAI.apiKey;
+  } else {
+    headers["Authorization"] = `Bearer ${await getBearerToken()}`;
+  }
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(
+      `Azure OpenAI error (${response.status}): ${errorText}`
+    );
+  }
+
+  const result = await response.json();
+  const imageData = result.data[0];
+
+  let filePath;
+  const filename = generateFilename(model);
+
+  if (imageData.b64_json) {
+    filePath = saveBase64ToFile(imageData.b64_json, filename);
+  } else if (imageData.url) {
+    filePath = await downloadImageToFile(imageData.url, filename);
+  } else {
+    throw new Error("Azure OpenAI returned neither b64_json nor url");
+  }
+
+  return {
+    filePath: filePath,
+    model: model,
+    revisedPrompt: imageData.revised_prompt || null,
+    size: body.size,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Azure AI Services (serverless) image generation
+// ---------------------------------------------------------------------------
+async function generateViaAzureAIServices(model, prompt, options = {}) {
+  const modelConfig = MODEL_REGISTRY[model];
+  if (!modelConfig) {
+    throw new Error(`Unknown model: ${model}`);
+  }
+
+  const endpoint = CONFIG.azureAIServices.endpoint.replace(/\/$/, "");
+
+  // Serverless endpoints typically use /images/generations
+  // but some models use the root endpoint. Try the standard path first.
+  const url = `${endpoint}/images/generations`;
+
+  const size = options.size || modelConfig.defaultSize;
+  const [width, height] = size.split("x").map(Number);
+
+  const body = {
+    prompt: prompt,
+    width: width,
+    height: height,
+    num_images: 1,
+    response_format: "b64_json",
+  };
+
+  // Some models accept additional params
+  if (options.guidance_scale !== undefined) {
+    body.guidance_scale = options.guidance_scale;
+  }
+  if (options.num_inference_steps !== undefined) {
+    body.num_inference_steps = options.num_inference_steps;
+  }
+
+  // Auth: API key as Bearer or managed identity token
+  const aiSvcToken = USE_KEY_AUTH_AI_SERVICES
+    ? CONFIG.azureAIServices.apiKey
+    : await getBearerToken();
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${aiSvcToken}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+
+    // If /images/generations fails, try the root endpoint
+    if (response.status === 404) {
+      return await generateViaAzureAIServicesFallback(
+        model,
+        prompt,
+        endpoint,
+        body
+      );
+    }
+
+    throw new Error(
+      `Azure AI Services error (${response.status}): ${errorText}`
+    );
+  }
+
+  const result = await response.json();
+  const filename = generateFilename(model);
+
+  // Handle various response shapes
+  let filePath;
+  if (result.data && result.data[0]) {
+    const imageData = result.data[0];
+    if (imageData.b64_json || imageData.base64) {
+      filePath = saveBase64ToFile(
+        imageData.b64_json || imageData.base64,
+        filename
+      );
+    } else if (imageData.url) {
+      filePath = await downloadImageToFile(imageData.url, filename);
+    }
+  } else if (result.images && result.images[0]) {
+    // Some models return { images: ["base64..."] }
+    filePath = saveBase64ToFile(result.images[0], filename);
+  } else if (result.image) {
+    // Some return { image: "base64..." }
+    filePath = saveBase64ToFile(result.image, filename);
+  } else if (result.output) {
+    // FLUX models sometimes return { output: "base64..." }
+    filePath = saveBase64ToFile(result.output, filename);
+  }
+
+  if (!filePath) {
+    // Last resort: save the raw response for debugging
+    const debugFile = path.join(
+      CONFIG.outputDir,
+      `debug_${filename}.json`
+    );
+    fs.writeFileSync(debugFile, JSON.stringify(result, null, 2));
+    throw new Error(
+      `Could not extract image from response. Response shape saved to ${debugFile} for debugging.`
+    );
+  }
+
+  return {
+    filePath: filePath,
+    model: model,
+    size: size,
+  };
+}
+
+// Fallback: POST directly to the serverless root endpoint
+async function generateViaAzureAIServicesFallback(
+  model,
+  prompt,
+  endpoint,
+  body
+) {
+  const fallbackToken = USE_KEY_AUTH_AI_SERVICES
+    ? CONFIG.azureAIServices.apiKey
+    : await getBearerToken();
+
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${fallbackToken}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(
+      `Azure AI Services fallback error (${response.status}): ${errorText}`
+    );
+  }
+
+  const result = await response.json();
+  const filename = generateFilename(model);
+  let filePath;
+
+  // Try all known response shapes
+  if (result.data && result.data[0]) {
+    const d = result.data[0];
+    filePath = saveBase64ToFile(d.b64_json || d.base64 || "", filename);
+  } else if (result.images && result.images[0]) {
+    filePath = saveBase64ToFile(result.images[0], filename);
+  } else if (result.image) {
+    filePath = saveBase64ToFile(result.image, filename);
+  } else if (result.output) {
+    filePath = saveBase64ToFile(result.output, filename);
+  }
+
+  if (!filePath) {
+    throw new Error("Could not extract image from fallback response.");
+  }
+
+  return { filePath, model, size: body.width + "x" + body.height };
+}
+
+// ---------------------------------------------------------------------------
+// Unified generation dispatcher
+// ---------------------------------------------------------------------------
+async function generateImage(model, prompt, options = {}) {
+  const modelConfig = MODEL_REGISTRY[model];
+  if (!modelConfig) {
+    const available = Object.keys(MODEL_REGISTRY).join(", ");
+    throw new Error(
+      `Unknown model "${model}". Available: ${available}`
+    );
+  }
+
+  switch (modelConfig.pattern) {
+    case "azure-openai":
+      return await generateViaAzureOpenAI(model, prompt, options);
+    case "azure-ai-services":
+      return await generateViaAzureAIServices(model, prompt, options);
+    default:
+      throw new Error(`Unsupported API pattern: ${modelConfig.pattern}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MCP Server Setup
+// ---------------------------------------------------------------------------
+const server = new Server(
+  {
+    name: "image-proxy",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Tool Definitions
+// ---------------------------------------------------------------------------
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "generate_image",
+        description:
+          "Generate an image using Azure-hosted models. Saves the image " +
+          "to local disk and returns ONLY the file path, keeping base64 " +
+          "data out of the context window. Supports: gpt-image-1.5, " +
+          "dall-e-3, flux-kontext-pro.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            prompt: {
+              type: "string",
+              description: "Text prompt describing the desired image.",
+            },
+            model: {
+              type: "string",
+              description:
+                "Model alias: gpt-image-1.5, dall-e-3, or flux-kontext-pro.",
+              enum: Object.keys(MODEL_REGISTRY),
+              default: "flux-kontext-pro",
+            },
+            size: {
+              type: "string",
+              description:
+                "Image dimensions (e.g. 1024x1024, 1024x1792, 1792x1024).",
+              default: "1024x1024",
+            },
+            quality: {
+              type: "string",
+              description:
+                "Image quality for OpenAI models: standard or hd.",
+              enum: ["standard", "hd"],
+              default: "standard",
+            },
+            style: {
+              type: "string",
+              description:
+                "Image style for dall-e-3 only: vivid or natural.",
+              enum: ["vivid", "natural"],
+            },
+          },
+          required: ["prompt"],
+        },
+      },
+      {
+        name: "base64_to_file",
+        description:
+          "Convert a base64-encoded image string to a file on disk. " +
+          "Use this when base64 image data is already in the context " +
+          "and you want to save it locally to free up context space.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            base64_data: {
+              type: "string",
+              description:
+                "Base64-encoded image data (with or without data URI prefix).",
+            },
+            filename: {
+              type: "string",
+              description:
+                "Optional filename. If not provided, one will be generated.",
+            },
+            format: {
+              type: "string",
+              description: "Image format extension.",
+              enum: ["png", "jpg", "webp"],
+              default: "png",
+            },
+          },
+          required: ["base64_data"],
+        },
+      },
+      {
+        name: "list_generated_images",
+        description:
+          "List all generated images in the output directory with " +
+          "file size, creation time, and model used (extracted from filename).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            limit: {
+              type: "number",
+              description: "Maximum number of images to list (newest first).",
+              default: 20,
+            },
+          },
+        },
+      },
+      {
+        name: "cleanup_images",
+        description:
+          "Remove generated images older than the specified number of days.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            older_than_days: {
+              type: "number",
+              description: "Delete images older than this many days.",
+              default: 7,
+            },
+            dry_run: {
+              type: "boolean",
+              description:
+                "If true, list files that would be deleted without deleting.",
+              default: true,
+            },
+          },
+        },
+      },
+    ],
+  };
+});
+
+// ---------------------------------------------------------------------------
+// Tool Handlers
+// ---------------------------------------------------------------------------
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      // ---------------------------------------------------------------
+      // generate_image
+      // ---------------------------------------------------------------
+      case "generate_image": {
+        const model = args.model || "flux-kontext-pro";
+        const prompt = args.prompt;
+
+        if (!prompt) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: prompt is required.",
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        // Validate config — endpoints always required, keys optional with managed identity
+        const modelConfig = MODEL_REGISTRY[model];
+        if (modelConfig.pattern === "azure-openai") {
+          if (!CONFIG.azureOpenAI.endpoint) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text:
+                    "Error: AZURE_OPENAI_ENDPOINT must be configured for model: " +
+                    model +
+                    ". Auth: set AZURE_OPENAI_API_KEY or use managed identity (az login).",
+                },
+              ],
+              isError: true,
+            };
+          }
+        }
+        if (modelConfig.pattern === "azure-ai-services") {
+          if (!CONFIG.azureAIServices.endpoint) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text:
+                    "Error: AZURE_AI_SERVICES_ENDPOINT must be configured for model: " +
+                    model +
+                    ". Auth: set AZURE_AI_SERVICES_KEY or use managed identity (az login).",
+                },
+              ],
+              isError: true,
+            };
+          }
+        }
+
+        const result = await generateImage(model, prompt, {
+          size: args.size,
+          quality: args.quality,
+          style: args.style,
+        });
+
+        // Build a compact metadata response - NO base64 touches the context
+        const stats = fs.statSync(result.filePath);
+        const fileSizeKB = (stats.size / 1024).toFixed(1);
+
+        let responseText =
+          `Image generated successfully.\n` +
+          `  File: ${result.filePath}\n` +
+          `  Model: ${result.model}\n` +
+          `  Size: ${result.size}\n` +
+          `  File size: ${fileSizeKB} KB`;
+
+        if (result.revisedPrompt) {
+          responseText += `\n  Revised prompt: ${result.revisedPrompt}`;
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: responseText,
+            },
+          ],
+        };
+      }
+
+      // ---------------------------------------------------------------
+      // base64_to_file
+      // ---------------------------------------------------------------
+      case "base64_to_file": {
+        const base64Data = args.base64_data;
+        if (!base64Data) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: base64_data is required.",
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        const format = args.format || "png";
+        const filename =
+          args.filename || generateFilename("converted", format);
+        const filePath = saveBase64ToFile(base64Data, filename);
+        const stats = fs.statSync(filePath);
+        const fileSizeKB = (stats.size / 1024).toFixed(1);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `Base64 image saved to file.\n` +
+                `  File: ${filePath}\n` +
+                `  Size: ${fileSizeKB} KB`,
+            },
+          ],
+        };
+      }
+
+      // ---------------------------------------------------------------
+      // list_generated_images
+      // ---------------------------------------------------------------
+      case "list_generated_images": {
+        ensureOutputDir();
+        const limit = args.limit || 20;
+        const files = fs.readdirSync(CONFIG.outputDir);
+
+        const imageFiles = files
+          .filter((f) =>
+            /\.(png|jpg|jpeg|webp)$/i.test(f)
+          )
+          .map((f) => {
+            const fullPath = path.join(CONFIG.outputDir, f);
+            const stats = fs.statSync(fullPath);
+            // Extract model from filename pattern: model_timestamp_id.ext
+            const modelMatch = f.match(/^([^_]+)_/);
+            return {
+              filename: f,
+              path: fullPath,
+              model: modelMatch ? modelMatch[1] : "unknown",
+              sizeKB: (stats.size / 1024).toFixed(1),
+              created: stats.birthtime.toISOString(),
+            };
+          })
+          .sort((a, b) => new Date(b.created) - new Date(a.created))
+          .slice(0, limit);
+
+        if (imageFiles.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No generated images found in ${CONFIG.outputDir}`,
+              },
+            ],
+          };
+        }
+
+        const listing = imageFiles
+          .map(
+            (f, i) =>
+              `${i + 1}. ${f.filename}\n` +
+              `   Model: ${f.model} | Size: ${f.sizeKB} KB | Created: ${f.created}`
+          )
+          .join("\n");
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `Generated images (${imageFiles.length}/${files.length} total):\n` +
+                `Directory: ${CONFIG.outputDir}\n\n${listing}`,
+            },
+          ],
+        };
+      }
+
+      // ---------------------------------------------------------------
+      // cleanup_images
+      // ---------------------------------------------------------------
+      case "cleanup_images": {
+        ensureOutputDir();
+        const olderThanDays = args.older_than_days || 7;
+        const dryRun = args.dry_run !== false;
+        const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
+
+        const files = fs.readdirSync(CONFIG.outputDir);
+        const toDelete = [];
+
+        for (const f of files) {
+          if (!/\.(png|jpg|jpeg|webp|json)$/i.test(f)) continue;
+          const fullPath = path.join(CONFIG.outputDir, f);
+          const stats = fs.statSync(fullPath);
+          if (stats.birthtimeMs < cutoff) {
+            toDelete.push({
+              filename: f,
+              sizeKB: (stats.size / 1024).toFixed(1),
+              created: stats.birthtime.toISOString(),
+            });
+          }
+        }
+
+        if (toDelete.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No images older than ${olderThanDays} days found.`,
+              },
+            ],
+          };
+        }
+
+        if (!dryRun) {
+          for (const f of toDelete) {
+            fs.unlinkSync(path.join(CONFIG.outputDir, f.filename));
+          }
+        }
+
+        const listing = toDelete
+          .map((f) => `  - ${f.filename} (${f.sizeKB} KB, ${f.created})`)
+          .join("\n");
+
+        const action = dryRun ? "Would delete" : "Deleted";
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `${action} ${toDelete.length} files older than ${olderThanDays} days:\n${listing}` +
+                (dryRun
+                  ? "\n\nThis was a dry run. Set dry_run=false to actually delete."
+                  : ""),
+            },
+          ],
+        };
+      }
+
+      default:
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Unknown tool: ${name}`,
+            },
+          ],
+          isError: true,
+        };
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error in ${name}: ${error.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // Log to stderr so it does not interfere with MCP stdio protocol
+  console.error("Image Proxy MCP server started.");
+  console.error(`Output directory: ${CONFIG.outputDir}`);
+  console.error(
+    `Auth - OpenAI: ${USE_KEY_AUTH_OPENAI ? "API key" : "Managed Identity"}`
+  );
+  console.error(
+    `Auth - AI Services: ${USE_KEY_AUTH_AI_SERVICES ? "API key" : "Managed Identity"}`
+  );
+
+  // Pre-flight check: verify managed identity login if needed
+  if (credential) {
+    try {
+      await credential.getToken(COGNITIVE_SCOPE);
+      console.error("Auth check: Managed Identity token acquired OK.");
+    } catch {
+      console.error(
+        "WARNING: Managed Identity auth failed. " +
+          "Run 'az login' or set API keys. " +
+          "Image generation will fail until this is resolved."
+      );
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "image-proxy-mcp",
+  "version": "1.0.0",
+  "description": "MCP server that proxies image generation to Azure (GPT-Image, DALL-E 3, FLUX Kontext Pro), saves to local disk, and returns file paths instead of base64 to keep context windows clean.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "image-proxy-mcp": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "test": "node test.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "image-generation",
+    "azure-openai",
+    "dall-e",
+    "flux",
+    "image-proxy"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lproux/MCP-Orchestration.git",
+    "directory": "tools/image-proxy"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@azure/identity": "^4.13.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "dotenv": "^16.4.7"
+  }
+}