Multi-Provider Image Generation Server

MCP图像生成服务器

一个模型上下文协议（MCP）服务器，用于使用多个AI提供商（包括腾讯浑源、OpenAI GPT image和豆瓣API）生成图像。

版本: 0.2.0

特性

🎯 Multi-API提供程序支持

• 腾讯浑源：18种艺术风格，采用中文优化
• OpenAI GPT映像：通过英语优化生成高质量图像
• 豆瓣（字节跳动）：12种款式，质量和速度平衡

🚀 核心功能

• 根据文本描述生成图像
• 支持跨不同提供商的多种图像样式
• 支持不同的图像分辨率
• 排除不需要的元素的负面提示
• 智能供应商选择和管理
• 具有特定于提供程序选项的统一参数格式

🌐 传输模式（v0.2.0中的新功能）

• stdio运输：本地IDE集成（Cursor、Windsurf）
• HTTP传输：远程访问和企业部署

- 多客户端并发连接 - 承载令牌身份验证 - 会话管理 - RESTful API端点 - 适用于云部署和远程访问

为什么是HTTP传输？ 版本0.2.0添加了 可流式传输的HTTP 支持（MCP 2024-11-05的官方标准），以实现： - 远程访问：Claude远程MCP需要公共HTTP端点（stdio仅在本地工作） - 企业部署：具有多个并发客户端的集中式服务部署 - 云原生：与容器、Kubernetes和负载均衡器兼容 注：这使用 可流式传输的HTTP （POST/GET/DELETE），而不是弃用的仅限SSE的方法。SSE保留了兼容性，但Streamable HTTP是推荐的标准。

🔧 智能提供商管理

• 自动检测可用的API提供商
• 支持指定特定提供者或自动选择
• 统一的错误处理和重试机制
• 灵活的参数格式： provider:style 和 provider:resolution

安装

使用紫外线（推荐）

UV是一个快速、现代的Python包管理器。推荐用法：

# Install UV (Windows)
curl -sSf https://astral.sh/uv/install.ps1 | powershell

# Install UV (macOS/Linux)
curl -sSf https://astral.sh/uv/install.sh | bash

# Clone the project and enter the directory
cd path/to/image-gen-mcp-server

# Create a UV virtual environment
uv venv
# Or specify an environment name
# uv venv my-env-name

# Activate the virtual environment (Windows)
.venv\Scripts\activate
# Activate the virtual environment (macOS/Linux)
source .venv/bin/activate

# Install dependencies (recommended)
uv pip install -e .

# Or use the lock file for exact versions
uv pip install -r requirements.lock.txt

使用传统pip

如果你喜欢传统的pip：

# Create a virtual environment
python -m venv venv
# Activate the virtual environment (Windows)
venv\Scripts\activate
# Activate the virtual environment (macOS/Linux)
source venv/bin/activate

# Install dependencies
pip install -e .
# Or use the lock file
pip install -r requirements.lock.txt

环境设置

创建一个 .env 项目根目录中的文件。看 .env.example 所有可用选项。

基本配置

# Image save directory
MCP_IMAGE_SAVE_DIR=./generated_images
# Public base URL for generated image links (HTTP mode, optional but recommended)
# MCP_PUBLIC_BASE_URL=https://mcp.your-domain.com
# Metadata TTL for get_image_data cache (seconds)
# MCP_IMAGE_RECORD_TTL=86400
# Max bytes allowed in get_image_data base64 response
# MCP_GET_IMAGE_DATA_MAX_BYTES=10485760

# API Provider Credentials (configure at least one)
TENCENT_SECRET_ID=your_tencent_secret_id
TENCENT_SECRET_KEY=your_tencent_secret_key
OPENAI_API_KEY=your_openai_api_key
DOUBAO_API_KEY=your_doubao_api_key
# Optional but recommended when multiple providers are configured
# MCP_DEFAULT_PROVIDER=openai

传输配置（可选）

# Transport mode: stdio (default, for local IDE) or http (for remote access)
MCP_TRANSPORT=stdio

# HTTP transport settings (only needed for HTTP mode)
MCP_HOST=127.0.0.1
MCP_PORT=8000

# Authentication (recommended for HTTP mode)
MCP_AUTH_TOKEN=your-secure-random-token

用法

🔄 运输方式

此服务器支持两种传输模式：

🚀 快速开始

统一入口点（推荐）

# Method 1: Run as module (recommended)
python -m mcp_image_server

# Method 2: Use entry script
./mcp-server

# Method 3: After pip install
mcp-image-server

统一服务器将自动使用您的 .env 文件：

• MCP_TRANSPORT=stdio → IDE集成的本地stdio模式
• MCP_TRANSPORT=http → 用于远程访问的HTTP服务器模式

📡 HTTP传输模式

对于远程访问和企业部署，请使用HTTP传输：

1.配置HTTP模式

# Set in .env file
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_AUTH_TOKEN=your-secure-token  # Optional but recommended

2.启动HTTP服务器

python -m mcp_image_server

服务器将于启动 http://127.0.0.1:8000 具有端点：

• GET /health -健康检查
• POST /mcp/v1/messages -发送JSON-RPC消息
• GET /mcp/v1/messages -订阅SSE活动
• DELETE /mcp/v1/messages -结束会话
• GET /images/{filename} -提供生成的图像文件

generate_image 工具返回 images[].url 对于HTTP客户端。\ 如果服务器通过反向代理/公共域暴露，请设置 MCP_PUBLIC_BASE_URL 以确保URL可从外部访问。 /images/* 是故意公开的，因此即使启用MCP API auth，浏览器/前端图像渲染也能工作。

最佳实践代理流程：

1. 呼叫 generate_image 获得可渲染图像+稳定 image_id/url.
2. 呼叫 get_image_data(image_id=...) 仅当需要可编程base64文本时。

3.测试HTTP服务器

# Check server health
curl http://127.0.0.1:8000/health

# Run comprehensive tests
python test_mcp_server.py

# Test with API key for actual image generation
python test_mcp_server.py --with-api

4.使用HTTP客户端

# Run example client
python example_http_client.py basic       # Explore server capabilities
python example_http_client.py generate    # Generate images (requires API key)

有关详细的HTTP传输文档，请参阅 HTTP_TRANSPORT_GUIDE.md

MCP服务器成功运行的屏幕截图：

连接到服务器

您可以从MCP兼容客户端进行连接（现在重新推荐光标）。服务器提供以下功能：

资源

• styles://list -列出所有可用的图像样式
• resolutions://list -列出所有可用的图像分辨率

工具

• generate_image -根据提示、样式和分辨率生成图像（OpenAI也支持 background/output_format/output_compression/moderation)
• get_image_data -通过以下方式获取先前生成的图像的base64文本 image_id

提示

• image_generation_prompt -创建图像生成提示模板

🎨 多API使用示例

基本用法

# Auto-select best available provider
generate_image(prompt="A cute cat in a garden")

# Specify a particular provider
generate_image(prompt="A cute cat", provider="openai")
generate_image(prompt="一只可爱的小猫", provider="hunyuan")
generate_image(prompt="Cute kitten", provider="doubao")

高级参数使用

# Use provider-specific styles and resolutions
generate_image(
    prompt="Cyberpunk city skyline", 
    style="hunyuan:saibopengke", 
    resolution="hunyuan:1024:768"
)

# Mix provider selection with standard parameters
generate_image(
    prompt="Fantasy magical forest",
    provider="doubao",
    style="fantasy",
    resolution="1024x768",
    negative_prompt="low quality, blurry"
)

# OpenAI with high-resolution output
generate_image(
    prompt="Artistic portrait of a musician",
    provider="openai",
    style="artistic",
    resolution="1536x1024"
)

📊 支持的提供者和参数

腾讯浑源

• 风格：18个选项，包括 riman, xieshi, shuimo, saibopengke, youhua
• 决议：8个选项 768:768 到 1280:720
• 专业：中国优化，艺术风格丰富

OpenAI GPT映像

• 风格：12个选项，包括 natural, vivid, realistic, artistic, anime
• 决议：4个选项： 1024x1024, 1536x1024, 1024x1536, auto
• 高级选项: background, output_format, output_compression, moderation （通过MCP客户端）
• 专业：高质量输出，英语优化

豆瓣（字节跳动）

• 风格：12个选项，包括 general, anime, chinese_painting, cyberpunk
• 决议：依赖于模型（由配置的模型/回退模型自动验证）
• 专业：平衡的质量和速度

光标集成

有关集成设置的详细信息和示例配置JSON，请参阅：

• docs/VSCODE_INGRATION.md

建议的最小环境变量：

• MCP_IMAGE_SAVE_DIR
• 您实际使用的提供商凭据：

TENCENT_SECRET_ID + TENCENT_SECRET_KEY, OPENAI_API_KEY, DOUBAO_API_KEY

可选提供程序/模型控件：

• OPENAI_BASE_URL, OPENAI_MODEL
• DOUBAO_ENDPOINT, DOUBAO_MODEL, DOUBAO_FALLBACK_MODEL
• MCP_DEFAULT_PROVIDER （启用多个提供程序时建议使用）

变更后 .env 运行时的模型/默认提供程序值，调用 reload_config.

🧪 测试

该项目包括全面的测试工具：

协议测试（不需要API密钥）

# Test MCP protocol functionality without API keys
python test_mcp_server.py

该测试：

• ✅ 健康检查端点
• ✅ MCP初始化握手
• ✅ 工具列表
• ✅ 资源列表和阅读
• ✅ 提示列表
• ✅ 会话管理

功能测试（需要API密钥）

# Test actual image generation with configured providers
python test_mcp_server.py --with-api

这还测试了：

• ✅ 使用OpenAI生成真实图像
• ✅ 使用浑源生成真实图像
• ✅ 使用豆瓣生成真实图像

备注：中必须至少配置一个API密钥 .env 运行功能测试。

故障排除

一般问题

• 确保环境变量设置正确
• 检查路径中是否有空格；必要时使用引号
• 确保虚拟环境已激活（如果使用）
• 尝试直接运行服务器脚本以检查错误
• 检查紫外线环境 uv --version

HTTP传输问题

• 连接被拒绝：确保服务器在正确的主机/端口上运行
• 401未经授权：检查 MCP_AUTH_TOKEN 配置
• 404未找到会话：重新初始化连接以获取新的会话ID
• 没有可用的提供商：在中至少配置一个API提供程序 .env

有关详细的故障排除，请参阅 HTTP_TRANSPORT_GUIDE.md

前端演示

有关前端集成示例，请参见 web-design-demo/. 此示例演示了如何使用Cursor IDE开发一个真实的项目，您可以在开发环境中使用我们的MCP工具直接生成和管理图像🛠️. 无需在不同的图像生成工具之间切换或离开IDE——一切都可以在开发工作流程中正确完成✨.

• 演示网站的屏幕截图

API 参考

多API体系结构

该项目现在通过统一的接口支持多个图像生成API：

支持的API

1. 腾讯混源图片生成API （原件）
2. OpenAI GPT图像API 新
3. 豆包图片生成API 新

统一MCP资源

• providers://list -列出所有可用的提供商
• styles://list -列出所有提供商的所有样式
• resolutions://list -列出所有提供商的所有分辨率
• styles://provider/{provider_name} -获取特定提供商的样式
• resolutions://provider/{provider_name} -获取特定提供商的解决方案

增强型MCP工具

• generate_image -具有智能路由的多提供商图像生成
• get_image_data -按id检索生成图像的base64文本数据
• reload_config -从env/.env重新加载运行时配置/模型，而无需重新启动进程（仅限安全子集）

腾讯混源图片生成API

该项目最初使用并继续支持腾讯混源图像生成API。以下是关键细节：

API终点

• 域名： hunyuan.tencentcloudapi.com
• 地区： ap-guangzhou （目前仅支持广州地区）
• 默认API速率限制：20个请求/秒
• 并发任务：默认一次1个任务

任务流程

1. 提交任务：提交带有文本描述的异步图像生成任务
2. 查询任务：使用任务ID获取任务状态和结果
3. 结果URL:生成的图像URL有效期为1小时

有关API文件和定价的详细信息，请参阅：

• API 文档
• 定价详细信息

OpenAI GPT图像API

API功能

• 高质量图像生成
• 自动提示优化
• 多种风格选择
• 高分辨率输出支持

豆宝API（字节跳动）

API功能

• ByteDance专有的图像生成模型
• 平衡的质量和速度
• 中英文即时支持
• 多种艺术风格

路线图

• 版本0.2.0 （当前）

- ✅ 腾讯混源图片生成API - ✅ OpenAI GPT图像API集成 - ✅ 豆包API集成 - ✅ 多供应商管理系统 - ✅ 智能提供商选择 - ✅ 统一参数接口 - ✅ 使用流式HTTP协议的HTTP传输 - ✅ 远程访问支持 - ✅ 多客户端并发连接 - ✅ 承载令牌身份验证 - ✅ 会话管理 - ✅ 全面的测试套件

• 未来计划

- 支持更多主流的文本到图像模型API，包括： - Qwen Image（Qwen/Wan家族） - 开源模型API服务（例如：FLUX、SDXL/SD3.5） - 高级功能： - 图像编辑和修改 - 批量图像生成 - 风格转换能力 - 自定义模型微调支持 - 增强的MCP集成： - 实时发电进度 - 图像历史和管理 - 高级提示模板

欢迎社区为更多模型集成和新功能做出贡献！

兼容性

• 标准：已通过Cursor和Windsurf验证。
• HTTP（流式HTTP）：适用于支持HTTP传输的MCP客户端。
• 对于其他客户端/环境，兼容性取决于客户端MCP的实现。

贡献

我们欢迎各种各样的贡献！以下是您可以提供帮助的一些方法：

• 🐛 报告错误和问题
• 💡 建议新功能或改进
• 🔧 提交拉取请求
• 🎨 添加对更多图像生成模型的支持

开始贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/AmazingFeature)
3. 提交您的更改(git commit -m 'feat: add some AmazingFeature')
4. 推到分支(git push origin feature/AmazingFeature)
5. 打开拉取请求

请确保根据需要更新测试，并遵循现有的编码风格。

我们感谢您有兴趣让这个项目变得更好！