mcp-image-gen: Instructions file for Codex

AGENTS.md

项目概述

这是一个基于 ** Model Context Protocol（MCP）** 的图像生成服务器项目。项目作为中间件，将 MCP 协议请求转换为标准的 OpenAI 兼容格式（/v1/images/generations）调用上游图像生成 API。专为云端部署场景设计，通过 Streamable HTTP 提供服务，支持 Claude Desktop、RikkaHub 等 MCP 客户端远程连接。

技术栈

• 运行时环境：Node.js >= 18.0.0
• 语言：TypeScript 5.4+
• Web 框架：Express.js 4.18.2
• MCP 协议 SDK：@modelcontextprotocol/sdk ^1.0.0
• 参数验证：Zod ^3.23.8
• 环境配置：dotenv ^16.4.5
• 跨域支持：cors ^2.8.5
• 模块格式：ES Module（"type": "module"）

核心文件结构

mcp-image-gen/
├── src/
│   ├── index.ts        # Express 服务器入口，Streamable HTTP 传输层实现
│   └── config.ts       # 配置管理，环境变量定义和类型
├── dist/               # TypeScript 编译输出（由 npm run build 生成）
│   ├── index.js
│   └── config.js
├── .env.example        # 环境变量配置模板
├── Dockerfile          # Docker 镜像构建文件
├── package.json        # 项目依赖声明和 npm 脚本
├── tsconfig.json       # TypeScript 编译配置
├── .github/workflows/
│   └── docker-publish.yml   # GitHub Actions 自动构建 Docker 镜像工作流
└── README.md           # 项目使用文档

构建和运行

本地开发

# 安装项目依赖
npm install

# 复制环境变量模板并配置
cp .env.example .env
# 编辑 .env 文件，填入 API_KEY 等必要配置

# 构建 TypeScript
npm run build

# 启动服务（前台运行）
npm start

# 开发模式（监听文件变化自动重启）
npm run dev

# 使用 MCP Inspector 测试
npm run inspect

Docker 部署

# 构建 Docker 镜像
docker build -t mcp-image-gen .

# 运行容器
docker run -d -p 3000:3000 -e API_KEY=your_api_key mcp-image-gen

# 使用 GitHub Container Registry 镜像
docker run -d -p 3000:3000 -e API_KEY=your_api_key ghcr.io/ranbo12138/mcp-image-gen:latest

服务端点

端点	方法	说明
/mcp	POST	MCP 协议主端点，处理客户端请求和初始化
/mcp	GET	SSE 通知端点，服务器向客户端推送消息
/mcp	DELETE	会话终止端点
/health	GET	健康检查端点，返回服务状态和活跃会话数

开发约定

代码风格规范

• 使用 TypeScript，启用严格模式（strict: true）
• 模块导入导出采用 ES Module 形式
• 变量和函数命名使用 camelCase 风格
• 常量命名使用大写字母加下划线
• 所有配置和类型在 config.ts 中集中定义

MCP 服务器架构

项目采用 MCP SDK 推荐的高级 API 模式：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";

// 创建服务器实例
const server = new McpServer({
  name: "cloud-image-generator",
  version: "3.0.0",
});

// 使用 Zod 定义参数 Schema
server.registerTool("generate_image", {
  title: "Generate Image",
  description: "...",
  inputSchema: {
    prompt: z.string().describe("..."),
    size: z.enum(["16:9", "9:16", "1:1", "2:3", "3:2"]).default("2:3"),
  },
}, async (params) => {
  // 工具实现
  return { content: [{ type: "text", text: "..." }] };
});