2Xapi.com-GPT-image-MCP-Server: Instructions file for Codex

AGENTS.md — AI 部署指南

本仓库是 GPT-image MCP Server：把 OpenAI 兼容的文生图/图生图接口封装成 MCP 工具。

你的任务（当用户说“部署 / 一键部署 / 配置这个 MCP / 帮我接入”时）： 把本项目作为 MCP server 接入用户指定的客户端（Codex / Claude Code / Claude Desktop / Cursor），让用户能在对话里说「画一只柴犬」直接出图、发一张图说「改成动漫风」就能改图（edit_image，图片支持本地路径 / URL / data URI / base64，支持 mask 局部重绘；内联图片预览默认关闭（include_preview=true 开启），输出带结构化结果）。

关键规则

1. API Key 必须由用户提供：不要编造、不要从仓库里找（仓库不含真实 key）。用户没说 key 时先询问。
2. key 与端点必须配套：IMAGE_API_KEY 是哪家供应商的，IMAGE_API_BASE_URL 就填哪家的（不填则用代码内置默认端点）。
3. 默认端点是 2xapi.com 中转站方案：内置默认端点为 https://2xa.cc.cd/v1（2xapi.com 中转站，官网 https://2Xapi.com），本 MCP 默认配套该中转站的生图方案；用户使用 2xapi.com 的 key 时无需配置端点。如果要使用其他 API 端点（OpenAI 官方 / Azure / 其他中转站），需要用户自行更换：设置 IMAGE_API_BASE_URL 环境变量（npm 版），或修改 config.json 的 api_base_url（Python 版）。
4. 优先 npm 版（gpt-image-mcp-server/，TypeScript，Node 18+）；Python 版（src/）作为备选，仅当用户环境没有 Node 时使用。
5. 不要提交/外发 config.json：它含真实 key，已被 .gitignore 排除。
6. 所有配置写在客户端配置里（环境变量方式），不要改仓库内文件。

部署步骤

1. 确认环境

node -v   # 需要 >= 18

没有 Node：提示用户安装 Node.js 18+（或改用 Python 版：python3 --version + uv --version）。

2. 安装依赖并构建 npm 版

cd gpt-image-mcp-server
npm install
npm run build     # 生成 dist/index.js

3. 获取用户的 API Key

向用户询问（一次性）：

• IMAGE_API_KEY（必填）— 形如 sk-xxxxxxxx
• IMAGE_API_BASE_URL（可选）— 到 /v1 一级；不填用内置默认

4. 接入客户端（关键命令）

• Codex（推荐，先问用户用什么客户端）：

codex mcp add GPT-image --env IMAGE_API_KEY=用户的key -- node /绝对路径/gpt-image-mcp-server/dist/index.js

（/绝对路径 = 仓库的绝对路径，例如 /Users/xxx/2Xapi.com-GPT-image-MCP-Server）

• Claude Code：

claude mcp add -s user gpt-image --env IMAGE_API_KEY=用户的key -- node /绝对路径/gpt-image-mcp-server/dist/index.js

• Claude Desktop：编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，在顶层 mcpServers 加：

{
  "mcpServers": {
    "GPT-image": {
      "command": "node",
      "args": ["/绝对路径/gpt-image-mcp-server/dist/index.js"],
      "env": { "IMAGE_API_KEY": "用户的key" }
    }
  }
}