Image Serv

图像生成MCP服务器

使用OpenAI生成和编辑图像的FastMCP服务器 gpt图像1 和 Azure FLUX.1 上下文 模型。部署为MCP工具或使用REST端点 与人工智能助手和应用程序的灵活集成。

特性

• 文本到图像生成：使用多个AI模型从自然语言提示中创建图像
• 图像编辑与彩绘：使用文本提示和可选掩码编辑现有图像（gpt-image 1）
• 多种格式：输出为PNG、JPEG或WEBP，质量可自定义
• 灵活的响应格式：以MCP图像、Markdown或Microsoft自适应卡的形式接收结果
• 快速增强：通过LLM自动优化提示以获得更好的结果
• 双重协议：通过用于AI助手的MCP协议或用于直接集成的REST API访问

快速开始

先决条件

• Python 3.12或更高版本
• 紫外线 包管理器
• API密钥：

- 必需：Azure OpenAI API密钥和端点（用于gpt-image-1模型） - 可选：Google AI API密钥（用于额外的图像生成功能）

安装

1. 克隆并导航到项目：

git clone 
cd image.serv

1. 安装依赖项：

uv sync

1. 配置环境变量：

cp .env.example .env
# Edit .env with your actual values

或者直接设置它们：

# REQUIRED: Azure OpenAI API Configuration
export OPENAI_API_KEY="your-azure-openai-api-key" # pragma: allowlist secret
export OPENAI_BASE_URL="https://your-resource-name.openai.azure.com"

# OPTIONAL: Google AI Configuration
export GOOGLE_API_KEY="your-google-api-key" # pragma: allowlist secret

# OPTIONAL: Backend server URL for image download URLs
export BACKEND_SERVER="http://localhost:8000"

# OPTIONAL: Temporary image storage directory
export TMP_PATH="./images"

# OPTIONAL: Default response format (image|markdown|adaptive_card)
export DEFAULT_RESPONSE_FORMAT="markdown"

# OPTIONAL: Logging level (DEBUG|INFO|WARNING|ERROR|CRITICAL)
export LOG_LEVEL="INFO"

# OPTIONAL: Server port
export PORT="8000"

用法

运行服务器

启动服务器以与Claude Desktop或其他MCP客户端集成：

uv run python -m server.server

服务器将在以下时间可用 http://localhost:8000 具有端点：

• POST /api/v1/generate_image -生成图像
• POST /api/v1/edit_image -编辑现有图像
• /api/docs -OpenAPI文档

MCP配置

{
    "servers": {
        "image-generation": {
            "type": "http",
            "url": "http://localhost:8000/mcp/v1",
            "gallery": true
        }
    }
}

工具和API

generate_image

根据文本描述创建图像。

参数：

例子：

generate_image(
    prompt="A serene mountain landscape at sunset with golden light reflecting off a lake",
    size="1536x1024",
    output_format="png",
    enhance_prompt=True,
    response_format="markdown"
)

edit_image

使用文本提示和可选的修复蒙版编辑现有图像。

参数：

例子：

edit_image(
    prompt="Add a vibrant rainbow across the sky",
    image_paths=["https://example.com/landscape.jpg"],
    mask_path="https://example.com/sky_mask.png",
    output_format="png",
    response_format="markdown"
)

图像输入格式

支持的输入法 image_paths 参数：

• HTTP/HTTPS URL: https://example.com/image.jpg
• 本地文件路径: /path/to/image.png
• Base64数据URL: data:image/png;base64,iVBORw0KG...

用面具作画

为了精确控制编辑，请使用遮罩图像：

1. 创建具有阿尔法透明度的PNG图像
2. 透明区域（alpha=0）标记要编辑的区域
3. 不透明区域保持不变
4. 遮罩尺寸必须与输入图像匹配

建筑

服务器遵循干净的分层架构：

MCP Client / REST Client
    ↓
FastMCP Server / FastAPI Routes
    ↓
Image Service Layer
    ↓
Image Generators (OpenAI, Google)
    ├── Prompt Enhancer
    ├── Image Processor
    └── Image Loader

关键组件

• mcp_server.py -FastMCP工具定义和服务器设置
• 服务器.py -统一MCP+REST API服务器
• api/routes.py -FastAPI REST端点
• 后端/image_service.py -核心业务逻辑
• 后端/生成器/ -人工智能提供商实施

- openai.py -OpenAI gpt-image 1集成

发展

运行测试

make test

跑步覆盖：

make test-coverage

代码质量

格式和棉绒代码：

make format
make check

可用命令

make help

响应格式

所有端点都通过以下方式支持三种响应格式 response_format 参数：

图像格式

返回适合显示或处理的原始图像数据。

Markdown格式

返回带有嵌入式base64图像的格式化markdown：

# Generated Image

![Generated Image](http://localhost:8000/_uploads/...)

自适应卡格式

返回适用于Teams或其他平台的Microsoft自适应卡JSON：

{
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "Image",
      "url": "http://localhost:8000/_uploads/..."
    }
  ]
}

错误处理

API返回标准HTTP状态代码：

• 200 OK -成功生成/编辑
• 400 Bad Request -无效参数
• 422 Unprocessable Entity -验证错误
• 500 Internal Server Error -API故障

错误响应包括详细消息：

{
  "status": "error",
  "error": "Description of what went wrong",
  "metadata": {
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

环境变量

许可证

此项目根据MIT许可证获得许可-请参阅 许可证.md 了解详情。