@hongxianzhi/seedream-image-mcp 1.0.2

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 wearzdk（wear工程师） <hi@wearzdk.me>
+
+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,126 @@
+# SeeDream Image MCP
+
+基于火山引擎 SeeDream 模型的 MCP (Model Context Protocol) 图片生成工具。
+
+## ✨ 特性
+
+- 🎨 使用火山引擎 SeeDream 4.0 模型生成高质量图片
+- 🔧 支持自定义尺寸、智能参考图等
+- 📝 无需编写复杂提示词，AI自动根据需求生成生图提示词
+- 🔌 MCP 协议支持，可在 Cursor、Claude Desktop 等客户端中使用
+
+## 📺 演示
+
+<video src="https://github.com/user-attachments/assets/2b82a9d4-7799-4625-a140-2a48845b2e4a" autoplay muted loop playsinline controls width="100%" height="auto"></video>
+
+## 🚀 快速开始
+
+### 1. 获取火山引擎 API Key
+
+前往 [火山引擎->火山方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey) 开通服务并申请 API Key。
+
+### 2. 使用 npx 运行
+
+```bash
+npx @hongxianzhi/seedream-image-mcp --ark-key=YOUR_API_KEY [--ark-model=MODEL_NAME] [--ark-endpoint=REQUEST_ENDPOINT]
+```
+
+**参数说明：**
+- `--ark-key` (必需) - 火山引擎 API Key
+- `--ark-model` (可选) - 模型名称，默认 `doubao-seedream-4-5-251128`
+- `--ark-endpoint` (可选) - 请求地址，默认 `https://ark.cn-beijing.volces.com/api/v3/images/generations`
+
+### 3. 在 Cursor、Claude Desktop 中配置
+
+编辑 `Cursor MCP配置` 或 `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "seedream-image": {
+      "command": "npx",
+      "args": ["@hongxianzhi/seedream-image-mcp", "--ark-key=YOUR_API_KEY", "--ark-model=doubao-seedream-4-5-251128", "--ark-endpoint=https://ark.cn-beijing.volces.com/api/v3/images/generations"]
+    }
+  }
+}
+```
+
+## 📖 使用示例
+
+在 AI Agent 工具中，你可以这样使用：
+
+```
+为这个页面添加合适的图片，避免过于单调
+```
+
+AI 会自动调用工具完成生成。
+
+## 📌 注意事项
+
+**图片链接时效性**：本项目使用火山引擎原始 API，生成的图片链接通常在 24 小时后失效。如果你需要长期保存图片，请及时下载到本地。
+
+## 🔄 两种使用方式
+
+你可以根据自己的需求选择：
+
+### 方式一：本地运行 🔧
+- 需要自己申请火山引擎 API key
+- 图片链接 24 小时后失效，需下载到本地使用。
+
+### 方式二：云端版本 ✨
+- ✅ 无需申请 API key，开箱即用
+- ✅ 图片支持永久存储在 CDN
+- ✅ 支持 webp 压缩、背景移除、快速并发生成多张图片等功能
+- ✅ 提供一定的免费额度
+- ✅ 量大时价格更优惠
+
+👉 了解云端版本：[https://mcp.pixelark.art](https://mcp.pixelark.art)
+
+---
+
+
+## 🛠️ 开发
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 编译项目
+
+```bash
+npm run build
+```
+
+### 全局安装
+
+如需全局安装此包以便在命令行中使用，可执行以下步骤：
+
+```bash
+# 1. 正常编译
+npm run build
+
+# 2. 拷贝 dist/index.js 到全局 npm 目录
+cp dist/index.js "$(npm prefix -g)/lib/node_modules/seedream-image-mcp/dist/index.js"
+
+# 3. 创建符号链接到全局目录
+ln -sf "$(npm prefix -g)/lib/node_modules/seedream-image-mcp/dist/index.js" "$(npm prefix -g)/bin/seedream-image-mcp"
+```
+
+或者使用 npm link（推荐）：
+
+```bash
+npm run build
+npm link
+```
+
+## 📄 许可证
+
+MIT
+
+## 🔗 相关链接
+
+- [云端版本](https://mcp.pixelark.art)
+- [火山引擎 SeeDream](https://www.volcengine.com/docs/ark/doubao-seedream)
+- [MCP 协议](https://modelcontextprotocol.io)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { generateImage, setArkApiKey } from "./utils/vol.js";
+// 解析命令行参数
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let arkKey = "";
+    let arkModel = "";
+    let arkEndpoint = "";
+    for (const arg of args) {
+        if (arg.startsWith("--ark-key=")) {
+            arkKey = arg.substring("--ark-key=".length);
+        }
+        else if (arg.startsWith("--ark-model=")) {
+            arkModel = arg.substring("--ark-model=".length);
+        }
+        else if (arg.startsWith("--ark-endpoint=")) {
+            arkEndpoint = arg.substring("--ark-endpoint=".length);
+        }
+    }
+    if (!arkKey) {
+        console.error("Error: --ark-key is required");
+        console.error("Usage: npx seedream-image-mcp --ark-key=YOUR_API_KEY [--ark-model=MODEL_NAME] [--ark-endpoint=REQUEST_ENDPOINT]");
+        process.exit(1);
+    }
+    return { arkKey, arkModel, arkEndpoint };
+}
+const { arkKey, arkModel, arkEndpoint } = parseArgs();
+setArkApiKey(arkKey, arkModel, arkEndpoint);
+const server = new McpServer({
+    name: "seedream-image-mcp",
+    version: "1.0.0",
+});
+// 注册图片生成工具
+server.registerTool("generate-image", {
+    title: "生成图片",
+    description: "使用火山引擎 SeeDream 模型生成图片。支持文字描述生成、智能参考图等功能",
+    inputSchema: {
+        type: "object",
+        properties: {
+            prompt: {
+                type: "string",
+                minLength: 1,
+                maxLength: 5000,
+                description: `图片描述提示词
+
+【提示词编写建议】
+1. 基础结构：内容主题 → 视觉细节 → 风格氛围 → 技术质量
+2. 关键要素：
+   - 主体内容：明确要生成什么（场景/物体/氛围）
+   - 视觉细节：材质、光影、色彩、构图、景深
+   - 风格定调：写实/插画/3D/扁平/抽象等
+   - 技术要求：分辨率、构图方式、背景类型
+3. 语言规范：使用现代中文，逗号分隔关键词
+4. 质量提升：结尾添加"高清细节，杰作"等质量声明
+
+【重要约束】
+- 默认添加"画面无文字"；如需文字，明确标注"画面文字内容：XXX"
+- 内容必须合法合规`,
+            },
+            size: {
+                type: "string",
+                description: `图片尺寸，格式为 WIDTHxHEIGHT，默认 2560x1440
+
+常用尺寸参考：
+- 21:9 超宽屏: 3024x1296
+- 16:9 横屏: 2560x1440
+- 4:3 传统: 2304x1728
+- 1:1 方形: 2048x2048
+- 3:4 竖屏: 1728x2304
+- 9:16 手机: 1440x2560`,
+            },
+            watermark: {
+                type: "boolean",
+                description: "是否添加AI生成水印，默认为 false",
+            },
+            images: {
+                type: "array",
+                items: {
+                    type: "string",
+                },
+                description: "智能参考图片 URL 列表，支持多张图片作为参考",
+            },
+        },
+        required: ["prompt"],
+    },
+}, async (args) => {
+    const prompt = args.prompt;
+    const size = args.size;
+    const watermark = args.watermark;
+    const images = args.images;
+    const result = await generateImage(prompt, {
+        size,
+        watermark,
+        images,
+    });
+    const output = {
+        success: result.success,
+        imageUrl: result.tempUri,
+        error: result.error,
+    };
+    if (result.success) {
+        const responseContent = [
+            {
+                type: "text",
+                text: `✅ 图片生成成功！
+
+🖼️  图片URL: ${result.tempUri}
+
+⚠️  重要提示：
+此链接通过 Base64 传递，已在下方直接显示。
+此 URL 链接通常在 24 小时后失效。
+如果你需要永久链接，可以考虑使用云端版本：https://mcp.pixelark.art`,
+            },
+        ];
+        // 如果有 base64 数据，添加 image 类型的 content
+        if (result.base64) {
+            responseContent.push({
+                type: "image",
+                data: result.base64,
+                mimeType: result.mimeType || "image/png",
+            });
+        }
+        return {
+            content: responseContent,
+            structuredContent: output,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `❌ 图片生成失败: ${result.error}
+
+💡 遇到问题？试试商业版：
+- 无需自己申请 API key
+- 更稳定的服务和技术支持
+- 注册即送 30 张免费额度
+👉 https://mcp.pixelark.art`,
+            },
+        ],
+        structuredContent: output,
+    };
+});
+// 启动服务器
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("SeeDream Image MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/dist/utils/vol.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 火山引擎图片生成相关工具函数
+ */
+export interface ImageGenerationOptions {
+    model?: string;
+    size?: string;
+    watermark?: boolean;
+    images?: string[];
+}
+export interface ImageGenerationResult {
+    tempUri: string;
+    base64?: string;
+    mimeType?: string;
+    success: boolean;
+    error?: string;
+}
+export declare function setArkApiKey(apiKey: string, model?: string, endpoint?: string): void;
+/**
+ * 使用火山引擎生成图片并存储到 OSS
+ * @param prompt 图片描述提示词
+ * @param options 可选配置项
+ * @returns 生成结果包含存储的 URI
+ */
+export declare function generateImage(prompt: string, options?: ImageGenerationOptions): Promise<ImageGenerationResult>;
+//# sourceMappingURL=vol.d.ts.map

package/dist/utils/vol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vol.d.ts","sourceRoot":"","sources":["../../src/utils/vol.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAOD,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,QAKlB;AAuCD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC,CA8HhC"}

package/dist/utils/vol.js

@@ -0,0 +1,150 @@
+import fs from "node:fs";
+import path from "node:path";
+let ARK_ENDPOINT = "https://ark.cn-beijing.volces.com/api/v3/images/generations";
+let ARK_MODEL = "doubao-seedream-4-5-251128";
+let ARK_API_KEY = "";
+export function setArkApiKey(apiKey, model, endpoint) {
+    ARK_API_KEY = apiKey;
+    if (model)
+        ARK_MODEL = model;
+    if (endpoint)
+        ARK_ENDPOINT = endpoint;
+}
+/**
+ * 处理图片，如果是本地路径则转换为 base64
+ */
+async function processImage(imagePath) {
+    if (imagePath.startsWith("http://") ||
+        imagePath.startsWith("https://") ||
+        imagePath.startsWith("data:")) {
+        console.error(`[SeeDream] Using image URL/DataURI: ${imagePath.substring(0, 50)}...`);
+        return imagePath;
+    }
+    try {
+        // 尝试读取本地文件
+        const absolutePath = path.isAbsolute(imagePath)
+            ? imagePath
+            : path.resolve(process.cwd(), imagePath);
+        if (fs.existsSync(absolutePath)) {
+            console.error(`[SeeDream] Reading local image: ${absolutePath}`);
+            const bitmap = fs.readFileSync(absolutePath);
+            const base64 = Buffer.from(bitmap).toString("base64");
+            // 注意：有的 API 可能需要 data:image/xxx;base64, 前缀，如果报错请检查
+            return base64;
+        }
+        else {
+            console.error(`[SeeDream] Local image not found: ${absolutePath}`);
+        }
+    }
+    catch (error) {
+        console.error(`[SeeDream] Error processing image ${imagePath}:`, error);
+    }
+    return imagePath;
+}
+/**
+ * 使用火山引擎生成图片并存储到 OSS
+ * @param prompt 图片描述提示词
+ * @param options 可选配置项
+ * @returns 生成结果包含存储的 URI
+ */
+export async function generateImage(prompt, options = {}) {
+    const { model = ARK_MODEL, watermark = false, images = [] } = options;
+    try {
+        // 构建请求参数
+        const requestBody = {
+            model,
+            prompt,
+            response_format: "url",
+            watermark,
+            // 智能组图
+            sequential_image_generation: "auto",
+            sequential_image_generation_options: {
+                max_images: 4,
+            },
+        };
+        // 只有当存在参考图时才添加 image 字段
+        if (images && images.length > 0) {
+            // 对图片进行处理，本地文件转 base64
+            const processedImages = await Promise.all(images.map((img) => processImage(img)));
+            requestBody.image = processedImages;
+        }
+        console.error("[SeeDream] Sending request to ARK API...");
+        // 打印请求体（隐藏 base64 以免日志过大）
+        const logBody = JSON.parse(JSON.stringify(requestBody));
+        if (logBody.image) {
+            logBody.image = logBody.image.map((img) => img.startsWith("http")
+                ? img
+                : `${img.substring(0, 30)}... (base64 trunced)`);
+        }
+        console.error("[SeeDream] Request Body Preview:", JSON.stringify(logBody, null, 2));
+        // 调用火山引擎 API 生成图片
+        const response = await fetch(ARK_ENDPOINT, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${ARK_API_KEY}`,
+            },
+            body: JSON.stringify(requestBody),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            console.error(`[SeeDream] API Error Response (${response.status}):`, errorText);
+            try {
+                const error = JSON.parse(errorText);
+                return {
+                    tempUri: "",
+                    success: false,
+                    error: `API Error: ${error.error.message || error.error.code}`,
+                };
+            }
+            catch (e) {
+                return {
+                    tempUri: "",
+                    success: false,
+                    error: `HTTP ${response.status}: ${errorText}`,
+                };
+            }
+        }
+        const result = (await response.json());
+        const imageUrl = result.data?.[0]?.url;
+        if (!imageUrl) {
+            return {
+                tempUri: "",
+                success: false,
+                error: "No image URL returned from API",
+            };
+        }
+        console.error(`[SeeDream] Image generated: ${imageUrl}`);
+        // 获取图片并转换为 base64
+        try {
+            console.error("[SeeDream] Fetching image for base64 conversion...");
+            const imageResponse = await fetch(imageUrl);
+            if (!imageResponse.ok)
+                throw new Error(`Failed to fetch image: ${imageResponse.statusText}`);
+            const buffer = await imageResponse.arrayBuffer();
+            const base64 = Buffer.from(buffer).toString("base64");
+            const mimeType = imageResponse.headers.get("content-type") || "image/png";
+            console.error(`[SeeDream] Successfully converted to base64 (${mimeType})`);
+            return {
+                tempUri: imageUrl,
+                base64,
+                mimeType,
+                success: true,
+            };
+        }
+        catch (fetchError) {
+            console.error("[SeeDream] Base64 conversion failed, falling back to URL only:", fetchError);
+            return {
+                tempUri: imageUrl,
+                success: true,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            tempUri: "",
+            success: false,
+            error: error instanceof Error ? error.message : "Unknown error occurred",
+        };
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@hongxianzhi/seedream-image-mcp",
+  "version": "1.0.2",
+  "description": "基于火山引擎 SeeDream 模型的 MCP 图片生成工具，支持在 Cursor、Claude Desktop 等客户端中使用",
+  "type": "module",
+  "bin": {
+    "seedream-image-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "image-generation",
+    "ai",
+    "seedream",
+    "volcengine",
+    "claude",
+    "cursor",
+    "text-to-image",
+    "ai-image"
+  ],
+  "author": "PixelArk Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hongxianzhi/seedream-image-mcp.git"
+  },
+  "homepage": "https://mcp.pixelark.art",
+  "bugs": {
+    "url": "https://github.com/hongxianzhi/seedream-image-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.4",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.21.1",
+    "zod": "^3.23.8"
+  }
+}