xiehaibin18/image-generation-mcp-server

🎨 Image Generation Service

[

基于 Model Context Protocol (MCP) 的 AI 图像生成服务，支持 Google Gemini 2.5 Flash Image 模型，提供高质量图像生成和多轮对话微调功能。

✨ 特性

• 🎯 高质量图像生成: 基于 Google Gemini 2.5 Flash Image 模型
• 🔄 多轮对话微调: 支持基于已生成图像进行迭代修改
• 🔒 企业级安全: 完整的输入验证、路径遍历防护、文件大小限制
• 📐 灵活的宽高比: 支持 1:1, 4:3, 16:9, 3:4, 9:16 多种比例
• 🛡️ 类型安全: 完整的 TypeScript 类型系统
• 📊 结构化日志: JSON 格式日志，便于监控和调试
• ⚡ 性能优化: 请求超时控制、环境变量缓存

📁 项目结构

image-generation-mcp-server/
├── src/                        # 源代码目录
│   ├── config.ts              # 配置常量（文件大小、超时、错误消息）
│   ├── utils.ts               # 工具函数（验证、解析、日志）
│   └── types.d.ts             # TypeScript 类型定义
├── generated_images/           # 生成的图像存储目录
├── index.ts                    # 主入口文件
├── package.json               # 项目依赖配置
├── tsconfig.json              # TypeScript 配置
├── .gitignore                 # Git 忽略规则
└── README.md                  # 本文件

🚀 快速开始

前置要求

• Bun >= 1.2.0
• Node.js >= 18.0.0（可选，Bun 已包含运行时）
• TypeScript >= 5.0.0

安装

# 克隆项目
git clone <repository-url>
cd image-generation-mcp-server

# 安装依赖
bun install

配置环境变量

创建 .env 文件或设置环境变量：

# OpenRouter API 密钥
export API_KEY="your_openrouter_api_key_here"

# API 端点（通常不需要修改）
export BASE_URL="https://openrouter.ai/api/v1/chat/completions"

获取 API 密钥:

1. 访问 OpenRouter
2. 注册并创建 API 密钥
3. 确保账户有足够的余额

运行服务

# 开发模式
bun run index.ts

# 或使用环境变量文件
API_KEY="sk-xxx" BASE_URL="https://..." bun run index.ts

📖 使用指南

基本用法

该服务作为 MCP 服务器运行，通过 stdin/stdout 进行通信。客户端（如 Claude Desktop）通过 MCP 协议调用 generate_image_from_prompt 工具。

参数说明

示例场景

1. 生成新图像

{
  "prompt": "一只橙色的小猫咪坐在窗台上，温暖的阳光洒在它身上，背景是模糊的城市景观，写实摄影风格",
  "model": "google/gemini-2.5-flash-image",
  "image_config": {
    "aspect_ratio": "16:9"
  }
}

2. 基于已有图像微调

{
  "prompt": "给猫咪戴上一顶红色的圣诞帽",
  "model": "google/gemini-2.5-flash-image",
  "image_config": {
    "aspect_ratio": "16:9"
  },
  "ref_image_name": "file:///path/to/generated_images/image_1234567890_abc123.png"
}

提示词编写技巧

为了获得最佳效果，请在 prompt 中包含：

1. 主体描述: 明确的对象、人物或场景
2. 视觉细节: 颜色、光线、材质、构图
3. 艺术风格: 写实、插画、油画、水彩、赛博朋克等
4. 情感氛围: 温暖、冷峻、梦幻、活泼等

良好示例:

未来科技感的城市夜景，霓虹灯闪烁，飞行汽车穿梭，
赛博朋克风格，蓝紫色调，高对比度，电影级渲染质量

不佳示例:

城市

🔒 安全特性

已实现的安全措施

• ✅ 路径遍历防护: 限制文件访问在 generated_images/ 目录内
• ✅ 文件大小限制: 最大 10MB，防止内存溢出攻击
• ✅ MIME 类型白名单: 仅允许图像格式（PNG, JPEG, GIF, WebP, SVG）
• ✅ 输入验证: 所有参数的类型和格式验证
• ✅ HTTP 超时控制: 60 秒超时，防止资源耗尽
• ✅ 环境变量保护: API 密钥通过环境变量注入
• ✅ 错误信息脱敏: 不泄露敏感系统信息

配置限制

可在 src/config.ts 中调整：

export const FILE_CONFIG = {
  MAX_FILE_SIZE_MB: 10, // 最大文件大小
  MAX_FILE_SIZE_BYTES: 10 * 1024 * 1024,
} as const;

export const API_CONFIG = {
  REQUEST_TIMEOUT_MS: 60000, // 请求超时时间
} as const;

详见

🛠️ 开发指南

代码结构

index.ts - 主入口

• 服务器初始化和启动
• 工具注册
• 业务流程编排

src/config.ts - 配置管理

• 文件系统配置
• MIME 类型白名单
• API 配置
• 错误消息常量

src/utils.ts - 工具函数

• 路径验证 (sanitizeFilePath)
• 数据解析 (parseDataUri)
• HTTP 包装 (fetchWithTimeout)
• 日志记录 (logger)

src/types.d.ts - 类型定义

• API 响应类型
• 配置类型
• 工具响应类型

添加新功能

1. 新增配置: 在 src/config.ts 中添加常量
2. 新增工具函数: 在 src/utils.ts 中实现纯函数
3. 新增类型: 在 src/types.d.ts 中定义接口
4. 更新主逻辑: 在 index.ts 中编排业务流程

代码规范

遵循函数式编程原则：

• ✅ 函数式编程优先（纯函数、不可变数据）
• ✅ 单一职责原则
• ✅ 详细的函数和参数命名
• ✅ 类型安全优先
• ✅ 最小化嵌套深度

📊 性能与限制

性能指标

• 平均响应时间: 10-30 秒（取决于图像复杂度）
• 最大并发: 无限制（建议在反向代理层添加限流）
• 内存占用: < 100MB（空闲时）
• 磁盘占用: 随生成图像数量增长

已知限制

🐛 故障排查

常见问题

1. 服务启动失败

症状: API_KEY_MISSING 或 BASE_URL_MISSING 错误

解决方案:

# 检查环境变量
echo $API_KEY
echo $BASE_URL

# 重新设置
export API_KEY="sk-xxx"
export BASE_URL="https://openrouter.ai/api/v1/chat/completions"

2. 图像生成超时

症状: 请求超过 60 秒无响应

解决方案:

• 检查网络连接
• 简化 prompt 描述
• 检查 OpenRouter API 状态
• 调整 API_CONFIG.REQUEST_TIMEOUT_MS

3. 文件大小超限

症状: File size exceeds maximum limit 错误

解决方案:

// 调整 src/config.ts
export const FILE_CONFIG = {
  MAX_FILE_SIZE_MB: 20, // 增加到 20MB
  MAX_FILE_SIZE_BYTES: 20 * 1024 * 1024,
};

4. 路径遍历错误

症状: Potential path traversal attack detected

解决方案:

• 确保 ref_image_name 使用完整的 file:// URI
• 仅引用 generated_images/ 目录中的文件
• 使用工具返回的路径，不要手动构建

日志分析

服务输出结构化 JSON 日志：

{
  "level": "ERROR",
  "message": "Image generation error",
  "error": "API request failed: 401 Unauthorized",
  "timestamp": "2025-10-11T10:30:00.000Z"
}

日志级别:

• INFO: 正常操作（启动、成功生成）
• WARN: 警告信息（不支持的格式）
• ERROR: 错误事件（API 失败、验证失败）

该文档由 AI 自动生成!