Gpt Image

MCP服务器GPT映像-1

](https://www.npmjs.com/package/mcp-server-gpt-image)  ](https://modelcontextprotocol.io)

模型上下文协议（MCP）服务器，使用GPT image-1模型和新的Responses API提供对OpenAI最新图像生成功能的访问。该服务器使像克劳德这样的人工智能助手能够使用尖端的多模式人工智能技术，使用自然语言提示生成和操纵图像。

🌟 特性

• 🎨 最新图像生成：使用OpenAI的GPT Image-1（2025年最先进的模型）创建令人惊叹的图像
• 🆕 双重API支持：在图像API（gpt-image-1）和响应API（使用图像工具的gpt-4o）之间选择
• ✏️ 高级图像编辑：使用文本提示和可选遮罩修改现有图像
• 🔄 多个传输：支持stdio（用于Claude Desktop）和HTTP（用于远程访问）
• ⚡ 实时流媒体：服务器发送事件（SSE）用于实时进度更新和部分预览
• 💾 智能缓存：用于即时重复请求的两层缓存系统（内存+磁盘）
• 🖼️ 图像优化：自动压缩，尺寸减少高达80%
• 🚀 生产就绪：Docker支持、会话管理和全面的错误处理
• 🔒 安全：通过环境变量进行API密钥身份验证
• 📊 灵活的选项：支持各种大小、质量级别和输出格式
• 🔄 会话上下文：具有对话历史跟踪功能的多回合图像编辑
• 🎯 高级文本渲染：GPT Image-1增强的图像中文本功能

📋 先决条件

• Node.js 18或更高版本
• npm或纱线
• OpenAI API密钥，可访问图像生成模型
• API组织验证 已完成图像生成访问

🚀 快速开始

安装

选项1：使用预构建版本（推荐）

# Clone the repository
git clone https://github.com/pavelsukhachev/mcp-server-gpt-image.git
cd mcp-server-gpt-image

# Install dependencies (required for runtime)
npm install --production

选项2：从源代码构建

# Clone the repository
git clone https://github.com/pavelsukhachev/mcp-server-gpt-image.git
cd mcp-server-gpt-image

# Install all dependencies
npm install

# Build the project
npm run build

配置

创建一个 .env 根目录中的文件：

# Required
OPENAI_API_KEY=your-openai-api-key-here

# API Configuration
API_MODE=responses                   # 'responses' (default, latest) or 'images' (legacy)
RESPONSES_MODEL=gpt-4o              # Model for Responses API (default: gpt-4o)

# Optional
PORT=3000
CORS_ORIGIN=*

# Cache Configuration
CACHE_DIR=.cache/images
CACHE_TTL=3600
CACHE_MAX_SIZE=100

# Feature Flags
ENABLE_CONVERSATION_CONTEXT=true    # Multi-turn conversation support
ENABLE_STREAMING=true               # Real-time streaming updates
ENABLE_OPTIMIZATION=true            # Image optimization

🎯 API模式和型号选择

响应API（推荐）

默认模式: API_MODE=responses

• 模型：带有图像生成工具的gpt-4o
• 技术：具有集成GPT Image-1功能的最新2025响应API
• 特性:

- 本地多模式理解 - 更好的上下文感知 - 增强提示跟踪 - 图像中出色的文本渲染 - 实时流媒体播放，部分预览 - 多回合对话支持

图像API（旧版）

传统模式: API_MODE=images

• 模型：gpt-image 1（专用图像模型）
• 技术：传统图像API端点
• 特性:

- 直接访问GPT Image-1模型 - 简单、专注的图像生成 - 向后兼容性

模型比较

🔧 用法

Claude桌面集成

将以下内容添加到您的Claude Desktop MCP设置中(~/Library/Application Support/Claude/claude_desktop_config.json 在 macOS 上：

{
  "mcpServers": {
    "gpt-image": {
      "command": "node",
      "args": ["/path/to/mcp-server-gpt-image/dist/index.js", "stdio"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

独立服务器（HTTP模式）

# Run in HTTP mode for remote access
npm run start:http

# Or use Docker
docker-compose up

服务器将在以下位置可用：

• 健康检查： http://localhost:3000/health
• MCP端点： http://localhost:3000/mcp
• 流媒体端点： http://localhost:3000/mcp/stream

🛠️ 可用工具

1. generate_image

通过可选的流媒体支持从文本提示生成图像。

参数：

• prompt （必填）：要生成的图像的文本描述
• size：图像尺寸

- 1024x1024 （默认） - 1024x1536 （肖像） - 1536x1024 （景观） - auto

• quality：渲染质量

- low （60%压缩） - medium （80%压缩） - high （95%质量） - auto （默认，85%质量）

• format：输出格式(png, jpeg, webp)
• background：背景透明度(transparent, opaque, auto)
• output_compression：显式压缩级别（0-100）
• n：要生成的图像数量（1-4）
• partialImages：要流式传输的部分图像数量（1-3，启用流式传输）
• stream：启用流模式以进行实时生成更新
• conversationId：对话上下文跟踪ID（可选）
• useContext：是否使用以前交互的对话上下文（默认值：false）
• maxContextEntries：要考虑的最大上下文条目数（1-10，默认值：5）

例子：

{
  "prompt": "A serene Japanese garden with cherry blossoms at sunset",
  "size": "1536x1024",
  "quality": "high",
  "format": "png",
  "partialImages": 2,
  "stream": true
}

2. edit_image

使用文本提示和可选掩码编辑现有图像。

参数：

• prompt （必填）：所需编辑的文本描述
• images （必填）：要编辑的base64编码图像数组
• mask：用于修复的Base64编码掩码（可选）
• 其他参数与 generate_image

例子：

{
  "prompt": "Add a red bridge over the stream",
  "images": ["base64_encoded_image_data..."],
  "mask": "base64_encoded_mask_data..."
}

API模式支持：

• 响应API：通过图像输入对话进行编辑（推荐）
• 图片API：使用传统端点进行直接图像编辑

3. clear_cache

清除内存和磁盘中的所有缓存图像。

例子：

// No parameters required
{}

4. cache_stats

获取缓存统计信息，包括内存条目和磁盘使用情况。

例子：

// No parameters required
{}

5. list_conversations

列出所有活动对话ID。

例子：

// No parameters required
{}

6. get_conversation

获取特定对话的完整历史记录。

参数：

• conversationId （必填）：要检索的对话ID

例子：

{
  "conversationId": "design-session-123"
}

7. clear_conversation

清除特定对话的历史记录。

参数：

• conversationId （必填）：要清除的对话ID

例子：

{
  "conversationId": "design-session-123"
}

🌊 流式图像生成

SSE实时生成

服务器支持通过服务器发送事件（SSE）生成流式图像，用于实时进度更新和部分图像预览。

端点: POST /mcp/stream

请求正文:

{
  "prompt": "A beautiful sunset over mountains",
  "partialImages": 3,
  "size": "1024x1024",
  "quality": "high"
}

响应：服务器发送的事件流

事件类型:

• progress：生成进度更新，包括百分比和消息
• partial：部分图像预览（base64编码）
• complete：带有修订提示的最终图像
• error：生成失败时的错误信息

API模式示例

响应API流 （推荐）：

// Using Responses API with gpt-4o
const response = await fetch('http://localhost:3000/mcp/stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    prompt: 'A futuristic city with flying cars',
    partialImages: 2,
    apiMode: 'responses'  // Use latest Responses API
  })
});

图像API流 （遗产）：

// Using traditional Images API with gpt-image-1
const response = await fetch('http://localhost:3000/mcp/stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    prompt: 'A futuristic city with flying cars',
    partialImages: 2,
    apiMode: 'images'  // Use legacy Images API
  })
});

客户端示例:

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const events = chunk.split('\n\n');
  
  for (const event of events) {
    if (event.startsWith('data: ')) {
      const data = JSON.parse(event.slice(6));
      console.log('Event:', data.type, data.data?.message);
    }
  }
}

看 examples/streaming-client.ts 为了完整实施。

🔄 多回合对话上下文

迭代图像细化

服务器现在支持在多个图像生成和编辑操作中维护对话上下文。这允许迭代细化，其中每个新提示都可以建立在以前的结果之上。

运作原理:

1. 分配一个 conversationId 与集团相关的运营
2. 启用 useContext: true 用以前的上下文增强提示
3. 系统会自动跟踪提示、修改后的提示和图像元数据
4. 上下文被持久化到磁盘，以便稍后恢复会话

工作流示例:

// Initial generation
{
  "prompt": "Create a serene mountain landscape",
  "conversationId": "landscape-design-001",
  "useContext": false  // First prompt doesn't need context
}

// Iterative refinement with context
{
  "prompt": "Add a crystal clear lake in the foreground",
  "conversationId": "landscape-design-001",
  "useContext": true,  // Will consider previous "mountain landscape" context
  "maxContextEntries": 5
}

// Further editing
{
  "prompt": "Make the sky more dramatic with sunset colors",
  "images": ["previous_generated_image_base64..."],
  "conversationId": "landscape-design-001",
  "useContext": true  // Considers both previous prompts for consistency
}

益处:

• 一致性：在迭代过程中保持风格和元素
• 情境感知：每一代都考虑以前的提示和结果
• 会话保持：稍后恢复工作，保留完整上下文
• 灵活的历史记录：控制使用多少上下文 maxContextEntries

管理对话:

• 使用 list_conversations 查看所有活动会话
• 使用 get_conversation 回顾会议的完整历史
• 使用 clear_conversation 需要时重新开始

💾 响应缓存

智能缓存系统

该服务器包括一个智能缓存系统，以减少API调用并提高响应时间。

特性:

• 内存+磁盘缓存：两层缓存可实现最佳性能
• 基于内容的密钥：根据提示、大小、质量和其他参数缓存密钥
• TTL支持：缓存条目的可配置生存时间
• 尺寸管理：缓存超过大小限制时自动清理
• 缓存工具：用于缓存管理的内置工具

配置 （通过环境变量）：

CACHE_DIR=.cache/images      # Cache directory (default: .cache/images)
CACHE_TTL=3600              # Cache TTL in seconds (default: 1 hour)
CACHE_MAX_SIZE=100          # Max cache size in MB (default: 100MB)

缓存行为:

• 相同的请求会立即返回缓存结果
• 缓存命中记录以供监控
• 过期的条目会自动清理
• 基于图像+掩码+提示组合的编辑操作缓存

🖼️ 图像优化

自动优化引擎

该服务器包括一个由夏普提供动力的智能图像优化引擎。

特性:

• 格式转换：自动在PNG、JPEG和WebP之间转换
• 智能压缩：基于图像特征的自适应质量
• 尺寸限制：在减小文件大小的同时保持尺寸
• 透明度处理：需要时保留alpha通道
• 递增式编码：更好的感知加载性能

优化结果:

• 典型的尺寸减小：JPEG为30-70%，WebP为20-50%
• 基于内容类型的自动格式选择
• 通过更小的文件大小保持视觉质量
• 记录用于监控的优化指标

🐳 Docker支持

使用Docker Compose

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Docker配置

包括 docker-compose.yml 提供：

• 容器自动重启
• 健康检查
• 生成图像的卷装
• 环境变量配置

🏗️ 建筑

代码库如下 SOLID原则 和 清洁建筑 可维护性和可测试性的模式。

src/
├── index.ts                  # Entry point with transport selection
├── server.ts                 # MCP server setup and tool registration
├── types.ts                  # TypeScript interfaces and Zod schemas
├── interfaces/               # Contract definitions (Dependency Inversion)
│   └── image-generation.interface.ts  # Core interfaces for DI
├── services/                 # Business logic (Single Responsibility)
│   ├── image-generator.ts    # Main image generation service
│   ├── streaming-image-generator.ts  # Streaming implementation
│   ├── file-converter.ts     # File conversion utilities
│   └── openai-client-adapter.ts     # OpenAI API adapter
├── adapters/                 # Interface adapters (Open/Closed)
│   ├── cache-adapter.ts      # Cache interface implementation
│   └── optimizer-adapter.ts  # Image optimizer interface
├── tools/
│   ├── image-generation.ts   # Tool endpoints using services
│   └── image-generation-streaming.ts # Streaming endpoints
├── transport/
│   └── http.ts               # HTTP/SSE transport with session management
└── utils/
    ├── cache.ts              # Two-tier caching system
    └── image-optimizer.ts    # Sharp-based image optimization

关键设计模式

• 依赖注入：所有服务都依赖于接口，而不是具体的实现
• 单一责任：每门课都有一个明确的目的
• 开闭原则：服务可以通过接口进行扩展
• 接口隔离：针对特定问题的重点接口
• 利斯科夫替补：所有实现都是可互换的

📝 例子

这 examples/ 目录包含完整的、可运行的示例：

• test-client.ts：基本MCP客户端示例
• streaming-client.ts：使用SSE生成流式图像
• optimization-demo.ts：图像优化功能演示

使用以下命令运行示例：

npx tsx examples/streaming-client.ts

💰 成本考虑

GPT Image-1通过生成专门的图像令牌来生成图像。成本和延迟取决于：

定价：5.00/1M文本输入令牌，10.00/1M图像输入令牌，40.00/1M图像输出令牌

🔒 安全最佳实践

1. API密钥管理:

- 永远不要将API密钥提交到版本控制 - 对敏感数据使用环境变量 - 定期旋转API键

1. 网络安全:

- 为生产环境适当配置CORS - 在生产环境中使用HTTPS - 对公共部署实施速率限制

1. 输入验证:

- 所有输入都使用Zod模式进行验证 - 强制执行文件大小限制 - 默认情况下应用内容审核

🚀 性能提示

优化发电速度

• 使用较低质量：从以下内容开始 quality: "low" 对于草稿，然后以更高的质量重新生成
• 启用缓存：相同的请求会立即从缓存中处理
• 使用流媒体：使用更快地获得部分结果 partialImages 参数

降低成本

• 缓存结果：自动缓存可防止冗余的API调用
• 优化图像：使用压缩来减少存储和带宽
• 监视器使用情况：跟踪缓存统计数据以了解使用模式

提高质量

• 详细提示：包括风格、情绪、灯光和透视细节
• 参考样式：提及特定的艺术风格或艺术家以保持一致性
• 迭代精化：使用edit_image工具细化特定区域

🚧 路线图

完成✅

• \[x\] 基本图像生成和编辑
• \[x\] Docker支持
• \[x\] 预制配电
• \[x\] 流媒体基础设施（基于SSE）
• \[x\] 局部图像模拟（1-3个预览）
• \[x\] 响应缓存（内存+磁盘）
• \[x\] 图像优化（格式转换和压缩）
• \[x\] SOLID原则架构重构
• \[x\] 全面的测试套件，包含90多项测试
• \[x\] 测试覆盖率报告（核心公用事业98%以上）
• \[x\] TDD（测试驱动开发）实践
• \[x\] 使用对话上下文进行多回合编辑
• \[x\] OpenAI Responses API与GPT-4o+image_generation工具的集成
• \[x\] 双API支持（图像API+响应API），无缝切换

进行中🚀

• \[\]使用队列管理进行批处理

未来计划📅

• \[\]用于双向通信的WebSocket传输
• \[\]文件上传支持（直接图像处理）
• \[\]自定义提示库
• \[\]使用情况分析和成本跟踪
• \[\]用于服务器管理的Web仪表板
• \[\]自定义处理器的插件系统

⚠️ 已知限制

API限制

• 生成时间：复杂的提示可能需要30秒
• 文本渲染：图像中生成的文本可能不一致
• 响应格式：目前仅返回base64图像（不支持URL）
• 模型访问：需要GPT Image-1的组织验证

技术限制

• 最大图像尺寸：受base64编码和传输限制
• 并发请求：受OpenAI API配额限制的速率
• 缓存大小：受可用磁盘空间限制

🧪 测试

该项目使用 速度 用于全面覆盖的测试：

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm test -- --watch

# Run specific test file
npm test -- src/utils/cache.test.ts

测试覆盖率

• 总体：约50%的陈述
• 核心服务：78.91%的覆盖率
• 公用事业：98.88%的覆盖率（缓存：100%，图像优化器：97.69%）
• 服务器：96.08%的覆盖率

测试方法

• 单元测试：对所有服务和公用设施进行全面测试
• 集成测试：MCP服务器端点测试
• TDD实践：先写测试，然后实现
• 嘲笑：独立测试的适当依赖性模拟

🤝 贡献

欢迎投稿！请遵循我们的开发实践：

开发过程

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 先写测试 （TDD方法）
4. 按照SOLID原则实现您的功能
5. 确保所有测试通过(npm test)
6. 检查测试覆盖率(npm run test:coverage)
7. 提交您的更改(git commit -m 'Add some amazing feature')
8. 推到分支(git push origin feature/amazing-feature)
9. 打开拉取请求

代码规范

• 遵循TypeScript的最佳实践
• 保持测试覆盖率在80%以上
• 对新服务使用依赖注入
• 遵循现有的代码模式和约定
• 用清晰的注释记录复杂的逻辑

📝 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 与 模型上下文协议SDK
• 由...驱动 OpenAI的GPT Image-1
• 图像优化 夏普
• 受到MCP社区的启发

📚 资源

• 模型上下文协议文档
• OpenAI图像生成指南
• GPT图像-1文档
• MCP服务器示例

______________________________________________________________________

备注：这是一个非正式的实施。GPT Image-1是OpenAI的产品。