@gracefullight/modelscope-image-mcp 0.1.1

package/README.ko.md

@@ -0,0 +1,113 @@
+# @gracefullight/modelscope-image-mcp
+
+> ModelScope API-Inference 이미지 생성을 위한 MCP 서버
+
+[![npm version](https://img.shields.io/npm/v/@gracefullight/modelscope-image-mcp.svg)](https://www.npmjs.com/package/@gracefullight/modelscope-image-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[English](./README.md) | **한국어**
+
+## 기능
+
+- **ModelScope 비동기 이미지 API** - 작업 제출 후 `/v1/tasks/{id}`를 폴링하고 결과를 다운로드
+- **모든 API-Inference 이미지 모델** - 커뮤니티 LoRA 저장소(예: `owner/lora-name`) 포함
+- **필수 환경변수 1개** - 나머지는 모두 기본값 제공
+- **로컬 파일 저장** - 이미지를 저장하고 절대 경로를 반환
+- **모든 stdio MCP 클라이언트** - Claude Desktop, Claude Code, Qwen Code, Cursor 등
+
+## 요구 사항
+
+- Node.js 20+
+- ModelScope 액세스 토큰 ([modelscope.ai](https://modelscope.ai) 또는 [modelscope.cn](https://modelscope.cn) 계정 설정에서 발급)
+
+## 빠른 시작
+
+MCP 클라이언트 설정에 서버를 추가합니다.
+
+```json
+{
+  "mcpServers": {
+    "modelscope-image": {
+      "command": "npx",
+      "args": ["-y", "@gracefullight/modelscope-image-mcp"],
+      "env": {
+        "MODELSCOPE_API_TOKEN": "ms-..."
+      }
+    }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add modelscope-image -e MODELSCOPE_API_TOKEN=ms-... -- npx -y @gracefullight/modelscope-image-mcp
+```
+
+## 설정
+
+필수 환경변수는 `MODELSCOPE_API_TOKEN` 하나입니다(`MODELSCOPE_SDK_TOKEN`도 인식). 선택 CLI 옵션은 다음과 같습니다.
+
+| 옵션 | 기본값 | 설명 |
+|------|--------|------|
+| `--model` | `Qwen/Qwen-Image` | 도구 호출에 `model`이 없을 때 사용할 모델 |
+| `--output-dir` | 프로젝트의 `generated-images` | 이미지 저장 디렉터리. 지정하지 않으면 클라이언트가 알려준 워크스페이스 루트([MCP roots](https://modelcontextprotocol.io/specification/2025-06-18/client/roots)) 아래 `generated-images`에 저장하고, 루트 정보가 없으면 서버 작업 디렉터리 아래에 저장 |
+| `--base-url` | `https://api-inference.modelscope.ai` | API 기본 URL. ModelScope 중국 사이트는 `https://api-inference.modelscope.cn` |
+
+LoRA 모델과 고정 저장 경로를 쓰는 예시:
+
+```json
+{
+  "mcpServers": {
+    "modelscope-image": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@gracefullight/modelscope-image-mcp",
+        "--model",
+        "owner/lora-name",
+        "--output-dir",
+        "/Users/me/Pictures/modelscope"
+      ],
+      "env": {
+        "MODELSCOPE_API_TOKEN": "ms-..."
+      }
+    }
+  }
+}
+```
+
+## 도구: `generate_image`
+
+| 파라미터 | 필수 | 설명 |
+|----------|------|------|
+| `prompt` | 예 | 생성할 이미지에 대한 상세 설명 |
+| `model` | 아니요 | ModelScope 모델 ID(LoRA 저장소 지원). 기본값은 `--model` |
+| `size` | 아니요 | `WIDTHxHEIGHT` 형식(예: `1024x1024`, `768x1344`). 지원 크기는 모델마다 다름 |
+| `output_filename` | 아니요 | 디렉터리를 제외한 파일 이름. 확장자는 반환된 이미지 형식을 따름 |
+
+성공하면 저장 경로, 모델, 작업 ID, 이미지 URL을 반환합니다. HTTP 오류, 작업 실패, 시간 초과는 도구 오류로 반환합니다.
+
+## 참고
+
+- 생성은 보통 수십 초가 걸립니다. 서버는 5초 간격으로 최대 10분간 폴링합니다.
+- 요청은 ModelScope API-Inference 사용량에 포함되며, ModelScope가 콘텐츠 검수로 프롬프트를 거부할 수 있습니다.
+- 모델은 사용하는 사이트의 API-Inference에서 제공되어야 합니다. modelscope.ai의 모델이 modelscope.cn에는 없을 수 있습니다.
+- 토큰은 API 기본 URL에만 전송되며 이미지 다운로드 호스트에는 전송하지 않습니다.
+
+## 코드에서 사용
+
+```ts
+import { generateImage, saveImage } from "@gracefullight/modelscope-image-mcp";
+
+const image = await generateImage(
+  { apiKey: process.env.MODELSCOPE_API_TOKEN ?? "", baseUrl: "https://api-inference.modelscope.ai" },
+  { prompt: "a red apple on a white table", model: "Qwen/Qwen-Image", size: "1024x1024" },
+);
+
+const path = await saveImage("./generated-images", image.bytes, image.contentType, "apple");
+```
+
+## 라이선스
+
+MIT

package/README.md

@@ -0,0 +1,113 @@
+# @gracefullight/modelscope-image-mcp
+
+> MCP server for ModelScope API-Inference image generation
+
+[![npm version](https://img.shields.io/npm/v/@gracefullight/modelscope-image-mcp.svg)](https://www.npmjs.com/package/@gracefullight/modelscope-image-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**English** | [한국어](./README.ko.md)
+
+## Features
+
+- **Async ModelScope image API** - Submits a task, polls `/v1/tasks/{id}`, and downloads the result
+- **Any API-Inference image model** - Including community LoRA repositories (e.g. `owner/lora-name`)
+- **One required environment variable** - Everything else has sensible defaults
+- **Local files** - Saves the image and returns its absolute path
+- **Any stdio MCP client** - Claude Desktop, Claude Code, Qwen Code, Cursor, and more
+
+## Requirements
+
+- Node.js 20+
+- A ModelScope access token (from your account settings on [modelscope.ai](https://modelscope.ai) or [modelscope.cn](https://modelscope.cn))
+
+## Quick Start
+
+Add the server to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "modelscope-image": {
+      "command": "npx",
+      "args": ["-y", "@gracefullight/modelscope-image-mcp"],
+      "env": {
+        "MODELSCOPE_API_TOKEN": "ms-..."
+      }
+    }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add modelscope-image -e MODELSCOPE_API_TOKEN=ms-... -- npx -y @gracefullight/modelscope-image-mcp
+```
+
+## Configuration
+
+The only required environment variable is `MODELSCOPE_API_TOKEN` (`MODELSCOPE_SDK_TOKEN` is also accepted). Optional CLI flags:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model` | `Qwen/Qwen-Image` | Model used when a tool call omits `model` |
+| `--output-dir` | `generated-images` in the project | Directory for saved images. Without it, images go to `generated-images` under the client's workspace root ([MCP roots](https://modelcontextprotocol.io/specification/2025-06-18/client/roots)), or under the server's working directory if the client reports no roots |
+| `--base-url` | `https://api-inference.modelscope.ai` | API base URL. Use `https://api-inference.modelscope.cn` for ModelScope China |
+
+Example with a LoRA model and a fixed output directory:
+
+```json
+{
+  "mcpServers": {
+    "modelscope-image": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@gracefullight/modelscope-image-mcp",
+        "--model",
+        "owner/lora-name",
+        "--output-dir",
+        "/Users/me/Pictures/modelscope"
+      ],
+      "env": {
+        "MODELSCOPE_API_TOKEN": "ms-..."
+      }
+    }
+  }
+}
+```
+
+## Tool: `generate_image`
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `prompt` | Yes | Detailed description of the image |
+| `model` | No | ModelScope model id (LoRA repositories supported). Defaults to `--model` |
+| `size` | No | `WIDTHxHEIGHT`, e.g. `1024x1024` or `768x1344`. Supported sizes depend on the model |
+| `output_filename` | No | File name without directories. The extension follows the returned image type |
+
+On success the tool returns the saved path, model, task id, and image URL. Failures (HTTP errors, failed tasks, timeouts) are returned as tool errors.
+
+## Notes
+
+- Generation usually takes tens of seconds. The server polls every 5 seconds for up to 10 minutes.
+- Requests count against your ModelScope API-Inference quota, and ModelScope may reject prompts through content moderation.
+- A model must be served by the API-Inference endpoint of the site you use; a model on modelscope.ai may not exist on modelscope.cn.
+- The token is sent only to the API base URL, never to the image download host.
+
+## Programmatic Usage
+
+```ts
+import { generateImage, saveImage } from "@gracefullight/modelscope-image-mcp";
+
+const image = await generateImage(
+  { apiKey: process.env.MODELSCOPE_API_TOKEN ?? "", baseUrl: "https://api-inference.modelscope.ai" },
+  { prompt: "a red apple on a white table", model: "Qwen/Qwen-Image", size: "1024x1024" },
+);
+
+const path = await saveImage("./generated-images", image.bytes, image.contentType, "apple");
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+
+// src/config.ts
+import { resolve } from "path";
+import { parseArgs } from "util";
+var DEFAULT_BASE_URL = "https://api-inference.modelscope.ai";
+var DEFAULT_MODEL = "Qwen/Qwen-Image";
+var DEFAULT_OUTPUT_DIR = "generated-images";
+var TOKEN_ENV_KEYS = ["MODELSCOPE_API_TOKEN", "MODELSCOPE_SDK_TOKEN"];
+function resolveConfig(argv, env = process.env, cwd = process.cwd()) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      model: { type: "string" },
+      "output-dir": { type: "string" },
+      "base-url": { type: "string" }
+    },
+    strict: true,
+    allowPositionals: false
+  });
+  const apiKey = TOKEN_ENV_KEYS.map((key) => env[key]?.trim()).find(Boolean);
+  if (!apiKey) {
+    throw new Error(`Set ${TOKEN_ENV_KEYS[0]} to your ModelScope access token.`);
+  }
+  const outputDir = values["output-dir"];
+  return {
+    apiKey,
+    baseUrl: normalizeBaseUrl(values["base-url"] ?? DEFAULT_BASE_URL),
+    defaultModel: values.model ?? DEFAULT_MODEL,
+    ...outputDir ? { outputDir: resolve(cwd, outputDir) } : {},
+    cwd
+  };
+}
+function resolveOutputDir(config, rootDirectories2 = []) {
+  return config.outputDir ?? resolve(rootDirectories2[0] ?? config.cwd, DEFAULT_OUTPUT_DIR);
+}
+function normalizeBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`--base-url must be a valid URL: ${value}`);
+  }
+  if (url.protocol !== "https:") {
+    throw new Error(`--base-url must use HTTPS: ${value}`);
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod";
+
+// src/modelscope-client.ts
+var DEFAULT_POLL_INTERVAL_MS = 5e3;
+var DEFAULT_TIMEOUT_MS = 10 * 6e4;
+var MAX_ERROR_BODY_CHARS = 500;
+var ModelScopeError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "ModelScopeError";
+    this.status = status;
+  }
+};
+var defaultSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+async function generateImage(options, request, signal) {
+  const fetchFn = options.fetch ?? fetch;
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  const auth = { Authorization: `Bearer ${options.apiKey}` };
+  const body = { model: request.model, prompt: request.prompt };
+  if (request.size) {
+    body.size = request.size;
+  }
+  const submitResponse = await fetchFn(`${baseUrl}/v1/images/generations`, {
+    method: "POST",
+    headers: { ...auth, "Content-Type": "application/json", "X-ModelScope-Async-Mode": "true" },
+    body: JSON.stringify(body),
+    signal
+  });
+  const submitted = await readJson(submitResponse, "submit");
+  const taskId = submitted.task_id;
+  if (!taskId) {
+    throw new ModelScopeError(
+      `ModelScope submit response did not include task_id: ${truncate(JSON.stringify(submitted))}`
+    );
+  }
+  const imageUrl = await waitForImageUrl(options, baseUrl, auth, taskId, signal);
+  const { contentType, bytes } = await downloadImage(fetchFn, imageUrl, signal);
+  return { taskId, imageUrl, contentType, bytes };
+}
+async function waitForImageUrl(options, baseUrl, auth, taskId, signal) {
+  const fetchFn = options.fetch ?? fetch;
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? Date.now;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const deadline = now() + timeoutMs;
+  for (; ; ) {
+    await sleep(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    signal?.throwIfAborted();
+    const response = await fetchFn(`${baseUrl}/v1/tasks/${encodeURIComponent(taskId)}`, {
+      headers: { ...auth, "X-ModelScope-Task-Type": "image_generation" },
+      signal
+    });
+    const task = await readJson(response, "poll");
+    const imageUrl = imageUrlFromTask(task, taskId);
+    if (imageUrl) {
+      return imageUrl;
+    }
+    if (now() >= deadline) {
+      throw new ModelScopeError(
+        `ModelScope task ${taskId} did not finish within ${Math.round(timeoutMs / 1e3)}s (last status: ${task.task_status ?? "unknown"})`
+      );
+    }
+  }
+}
+function imageUrlFromTask(task, taskId) {
+  if (task.task_status === "FAILED") {
+    throw new ModelScopeError(
+      `ModelScope task ${taskId} failed: ${truncate(task.message ?? JSON.stringify(task))}`
+    );
+  }
+  if (task.task_status !== "SUCCEED") {
+    return void 0;
+  }
+  const imageUrl = task.output_images?.[0];
+  if (!imageUrl) {
+    throw new ModelScopeError(`ModelScope task ${taskId} succeeded without output_images`);
+  }
+  return imageUrl;
+}
+async function downloadImage(fetchFn, imageUrl, signal) {
+  let url;
+  try {
+    url = new URL(imageUrl);
+  } catch {
+    throw new ModelScopeError(`ModelScope returned an invalid image URL: ${truncate(imageUrl)}`);
+  }
+  if (url.protocol !== "https:") {
+    throw new ModelScopeError(`ModelScope returned a non-HTTPS image URL: ${truncate(imageUrl)}`);
+  }
+  const response = await fetchFn(url, { signal });
+  if (!response.ok) {
+    throw new ModelScopeError(
+      `Image download failed with HTTP ${response.status}`,
+      response.status
+    );
+  }
+  const contentType = (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+  if (!contentType.startsWith("image/")) {
+    throw new ModelScopeError(
+      `Downloaded content is not an image (${contentType || "unknown content type"})`
+    );
+  }
+  return { contentType, bytes: new Uint8Array(await response.arrayBuffer()) };
+}
+async function readJson(response, stage) {
+  const text = await response.text();
+  if (!response.ok) {
+    throw new ModelScopeError(
+      `ModelScope ${stage} failed with HTTP ${response.status}: ${truncate(text)}`,
+      response.status
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new ModelScopeError(
+      `ModelScope ${stage} returned invalid JSON (HTTP ${response.status})`,
+      response.status
+    );
+  }
+}
+function truncate(value) {
+  return value.length > MAX_ERROR_BODY_CHARS ? `${value.slice(0, MAX_ERROR_BODY_CHARS)}\u2026` : value;
+}
+
+// src/roots.ts
+import { fileURLToPath } from "url";
+function rootDirectories(roots) {
+  return roots.flatMap((root) => {
+    if (!root.uri.startsWith("file://")) {
+      return [];
+    }
+    try {
+      return [fileURLToPath(root.uri)];
+    } catch {
+      return [];
+    }
+  });
+}
+
+// src/save-image.ts
+import { randomUUID } from "crypto";
+import { mkdir, writeFile } from "fs/promises";
+import { basename, extname, join, resolve as resolve2 } from "path";
+var EXTENSION_BY_CONTENT_TYPE = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+  "image/gif": ".gif"
+};
+function toFileStem(name, date = /* @__PURE__ */ new Date(), id = randomUUID().slice(0, 8)) {
+  const raw = name ? basename(name, extname(name)) : "";
+  const stem = raw.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^[._]+|[._]+$/g, "");
+  if (stem) {
+    return stem;
+  }
+  const stamp = date.toISOString().replace(/[-:]/g, "").replace(/\..+$/, "").replace("T", "-");
+  return `${stamp}-${id}`;
+}
+async function saveImage(outputDir, bytes, contentType, filename) {
+  const dir = resolve2(outputDir);
+  await mkdir(dir, { recursive: true });
+  const path = join(
+    dir,
+    `${toFileStem(filename)}${EXTENSION_BY_CONTENT_TYPE[contentType] ?? ".png"}`
+  );
+  await writeFile(path, bytes);
+  return path;
+}
+
+// src/version.ts
+var VERSION = "0.1.1";
+
+// src/server.ts
+var SIZE_PATTERN = /^\d{2,4}x\d{2,4}$/;
+var ROOTS_TIMEOUT_MS = 5e3;
+var generateImageInputSchema = z.object({
+  prompt: z.string().trim().min(1).describe("Detailed description of the image to generate."),
+  model: z.string().trim().min(1).optional().describe(
+    "ModelScope model id, including LoRA repositories. Defaults to the server's configured model."
+  ),
+  size: z.string().regex(SIZE_PATTERN, "size must look like 1024x1024").optional().describe("Output size as WIDTHxHEIGHT, e.g. 1024x1024 or 768x1344."),
+  output_filename: z.string().optional().describe("File name without directories. The extension follows the returned image type.")
+});
+async function runGenerateImage(config, input, deps = {}) {
+  const generate = deps.generate ?? generateImage;
+  const save = deps.save ?? saveImage;
+  const model = input.model ?? config.defaultModel;
+  try {
+    const roots = config.outputDir || !deps.listRootDirectories ? [] : await deps.listRootDirectories();
+    const outputDir = resolveOutputDir(config, roots);
+    const image = await generate(
+      { apiKey: config.apiKey, baseUrl: config.baseUrl },
+      { prompt: input.prompt, model, size: input.size }
+    );
+    const path = await save(outputDir, image.bytes, image.contentType, input.output_filename);
+    const lines = [
+      `Image saved to ${path}`,
+      `model: ${model}`,
+      ...input.size ? [`size: ${input.size}`] : [],
+      `task_id: ${image.taskId}`,
+      `url: ${image.imageUrl}`
+    ];
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Image generation failed: ${message}` }]
+    };
+  }
+}
+function createServer(config, deps = {}) {
+  const server = new McpServer({ name: "modelscope-image-mcp", version: VERSION });
+  const toolDeps = {
+    listRootDirectories: () => listClientRootDirectories(server),
+    ...deps
+  };
+  server.registerTool(
+    "generate_image",
+    {
+      title: "Generate image",
+      description: "Generate an image with a ModelScope API-Inference model (LoRA repository ids supported) and save it locally. Returns the saved file path.",
+      inputSchema: generateImageInputSchema
+    },
+    (input) => runGenerateImage(config, input, toolDeps)
+  );
+  return server;
+}
+async function listClientRootDirectories(server) {
+  if (!server.server.getClientCapabilities()?.roots) {
+    return [];
+  }
+  try {
+    const { roots } = await server.server.listRoots(void 0, { timeout: ROOTS_TIMEOUT_MS });
+    return rootDirectories(roots);
+  } catch {
+    return [];
+  }
+}
+
+// src/cli.ts
+async function main() {
+  const config = resolveConfig(process.argv.slice(2));
+  const server = createServer(config);
+  await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+  console.error(`modelscope-image-mcp: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+import { McpServer, CallToolResult } from '@modelcontextprotocol/server';
+import * as z from 'zod';
+
+declare const DEFAULT_BASE_URL = "https://api-inference.modelscope.ai";
+declare const DEFAULT_MODEL = "Qwen/Qwen-Image";
+declare const DEFAULT_OUTPUT_DIR = "generated-images";
+/** The first key is canonical; the second keeps compatibility with the Python modelscope-image-mcp. */
+declare const TOKEN_ENV_KEYS: readonly ["MODELSCOPE_API_TOKEN", "MODELSCOPE_SDK_TOKEN"];
+interface ServerConfig {
+    apiKey: string;
+    baseUrl: string;
+    defaultModel: string;
+    /** Absolute `--output-dir`. When unset, images go to the client's workspace root. */
+    outputDir?: string;
+    cwd: string;
+}
+declare function resolveConfig(argv: string[], env?: NodeJS.ProcessEnv, cwd?: string): ServerConfig;
+/**
+ * Chooses where images are saved: the explicit `--output-dir`, otherwise `generated-images`
+ * under the first workspace root reported by the client, otherwise under the working directory.
+ */
+declare function resolveOutputDir(config: ServerConfig, rootDirectories?: string[]): string;
+
+interface ModelScopeClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+}
+interface ImageGenerationRequest {
+    prompt: string;
+    model: string;
+    size?: string;
+}
+interface GeneratedImage {
+    taskId: string;
+    imageUrl: string;
+    contentType: string;
+    bytes: Uint8Array;
+}
+declare class ModelScopeError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+/**
+ * Generates an image through the ModelScope async API:
+ * submit with X-ModelScope-Async-Mode, poll /v1/tasks/{id}, then download the first output image.
+ */
+declare function generateImage(options: ModelScopeClientOptions, request: ImageGenerationRequest, signal?: AbortSignal): Promise<GeneratedImage>;
+
+interface RootLike {
+    uri: string;
+}
+/** Converts MCP roots to local directory paths, skipping non-file and malformed URIs. */
+declare function rootDirectories(roots: RootLike[]): string[];
+
+/** Returns a filesystem-safe file stem; directories and extensions in `name` are discarded. */
+declare function toFileStem(name?: string, date?: Date, id?: string): string;
+declare function saveImage(outputDir: string, bytes: Uint8Array, contentType: string, filename?: string): Promise<string>;
+
+declare const generateImageInputSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    model: z.ZodOptional<z.ZodString>;
+    size: z.ZodOptional<z.ZodString>;
+    output_filename: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type GenerateImageInput = z.infer<typeof generateImageInputSchema>;
+interface GenerateImageDeps {
+    generate?: typeof generateImage;
+    save?: typeof saveImage;
+    /** Workspace root directories reported by the client; consulted only when `--output-dir` is unset. */
+    listRootDirectories?: () => Promise<string[]>;
+}
+declare function runGenerateImage(config: ServerConfig, input: GenerateImageInput, deps?: GenerateImageDeps): Promise<CallToolResult>;
+declare function createServer(config: ServerConfig, deps?: GenerateImageDeps): McpServer;
+
+declare const VERSION = "0.1.1";
+
+export { DEFAULT_BASE_URL, DEFAULT_MODEL, DEFAULT_OUTPUT_DIR, type GenerateImageDeps, type GenerateImageInput, type GeneratedImage, type ImageGenerationRequest, type ModelScopeClientOptions, ModelScopeError, type RootLike, type ServerConfig, TOKEN_ENV_KEYS, VERSION, createServer, generateImage, generateImageInputSchema, resolveConfig, resolveOutputDir, rootDirectories, runGenerateImage, saveImage, toFileStem };

package/dist/index.js

@@ -0,0 +1,307 @@
+// src/config.ts
+import { resolve } from "path";
+import { parseArgs } from "util";
+var DEFAULT_BASE_URL = "https://api-inference.modelscope.ai";
+var DEFAULT_MODEL = "Qwen/Qwen-Image";
+var DEFAULT_OUTPUT_DIR = "generated-images";
+var TOKEN_ENV_KEYS = ["MODELSCOPE_API_TOKEN", "MODELSCOPE_SDK_TOKEN"];
+function resolveConfig(argv, env = process.env, cwd = process.cwd()) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      model: { type: "string" },
+      "output-dir": { type: "string" },
+      "base-url": { type: "string" }
+    },
+    strict: true,
+    allowPositionals: false
+  });
+  const apiKey = TOKEN_ENV_KEYS.map((key) => env[key]?.trim()).find(Boolean);
+  if (!apiKey) {
+    throw new Error(`Set ${TOKEN_ENV_KEYS[0]} to your ModelScope access token.`);
+  }
+  const outputDir = values["output-dir"];
+  return {
+    apiKey,
+    baseUrl: normalizeBaseUrl(values["base-url"] ?? DEFAULT_BASE_URL),
+    defaultModel: values.model ?? DEFAULT_MODEL,
+    ...outputDir ? { outputDir: resolve(cwd, outputDir) } : {},
+    cwd
+  };
+}
+function resolveOutputDir(config, rootDirectories2 = []) {
+  return config.outputDir ?? resolve(rootDirectories2[0] ?? config.cwd, DEFAULT_OUTPUT_DIR);
+}
+function normalizeBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`--base-url must be a valid URL: ${value}`);
+  }
+  if (url.protocol !== "https:") {
+    throw new Error(`--base-url must use HTTPS: ${value}`);
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+// src/modelscope-client.ts
+var DEFAULT_POLL_INTERVAL_MS = 5e3;
+var DEFAULT_TIMEOUT_MS = 10 * 6e4;
+var MAX_ERROR_BODY_CHARS = 500;
+var ModelScopeError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "ModelScopeError";
+    this.status = status;
+  }
+};
+var defaultSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+async function generateImage(options, request, signal) {
+  const fetchFn = options.fetch ?? fetch;
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  const auth = { Authorization: `Bearer ${options.apiKey}` };
+  const body = { model: request.model, prompt: request.prompt };
+  if (request.size) {
+    body.size = request.size;
+  }
+  const submitResponse = await fetchFn(`${baseUrl}/v1/images/generations`, {
+    method: "POST",
+    headers: { ...auth, "Content-Type": "application/json", "X-ModelScope-Async-Mode": "true" },
+    body: JSON.stringify(body),
+    signal
+  });
+  const submitted = await readJson(submitResponse, "submit");
+  const taskId = submitted.task_id;
+  if (!taskId) {
+    throw new ModelScopeError(
+      `ModelScope submit response did not include task_id: ${truncate(JSON.stringify(submitted))}`
+    );
+  }
+  const imageUrl = await waitForImageUrl(options, baseUrl, auth, taskId, signal);
+  const { contentType, bytes } = await downloadImage(fetchFn, imageUrl, signal);
+  return { taskId, imageUrl, contentType, bytes };
+}
+async function waitForImageUrl(options, baseUrl, auth, taskId, signal) {
+  const fetchFn = options.fetch ?? fetch;
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? Date.now;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const deadline = now() + timeoutMs;
+  for (; ; ) {
+    await sleep(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    signal?.throwIfAborted();
+    const response = await fetchFn(`${baseUrl}/v1/tasks/${encodeURIComponent(taskId)}`, {
+      headers: { ...auth, "X-ModelScope-Task-Type": "image_generation" },
+      signal
+    });
+    const task = await readJson(response, "poll");
+    const imageUrl = imageUrlFromTask(task, taskId);
+    if (imageUrl) {
+      return imageUrl;
+    }
+    if (now() >= deadline) {
+      throw new ModelScopeError(
+        `ModelScope task ${taskId} did not finish within ${Math.round(timeoutMs / 1e3)}s (last status: ${task.task_status ?? "unknown"})`
+      );
+    }
+  }
+}
+function imageUrlFromTask(task, taskId) {
+  if (task.task_status === "FAILED") {
+    throw new ModelScopeError(
+      `ModelScope task ${taskId} failed: ${truncate(task.message ?? JSON.stringify(task))}`
+    );
+  }
+  if (task.task_status !== "SUCCEED") {
+    return void 0;
+  }
+  const imageUrl = task.output_images?.[0];
+  if (!imageUrl) {
+    throw new ModelScopeError(`ModelScope task ${taskId} succeeded without output_images`);
+  }
+  return imageUrl;
+}
+async function downloadImage(fetchFn, imageUrl, signal) {
+  let url;
+  try {
+    url = new URL(imageUrl);
+  } catch {
+    throw new ModelScopeError(`ModelScope returned an invalid image URL: ${truncate(imageUrl)}`);
+  }
+  if (url.protocol !== "https:") {
+    throw new ModelScopeError(`ModelScope returned a non-HTTPS image URL: ${truncate(imageUrl)}`);
+  }
+  const response = await fetchFn(url, { signal });
+  if (!response.ok) {
+    throw new ModelScopeError(
+      `Image download failed with HTTP ${response.status}`,
+      response.status
+    );
+  }
+  const contentType = (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+  if (!contentType.startsWith("image/")) {
+    throw new ModelScopeError(
+      `Downloaded content is not an image (${contentType || "unknown content type"})`
+    );
+  }
+  return { contentType, bytes: new Uint8Array(await response.arrayBuffer()) };
+}
+async function readJson(response, stage) {
+  const text = await response.text();
+  if (!response.ok) {
+    throw new ModelScopeError(
+      `ModelScope ${stage} failed with HTTP ${response.status}: ${truncate(text)}`,
+      response.status
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new ModelScopeError(
+      `ModelScope ${stage} returned invalid JSON (HTTP ${response.status})`,
+      response.status
+    );
+  }
+}
+function truncate(value) {
+  return value.length > MAX_ERROR_BODY_CHARS ? `${value.slice(0, MAX_ERROR_BODY_CHARS)}\u2026` : value;
+}
+
+// src/roots.ts
+import { fileURLToPath } from "url";
+function rootDirectories(roots) {
+  return roots.flatMap((root) => {
+    if (!root.uri.startsWith("file://")) {
+      return [];
+    }
+    try {
+      return [fileURLToPath(root.uri)];
+    } catch {
+      return [];
+    }
+  });
+}
+
+// src/save-image.ts
+import { randomUUID } from "crypto";
+import { mkdir, writeFile } from "fs/promises";
+import { basename, extname, join, resolve as resolve2 } from "path";
+var EXTENSION_BY_CONTENT_TYPE = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+  "image/gif": ".gif"
+};
+function toFileStem(name, date = /* @__PURE__ */ new Date(), id = randomUUID().slice(0, 8)) {
+  const raw = name ? basename(name, extname(name)) : "";
+  const stem = raw.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^[._]+|[._]+$/g, "");
+  if (stem) {
+    return stem;
+  }
+  const stamp = date.toISOString().replace(/[-:]/g, "").replace(/\..+$/, "").replace("T", "-");
+  return `${stamp}-${id}`;
+}
+async function saveImage(outputDir, bytes, contentType, filename) {
+  const dir = resolve2(outputDir);
+  await mkdir(dir, { recursive: true });
+  const path = join(
+    dir,
+    `${toFileStem(filename)}${EXTENSION_BY_CONTENT_TYPE[contentType] ?? ".png"}`
+  );
+  await writeFile(path, bytes);
+  return path;
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod";
+
+// src/version.ts
+var VERSION = "0.1.1";
+
+// src/server.ts
+var SIZE_PATTERN = /^\d{2,4}x\d{2,4}$/;
+var ROOTS_TIMEOUT_MS = 5e3;
+var generateImageInputSchema = z.object({
+  prompt: z.string().trim().min(1).describe("Detailed description of the image to generate."),
+  model: z.string().trim().min(1).optional().describe(
+    "ModelScope model id, including LoRA repositories. Defaults to the server's configured model."
+  ),
+  size: z.string().regex(SIZE_PATTERN, "size must look like 1024x1024").optional().describe("Output size as WIDTHxHEIGHT, e.g. 1024x1024 or 768x1344."),
+  output_filename: z.string().optional().describe("File name without directories. The extension follows the returned image type.")
+});
+async function runGenerateImage(config, input, deps = {}) {
+  const generate = deps.generate ?? generateImage;
+  const save = deps.save ?? saveImage;
+  const model = input.model ?? config.defaultModel;
+  try {
+    const roots = config.outputDir || !deps.listRootDirectories ? [] : await deps.listRootDirectories();
+    const outputDir = resolveOutputDir(config, roots);
+    const image = await generate(
+      { apiKey: config.apiKey, baseUrl: config.baseUrl },
+      { prompt: input.prompt, model, size: input.size }
+    );
+    const path = await save(outputDir, image.bytes, image.contentType, input.output_filename);
+    const lines = [
+      `Image saved to ${path}`,
+      `model: ${model}`,
+      ...input.size ? [`size: ${input.size}`] : [],
+      `task_id: ${image.taskId}`,
+      `url: ${image.imageUrl}`
+    ];
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Image generation failed: ${message}` }]
+    };
+  }
+}
+function createServer(config, deps = {}) {
+  const server = new McpServer({ name: "modelscope-image-mcp", version: VERSION });
+  const toolDeps = {
+    listRootDirectories: () => listClientRootDirectories(server),
+    ...deps
+  };
+  server.registerTool(
+    "generate_image",
+    {
+      title: "Generate image",
+      description: "Generate an image with a ModelScope API-Inference model (LoRA repository ids supported) and save it locally. Returns the saved file path.",
+      inputSchema: generateImageInputSchema
+    },
+    (input) => runGenerateImage(config, input, toolDeps)
+  );
+  return server;
+}
+async function listClientRootDirectories(server) {
+  if (!server.server.getClientCapabilities()?.roots) {
+    return [];
+  }
+  try {
+    const { roots } = await server.server.listRoots(void 0, { timeout: ROOTS_TIMEOUT_MS });
+    return rootDirectories(roots);
+  } catch {
+    return [];
+  }
+}
+export {
+  DEFAULT_BASE_URL,
+  DEFAULT_MODEL,
+  DEFAULT_OUTPUT_DIR,
+  ModelScopeError,
+  TOKEN_ENV_KEYS,
+  VERSION,
+  createServer,
+  generateImage,
+  generateImageInputSchema,
+  resolveConfig,
+  resolveOutputDir,
+  rootDirectories,
+  runGenerateImage,
+  saveImage,
+  toFileStem
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@gracefullight/modelscope-image-mcp",
+  "version": "0.1.1",
+  "description": "MCP server for ModelScope API-Inference image generation with async task polling and LoRA model support",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "modelscope-image-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest",
+    "typecheck": "tsc",
+    "lint": "biome check src",
+    "lint:fix": "biome check --write src",
+    "format": "biome format --write src"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "modelscope",
+    "image-generation",
+    "text-to-image",
+    "lora",
+    "qwen-image",
+    "flux"
+  ],
+  "author": {
+    "name": "Eunkwang Shin",
+    "email": "gracefullight.dev@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gracefullight/pkgs.git",
+    "directory": "packages/modelscope-image-mcp"
+  },
+  "homepage": "https://github.com/gracefullight/pkgs/tree/main/packages/modelscope-image-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/gracefullight/pkgs/issues"
+  },
+  "license": "MIT",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/gracefullight"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.9",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6",
+    "vitest": "^4.0.17"
+  }
+}