seedream-mcp 1.0.0

基于火山引擎Seedream 4.0 API的MCP工具，支持AI图像生成功能

Seedream 4.0 MCP 工具

基于火山引擎 Seedream 4.0 API 的 MCP（Model Context Protocol）工具集，提供文生图、图生图、多图融合和组图生成等功能。

功能特性

• 🎨 文生图：根据文本描述生成高质量图像
• 🖼️ 图生图：基于参考图像和文本指令生成新图像
• 🎭 多图融合：融合多张参考图的特征生成新图像
• 📚 组图生成：生成一组内容关联的图像序列
• 💾 自动保存：自动下载并保存生成的图片到本地，解决 URL 过期问题
• 📝 Markdown 支持：自动生成本地图片的 Markdown 引用格式
• 🔧 完整的 MCP 协议支持：符合 MCP 标准，可与支持 MCP 的客户端无缝集成

安装要求

• Python 3.8+
• 火山引擎 Seedream 4.0 API 密钥

安装方法

1. 克隆项目

git clone <repository-url>
cd Seedream_MCP

2. 安装依赖

pip install -e .

3. 配置环境变量

创建 .env 文件：

# 必需配置
ARK_API_KEY=your_api_key_here

# 可选配置
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
SEEDREAM_MODEL_ID=doubao-seedream-4-0-250828
SEEDREAM_DEFAULT_SIZE=2K
SEEDREAM_DEFAULT_WATERMARK=true
SEEDREAM_TIMEOUT=60
SEEDREAM_API_TIMEOUT=60
SEEDREAM_MAX_RETRIES=3
LOG_LEVEL=INFO
LOG_FILE=logs/seedream_mcp.log

# 自动保存配置
SEEDREAM_AUTO_SAVE_ENABLED=true
SEEDREAM_AUTO_SAVE_BASE_DIR=./seedream_images
SEEDREAM_AUTO_SAVE_DOWNLOAD_TIMEOUT=30
SEEDREAM_AUTO_SAVE_MAX_RETRIES=3
SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE=52428800
SEEDREAM_AUTO_SAVE_MAX_CONCURRENT=5
SEEDREAM_AUTO_SAVE_DATE_FOLDER=true
SEEDREAM_AUTO_SAVE_CLEANUP_DAYS=30

使用方法

作为 MCP 服务器运行

python -m seedream_mcp.server

在代码中使用

import asyncio
from seedream_mcp import SeedreamClient, SeedreamConfig

async def main():
    # 加载配置
    config = SeedreamConfig.from_env()

    # 创建客户端
    client = SeedreamClient(config)

    try:
        # 文生图（启用自动保存）
        result = await client.text_to_image(
            prompt="一只可爱的小猫咪，卡通风格",
            size="2K",
            watermark=True,
            auto_save=True,
            custom_name="cute_cat"
        )
        print(f"生成的图像URL: {result['image_url']}")
        print(f"本地保存路径: {result['local_path']}")
        print(f"Markdown引用: {result['markdown']}")

        # 图生图
        result = await client.image_to_image(
            prompt="将这张图片转换为油画风格",
            image="path/to/image.jpg",
            size="2K",
            auto_save=True
        )
        print(f"转换后的图像URL: {result['image_url']}")
        print(f"本地保存路径: {result['local_path']}")

    finally:
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

工具说明

1. seedream_text_to_image

根据文本描述生成图像。

参数：

• prompt (必需): 文本描述，建议不超过 300 汉字或 600 英文单词
• size (可选): 图像尺寸，可选值：1K、2K、4K，默认 2K
• watermark (可选): 是否添加水印，默认 true
• response_format (可选): 响应格式，可选值：url、b64_json，默认 url
• auto_save (可选): 是否自动保存图片到本地，默认使用全局配置
• save_path (可选): 自定义保存路径，不指定则使用默认路径
• custom_name (可选): 自定义文件名前缀

示例：

{
  "prompt": "一只可爱的小猫咪，卡通风格",
  "size": "2K",
  "watermark": true,
  "response_format": "url",
  "auto_save": true,
  "custom_name": "cute_cat"
}

2. seedream_image_to_image

基于参考图像和文本指令生成新图像。

参数：

• prompt (必需): 图像编辑指令
• image (必需): 参考图像 URL 或本地文件路径
• size (可选): 输出图像尺寸，默认 2K
• watermark (可选): 是否添加水印，默认 true
• auto_save (可选): 是否自动保存图片到本地，默认使用全局配置
• save_path (可选): 自定义保存路径，不指定则使用默认路径
• custom_name (可选): 自定义文件名前缀

示例：

{
  "prompt": "将这张图片转换为油画风格",
  "image": "https://example.com/image.jpg",
  "size": "2K",
  "watermark": false,
  "auto_save": true,
  "custom_name": "oil_painting"
}

3. seedream_multi_image_fusion

融合多张参考图的特征生成新图像。

参数：

• prompt (必需): 融合指令描述
• images (必需): 多张参考图像 URL 或文件路径数组（2-5 张）
• size (可选): 输出图像尺寸，默认 2K
• auto_save (可选): 是否自动保存图片到本地，默认使用全局配置
• save_path (可选): 自定义保存路径，不指定则使用默认路径
• custom_name (可选): 自定义文件名前缀

示例：

{
  "prompt": "将这些图片融合成一个艺术作品",
  "images": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg",
    "https://example.com/image3.jpg"
  ],
  "size": "4K",
  "auto_save": true,
  "custom_name": "fusion_art"
}

4. seedream_sequential_generation

生成一组内容关联的图像序列。

参数：

• prompt (必需): 组图生成描述
• max_images (可选): 最大图像数量（1-10），默认 3
• images (可选): 参考图像数组
• size (可选): 图像尺寸，默认 2K
• auto_save (可选): 是否自动保存图片到本地，默认使用全局配置
• save_path (可选): 自定义保存路径，不指定则使用默认路径
• custom_name (可选): 自定义文件名前缀

示例：

{
  "prompt": "科幻城市景观，未来主义风格",
  "max_images": 4,
  "size": "2K",
  "auto_save": true,
  "custom_name": "sci_fi_city"
}

配置选项

环境变量	描述	默认值	必需
ARK_API_KEY	火山引擎 API 密钥	-	✅
ARK_BASE_URL	API 基础 URL	https://ark.cn-beijing.volces.com/api/v3	❌
SEEDREAM_MODEL_ID	模型 ID	doubao-seedream-4-0-250828	❌
SEEDREAM_DEFAULT_SIZE	默认图像尺寸	2K	❌
SEEDREAM_DEFAULT_WATERMARK	默认水印设置	true	❌
SEEDREAM_TIMEOUT	请求超时时间（秒）	60	❌
SEEDREAM_API_TIMEOUT	API 超时时间（秒）	60	❌
SEEDREAM_MAX_RETRIES	最大重试次数	3	❌
LOG_LEVEL	日志级别	INFO	❌
LOG_FILE	日志文件路径	logs/seedream_mcp.log	❌
SEEDREAM_AUTO_SAVE_ENABLED	是否启用自动保存	true	❌
SEEDREAM_AUTO_SAVE_BASE_DIR	自动保存基础目录	./seedream_images	❌
SEEDREAM_AUTO_SAVE_DOWNLOAD_TIMEOUT	下载超时时间（秒）	30	❌
SEEDREAM_AUTO_SAVE_MAX_RETRIES	下载最大重试次数	3	❌
SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE	最大文件大小（字节）	52428800	❌
SEEDREAM_AUTO_SAVE_MAX_CONCURRENT	最大并发下载数	5	❌
SEEDREAM_AUTO_SAVE_DATE_FOLDER	是否创建日期文件夹	true	❌
SEEDREAM_AUTO_SAVE_CLEANUP_DAYS	自动清理天数	30	❌

自动保存功能

自动保存功能解决了生成图片 URL 在 24 小时后过期的问题，提供永久可用的本地图片存储。

核心特性

• 自动下载：生成图片后自动下载到本地指定目录
• 智能命名：使用时间戳 + 内容哈希 + 尺寸信息的命名规则
• 目录管理：按工具类型和日期自动分类存储
• Markdown 支持：自动生成本地图片的 Markdown 引用格式
• 错误恢复：下载失败时提供原始 URL 作为备选
• 并发下载：支持批量图片的并发下载处理

使用示例

# 启用自动保存的文生图
result = await client.text_to_image(
    prompt="美丽的风景画",
    auto_save=True,
    custom_name="landscape"
)

# 返回结果包含：
# - image_url: 原始图片URL
# - local_path: 本地保存路径
# - markdown: Markdown引用格式
# - save_result: 保存操作的详细信息

文件组织结构

images/
├── 2024-01-15/
│ ├── text_to_image/
│ │ ├── landscape_20240115_143022_abc123_2K.png
│ │ └── portrait_20240115_143045_def456_4K.png
│ ├── image_to_image/
│ │ └── style_transfer_20240115_144001_ghi789_2K.png
│ └── multi_image_fusion/
│ └── fusion_art_20240115_145030_jkl012_4K.png
└── 2024-01-16/
└── ...

配置说明

• SEEDREAM_AUTO_SAVE_ENABLED: 全局启用/禁用自动保存
• SEEDREAM_AUTO_SAVE_BASE_DIR: 图片保存的根目录
• SEEDREAM_AUTO_SAVE_DATE_FOLDER: 是否按日期创建子文件夹
• SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE: 限制下载的最大文件大小
• SEEDREAM_AUTO_SAVE_MAX_CONCURRENT: 控制并发下载数量
• SEEDREAM_AUTO_SAVE_CLEANUP_DAYS: 自动清理超过指定天数的旧文件

错误处理

工具提供完整的错误处理机制：

• 参数验证错误：检查必需参数和参数格式
• API 调用错误：处理网络错误、超时等问题
• 认证错误：API 密钥无效或过期
• 配额错误：API 调用次数超限
• 服务器错误：火山引擎服务异常

日志记录

工具支持详细的日志记录：

• 函数调用日志
• API 请求和响应日志
• 错误和异常日志
• 性能监控日志

日志级别可通过 LOG_LEVEL 环境变量配置。

开发和测试

运行测试

# 运行集成测试
python tests/test_mcp_integration.py

# 运行验证脚本
python verify_installation.py

项目结构

Seedream_MCP/
├── seedream_mcp/           # 主要代码
│   ├── __init__.py
│   ├── client.py           # API客户端
│   ├── config.py           # 配置管理
│   ├── server.py           # MCP服务器
│   ├── tools/              # 工具实现
│   └── utils/              # 工具函数
├── docs/                   # 文档目录
├── tests/                  # 测试文件
├── examples/               # 使用示例
├── verifys/                # 验证脚本
├── .env.example           # 环境变量示例
├── main.py                # 主程序入口
├── requirements.txt       # 依赖列表
└── README.md             # 说明文档

许可证

本项目采用 MIT 许可证。

支持

如有问题或建议，请提交 Issue 或 Pull Request。