codex-ergouzi-media-mcp

一个将 Ergouzi 媒体任务封装为 Codex 插件的本地 MCP 适配器。仓库本身是普通 GitHub 项目，不依赖 Codex marketplace。

功能

• 查询 API Key 可见的模型列表

• 创建、查询和取消图片/视频预测任务

• 下载任务输出并自动识别 JPEG、PNG、WebP、MP4 等文件后缀

• 支持本地媒体文件转换为 data URI

• 下载结果使用流式写入、大小限制和临时文件原子落盘

Related MCP server: gemini-nano-banana-mcp

目录结构

codex-ergouzi-media-mcp/
├─ plugins/ergouzi-media-mcp/
│  ├─ .codex-plugin/plugin.json  # Codex 插件清单
│  ├─ .mcp.json                  # MCP 启动配置
│  ├─ README.md                 # 插件说明
│  └─ scripts/
│     ├─ server.mjs             # MCP 协议入口
│     └─ lib.mjs                # API、媒体、任务和下载逻辑
├─ scripts/validate.mjs          # 清单和入口校验
├─ scripts/smoke.mjs             # 工具注册 Smoke 校验
├─ test/lib.test.mjs             # 本地契约测试
├─ .github/workflows/ci.yml      # GitHub Actions
├─ package.json
├─ package-lock.json
└─ CHANGELOG.md

环境要求

• Node.js 20.0.0 或更高版本

• 一个可用的 Ergouzi API Key

• Codex Desktop 或其他支持 stdio MCP 的客户端

安装

git clone https://github.com/miao111994/codex-ergouzi-media-mcp.git
cd codex-ergouzi-media-mcp
npm ci

在 Windows PowerShell 中也可以使用同样的命令。

配置凭据

Windows 默认读取：

C:\Users\<你的用户名>\AppData\Roaming\ergouzi\credentials.json

macOS / Linux 默认读取：

~/.config/ergouzi/credentials.json

文件内容示例：

{
  "api_key": "YOUR_API_KEY",
  "base_url": "https://ergouzi.life"
}

也可以用环境变量覆盖：

• ERGOUZI_MEDIA_API_KEY

• ERGOUZI_MEDIA_BASE_URL

• ERGOUZI_CONFIG_FILE

在 Codex 中安装

完成 npm ci 和凭据配置后，在 Codex 的插件管理界面添加本地插件目录：

<仓库目录>/plugins/ergouzi-media-mcp

Codex 会读取 .codex-plugin/plugin.json，再根据 .mcp.json 执行：

node scripts/server.mjs

不需要把仓库根目录当作 MCP 入口，也不需要创建 marketplace 文件。

调用工具

插件提供以下 MCP 工具：

• list_models

• create_prediction

• get_prediction

• cancel_prediction

• download_prediction

在 Codex 中可以直接使用自然语言调用，例如：

调用 ergouzi-media-mcp 的 list_models，列出可用模型。

使用 ergouzi/e-image 创建一张雨夜街道图片，完成后下载到 F:\生图MCP制作\outputs。

默认下载目录为：

<当前工作目录>/outputs/ergouzi-media-mcp

回执会写入该目录下的 receipts/YYYY-MM-DD/ 子目录。

模型和本地文件行为

list_models 以服务端返回为准。创建任务不再依赖本地硬编码模型名单，因此服务端新增普通 JSON 模型时无需同步发布插件。

本地文件输入使用以下形式，并且只允许出现在插件已声明的媒体字段中：

{
  "$local_file": "C:/path/to/file.png"
}

未知模型可以使用普通 JSON 或 HTTPS 媒体 URL，但未知媒体字段中的 $local_file 会被拒绝。

本地验证

npm run validate
npm test
npm run smoke
npm run audit

测试不会调用真实 API，下载测试使用本地模拟响应。

依赖审计

npm audit 依赖当前配置的 registry audit 接口。部分镜像只提供包下载，不提供 npm audit endpoint，因此可能返回 NOT_IMPLEMENTED；官方 endpoint 也可能因本机网络或 npm 版本返回接口错误。

本仓库提供了带 fallback 的审计命令：

npm run audit

它会先尝试官方 npm audit endpoint，失败后自动使用 OSV Scanner API 扫描 package-lock.json 中的 npm 依赖。GitHub 仓库同时启用了 Dependabot，用于持续发现依赖更新和已知漏洞。

发布版本

当前版本为 0.2.1。版本变更记录见 CHANGELOG.md。