# Azure OpenAI GPT-Image-1 MCP Server

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://python.org)
[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-v1.9.4-green.svg)](https://github.com/modelcontextprotocol/python-sdk)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> 一个基于Azure OpenAI **gpt-image-1**模型的Model Context Protocol (MCP) 服务器，使用官方MCP SDK的**Streamable HTTP Transport**实现，为AI助手提供强大的图像生成和编辑能力。

---

## ✨ 核心特性

- 🎨 **图像生成**: 基于文本提示生成高质量图像
- ✏️ **图像编辑**: 编辑现有图像，支持掩码编辑和多图片参考
- 🌐 **Streamable HTTP Transport**: 使用官方MCP SDK的HTTP传输模式
- 🔍 **MCP Inspector兼容**: 支持官方MCP Inspector图形化界面测试
- 🐳 **Docker就绪**: 完整的Docker支持，针对中国大陆网络优化
- 🚀 **高性能**: 异步处理，支持并发请求
- 🛡️ **类型安全**: 完整的类型提示和数据验证

## 🚀 gpt-image-1模型优势

gpt-image-1是OpenAI发布的最新图像生成模型（2025年），相比DALL-E 3具有显著改进：

- **更好的图像质量**: 更精细的细节和更高的一致性
- **更强的提示理解**: 更准确地理解复杂的文本描述
- **更快的生成速度**: 优化的模型架构提供更快的响应
- **更多控制选项**: 支持更多的生成参数和输出格式

---

## 🛠️ 快速开始

### 前置要求

- Python 3.8+
- Azure OpenAI 订阅和gpt-image-1模型部署
- Docker (可选，推荐用于生产环境)

### 安装与配置

```bash
# 克隆项目
git clone https://github.com/WW-AI-Lab/azure-gpt-image.git
cd azure-gpt-image

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/macOS

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp env.example .env
# 编辑 .env 文件，设置您的Azure OpenAI配置
```

### 启动服务

```bash
# Streamable HTTP Transport (推荐)
python -m azure_gpt_image --port 3000

# 或使用Docker
docker-compose up -d
```

---

## 🔧 使用方法

### MCP工具调用

#### 1. 图像生成 (GPT-Image-1)

```json
{
  "name": "generate_image",
  "arguments": {
    "prompt": "A serene mountain landscape with a crystal clear lake, golden hour lighting",
    "size": "1024x1536",
    "quality": "high",
    "output_format": "JPEG"
  }
}
```

#### 2. 图像编辑 (支持多图片参考)

```json
{
  "name": "edit_image",
  "arguments": {
    "image_data": ["base64_image_1", "base64_image_2"],
    "prompt": "Combine these images into a cohesive landscape",
    "size": "1536x1024",
    "quality": "medium"
  }
}
```

### 集成示例

#### Claude Desktop集成

```json
{
  "mcpServers": {
    "azure-gpt-image": {
      "command": "python",
      "args": ["-m", "azure_gpt_image", "--port", "3000"],
      "env": {
        "AZURE_OPENAI_ENDPOINT": "https://your-resource.openai.azure.com/",
        "AZURE_OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### MCP Inspector测试

1. 启动服务器：`python -m azure_gpt_image --port 3000`
2. 打开MCP Inspector并连接到：`http://localhost:3000/mcp`

---

## 🐳 Docker部署

### 快速启动

```bash
# 准备并编辑 .env 文件，设置您的Azure OpenAI配置
cp env.example .env

# 使用Docker Compose (推荐)
docker-compose up -d

# 或直接使用Docker
docker build -t azure-gpt-image .
docker run -d -p 3000:3000 --env-file .env azure-gpt-image
```

### 网络优化 (中国大陆)

Dockerfile已针对中国大陆网络环境优化：
- 使用华为云PyPI镜像源
- 优化构建缓存层级
- 支持健康检查和自动重启

详细部署说明请参考 [docs/deployment.md](docs/deployment.md)

---

## 📚 文档

| 文档 | 说明 |
|------|------|
| [技术规范](docs/technical-specification.md) | 详细的技术实现和API规范 |
| [开发计划](docs/development-plan.md) | 项目开发路线图和架构设计 |
| [部署指南](docs/deployment.md) | 生产环境部署最佳实践 |

---

## 🧪 测试

```bash
# 运行所有测试
python -m pytest tests/ -v

# 运行特定测试
python -m pytest tests/test_mcp_server.py -v

# 运行集成测试
python -m pytest tests/test_integration.py -v
```

---

## 🔧 开发

### 项目结构

```
azure-gpt-image/
├── .cursor/rules/          # Cursor规则文件
├── src/azure_gpt_image/    # 核心代码
├── tests/                  # 测试文件
├── docs/                   # 文档
├── docker-compose.yml      # Docker编排
└── Dockerfile             # Docker镜像
```

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI端点 | 必填 |
| `AZURE_OPENAI_API_KEY` | API密钥 | 必填 |
| `AZURE_OPENAI_DEPLOYMENT_NAME` | 部署名称 | `gpt-image-1` |
| `MCP_SERVER_PORT` | 服务器端口 | `3000` |

---

## ⚠️ 免责声明

> **本项目属于 [WW-AI-Lab](https://github.com/WW-AI-Lab) 实验性仓库**  
> 
> - 🧪 **实验性质**: 用于概念验证和技术探索
> - 📚 **学习目的**: 仅供学习和研究使用
> - 🚫 **非生产就绪**: 不保证生产环境可用性
> - 🤝 **欢迎贡献**: Fork / Issue / PR 都非常欢迎

如需生产级解决方案，请联系 [toxingwang@gmail.com](mailto:toxingwang@gmail.com) 获得专业支持。

---

## 🤝 联系方式

| 渠道 | 地址 | 用途 |
|------|------|------|
| 📧 **Email** | [toxingwang@gmail.com](mailto:toxingwang@gmail.com) | 合作 / 业务咨询 |
| 🐦 **X (Twitter)** | [@WW_AI_Lab](https://x.com/WW_AI_Lab) | 最新动态、技术碎片 |
| 💬 **微信** | toxingwang | 深度交流，添加请注明来源 |

---

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

---

## 🌟 相关项目

- [jinja2-mcp-server](https://github.com/WW-AI-Lab/jinja2-mcp-server) - Jinja2模板转换的MCP服务
- [browser-use-playwright](https://github.com/WW-AI-Lab/browser-use-playwright) - AI驱动的浏览器自动化
- [Dify-Batch](https://github.com/WW-AI-Lab/Dify-Batch) - Dify Workflow批量执行系统

---

⭐ **如果这个项目对您有帮助，请给我们一个星星！**