# 即梦AI图像生成 MCP 服务

这是一个基于 [FastMCP](https://github.com/jlowin/fastmcp) 框架的 MCP (Model Context Protocol) 服务，用于调用即梦AI图像生成API。

---

**📚 快速链接：**
- 🚀 [快速开始指南](QUICKSTART.md) - 5分钟快速测试
- 🧪 [测试指南](TESTING.md) - 详细的测试方法说明
- 📖 完整文档（当前页面）

---

## 功能特性

- 🎨 AI图像生成
- 🔄 自动轮询等待生成完成
- 📥 自动下载并保存图片到指定文件夹
- 📝 按顺序命名文件（01.jpg, 02.jpg等）
- 🔧 完整的参数配置（尺寸、模型、提示词等）
- 🔐 安全的token管理
- 📊 详细的响应结果

## 项目结构

```
jimeng-mcp/
├── server.py         # FastMCP服务器主文件
├── service.py        # 图像生成服务核心逻辑
├── header_util.py    # HTTP请求头生成工具
├── requirements.txt  # Python依赖
├── curl.sh          # 原始curl命令参考
└── README.md        # 项目文档
```

## 安装

1. 克隆或下载本项目

2. 安装依赖：
```bash
pip install -r requirements.txt
```

## 配置

设置环境变量 `JIMENG_TOKEN`，这是即梦平台的认证token（sessionid）：

```bash
export JIMENG_TOKEN="your_session_id_here"
```

或者在运行时指定：

```bash
JIMENG_TOKEN="your_token" python server.py
```

## 使用方法

### 方式 1: 快速测试（推荐）

使用测试脚本快速验证功能：

```bash
# 1. 设置token
export JIMENG_TOKEN="your_session_id_here"

# 2. 运行测试
python test_client.py

# 3. 查看生成的图片
ls -lh ./test_output/
```

详细测试说明请查看 [TESTING.md](TESTING.md)

### 方式 2: 作为MCP服务使用

#### 在 Claude Desktop 中配置：

编辑配置文件：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

添加以下配置：

```json
{
  "mcpServers": {
    "jimeng-image-generator": {
      "command": "python",
      "args": ["/absolute/path/to/jimeng-mcp/server.py"],
      "env": {
        "JIMENG_TOKEN": "your_session_id_here"
      }
    }
  }
}
```

重启 Claude Desktop 后即可使用。

### 方式 3: 在代码中直接使用

```python
from service import create_service

token = "your_token"
service = create_service(token)

result = service.generate_image(
    prompt="秋日街道旁的时尚店铺",
    save_folder="./output",
    width=960,
    height=1024
)
print(result)
```

### MCP工具

#### generate_image - 生成图像并保存

生成AI图像，自动轮询等待完成，下载并保存到指定文件夹。

**参数：**
- `prompt` (str, 必需): 图像生成提示词，详细描述要生成的图像内容
- `save_folder` (str, 必需): 图片保存文件夹路径（相对路径或绝对路径）
- `width` (int, 可选): 图像宽度，默认1728
- `height` (int, 可选): 图像高度，默认2304
- `model` (str, 可选): 使用的模型，默认 high_aes_general_v40
- `negative_prompt` (str, 可选): 负面提示词，描述不希望出现的内容
- `sample_strength` (float, 可选): 采样强度(0-1)，默认0.5

**示例：**
```python
generate_image(
    prompt="秋日街道旁的时尚店铺，一位长发微卷的亚洲女性站在橱窗边",
    save_folder="./output/autumn_fashion",
    width=960,
    height=1024
)
```

**返回：**
```json
{
  "success": true,
  "submit_id": "9fff4adc-ed58-479c-9d99-5a2fee0bb097",
  "image_urls": [
    "https://...",
    "https://...",
    "https://..."
  ],
  "saved_files": [
    "./output/autumn_fashion/01.jpg",
    "./output/autumn_fashion/02.jpg",
    "./output/autumn_fashion/03.jpg"
  ],
  "total_images": 3,
  "save_folder": "./output/autumn_fashion"
}
```

**工作流程：**
1. 提交图像生成请求
2. 自动轮询等待生成完成（最多3分钟，每3秒轮询一次）
3. 获取生成的图片URL列表
4. 依次下载所有图片
5. 按顺序保存为 01.jpg, 02.jpg, 03.jpg 等

### MCP资源

#### jimeng://config - 查看配置信息

获取当前服务配置信息，包括token状态、默认参数等。

## 图像尺寸建议

根据小红书等平台的推荐尺寸：

- **竖图（15:16）**：1728x2304 或 960x1024 - 推荐用于小红书
- **方图（1:1）**：1024x1024
- **横图（16:9）**：1920x1080

## 服务架构

```
┌─────────────────┐
│   MCP Client    │
│   (Claude等)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   server.py     │  FastMCP服务器
│   (MCP接口层)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   service.py    │  业务逻辑层
│                 │  • 图像生成请求
│                 │  • 轮询生成结果
│                 │  • 下载图片
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  header_util.py │  工具层
│   (签名生成)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   即梦AI API    │
│  (外部服务)      │
│  • /generate    │
│  • /history     │
└─────────────────┘
```

## 技术细节

### 核心功能

1. **请求签名生成** (`header_util.py`)
   - 动态生成设备ID和WebID
   - 计算请求签名(MD5)
   - 构建完整的HTTP请求头

2. **图像生成服务** (`service.py`)
   - 构建复杂的draft_content JSON结构
   - 处理图像尺寸和比例计算
   - 管理UUID和随机种子生成
   - 封装API调用逻辑
   - **轮询机制**：自动轮询检查生成状态
   - **下载功能**：批量下载并保存图片

3. **MCP服务器** (`server.py`)
   - 使用FastMCP框架
   - 提供标准化的工具接口
   - 环境变量管理
   - 一站式生成和下载流程

### 完整工作流程

1. **提交生成请求**
   - 生成唯一的submit_id、draft_id等UUID
   - 根据prompt和参数构建draft_content
   - 使用header_util生成签名和请求头
   - 发送POST请求到 `/mweb/v1/aigc_draft/generate`

2. **轮询生成结果**
   - 使用submit_id轮询 `/mweb/v1/get_history_by_ids` 接口
   - 每3秒检查一次状态
   - 最多轮询60次（总计3分钟）
   - 状态码：1=生成中, 2=成功, 3=失败

3. **下载图片**
   - 从返回结果中提取图片URL列表
   - 依次下载每张图片
   - 按照顺序命名为 01.jpg, 02.jpg, 03.jpg 等
   - 保存到指定文件夹

4. **返回结果**
   - 返回包含图片URL和本地路径的完整结果

## 开发

### 环境要求

- Python 3.8+
- fastmcp >= 0.1.0
- requests >= 2.31.0

### 测试

直接运行服务器进行测试：

```bash
JIMENG_TOKEN="your_token" python server.py
```

然后使用MCP客户端（如Claude Desktop）连接测试。

## 故障排查

### Token未设置

**错误：** `JIMENG_TOKEN环境变量未设置`

**解决：** 确保设置了环境变量：
```bash
export JIMENG_TOKEN="your_session_id"
```

### API请求失败

**可能原因：**
1. Token过期或无效
2. 网络连接问题
3. API参数错误

**解决：**
1. 检查token是否有效
2. 确认网络连接
3. 查看详细错误信息

## 注意事项

⚠️ **重要提示：**

1. **Token安全**：请勿在代码中硬编码token，使用环境变量
2. **请求频率**：遵守API的调用频率限制
3. **提示词质量**：更详细的提示词能生成更好的图像
4. **图像尺寸**：确保宽高比符合需求
5. **轮询超时**：图像生成最多等待3分钟，超时将返回错误
6. **文件命名**：图片自动按顺序命名（01.jpg, 02.jpg等），不会覆盖现有文件
7. **网络稳定性**：确保网络连接稳定，下载大图片可能需要时间

## 许可证

本项目仅供学习和研究使用。

## 相关链接

- [FastMCP 文档](https://github.com/jlowin/fastmcp)
- [MCP 协议说明](https://modelcontextprotocol.io/)
- 即梦AI官网: https://jimeng.jianying.com