使用说明

图像生成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密钥（用于额外的图像生成功能）

安装

克隆并导航到项目：

git clone <repository>
cd image.serv

安装依赖项：

uv sync

配置环境变量：

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

根据文本描述创建图像。

参数：

参数	类型	默认值	说明
`prompt`	string	必填	图像描述（最多32000个字符）
`size`	字符串	`auto`	尺寸： `1024x1024`, `1536x1024`, `1024x1536`，或 `auto`
`output_format`	字符串	`jpeg`	输出格式： `png`, `jpeg`，或 `webp`
`seed`	整数	`0`	随机种子用于再现性（0=随机）
`enhance_prompt`	布尔值	`true`	通过LLM自动增强提示
`response_format`	字符串	`image`	响应类型： `image`, `markdown`，或 `adaptive_card`
`background`	字符串	`auto` 背景 `transparent`, `opaque`，或 `auto`

例子：

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

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

参数：

参数	类型	默认值	说明
`prompt`	string	必填	所需编辑的描述（最多32000个字符）
`image_paths`	array	必填	图像URL、文件路径或base64数据URL（最多16个）
`mask_path`	string	可选	用于修复的PNG掩码（透明=编辑区）
`size`	字符串	`auto`	输出尺寸
`output_format`	字符串	`jpeg`	输出格式： `png`, `jpeg`，或 `webp`
`background`	字符串	`auto`	背景设置
`response_format`	字符串	`image`	响应类型： `image`, `markdown`，或 `adaptive_card`

例子：

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...

用面具作画

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

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

建筑

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

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"
  }
}

环境变量

变量	必填	默认	描述
`OPENAI_API_KEY`	是	-	gpt-image 1的Azure OpenAI密钥
`OPENAI_BASE_URL`	是	-	Azure OpenAI端点URL（例如。， `https://your-resource-name.openai.azure.com`)
`GOOGLE_API_KEY`	否	-	用于图像生成的Google AI密钥
`BACKEND_SERVER`	没有	`http://localhost:8000`	图像下载URL的后端服务器URL（使用 `http://host.docker.internal:8000` 在Docker中）
`TMP_PATH`	没有	`./images`	用于存储生成图像的目录（使用 `/app/images` 在Docker中）
`DEFAULT_RESPONSE_FORMAT`	没有	`markdown`	默认响应格式： `image`, `markdown`，或 `adaptive_card`
`LOG_LEVEL`	没有	`INFO`	日志记录级别： `DEBUG`, `INFO`, `WARNING`, `ERROR`，或 `CRITICAL`
`PORT`	没有	`8000`	服务器端口

许可证

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