modelscope-image-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# modelscope-image-mcp
+
+魔搭（ModelScope）文生图 / 图生图 MCP 服务。零依赖，Node.js >= 18。
+
+免费调用 Qwen-Image、Z-Image、FLUX.1 等模型，生成的图片自动保存到本地。
+
+## 工具
+
+| 工具 | 说明 |
+| --- | --- |
+| `text_to_image` | 按文字描述生成图片 |
+| `image_to_image` | 基于输入图片 + 文字指令做图片编辑（换背景、改风格、增删元素） |
+| `list_models` | 列出已实测可用的模型 |
+
+## 已验证可用的模型
+
+文生图：
+
+- `Qwen/Qwen-Image`
+- `Tongyi-MAI/Z-Image-Turbo`
+- `Tongyi-MAI/Z-Image`
+- `black-forest-labs/FLUX.1-Krea-dev`
+
+图生图 / 图片编辑（**必须**提供 `image` 参数）：
+
+- `Qwen/Qwen-Image-Edit`
+- `Qwen/Qwen-Image-Edit-2509`
+- `black-forest-labs/FLUX.1-Kontext-dev`
+
+## 环境变量
+
+| 变量 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `MODELSCOPE_API_KEY` | 是 | — | 在 https://modelscope.cn 个人中心获取 |
+| `MODELSCOPE_API_BASE` | 否 | `https://api-inference.modelscope.cn/v1` | 接口地址 |
+| `MODELSCOPE_OUTPUT_DIR` | 否 | `~/modelscope-images` | 图片保存目录 |
+| `MODELSCOPE_TIMEOUT_MS` | 否 | `300000` | 任务超时毫秒数 |
+
+## 安装（免注册，本地文件方式）
+
+不需要 npm 账号，把整个目录拷到任意位置即可。MCP 配置二选一：
+
+**方式一：直接跑源码**（推荐，最简单）
+
+```json
+"modelscope-image": {
+  "command": "node",
+  "args": ["C:/path/to/modelscope-image-mcp/server.js"],
+  "env": { "MODELSCOPE_API_KEY": "ms-你的Key" }
+}
+```
+
+> Windows 上如果 `node` 不在 PATH 里，把 `command` 换成 node.exe 的绝对路径，
+> 例如 `C:/nvm4w/nodejs/node.exe`。
+
+**方式二：打包成 tgz 再跑**（整个包压缩成一个文件，便于拷贝）
+
+```powershell
+cd C:\path\to\modelscope-image-mcp
+npm pack
+```
+
+会生成 `modelscope-image-mcp-1.0.0.tgz`，然后：
+
+```json
+"modelscope-image": {
+  "command": "npx",
+  "args": ["-y", "C:/path/to/modelscope-image-mcp-1.0.0.tgz"],
+  "env": { "MODELSCOPE_API_KEY": "ms-你的Key" }
+}
+```
+
+## 使用示例
+
+```text
+用 text_to_image 生成一张“赛博朋克风格的广州塔夜景”，尺寸 1024x1024
+
+用 image_to_image 把这张图 <图片URL> 的背景换成雪山
+```
+
+## 注意事项
+
+- 接口是**异步任务制**：提交后拿 `task_id` 轮询，通常几十秒出图。
+- 轮询最长等 `MODELSCOPE_TIMEOUT_MS`（默认 5 分钟）。传**本地大图**做图生图时会慢很多，
+  因为要转 base64 上传，建议优先用公网图片 URL。
+- 图片默认保存在 `~/modelscope-images`，文件名形如 `ms-2026-10-15T06-30-00-000Z-1234.png`。
+- 本服务不打印任何 API Key，Key 只从环境变量读取。
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,31 @@
-{
-  "name": "modelscope-image-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "modelscope-image-mcp",
+  "version": "1.0.0",
+  "description": "ModelScope (魔搭) 文生图 / 图生图 MCP 服务：免费调用 Qwen-Image、Z-Image、FLUX.1 等模型",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "modelscope-image-mcp": "server.js"
+  },
+  "files": [
+    "server.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "modelscope",
+    "text-to-image",
+    "image-to-image",
+    "image-editing",
+    "qwen-image",
+    "z-image",
+    "flux"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "start": "node server.js"
+  }
+}

package/server.js

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+/**
+ * ModelScope（魔搭）图片生成 MCP 服务
+ *
+ * 提供三个工具：
+ *   - text_to_image   文生图
+ *   - image_to_image  图生图 / 图片编辑
+ *   - list_models     列出本服务已实测可用的模型
+ *
+ * 配置（环境变量）：
+ *   MODELSCOPE_API_KEY     （必填）魔搭 API Key，在 https://modelscope.cn 个人中心获取
+ *   MODELSCOPE_API_BASE    接口地址，默认 https://api-inference.modelscope.cn/v1
+ *   MODELSCOPE_OUTPUT_DIR  图片保存目录，默认 ~/modelscope-images
+ *   MODELSCOPE_TIMEOUT_MS  任务超时毫秒数，默认 300000
+ *
+ * 说明：零依赖，需要 Node.js >= 18（内置 fetch）。
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+
+const API_BASE = (
+  process.env.MODELSCOPE_API_BASE || "https://api-inference.modelscope.cn/v1"
+).replace(/\/+$/, "");
+const API_KEY = process.env.MODELSCOPE_API_KEY || "";
+const OUTPUT_DIR =
+  process.env.MODELSCOPE_OUTPUT_DIR || path.join(os.homedir(), "modelscope-images");
+const TASK_TIMEOUT_MS = Number(process.env.MODELSCOPE_TIMEOUT_MS || 300000);
+const POLL_INTERVAL_MS = 3000;
+
+const TEXT_TO_IMAGE_MODELS = [
+  { id: "Qwen/Qwen-Image", name: "Qwen-Image", desc: "通义千问图像生成，中英文文字渲染强，综合最稳" },
+  { id: "Tongyi-MAI/Z-Image-Turbo", name: "Z-Image-Turbo", desc: "轻量快速，出图速度快" },
+  { id: "Tongyi-MAI/Z-Image", name: "Z-Image", desc: "Z-Image 标准版，画质更好" },
+  { id: "black-forest-labs/FLUX.1-Krea-dev", name: "FLUX.1-Krea-dev", desc: "FLUX 系列，质感细腻" },
+];
+
+const IMAGE_TO_IMAGE_MODELS = [
+  { id: "Qwen/Qwen-Image-Edit", name: "Qwen-Image-Edit", desc: "指令式图片编辑（必须提供 image）" },
+  { id: "Qwen/Qwen-Image-Edit-2509", name: "Qwen-Image-Edit-2509", desc: "图片编辑增强版（必须提供 image）" },
+  { id: "black-forest-labs/FLUX.1-Kontext-dev", name: "FLUX.1-Kontext-dev", desc: "FLUX 图片编辑（必须提供 image）" },
+];
+
+const DEFAULT_TEXT_TO_IMAGE_MODEL = "Qwen/Qwen-Image";
+const DEFAULT_IMAGE_TO_IMAGE_MODEL = "Qwen/Qwen-Image-Edit";
+
+// ---------------------------------------------------------------- 基础工具
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function log(...args) {
+  // 只能往 stderr 写，stdout 被 JSON-RPC 占用
+  process.stderr.write(args.join(" ") + "\n");
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-").replace("Z", "");
+}
+
+// ---------------------------------------------------------- ModelScope 调用
+
+async function submitTask(payload) {
+  if (!API_KEY) {
+    throw new Error(
+      "未配置 MODELSCOPE_API_KEY 环境变量：请在 https://modelscope.cn 个人中心获取 API Key，并在 MCP 配置的 env 中设置"
+    );
+  }
+
+  const res = await fetch(`${API_BASE}/images/generations`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${API_KEY}`,
+      "Content-Type": "application/json",
+      // 关键：不带这个头会拿不到 task_id
+      "X-ModelScope-Async-Mode": "true",
+    },
+    body: JSON.stringify(payload),
+  });
+
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new Error(`提交任务失败：HTTP ${res.status} ${text.slice(0, 300)}`);
+  }
+
+  if (!res.ok || !data.task_id) {
+    throw new Error(`提交任务失败：HTTP ${res.status} ${JSON.stringify(data).slice(0, 500)}`);
+  }
+  return data.task_id;
+}
+
+async function waitTask(taskId, timeoutMs = TASK_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    const res = await fetch(`${API_BASE}/tasks/${taskId}`, {
+      headers: {
+        Authorization: `Bearer ${API_KEY}`,
+        // 关键：轮询不带这个头拿不到 output_images
+        "X-ModelScope-Task-Type": "image_generation",
+      },
+    });
+
+    const text = await res.text();
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      throw new Error(`查询任务失败：HTTP ${res.status} ${text.slice(0, 300)}`);
+    }
+
+    const status = data.task_status;
+    if (status === "SUCCEED") return data;
+    if (status === "FAILED") {
+      throw new Error(`任务失败：${JSON.stringify(data.errors || data).slice(0, 500)}`);
+    }
+    // PENDING / RUNNING 继续等
+    await sleep(POLL_INTERVAL_MS);
+  }
+
+  throw new Error(`任务超时（${Math.round(timeoutMs / 1000)}s），可调大 MODELSCOPE_TIMEOUT_MS`);
+}
+
+async function downloadImage(url, dir) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`下载图片失败：HTTP ${res.status} ${url}`);
+
+  const buf = Buffer.from(await res.arrayBuffer());
+  await fs.promises.mkdir(dir, { recursive: true });
+
+  let ext = ".png";
+  try {
+    const extname = path.extname(new URL(url).pathname);
+    if (extname) ext = extname;
+  } catch {
+    /* 忽略，用默认后缀 */
+  }
+
+  const file = path.join(dir, `ms-${timestamp()}-${Math.floor(Math.random() * 1e4)}${ext}`);
+  await fs.promises.writeFile(file, buf);
+  return file;
+}
+
+/** 把入参转成接口能接受的图片引用：http(s) 直接透传，本地文件转 data URI */
+async function toImageRef(input) {
+  if (/^https?:\/\//i.test(input)) return input;
+
+  const abs = path.resolve(input);
+  const buf = await fs.promises.readFile(abs);
+  const raw = path.extname(abs).slice(1).toLowerCase();
+  const mime =
+    raw === "jpg" || raw === "jpeg"
+      ? "image/jpeg"
+      : raw === "webp"
+        ? "image/webp"
+        : `image/${raw || "png"}`;
+  return `data:${mime};base64,${buf.toString("base64")}`;
+}
+
+// ------------------------------------------------------------------ 生成流程
+
+async function runGeneration({ model, prompt, negativePrompt, size, seed, image, outputDir }) {
+  const payload = { model, prompt };
+  if (negativePrompt) payload.negative_prompt = negativePrompt;
+  if (size) payload.size = size;
+  if (seed !== undefined && seed !== null) payload.seed = seed;
+  if (image) payload.image_url = await toImageRef(image);
+
+  const taskId = await submitTask(payload);
+  const result = await waitTask(taskId);
+
+  const raw = result.output_images ?? result.output_image ?? [];
+  const urls = (Array.isArray(raw) ? raw : [raw]).filter(Boolean);
+
+  const dir = outputDir || OUTPUT_DIR;
+  const files = [];
+  for (const url of urls) {
+    files.push(await downloadImage(url, dir));
+  }
+
+  return { taskId, files, urls };
+}
+
+function renderResult({ taskId, files, urls }) {
+  if (!files.length) {
+    return `任务 ${taskId} 已完成，但未返回图片。原始响应：${JSON.stringify(urls)}`;
+  }
+  const lines = [`已生成 ${files.length} 张图片：`, ""];
+  files.forEach((f, i) => {
+    lines.push(`${i + 1}. 本地文件：${f}`);
+    if (urls[i]) lines.push(`   原始链接：${urls[i]}`);
+  });
+  lines.push("", `任务 ID：${taskId}`);
+  return lines.join("\n");
+}
+
+function renderModelList() {
+  const fmt = (list) =>
+    list.map((m) => `  - ${m.id}\n      ${m.name}：${m.desc}`).join("\n");
+  return [
+    "文生图模型：",
+    fmt(TEXT_TO_IMAGE_MODELS),
+    "",
+    "图生图 / 图片编辑模型（必须提供 image 参数）：",
+    fmt(IMAGE_TO_IMAGE_MODELS),
+    "",
+    `默认：文生图 = ${DEFAULT_TEXT_TO_IMAGE_MODEL}，图生图 = ${DEFAULT_IMAGE_TO_IMAGE_MODEL}`,
+  ].join("\n");
+}
+
+// -------------------------------------------------------------------- 工具层
+
+async function callTool(name, args) {
+  switch (name) {
+    case "list_models":
+      return renderModelList();
+
+    case "text_to_image": {
+      const prompt = args.prompt;
+      if (!prompt) throw new Error("缺少必填参数 prompt");
+      const result = await runGeneration({
+        model: args.model || DEFAULT_TEXT_TO_IMAGE_MODEL,
+        prompt,
+        negativePrompt: args.negative_prompt,
+        size: args.size,
+        seed: args.seed,
+        outputDir: args.output_dir,
+      });
+      return renderResult(result);
+    }
+
+    case "image_to_image": {
+      const image = args.image;
+      const prompt = args.prompt;
+      if (!image) throw new Error("缺少必填参数 image（公网 URL 或本地文件绝对路径）");
+      if (!prompt) throw new Error("缺少必填参数 prompt");
+      const result = await runGeneration({
+        model: args.model || DEFAULT_IMAGE_TO_IMAGE_MODEL,
+        prompt,
+        negativePrompt: args.negative_prompt,
+        size: args.size,
+        seed: args.seed,
+        image,
+        outputDir: args.output_dir,
+      });
+      return renderResult(result);
+    }
+
+    default:
+      throw new Error(`未知工具：${name}`);
+  }
+}
+
+const TOOLS = [
+  {
+    name: "text_to_image",
+    description:
+      "用魔搭（ModelScope）的文生图模型，按文字描述生成图片，自动保存到本地并返回文件路径。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "图片的文字描述，中英文均可" },
+        model: {
+          type: "string",
+          description: `模型 ID，默认 ${DEFAULT_TEXT_TO_IMAGE_MODEL}。可选：${TEXT_TO_IMAGE_MODELS.map((m) => m.id).join("、")}`,
+        },
+        negative_prompt: { type: "string", description: "反向提示词，描述不希望出现的内容" },
+        size: { type: "string", description: "图片尺寸，如 1024x1024、1280x720（部分模型支持）" },
+        seed: { type: "integer", description: "随机种子，便于复现同一张图" },
+        output_dir: { type: "string", description: "图片保存目录，默认 ~/modelscope-images" },
+      },
+      required: ["prompt"],
+    },
+  },
+  {
+    name: "image_to_image",
+    description:
+      "用魔搭（ModelScope）的图片编辑模型，基于输入图片 + 文字指令生成新图片（换背景、改风格、增删元素等）。必须提供 image。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        image: {
+          type: "string",
+          description:
+            "输入图片：推荐公网 URL（快）；本地文件请给绝对路径（会转 base64 上传，较慢，可能需调大超时）",
+        },
+        prompt: { type: "string", description: "编辑指令，例如“把背景换成夜晚的城市街景”" },
+        model: {
+          type: "string",
+          description: `模型 ID，默认 ${DEFAULT_IMAGE_TO_IMAGE_MODEL}。可选：${IMAGE_TO_IMAGE_MODELS.map((m) => m.id).join("、")}`,
+        },
+        negative_prompt: { type: "string", description: "反向提示词" },
+        size: { type: "string", description: "输出图片尺寸，如 1024x1024" },
+        seed: { type: "integer", description: "随机种子" },
+        output_dir: { type: "string", description: "图片保存目录" },
+      },
+      required: ["image", "prompt"],
+    },
+  },
+  {
+    name: "list_models",
+    description: "列出本服务已实测可用的文生图 / 图生图模型清单。",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+];
+
+// ------------------------------------------------------------ MCP JSON-RPC
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+async function handleMessage(msg) {
+  const { id, method, params } = msg;
+
+  switch (method) {
+    case "initialize":
+      reply(id, {
+        protocolVersion: params?.protocolVersion || "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "modelscope-image-mcp", version: "1.0.0" },
+      });
+      return;
+
+    case "ping":
+      reply(id, {});
+      return;
+
+    case "tools/list":
+      reply(id, { tools: TOOLS });
+      return;
+
+    case "tools/call": {
+      const name = params?.name;
+      const args = params?.arguments || {};
+      try {
+        const text = await callTool(name, args);
+        reply(id, { content: [{ type: "text", text }] });
+      } catch (err) {
+        reply(id, {
+          content: [{ type: "text", text: `错误: ${err?.message || String(err)}` }],
+          isError: true,
+        });
+      }
+      return;
+    }
+
+    default:
+      replyError(id, -32601, `不支持的方法: ${method}`);
+  }
+}
+
+let pending = 0;
+let stdinEnded = false;
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+
+  let msg;
+  try {
+    msg = JSON.parse(trimmed);
+  } catch {
+    log("无法解析的输入:", trimmed.slice(0, 200));
+    return;
+  }
+
+  // 通知（无 id）不需要回复
+  if (msg.id === undefined || msg.id === null) return;
+
+  pending++;
+  handleMessage(msg)
+    .catch((err) => replyError(msg.id, -32603, err?.message || String(err)))
+    .finally(() => {
+      pending--;
+      if (stdinEnded && pending === 0) process.exit(0);
+    });
+});
+
+rl.on("close", () => {
+  stdinEnded = true;
+  if (pending === 0) process.exit(0);
+});
+
+log("modelscope-image-mcp 已启动" + (API_KEY ? "" : "（警告：未配置 MODELSCOPE_API_KEY）"));