# Listenseu Image MCP

让用户在自己的 Codex 中，通过本地 MCP 调用 `https://api.listenseu.top` 的图像接口。

这个项目的默认凭据流程是：

```text
用户用个人 API Key 登录 Codex
        ↓
Codex 的 active model provider = https://api.listenseu.top/v1
        ↓
MCP 启动器验证 provider，然后读取本机 Codex 登录凭据
        ↓
调用 api.listenseu.top/v1/images/generations 或 /v1/images/edits
```

安装器不会再次询问 API Key，也不会把 Key 写入 GitHub、MCP 配置或仓库文件。启动器只在 provider 地址匹配时复用凭据；如果用户当前登录的是其他 provider，MCP 会拒绝启动。

## 功能

| 工具 | 用途 |
| --- | --- |
| `image_generate` | 文生图，默认使用 Flare |
| `image_edit` | 单张本地图片编辑，可选 PNG mask，默认使用 Sunburst |
| `image_batch_edit` | 对多张图片逐张执行同一编辑指令，默认使用 Sunburst |
| `image_multi_reference` | 融合 2-10 张参考图生成一张图，默认使用 Sunburst |
| `server_info` | 查看中转站、模型、凭据状态和安全边界 |

当前支持以下模型：

- `gpt-image-2.5-flare`：文生图默认模型。
- `gpt-image-2.5-sunburst`：编辑、批量编辑和多图参考的默认模型。
- `gpt-image-2`：保留为显式兼容选项。

四个图像工具都接受可选的 `model` 参数。GPT Image 2.5 支持
`auto / low / medium / high / xhigh / max`；`gpt-image-2` 最高支持 `high`。
API 地址仍固定为 `https://api.listenseu.top`，输出默认保存到用户的
`Pictures/listenseu-out` 目录。

## 前置条件

- 已安装 Codex CLI/桌面版，并能运行 `codex` 命令。
- Python 3.11 或更高版本。
- 用户已经在 Codex 中配置 `https://api.listenseu.top/v1` 为当前模型提供商。
- 用户已经使用自己的 API Key 登录 Codex。Key 必须存在于 Codex 的本机登录凭据中；本项目不会让用户在安装器里再次输入。

如果还没有配置 provider，可以在 Codex 配置中使用类似结构（名称可自定义）：

```toml
model_provider = "ListenSEU"

[model_providers.ListenSEU]
name = "ListenSEU"
base_url = "https://api.listenseu.top/v1"
wire_api = "responses"
requires_openai_auth = true
```

保存后，用 Codex 自己的登录流程完成个人 API Key 登录。不要把真实 Key 粘贴到 README、命令行参数或 GitHub Issues。

## 安装

在用户本机执行：

```bash
git clone https://github.com/Listen-Sun/listenseu-image-mcp.git
cd listenseu-image-mcp
python install.py
```

安装器会：

1. 检查 Codex 当前 provider 是否为 `https://api.listenseu.top/v1`。
2. 检查 Codex 本机是否已有个人 API 登录凭据（只检查存在性，不打印值）。
3. 创建仓库内虚拟环境并安装依赖。
4. 做一次不联网的 MCP `initialize` + `tools/list` 握手。
5. 用 `codex mcp add` 注册 `listenseu-image`。

安装完成后重启 Codex，然后让它调用：

```text
调用 listenseu-image 的 server_info，检查 api_key_configured。
```

正常结果应包含：

```json
{
  "base_url": "https://api.listenseu.top",
  "available_models": [
    "gpt-image-2",
    "gpt-image-2.5-flare",
    "gpt-image-2.5-sunburst"
  ],
  "default_models": {
    "image_generate": "gpt-image-2.5-flare",
    "image_edit": "gpt-image-2.5-sunburst",
    "image_batch_edit": "gpt-image-2.5-sunburst",
    "image_multi_reference": "gpt-image-2.5-sunburst"
  },
  "api_key_configured": true,
  "credential_is_returned": false
}
```

如果已有同名 MCP，需要明确允许替换：

```bash
python install.py --yes
```

只检查登录状态，不安装：

```bash
python install.py --check
```

只安装依赖并做握手、不改 Codex 配置：

```bash
python install.py --skip-register
```

卸载 MCP 配置（不删除仓库和虚拟环境）：

```bash
python install.py --uninstall
```

## 使用方式

内置 `$imagegen` 是 Codex 自带工具，它不会因为安装了本项目就自动改用第三方中转站。要确保请求走你的中转站，请在任务中明确要求使用 `listenseu-image`，例如：

```text
使用 listenseu-image 的 image_generate，model 设为 gpt-image-2.5-flare，生成一张 1024x1024 的……
```

编辑本地图片时：

```text
使用 listenseu-image 的 image_edit，model 设为 gpt-image-2.5-sunburst，读取 C:\\path\\input.png，只改变背景……
```

输入图片必须是本机可读的 PNG、JPEG 或 WebP。MCP 会先验证文件格式和大小，再上传到 `/v1/images/edits`。

## 尺寸与输出

- 宽高必须是 16 的倍数。
- 边长范围为 256-3840。
- 总像素范围为 655,360-8,294,400。
- 长宽比不能超过 3:1。
- 2K/4K 请求只允许 `n=1`，避免意外放大费用。
- 生成结果会先验证图片格式，再以原子方式保存，避免留下半个文件。
- `save_dir` 必须位于 `LISTENSEU_SAVE_DIR_ROOT` 之下；默认根目录是 `~/Pictures/listenseu-out`。

## 安全设计

- API Base URL 写死为 `https://api.listenseu.top`，工具参数不能改写到任意站点。
- 启动器先比对 Codex 当前 active provider，再读取 `~/.codex/auth.json` 中的 `OPENAI_API_KEY`。
- Key 只保存在 MCP 进程内存中，不写入 MCP 环境变量，也不会被子进程继承。
- MCP 工具没有 `api_key` 参数；`model` 只接受文档列出的模型白名单。
- `server_info` 只返回布尔状态和来源标签，不返回 Key。
- 上游返回 URL 时，只接受 HTTPS，并拒绝解析到本机、内网或保留地址。
- 任何日志、截图、Issue 或测试输出都不得包含真实 Key。

## 常见问题

### `api_key_configured` 是 false

确认 Codex 当前 provider 的 `base_url` 精确为 `https://api.listenseu.top/v1`，并确认 Codex 登录凭据中有 `OPENAI_API_KEY`。改完后完全重启 Codex，让 MCP 子进程重新读取凭据。

### 安装器提示 provider 不匹配

这是故意的安全阻断。它不会把当前其他 provider 的 Key 发送到你的中转站。先切换到 ListenSEU provider，再运行安装器。

### 请求仍然走 OpenAI 官方

不要只说“生成一张图”，而要明确要求调用 `listenseu-image` 的工具。内置 `$imagegen` 与这个 MCP 是两个独立的工具入口。

### 编辑请求返回 HTTP 400

请先用 `image_generate` 验证登录和生成线路，再检查参考图格式、尺寸和大小。当前中转站的具体模型/编辑能力以 `server_info` 和接口返回为准。

## 官方参考

- [Codex MCP 配置（OpenAI Docs）](https://developers.openai.com/codex/mcp/)
- [Codex 配置文件](https://developers.openai.com/codex/config-basic)

## 许可证

本项目使用 MIT License，见 [LICENSE](LICENSE)。