# 智谱AI图像生成MCP服务器

这是一个Model Context Protocol (MCP) 服务器，提供智谱AI图像生成API的访问能力。通过这个服务器，你可以使用智谱AI的CogView系列模型来生成高质量的图像。

## 功能特性

- 🎨 支持智谱AI CogView系列模型进行图像生成
- 📐 支持多种图像尺寸和质量设置
- 🔒 完整的参数验证和错误处理
- 🚀 基于MCP协议，可与Claude Desktop等客户端集成
- 📊 提供模型和尺寸规格查询功能

## 支持的模型

- **cogview-4-250304**: CogView-4最新版本，支持高质量和标准质量两种模式
- **cogview-4**: CogView-4标准版本
- **cogview-3-flash**: CogView-3快速版本，生成速度更快

## 安装和配置

### 1. 克隆或下载项目

```bash
git clone <项目地址>
cd jimeng-image-mcp
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 设置API密钥

设置环境变量：
```bash
export ZHIPU_API_KEY="your_api_key_here"
```

或者在调用工具时直接提供API密钥参数。

### 4. 获取智谱AI API密钥

1. 访问 [智谱AI开放平台](https://open.bigmodel.cn/)
2. 注册账户并登录
3. 在API管理页面创建API密钥
4. 复制密钥并设置到环境变量中

## 使用方法

### 启动MCP服务器

```bash
python zhipu_mcp_server.py
```

服务器将通过stdio协议监听MCP客户端连接。

### 在Claude Desktop中使用

将以下配置添加到Claude Desktop的配置文件中：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "jimeng-image": {
      "command": "python",
      "args": ["/path/to/jimeng-image-mcp/jimeng_image_server.py"],
      "env": {
        "ZHIPU_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## 可用工具

### 1. generate_image - 生成图像

生成基于文本描述的图像。

**参数：**
- `prompt` (必需): 图像描述文本
- `model` (可选): 模型选择，默认为 "cogview-4-250304"
- `quality` (可选): 图像质量，"hd" 或 "standard"，默认为 "standard"
- `size` (可选): 图像尺寸，默认为 "1024x1024"
- `user_id` (可选): 用户ID，用于违规行为监控
- `api_key` (可选): API密钥，如果未设置环境变量

**示例：**
```
生成一张可爱小猫咪的图片，高质量，尺寸为1024x1024
```

### 2. get_supported_models - 获取支持的模型

返回所有支持的图像生成模型及其描述。

### 3. get_supported_sizes - 获取支持的尺寸

返回推荐的图像尺寸规格及其用途说明。

### 4. generate_image_with_url_download - 生成图像并下载

生成图像并可选择下载图像数据到本地（返回base64编码）。

**参数：**
- 与 `generate_image` 相同的所有参数
- `download_image` (可选): 是否下载图像数据，默认为 false

### 5. test_api_connection - 测试API连接

测试与智谱AI API的连接状态。

**参数：**
- `api_key` (可选): API密钥，如果未设置环境变量

## 可用资源

### config://api-info - API配置信息

获取当前API配置状态，包括API地址、密钥状态等信息。

## 参数说明

### 图像质量 (quality)
- **hd**: 高质量模式，生成更精细的图像，耗时约20秒
- **standard**: 标准模式，快速生成，耗时约5-10秒

### 图像尺寸 (size)
推荐尺寸：
- `1024x1024`: 正方形，适合大部分场景
- `768x1344`: 竖屏，适合手机壁纸
- `864x1152`: 竖屏，适合头像肖像
- `1344x768`: 横屏，适合桌面壁纸
- `1152x864`: 横屏，适合风景照
- `1440x720`: 宽屏，适合超宽屏壁纸
- `720x1440`: 长竖屏，适合手机长图

自定义尺寸要求：
- 宽高范围：512px - 2048px
- 必须是16的倍数
- 最大像素数不超过2^21px

## 错误处理

服务器包含完整的错误处理机制：

- **参数验证错误**: 提示具体的参数问题
- **API调用错误**: 显示详细的API错误信息
- **网络错误**: 处理网络连接问题
- **认证错误**: 提示API密钥相关问题

## 使用示例

### 基础图像生成
```
请使用generate_image工具生成一张"夕阳下的樱花树"的图片
```

### 高质量图像生成
```
使用generate_image工具，以高质量模式生成"现代城市夜景"，尺寸为1344x768
```

### 查询可用模型
```
请使用get_supported_models工具查看所有可用的图像生成模型
```

## 技术架构

- **MCP协议**: 基于Model Context Protocol 1.0
- **异步处理**: 使用httpx进行异步HTTP请求
- **类型安全**: 使用Pydantic进行数据验证
- **错误恢复**: 完整的异常处理和错误信息反馈

## 注意事项

1. **API密钥安全**: 请妥善保管你的API密钥，不要在代码中硬编码
2. **费用管理**: 图像生成需要消耗API配额，请注意费用控制
3. **内容合规**: 请确保生成的内容符合相关法律法规
4. **图片保存**: API返回的图片链接有效期为30天，请及时保存

## 故障排除

### 1. 服务器无法启动
- 检查Python版本（需要3.8+）
- 确认所有依赖已正确安装
- 查看错误日志获取详细信息

### 2. API调用失败
- 验证API密钥是否正确设置
- 检查网络连接
- 确认API配额是否充足

### 3. 图像生成失败
- 检查提示词是否符合内容政策
- 验证参数设置是否正确
- 查看API返回的错误信息

## 开发和扩展

如果你想修改或扩展这个服务器：

1. 修改 `zhipu_mcp_server.py` 文件
2. 添加新的工具函数使用 `@mcp.tool()` 装饰器
3. 添加新的资源使用 `@mcp.resource()` 装饰器
4. 运行测试确保功能正常

## 许可证

本项目基于MIT许可证开源。

## 支持和反馈

如果遇到问题或有改进建议，请创建Issue或提交Pull Request。