imagen-switch-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imagen-switch-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,331 @@
+# imagen-switch-mcp
+
+`imagen-switch-mcp` 是一个 TypeScript 实现的 MCP server，用环境变量把任意 MCP Agent 连接到图像生成/编辑端点。
+
+它内置 OpenAI Images、OpenAI 兼容网关、Gemini 图像接口，并提供 `custom` 数据驱动适配器，用于接入长尾 Provider。
+
+## 功能
+
+- MCP 工具：`generate_image` 与 `edit_image`
+- Provider：`openai`、`gemini`、`custom`
+- 输入图：本地路径、data URL、裸 base64、HTTP(S) URL
+- 输出：默认保存到本地并返回绝对路径，可选内联返回 MCP image 内容块
+- HTTP：统一认证注入、超时、429/5xx/网络错误重试、友好错误信息与 API key 脱敏
+- 分发：发布到 npm 后可通过 `npx -y imagen-switch-mcp` 直接启动
+
+## 快速开始
+
+### 作为 npm 包使用
+
+发布后，在 Agent 的 MCP 配置里使用：
+
+```json
+{
+  "mcpServers": {
+    "imagen": {
+      "command": "npx",
+      "args": ["-y", "imagen-switch-mcp"],
+      "env": {
+        "IMAGEN_FORMAT": "openai",
+        "IMAGEN_BASE_URL": "https://api.openai.com/v1",
+        "IMAGEN_API_KEY": "sk-...",
+        "IMAGEN_MODEL": "gpt-image-2",
+        "IMAGEN_OUTPUT_DIR": "D:/generated/imagen"
+      }
+    }
+  }
+}
+```
+
+### 本地开发版本使用
+
+还没发布到 npm 时，先构建：
+
+```powershell
+cd D:\Repo\projects\imagen-switch
+npm install
+npm run build
+```
+
+然后让 Agent 指向本地构建产物：
+
+```json
+{
+  "mcpServers": {
+    "imagen": {
+      "command": "node",
+      "args": ["D:/Repo/projects/imagen-switch/dist/index.js"],
+      "env": {
+        "IMAGEN_FORMAT": "openai",
+        "IMAGEN_BASE_URL": "https://api.openai.com/v1",
+        "IMAGEN_API_KEY": "sk-...",
+        "IMAGEN_MODEL": "gpt-image-2",
+        "IMAGEN_OUTPUT_DIR": "D:/Repo/projects/imagen-switch/.imagen"
+      }
+    }
+  }
+}
+```
+
+配置后重启 Agent。工具列表中应出现：
+
+- `generate_image`
+- `edit_image`
+
+## 工具
+
+### `generate_image`
+
+```text
+generate_image(prompt, model?, size?, n?, output_path?, ...provider 参数)
+```
+
+OpenAI 格式常用参数：
+
+```text
+generate_image(
+  prompt="一只透明背景的极简柴犬贴纸",
+  background="transparent",
+  output_format="png"
+)
+```
+
+### `edit_image`
+
+```text
+edit_image(prompt, images[], mask?, model?, size?, n?, output_path?, ...provider 参数)
+```
+
+`images` 支持：
+
+- 本地文件路径
+- `data:image/png;base64,...`
+- 裸 base64
+- `https://...`
+
+## 环境变量
+
+| 变量 | 说明 | 默认 |
+| --- | --- | --- |
+| `IMAGEN_FORMAT` | `openai`、`gemini`、`custom` | `openai` |
+| `IMAGEN_BASE_URL` | Provider API 基址 | openai/gemini 有内置默认 |
+| `IMAGEN_API_KEY` | Provider API key | 无 |
+| `IMAGEN_MODEL` | 默认模型 | 无 |
+| `IMAGEN_OUTPUT_DIR` | 图像保存目录 | 系统临时目录下 `imagen-switch/` |
+| `IMAGEN_RETURN_INLINE` | 是否同时返回 MCP image 内容块 | `false` |
+| `IMAGEN_TIMEOUT_MS` | 单次请求超时 | `120000` |
+| `IMAGEN_MAX_RETRIES` | 429/5xx/网络错误重试次数 | `2` |
+| `IMAGEN_EXTRA_BODY` | 额外 JSON body，JSON 对象字符串 | `{}` |
+| `IMAGEN_EXTRA_HEADERS` | 额外 headers，JSON 对象字符串 | `{}` |
+| `IMAGEN_EXTRA_QUERY` | 额外 query，JSON 对象字符串 | `{}` |
+
+`custom` 专用变量：
+
+| 变量 | 说明 |
+| --- | --- |
+| `IMAGEN_CUSTOM_GENERATE_PATH` | 生成接口路径，如 `/v1/text2image` |
+| `IMAGEN_CUSTOM_EDIT_PATH` | 编辑接口路径；配置后才注册 `edit_image` |
+| `IMAGEN_CUSTOM_ENCODING` | `json` 或 `multipart` |
+| `IMAGEN_CUSTOM_BODY_TEMPLATE` | 请求体模板，支持 `{{prompt}}`、`{{model}}`、`{{size}}`、`{{n}}`、`{{image}}` |
+| `IMAGEN_CUSTOM_RESPONSE_IMAGES_PATH` | 响应图像路径，如 `output.images[*]` |
+| `IMAGEN_CUSTOM_RESPONSE_IMAGE_KIND` | `b64`、`url`、`dataurl` |
+
+完整设计背景见 [设计文档](docs/superpowers/specs/2026-06-23-imagen-switch-mcp-design.md)。
+
+## Provider 配方
+
+### OpenAI
+
+```json
+{
+  "IMAGEN_FORMAT": "openai",
+  "IMAGEN_BASE_URL": "https://api.openai.com/v1",
+  "IMAGEN_API_KEY": "sk-...",
+  "IMAGEN_MODEL": "gpt-image-2"
+}
+```
+
+### OpenAI 兼容网关
+
+```json
+{
+  "IMAGEN_FORMAT": "openai",
+  "IMAGEN_BASE_URL": "https://your-gateway.example/v1",
+  "IMAGEN_API_KEY": "...",
+  "IMAGEN_MODEL": "flux.1-schnell"
+}
+```
+
+### Gemini
+
+```json
+{
+  "IMAGEN_FORMAT": "gemini",
+  "IMAGEN_BASE_URL": "https://generativelanguage.googleapis.com/v1beta",
+  "IMAGEN_API_KEY": "...",
+  "IMAGEN_MODEL": "gemini-2.5-flash-image"
+}
+```
+
+### custom
+
+```json
+{
+  "IMAGEN_FORMAT": "custom",
+  "IMAGEN_BASE_URL": "https://api.example.com",
+  "IMAGEN_API_KEY": "...",
+  "IMAGEN_CUSTOM_GENERATE_PATH": "/v1/text2image",
+  "IMAGEN_CUSTOM_ENCODING": "json",
+  "IMAGEN_CUSTOM_BODY_TEMPLATE": "{\"model\":\"{{model}}\",\"prompt\":\"{{prompt}}\",\"num\":{{n}}}",
+  "IMAGEN_CUSTOM_RESPONSE_IMAGES_PATH": "output.images[*]",
+  "IMAGEN_CUSTOM_RESPONSE_IMAGE_KIND": "url"
+}
+```
+
+## 真实端点人工测试
+
+真实端点测试会消耗 Provider 额度。不要把 API key 写进仓库文件。
+
+先构建：
+
+```powershell
+npm install
+npm run build
+```
+
+设置环境变量，以 OpenAI 为例：
+
+```powershell
+$env:IMAGEN_FORMAT="openai"
+$env:IMAGEN_BASE_URL="https://api.openai.com/v1"
+$env:IMAGEN_API_KEY="你的真实 API Key"
+$env:IMAGEN_MODEL="gpt-image-2"
+$env:IMAGEN_OUTPUT_DIR="D:\Repo\projects\imagen-switch\.imagen-real"
+```
+
+可以使用仓库根目录的 `tmp-real-test.mjs`，也可以临时创建同名文件。通用测试脚本如下：
+
+```js
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "node",
+  args: ["dist/index.js"],
+  env: process.env,
+});
+
+const client = new Client({ name: "real-test", version: "0.0.0" });
+await client.connect(transport);
+
+const tools = await client.listTools();
+console.log("tools:", tools.tools.map((tool) => tool.name));
+
+const result = await client.callTool(
+  {
+    name: "generate_image",
+    arguments: {
+      prompt: "一只透明背景的极简柴犬贴纸",
+      background: "transparent",
+      output_format: "png",
+    },
+  },
+  undefined,
+  { timeout: 300_000 },
+);
+
+console.dir(result, { depth: null });
+await client.close();
+```
+
+运行：
+
+```powershell
+node .\tmp-real-test.mjs
+```
+
+成功时返回文本中会包含保存路径，例如：
+
+```text
+已生成 1 张图像（provider=openai, model=gpt-image-2）：
+- D:\Repo\projects\imagen-switch\.imagen-real\imagen-0000000000000-0.png
+```
+
+测试结束后清理环境变量：
+
+```powershell
+Remove-Item Env:\IMAGEN_FORMAT,Env:\IMAGEN_BASE_URL,Env:\IMAGEN_API_KEY,Env:\IMAGEN_MODEL,Env:\IMAGEN_OUTPUT_DIR -ErrorAction SilentlyContinue
+```
+
+## 开发
+
+```powershell
+npm install
+npm test
+npm run typecheck
+npm run build
+```
+
+常用脚本：
+
+| 命令 | 说明 |
+| --- | --- |
+| `npm test` | 运行 Vitest |
+| `npm run typecheck` | TypeScript 类型检查 |
+| `npm run build` | 通过 tsup 构建 `dist/index.js` |
+| `npm run ci` | 测试、类型检查、构建 |
+| `npm run publish:dry-run` | 本地检查 npm 发布包内容 |
+
+目录结构：
+
+```text
+src/
+  adapters/       Provider 适配器与 registry
+  config.ts       环境变量解析与校验
+  errors.ts       友好错误与 API key 脱敏
+  http.ts         fetch、认证、超时、重试、下载
+  input.ts        输入图解析
+  output.ts       图像 materialize、落盘、工具返回
+  server.ts       MCP server 工具注册与流水线
+  index.ts        stdio 入口
+test/
+```
+
+## 发布到 npm
+
+发布前确认：
+
+```powershell
+npm run ci
+npm run publish:dry-run
+```
+
+手动发布：
+
+```powershell
+npm publish --provenance --access public
+```
+
+自动发布使用 `.github/workflows/npm-publish.yml`，只监听 `main` 分支。
+
+当前 workflow 使用 npm automation token，适合包的首次发布，也能避开 publish 2FA 在 CI 中要求一次性验证码的问题：
+
+1. 在 npm 创建 `Automation` 类型的 access token。
+2. 在 GitHub 仓库设置 `Settings -> Secrets and variables -> Actions` 中新增 secret：`NPM_AUTOMATION_TOKEN`。
+3. 不要使用普通 classic/granular publish token；如果账号开启了 publish 2FA，这类 token 会在 CI 中触发 `EOTP`，因为 Action 无法输入一次性验证码。
+
+发布成功后，如果想改成 npm Trusted Publishing，可以在 npm package 的发布设置里添加 GitHub Actions trusted publisher，并相应调整 workflow 移除 token 校验。
+
+合并到 `main` 后，Action 会运行 `npm run ci`。如果 `package.json` 中的版本还没有发布过，Action 会执行 `npm publish --provenance --access public`；如果版本已存在于 npm，Action 会跳过发布，避免主分支文档更新导致失败。
+
+发布新版本时，请先更新 `package.json` 里的 `version`，再合并到主分支。
+
+## 安全
+
+- 不要把 `IMAGEN_API_KEY` 写入仓库。
+- `.env`、`.env.*`、`.imagen/`、`.imagen-real/` 已被忽略。
+- 错误信息会对已配置的 API key 做脱敏处理。
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,723 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { pathToFileURL } from "url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/errors.ts
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+var ProviderError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "ProviderError";
+    this.status = status;
+  }
+};
+function redactKey(text, apiKey) {
+  if (!apiKey) return text;
+  return text.split(apiKey).join("***");
+}
+function friendlyHttpError(status, providerBody) {
+  const body = providerBody.slice(0, 800);
+  if (status === 401 || status === 403) {
+    return `\u8BA4\u8BC1\u5931\u8D25 (HTTP ${status})\uFF1A\u8BF7\u68C0\u67E5 IMAGEN_API_KEY / IMAGEN_AUTH_*\u3002Provider \u8FD4\u56DE\uFF1A${body}`;
+  }
+  if (status === 429) {
+    return `\u89E6\u53D1\u9650\u6D41 (HTTP 429)\uFF1A\u8BF7\u7A0D\u540E\u91CD\u8BD5\u6216\u964D\u4F4E\u9891\u7387\u3002Provider \u8FD4\u56DE\uFF1A${body}`;
+  }
+  if (status === 400) {
+    return `\u8BF7\u6C42\u53C2\u6570\u88AB\u62D2 (HTTP 400)\uFF1A${body}`;
+  }
+  return `Provider \u8FD4\u56DE\u9519\u8BEF (HTTP ${status})\uFF1A${body}`;
+}
+
+// src/config.ts
+function parseJsonEnv(name, value) {
+  if (!value) return {};
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("not an object");
+    }
+    return parsed;
+  } catch (e) {
+    throw new ConfigError(`\u73AF\u5883\u53D8\u91CF ${name} \u4E0D\u662F\u5408\u6CD5\u7684 JSON \u5BF9\u8C61\uFF1A${e.message}`);
+  }
+}
+function parseIntEnv(name, value, fallback) {
+  if (value === void 0 || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isFinite(n)) {
+    throw new ConfigError(`\u73AF\u5883\u53D8\u91CF ${name} \u5FC5\u987B\u662F\u6570\u5B57\uFF0C\u6536\u5230\uFF1A${value}`);
+  }
+  return n;
+}
+function optionalCustomImageKind(value) {
+  if (value === void 0 || value === "") return void 0;
+  if (value === "b64" || value === "url" || value === "dataurl") return value;
+  throw new ConfigError(`IMAGEN_CUSTOM_RESPONSE_IMAGE_KIND \u5FC5\u987B\u662F b64|url|dataurl\uFF0C\u6536\u5230\uFF1A${value}`);
+}
+function loadRawConfig(env) {
+  const style = env.IMAGEN_AUTH_STYLE;
+  if (style && !["bearer", "header", "query", "none"].includes(style)) {
+    throw new ConfigError(`IMAGEN_AUTH_STYLE \u5FC5\u987B\u662F bearer|header|query|none\uFF0C\u6536\u5230\uFF1A${style}`);
+  }
+  const encoding = env.IMAGEN_CUSTOM_ENCODING ?? "json";
+  if (!["json", "multipart"].includes(encoding)) {
+    throw new ConfigError(`IMAGEN_CUSTOM_ENCODING \u5FC5\u987B\u662F json|multipart\uFF0C\u6536\u5230\uFF1A${encoding}`);
+  }
+  return {
+    format: env.IMAGEN_FORMAT ?? "openai",
+    baseUrl: env.IMAGEN_BASE_URL,
+    apiKey: env.IMAGEN_API_KEY,
+    model: env.IMAGEN_MODEL,
+    authStyle: style,
+    authHeaderName: env.IMAGEN_AUTH_HEADER_NAME,
+    authQueryName: env.IMAGEN_AUTH_QUERY_NAME,
+    outputDir: env.IMAGEN_OUTPUT_DIR,
+    returnInline: env.IMAGEN_RETURN_INLINE === "true",
+    timeoutMs: parseIntEnv("IMAGEN_TIMEOUT_MS", env.IMAGEN_TIMEOUT_MS, 12e4),
+    maxRetries: parseIntEnv("IMAGEN_MAX_RETRIES", env.IMAGEN_MAX_RETRIES, 2),
+    extraBody: parseJsonEnv("IMAGEN_EXTRA_BODY", env.IMAGEN_EXTRA_BODY),
+    extraHeaders: parseJsonEnv("IMAGEN_EXTRA_HEADERS", env.IMAGEN_EXTRA_HEADERS),
+    extraQuery: parseJsonEnv("IMAGEN_EXTRA_QUERY", env.IMAGEN_EXTRA_QUERY),
+    custom: {
+      generatePath: env.IMAGEN_CUSTOM_GENERATE_PATH,
+      editPath: env.IMAGEN_CUSTOM_EDIT_PATH,
+      encoding,
+      bodyTemplate: env.IMAGEN_CUSTOM_BODY_TEMPLATE,
+      responseImagesPath: env.IMAGEN_CUSTOM_RESPONSE_IMAGES_PATH,
+      responseImageKind: optionalCustomImageKind(env.IMAGEN_CUSTOM_RESPONSE_IMAGE_KIND)
+    }
+  };
+}
+function resolveBaseUrl(raw, defaultBaseUrl) {
+  const url = raw.baseUrl ?? defaultBaseUrl;
+  if (!url) {
+    throw new ConfigError(`\u7F3A\u5C11 IMAGEN_BASE_URL\uFF0C\u4E14 format "${raw.format}" \u65E0\u5185\u7F6E\u9ED8\u8BA4\u503C`);
+  }
+  return url.replace(/\/+$/, "");
+}
+function resolveAuth(raw, defaults) {
+  return {
+    style: raw.authStyle ?? defaults.style,
+    headerName: raw.authHeaderName ?? defaults.headerName,
+    queryName: raw.authQueryName ?? defaults.queryName,
+    apiKey: raw.apiKey
+  };
+}
+
+// src/server.ts
+import { tmpdir } from "os";
+import { join as join2 } from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z as z2 } from "zod";
+
+// src/adapters/openai.ts
+import { z } from "zod";
+var OPENAI_META = {
+  format: "openai",
+  defaultBaseUrl: "https://api.openai.com/v1",
+  defaultAuth: { style: "bearer" },
+  supportsEdit: true,
+  extraParams: {
+    quality: z.string().optional().describe("standard/high (gpt-image-2); low/medium/high/auto (gpt-image-1); standard/hd (dall-e-3)"),
+    background: z.string().optional().describe("auto | transparent | opaque"),
+    thinking: z.string().optional().describe("off | low | medium | high"),
+    seed: z.number().int().optional().describe("int32"),
+    output_format: z.string().optional().describe("png | jpeg | webp"),
+    output_compression: z.number().int().optional().describe("0-100"),
+    moderation: z.string().optional().describe("auto | low"),
+    user: z.string().optional().describe("abuse detection identifier")
+  }
+};
+function parseResponse(raw) {
+  const data = raw?.data;
+  if (!Array.isArray(data)) return [];
+  const out = [];
+  for (const item of data) {
+    const image = item;
+    if (typeof image.b64_json === "string") {
+      out.push({ kind: "b64", data: image.b64_json });
+    } else if (typeof image.url === "string") {
+      out.push({ kind: "url", data: image.url });
+    }
+  }
+  return out;
+}
+function appendFormValue(fd, key, value) {
+  if (value === void 0 || value === null) return;
+  fd.set(key, typeof value === "object" ? JSON.stringify(value) : String(value));
+}
+function imageBlob(image) {
+  const copy = new Uint8Array(image.bytes.length);
+  copy.set(image.bytes);
+  return new Blob([copy.buffer], { type: image.mime });
+}
+function createOpenAiAdapter(baseUrl) {
+  return {
+    ...OPENAI_META,
+    buildGenerate(req) {
+      const body = {
+        ...req.params,
+        model: req.model,
+        prompt: req.prompt,
+        n: req.n
+      };
+      if (req.size) body.size = req.size;
+      return { method: "POST", url: `${baseUrl}/images/generations`, headers: {}, body };
+    },
+    buildEdit(req, images, mask) {
+      const fd = new FormData();
+      fd.set("prompt", req.prompt);
+      fd.set("model", req.model);
+      fd.set("n", String(req.n));
+      if (req.size) fd.set("size", req.size);
+      for (const [key, value] of Object.entries(req.params)) {
+        appendFormValue(fd, key, value);
+      }
+      const field = images.length > 1 ? "image[]" : "image";
+      for (const img of images) {
+        fd.append(field, imageBlob(img), "image.png");
+      }
+      if (mask) fd.set("mask", imageBlob(mask), "mask.png");
+      return { method: "POST", url: `${baseUrl}/images/edits`, headers: {}, body: fd };
+    },
+    parseResponse
+  };
+}
+
+// src/adapters/gemini.ts
+var GEMINI_META = {
+  format: "gemini",
+  defaultBaseUrl: "https://generativelanguage.googleapis.com/v1beta",
+  defaultAuth: { style: "header", headerName: "x-goog-api-key" },
+  supportsEdit: true,
+  extraParams: {}
+};
+function bytesToB64(bytes) {
+  return Buffer.from(bytes).toString("base64");
+}
+function baseGenerationConfig(req) {
+  const existing = req.params.generationConfig ?? {};
+  const generationConfig = {
+    responseModalities: ["TEXT", "IMAGE"],
+    ...existing
+  };
+  if (req.size) {
+    generationConfig.imageConfig = {
+      ...generationConfig.imageConfig ?? {},
+      aspectRatio: req.size
+    };
+  }
+  return generationConfig;
+}
+function parseResponse2(raw) {
+  const parts = raw?.candidates?.[0]?.content?.parts ?? [];
+  const out = [];
+  for (const part of parts) {
+    const inline = part.inline_data ?? part.inlineData;
+    if (inline?.data) {
+      out.push({
+        kind: "b64",
+        data: inline.data,
+        mime: inline.mime_type ?? inline.mimeType ?? "image/png"
+      });
+    }
+  }
+  return out;
+}
+function createGeminiAdapter(baseUrl) {
+  return {
+    ...GEMINI_META,
+    buildGenerate(req) {
+      const { generationConfig: _generationConfig, ...params } = req.params;
+      const body = {
+        contents: [{ parts: [{ text: req.prompt }] }],
+        ...params,
+        generationConfig: baseGenerationConfig(req)
+      };
+      return { method: "POST", url: `${baseUrl}/models/${req.model}:generateContent`, headers: {}, body };
+    },
+    buildEdit(req, images, _mask) {
+      const { generationConfig: _generationConfig, ...params } = req.params;
+      const parts = [{ text: req.prompt }];
+      for (const img of images) {
+        parts.push({ inline_data: { mime_type: img.mime, data: bytesToB64(img.bytes) } });
+      }
+      const body = {
+        contents: [{ parts }],
+        ...params,
+        generationConfig: baseGenerationConfig(req)
+      };
+      return { method: "POST", url: `${baseUrl}/models/${req.model}:generateContent`, headers: {}, body };
+    },
+    parseResponse: parseResponse2
+  };
+}
+
+// src/adapters/jsonpath.ts
+function extractPath(obj, path) {
+  const tokens = path.replace(/\[(\d+|\*)\]/g, ".$1").split(".").filter(Boolean);
+  let current = [obj];
+  for (const token of tokens) {
+    const next = [];
+    for (const node of current) {
+      if (node == null) continue;
+      if (token === "*") {
+        if (Array.isArray(node)) next.push(...node);
+      } else if (/^\d+$/.test(token)) {
+        if (Array.isArray(node)) {
+          const value = node[Number(token)];
+          if (value !== void 0) next.push(value);
+        }
+      } else {
+        const value = node[token];
+        if (value !== void 0) next.push(value);
+      }
+    }
+    current = next;
+  }
+  return current;
+}
+
+// src/adapters/custom.ts
+var CUSTOM_META = {
+  format: "custom",
+  defaultAuth: { style: "bearer" },
+  extraParams: {}
+};
+function escapeTemplateString(value) {
+  return JSON.stringify(value).slice(1, -1);
+}
+function render(template, req) {
+  const filled = template.replace(/\{\{prompt\}\}/g, escapeTemplateString(req.prompt)).replace(/\{\{model\}\}/g, escapeTemplateString(req.model)).replace(/\{\{size\}\}/g, escapeTemplateString(req.size ?? "")).replace(/\{\{n\}\}/g, String(req.n));
+  try {
+    return JSON.parse(filled);
+  } catch (e) {
+    throw new ConfigError(`\u6E32\u67D3 IMAGEN_CUSTOM_BODY_TEMPLATE \u540E\u4E0D\u662F\u5408\u6CD5 JSON\uFF1A${e.message}`);
+  }
+}
+function appendFormValue2(fd, key, value) {
+  if (value === void 0 || value === null) return;
+  if (value instanceof Blob) {
+    fd.set(key, value);
+    return;
+  }
+  fd.set(key, typeof value === "object" ? JSON.stringify(value) : String(value));
+}
+function encodeBody(encoding, fields, params) {
+  const merged = { ...fields, ...params };
+  if (encoding === "json") return merged;
+  const fd = new FormData();
+  for (const [key, value] of Object.entries(merged)) {
+    appendFormValue2(fd, key, value);
+  }
+  return fd;
+}
+function createCustomAdapter(baseUrl, custom) {
+  const kind = custom.responseImageKind ?? "url";
+  return {
+    ...CUSTOM_META,
+    supportsEdit: Boolean(custom.editPath),
+    defaultBaseUrl: void 0,
+    buildGenerate(req) {
+      if (!custom.generatePath) throw new ConfigError("custom \u683C\u5F0F\u7F3A\u5C11 IMAGEN_CUSTOM_GENERATE_PATH");
+      if (!custom.bodyTemplate) throw new ConfigError("custom \u683C\u5F0F\u7F3A\u5C11 IMAGEN_CUSTOM_BODY_TEMPLATE");
+      const body = encodeBody(custom.encoding, render(custom.bodyTemplate, req), req.params);
+      return { method: "POST", url: `${baseUrl}${custom.generatePath}`, headers: {}, body };
+    },
+    buildEdit(req, images, _mask) {
+      if (!custom.editPath) throw new ConfigError("custom \u683C\u5F0F\u672A\u914D\u7F6E IMAGEN_CUSTOM_EDIT_PATH\uFF0C\u4E0D\u652F\u6301 edit");
+      if (!custom.bodyTemplate) throw new ConfigError("custom \u683C\u5F0F\u7F3A\u5C11 IMAGEN_CUSTOM_BODY_TEMPLATE");
+      const b64 = Buffer.from(images[0]?.bytes ?? new Uint8Array()).toString("base64");
+      const template = custom.bodyTemplate.replace(/\{\{image\}\}/g, escapeTemplateString(b64));
+      const body = encodeBody(custom.encoding, render(template, req), req.params);
+      return { method: "POST", url: `${baseUrl}${custom.editPath}`, headers: {}, body };
+    },
+    parseResponse(raw) {
+      if (!custom.responseImagesPath) throw new ConfigError("custom \u683C\u5F0F\u7F3A\u5C11 IMAGEN_CUSTOM_RESPONSE_IMAGES_PATH");
+      const values = extractPath(raw, custom.responseImagesPath);
+      return values.filter((value) => typeof value === "string").map((value) => {
+        if (kind === "url") return { kind: "url", data: value };
+        if (kind === "dataurl") {
+          const match = value.match(/^data:([^;]+);base64,(.+)$/s);
+          return { kind: "b64", data: match ? match[2] : value, mime: match?.[1] };
+        }
+        return { kind: "b64", data: value };
+      });
+    }
+  };
+}
+
+// src/adapters/registry.ts
+function createAdapter(raw) {
+  if (raw.format === "openai") {
+    const baseUrl = resolveBaseUrl(raw, OPENAI_META.defaultBaseUrl);
+    return { adapter: createOpenAiAdapter(baseUrl), baseUrl, auth: resolveAuth(raw, OPENAI_META.defaultAuth) };
+  }
+  if (raw.format === "gemini") {
+    const baseUrl = resolveBaseUrl(raw, GEMINI_META.defaultBaseUrl);
+    return { adapter: createGeminiAdapter(baseUrl), baseUrl, auth: resolveAuth(raw, GEMINI_META.defaultAuth) };
+  }
+  if (raw.format === "custom") {
+    const baseUrl = resolveBaseUrl(raw, void 0);
+    return { adapter: createCustomAdapter(baseUrl, raw.custom), baseUrl, auth: resolveAuth(raw, CUSTOM_META.defaultAuth) };
+  }
+  throw new ConfigError(`\u672A\u77E5 format / IMAGEN_FORMAT "${raw.format}"\uFF0C\u53D7\u652F\u6301\uFF1Aopenai | gemini | custom`);
+}
+
+// src/adapters/overrides.ts
+function applyOverrides(spec, extra) {
+  return {
+    ...spec,
+    headers: { ...spec.headers, ...extra.headers },
+    query: { ...spec.query ?? {}, ...extra.query }
+  };
+}
+
+// src/http.ts
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function shouldRetryStatus(status) {
+  return status === 429 || status >= 500;
+}
+function appendQuery(url, query) {
+  const out = new URL(url);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    out.searchParams.set(key, value);
+  }
+  return out.toString();
+}
+function applyAuth(url, headers, auth) {
+  if (auth.style === "none" || !auth.apiKey) return url;
+  if (auth.style === "bearer") {
+    headers.Authorization = `Bearer ${auth.apiKey}`;
+    return url;
+  }
+  if (auth.style === "header") {
+    headers[auth.headerName ?? "Authorization"] = auth.apiKey;
+    return url;
+  }
+  const queryName = auth.queryName ?? "key";
+  return appendQuery(url, { [queryName]: auth.apiKey });
+}
+function bodyAndHeaders(body, headers) {
+  if (body instanceof FormData) return body;
+  if (!Object.keys(headers).some((key) => key.toLowerCase() === "content-type")) {
+    headers["Content-Type"] = "application/json";
+  }
+  return JSON.stringify(body);
+}
+async function withTimeoutFetch(url, init, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function retrying(maxRetries, operation) {
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+    try {
+      return await operation(attempt);
+    } catch (e) {
+      lastError = e;
+      if (e instanceof ProviderError && !shouldRetryStatus(e.status ?? 0)) break;
+      if (attempt === maxRetries) break;
+      await sleep(Math.min(50 * 2 ** attempt, 1e3));
+    }
+  }
+  throw lastError;
+}
+async function sendRequest(spec, auth, opts) {
+  return retrying(opts.maxRetries, async () => {
+    const headers = { ...spec.headers };
+    let url = appendQuery(spec.url, spec.query);
+    url = applyAuth(url, headers, auth);
+    const response = await withTimeoutFetch(
+      url,
+      {
+        method: spec.method,
+        headers,
+        body: bodyAndHeaders(spec.body, headers)
+      },
+      opts.timeoutMs
+    );
+    if (!response.ok) {
+      const providerBody = redactKey(await response.text(), auth.apiKey);
+      throw new ProviderError(friendlyHttpError(response.status, providerBody), response.status);
+    }
+    return response.json();
+  });
+}
+async function downloadToBytes(url, opts) {
+  return retrying(opts.maxRetries, async () => {
+    const response = await withTimeoutFetch(url, { method: "GET" }, opts.timeoutMs);
+    if (!response.ok) {
+      throw new ProviderError(`\u56FE\u50CF\u4E0B\u8F7D\u5931\u8D25 (HTTP ${response.status})\uFF1A${await response.text()}`, response.status);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const mime = response.headers.get("content-type")?.split(";")[0] || "application/octet-stream";
+    return { bytes, mime };
+  });
+}
+
+// src/input.ts
+import { readFile } from "fs/promises";
+function sniffMime(bytes) {
+  if (bytes[0] === 137 && bytes[1] === 80) return "image/png";
+  if (bytes[0] === 255 && bytes[1] === 216) return "image/jpeg";
+  if (bytes[0] === 71 && bytes[1] === 73) return "image/gif";
+  if (bytes[0] === 82 && bytes[1] === 73 && bytes[8] === 87) return "image/webp";
+  return "application/octet-stream";
+}
+var DATA_URL_RE = /^data:([^;]+);base64,(.+)$/s;
+async function resolveImage(ref, timeoutMs) {
+  const dataMatch = ref.match(DATA_URL_RE);
+  if (dataMatch) {
+    const bytes = new Uint8Array(Buffer.from(dataMatch[2], "base64"));
+    return { bytes, mime: dataMatch[1] };
+  }
+  if (/^https?:\/\//.test(ref)) {
+    return downloadToBytes(ref, { timeoutMs, maxRetries: 0 });
+  }
+  const compact = ref.replace(/\s/g, "");
+  if (/^[A-Za-z0-9+/=]+$/.test(compact) && compact.length % 4 === 0 && compact.length > 16) {
+    const bytes = new Uint8Array(Buffer.from(compact, "base64"));
+    if (bytes.length > 0) return { bytes, mime: sniffMime(bytes) };
+  }
+  try {
+    const buf = await readFile(ref);
+    const bytes = new Uint8Array(buf);
+    return { bytes, mime: sniffMime(bytes) };
+  } catch {
+    throw new ConfigError(`\u65E0\u6CD5\u89E3\u6790\u8F93\u5165\u56FE\uFF1A${ref}\uFF08\u65E2\u975E data URL / http URL / base64\uFF0C\u4E5F\u975E\u53EF\u8BFB\u6587\u4EF6\uFF09`);
+  }
+}
+
+// src/output.ts
+import { mkdir, stat, writeFile } from "fs/promises";
+import { basename, dirname, extname, join, resolve } from "path";
+function extFromMime(mime) {
+  if (mime.includes("jpeg") || mime.includes("jpg")) return "jpg";
+  if (mime.includes("webp")) return "webp";
+  if (mime.includes("gif")) return "gif";
+  if (mime.includes("png")) return "png";
+  return "png";
+}
+function mimeFromOutputFormat(format) {
+  if (format !== "png" && format !== "jpeg" && format !== "jpg" && format !== "webp") return void 0;
+  return format === "jpg" || format === "jpeg" ? "image/jpeg" : `image/${format}`;
+}
+async function materialize(images, opts) {
+  const out = [];
+  const preferredMime = mimeFromOutputFormat(opts.preferredOutputFormat);
+  for (const image of images) {
+    if (image.kind === "b64") {
+      out.push({
+        bytes: new Uint8Array(Buffer.from(image.data, "base64")),
+        mime: image.mime ?? preferredMime ?? "image/png"
+      });
+    } else {
+      out.push(await downloadToBytes(image.data, opts));
+    }
+  }
+  return out;
+}
+async function isDir(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function saveImages(mats, opts) {
+  const paths = [];
+  const multi = mats.length > 1;
+  let targetDir = opts.outputDir;
+  let baseName;
+  if (opts.outputPath) {
+    const outputPath = resolve(opts.outputPath);
+    if (opts.outputPath.endsWith("/") || opts.outputPath.endsWith("\\") || await isDir(outputPath)) {
+      targetDir = outputPath;
+    } else {
+      targetDir = dirname(outputPath);
+      baseName = basename(outputPath);
+    }
+  }
+  await mkdir(targetDir, { recursive: true });
+  const stamp = Date.now();
+  for (let i = 0; i < mats.length; i += 1) {
+    const ext = extFromMime(mats[i].mime);
+    let name;
+    if (baseName) {
+      if (multi) {
+        const currentExt = extname(baseName);
+        const base = baseName.slice(0, baseName.length - currentExt.length);
+        name = `${base}-${i}${currentExt || `.${ext}`}`;
+      } else {
+        name = baseName;
+      }
+    } else {
+      name = `imagen-${stamp}-${i}.${ext}`;
+    }
+    const full = join(targetDir, name);
+    await writeFile(full, mats[i].bytes);
+    paths.push(resolve(full));
+  }
+  return paths;
+}
+function buildToolResult(paths, mats, meta, returnInline) {
+  const lines = [
+    `\u5DF2\u751F\u6210 ${paths.length} \u5F20\u56FE\u50CF\uFF08provider=${meta.provider}, model=${meta.model}${meta.size ? `, size=${meta.size}` : ""}\uFF09\uFF1A`,
+    ...paths.map((path) => `- ${path}`)
+  ];
+  const content = [{ type: "text", text: lines.join("\n") }];
+  if (returnInline) {
+    for (const mat of mats) {
+      content.push({ type: "image", data: Buffer.from(mat.bytes).toString("base64"), mimeType: mat.mime });
+    }
+  }
+  return { content, isError: false };
+}
+
+// src/server.ts
+var coreShape = {
+  prompt: z2.string().describe("\u56FE\u50CF\u63CF\u8FF0/\u7F16\u8F91\u6307\u4EE4"),
+  model: z2.string().optional().describe("\u8986\u76D6\u9ED8\u8BA4\u6A21\u578B IMAGEN_MODEL"),
+  size: z2.string().optional().describe("\u5982 1024x1024\uFF1B\u9002\u914D\u5668\u81EA\u52A8\u6620\u5C04"),
+  n: z2.number().int().optional().describe("\u751F\u6210\u5F20\u6570\uFF0C\u9ED8\u8BA4 1"),
+  output_path: z2.string().optional().describe("\u4FDD\u5B58\u6587\u4EF6\u540D\u6216\u76EE\u5F55\uFF0C\u8986\u76D6\u9ED8\u8BA4\u8F93\u51FA\u76EE\u5F55")
+};
+var CORE_KEYS = /* @__PURE__ */ new Set(["prompt", "model", "size", "n", "output_path", "images", "mask"]);
+function defaultDir() {
+  return join2(tmpdir(), "imagen-switch");
+}
+function toNormReq(args, raw) {
+  const model = args.model ?? raw.model;
+  if (!model) throw new ConfigError("\u672A\u63D0\u4F9B model\uFF0C\u4E14\u672A\u8BBE\u7F6E IMAGEN_MODEL");
+  const extras = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (!CORE_KEYS.has(key) && value !== void 0) extras[key] = value;
+  }
+  return {
+    prompt: args.prompt,
+    model,
+    size: args.size,
+    n: args.n ?? 1,
+    params: { ...raw.extraBody, ...extras }
+  };
+}
+function errorResult(error, apiKey) {
+  const message = error instanceof Error ? error.message : String(error);
+  return { content: [{ type: "text", text: redactKey(message, apiKey) }], isError: true };
+}
+function buildServer(raw) {
+  const { adapter, auth } = createAdapter(raw);
+  const server = new McpServer({ name: "imagen-switch", version: "0.1.0" });
+  const opts = { timeoutMs: raw.timeoutMs, maxRetries: raw.maxRetries };
+  const overrides = { headers: raw.extraHeaders, query: raw.extraQuery };
+  server.registerTool(
+    "generate_image",
+    {
+      title: "Generate Image",
+      description: "\u7528\u914D\u7F6E\u7684 Provider \u751F\u6210\u56FE\u50CF\uFF0C\u4FDD\u5B58\u5230\u672C\u5730\u5E76\u8FD4\u56DE\u8DEF\u5F84\u3002",
+      inputSchema: { ...coreShape, ...adapter.extraParams }
+    },
+    async (args) => {
+      try {
+        const req = toNormReq(args, raw);
+        const spec = applyOverrides(adapter.buildGenerate(req), overrides);
+        const rawResponse = await sendRequest(spec, auth, opts);
+        const images = adapter.parseResponse(rawResponse);
+        if (images.length === 0) throw new ProviderError("Provider \u672A\u8FD4\u56DE\u4EFB\u4F55\u56FE\u50CF");
+        const mats = await materialize(images, { ...opts, preferredOutputFormat: req.params.output_format });
+        const paths = await saveImages(mats, {
+          outputDir: raw.outputDir ?? defaultDir(),
+          outputPath: args.output_path
+        });
+        return buildToolResult(paths, mats, { model: req.model, size: req.size, provider: adapter.format }, raw.returnInline);
+      } catch (e) {
+        return errorResult(e, auth.apiKey);
+      }
+    }
+  );
+  if (adapter.supportsEdit) {
+    server.registerTool(
+      "edit_image",
+      {
+        title: "Edit Image",
+        description: "\u57FA\u4E8E\u4E00\u5F20\u6216\u591A\u5F20\u8F93\u5165\u56FE\u6309\u6307\u4EE4\u7F16\u8F91/\u91CD\u7ED8\uFF0C\u4FDD\u5B58\u5230\u672C\u5730\u5E76\u8FD4\u56DE\u8DEF\u5F84\u3002",
+        inputSchema: {
+          ...coreShape,
+          images: z2.array(z2.string()).describe("\u8F93\u5165\u56FE\uFF1A\u672C\u5730\u8DEF\u5F84 / data URL / \u88F8 base64 / http(s) URL"),
+          mask: z2.string().optional().describe("inpaint \u8499\u7248\uFF08\u652F\u6301\u7684 Provider \u624D\u7528\uFF09"),
+          ...adapter.extraParams
+        }
+      },
+      async (args) => {
+        try {
+          const req = toNormReq(args, raw);
+          const refs = args.images ?? [];
+          if (refs.length === 0) throw new ConfigError("edit_image \u9700\u8981\u81F3\u5C11\u4E00\u5F20 images");
+          const images = await Promise.all(refs.map((ref) => resolveImage(ref, opts.timeoutMs)));
+          const mask = args.mask ? await resolveImage(args.mask, opts.timeoutMs) : void 0;
+          const spec = applyOverrides(adapter.buildEdit(req, images, mask), overrides);
+          const rawResponse = await sendRequest(spec, auth, opts);
+          const out = adapter.parseResponse(rawResponse);
+          if (out.length === 0) throw new ProviderError("Provider \u672A\u8FD4\u56DE\u4EFB\u4F55\u56FE\u50CF");
+          const mats = await materialize(out, { ...opts, preferredOutputFormat: req.params.output_format });
+          const paths = await saveImages(mats, {
+            outputDir: raw.outputDir ?? defaultDir(),
+            outputPath: args.output_path
+          });
+          return buildToolResult(paths, mats, { model: req.model, size: req.size, provider: adapter.format }, raw.returnInline);
+        } catch (e) {
+          return errorResult(e, auth.apiKey);
+        }
+      }
+    );
+  }
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  let raw;
+  try {
+    raw = loadRawConfig(process.env);
+  } catch (e) {
+    process.stderr.write(`[imagen-switch] \u914D\u7F6E\u9519\u8BEF\uFF1A${e instanceof Error ? e.message : String(e)}
+`);
+    process.exit(1);
+  }
+  const server = buildServer(raw);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`[imagen-switch] started (format=${raw.format})
+`);
+  process.on("SIGINT", async () => {
+    await server.close();
+    process.exit(0);
+  });
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((e) => {
+    process.stderr.write(`[imagen-switch] fatal: ${e instanceof Error ? e.message : String(e)}
+`);
+    process.exit(1);
+  });
+}
+export {
+  main
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "imagen-switch-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for multi-provider image generation via env config",
+  "type": "module",
+  "bin": {
+    "imagen-switch-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "ci": "npm test && npm run typecheck && npm run build",
+    "prepublishOnly": "npm run ci",
+    "publish:dry-run": "npm publish --dry-run",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "image-generation",
+    "openai",
+    "gemini",
+    "imagen",
+    "agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}