# CloseAI Image MCP

一个把 [CloseAI](https://jasperio.xyz:8848/app) 生图服务接入 Codex 的本地 MCP Server。

它通过 CloseAI 网站已有的会话接口调用 `gpt-image-2`，支持直接生成图片、上传图片、编辑图片，并把生成的资产下载到本机文件系统。

## 功能

- 默认使用 `gpt-image-2`
- 生成 1 到 4 张图片
- 支持 `auto`、`1024x1024`、自定义尺寸等服务端尺寸参数
- 支持 `auto`、`low`、`medium`、`high` 质量参数
- 支持上传图片后编辑
- 生成完成后自动下载本地文件，并返回 `local_path`
- 支持使用资产 ID 下载已有图片
- 通过 SSE 等待任务完成
- 不把 Cookie 写入源码、日志或 Git

## 环境要求

- Node.js 20 或更高版本
- 一个可以正常登录 CloseAI 的账号
- Codex Desktop 或其他支持 MCP stdio server 的客户端

## 安装

```sh
git clone https://github.com/wangzaiwang-hub/imagegen-mcp.git
cd imagegen-mcp
npm install
npm run check
npm test
```

## 配置 Cookie

本项目需要使用你自己账号的浏览器会话 Cookie。不要把 Cookie 提交到 GitHub，也不要写进 `package.json` 或源码。

推荐保存到权限为 `600` 的本地文件：

```sh
mkdir -p ~/.config/closeai-image-mcp
touch ~/.config/closeai-image-mcp/cookie
chmod 600 ~/.config/closeai-image-mcp/cookie
```

把浏览器开发者工具 Network 请求中的完整 `Cookie` 请求头值写入该文件。也可以使用环境变量：

```sh
export CLOSEAI_COOKIE_FILE="$HOME/.config/closeai-image-mcp/cookie"
```

可选环境变量：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `CLOSEAI_BASE_URL` | `https://jasperio.xyz:8848` | CloseAI 服务地址 |
| `CLOSEAI_IMAGE_MODEL` | `gpt-image-2` | 默认图片模型 |
| `CLOSEAI_OUTPUT_DIR` | `outputs` | 本地图片输出目录 |
| `CLOSEAI_TIMEOUT_SECONDS` | `600` | 生图任务等待时间 |
| `CLOSEAI_DOWNLOAD_TIMEOUT_SECONDS` | `900` | 图片下载总等待时间 |

## Codex 配置

在 `~/.codex/config.toml` 中加入：

```toml
[mcp_servers.closeai_image]
command = "node"
args = ["/绝对路径/imagegen-mcp/src/server.mjs"]
env = { CLOSEAI_COOKIE_FILE = "/Users/你的用户名/.config/closeai-image-mcp/cookie", CLOSEAI_OUTPUT_DIR = "/绝对路径/imagegen-mcp/outputs" }
```

重启 Codex 后，MCP 工具会出现在可用工具列表中。

## MCP 工具

### `closeai_generate_image`

生成图片。必填参数：`prompt`。常用可选参数：`model`、`count`、`size`、`quality`、`output_dir`。

### `closeai_edit_image`

编辑已有 CloseAI 资产。需要 `prompt` 和 `source_asset_ids`。

### `closeai_upload_image`

上传本地图片，返回 CloseAI 资产 ID。

### `closeai_download_asset`

根据资产 ID 下载图片到本地，并返回 `local_path`。

### `closeai_list_models`

读取当前账号可用的模型列表。

## 下载说明

CloseAI 的资产接口偶尔会在图片传输过程中断开连接。MCP 下载器会：

1. 自动重试多个连接
2. 验证下载内容是否为同一个文件前缀
3. 校验最终文件大小
4. 只有文件完整时才返回成功

如果源站持续断流，工具会返回明确错误，不会把残缺图片标记为成功。

## 开发检查

```sh
npm run check
npm test
```

## 注意事项

- 本项目不是 CloseAI 官方项目。
- 需要使用者自行拥有并维护 CloseAI 账号及 Cookie。
- 请遵守目标服务的使用条款、账号安全要求和内容政策。
- Cookie 只应保存在本机，不要提交到公开仓库或发送给他人。