金大哥 - media-gen-mcp MCP 详情

article

README

🚀 media-gen-mcp

Media Gen MCP 是一款严格使用 TypeScript 编写的模型上下文协议（MCP）服务器，支持 OpenAI 图像（gpt-image-1.5、gpt-image-1）、OpenAI 视频（Sora）以及 Google GenAI 视频（Veo）。它能实现图像的生成与编辑、视频作业的创建与混音，还能从 URL 或磁盘获取媒体资源，并提供智能的 resource_link 与内联 image 输出，同时支持可选的 sharp 处理。该项目聚焦于生产环境（具备完整的严格类型检查、ESLint 和 Vitest 持续集成），可与 fast-agent、Claude Desktop、ChatGPT、Cursor、VS Code、Windsurf 以及任何兼容 MCP 的客户端协同工作。

🚀 快速开始

fast-agent

在 fast-agent 中，MCP 服务器的配置位于 fastagent.config.yaml 文件的 mcp.servers 部分（具体可参考 fast-agent 文档）。若要通过 npx 将 media-gen-mcp 作为 MCP 服务器添加，可按如下配置：

# fastagent.config.yaml

mcp:
  servers:
    # 已有服务器配置（例如 fetch、filesystem、huggingface 等）
    media-gen-mcp:
      command: "npx"
      args: ["-y", "github:strato-space/media-gen-mcp", "--env-file", "/path/to/media-gen.env"]

需将 OPENAI_API_KEY 及其他配置信息添加到 media-gen.env 文件中（可参考本仓库中的 .env.sample 文件）。

Windsurf

使用以下 JSON 格式，通过 npx 从 GitHub 运行 media-gen-mcp 并将其添加为 MCP 服务器（Claude Desktop / VS Code 的配置方式与之类似）：

{
  "mcpServers": {
    "media-gen-mcp": {
      "command": "npx",
      "args": ["-y", "github:strato-space/media-gen-mcp", "--env-file", "/path/to/media-gen.env"]
    }
  }
}

✨ 主要特性

严格支持 MCP 规范：工具输出为符合最新 MCP 架构的一级 CallToolResult 对象，涵盖 content 项（如 text、image、resource_link、resource）、可选的 structuredContent、可选的顶级 files 以及用于表示失败的 isError 标志。
全面覆盖 gpt-image-1.5 和 sora-2/sora-2-pro 参数（生成与编辑）：
- openai-images-generate 模拟 OpenAI 图像的 create API，支持 gpt-image-1.5（未来版本计划支持 gpt-image-1 及 DALL·E），可处理背景、审核、尺寸、质量、输出格式、输出压缩、生成数量、用户标识等参数。
- openai-images-edit 模拟 OpenAI 图像的 createEdit API，支持 gpt-image-1.5（未来版本计划支持 gpt-image-1），可处理图像、遮罩、生成数量、质量、尺寸、用户标识等参数。
OpenAI 视频（Sora）作业工具（创建 / 混音 / 列表 / 检索 / 删除 / 内容获取）：
- openai-videos-create 模拟 videos/create，可选择等待作业完成。
- openai-videos-remix 模拟 videos/remix。
- openai-videos-list 模拟 videos/list。
- openai-videos-retrieve 模拟 videos/retrieve。
- openai-videos-delete 模拟 videos/delete。
- openai-videos-retrieve-content 模拟 videos/content，可将 video / thumbnail / spritesheet 资源下载到磁盘，并返回 MCP resource_link（默认）或嵌入式 resource 块（通过 tool_result）。
Google GenAI（Veo）操作与下载（生成 / 检索操作 / 检索内容）：
- google-videos-generate 启动一个长时间运行的操作（ai.models.generateVideos），可选择等待操作完成并下载 .mp4 输出文件。Veo 模型参考
- google-videos-retrieve-operation 轮询现有操作。
- google-videos-retrieve-content 从已完成的操作中下载 .mp4 文件，并返回 MCP resource_link（默认）或嵌入式 resource 块（通过 tool_result）。
从 URL 或文件获取并处理图像：fetch-images 工具可从 HTTP(S) URL 或本地文件路径加载图像，并支持可选的用户控制压缩（默认禁用），最多可并行处理 20 张图像。
从 URL 或文件获取视频：fetch-videos 工具可列出本地视频或从远程视频 URL 下载视频到磁盘，并返回 MCP resource_link（默认）或嵌入式 resource 块（通过 tool_result）。
混合与编辑多达 16 张图像：openai-images-edit 支持将 image 作为单个字符串或包含 1 - 16 个文件路径/Base64 字符串的数组，符合 OpenAI GPT 图像模型（gpt-image-1.5、gpt-image-1）的图像编辑规范。
智能图像压缩：内置基于 sharp 的压缩功能，可在保持视觉质量的前提下，通过迭代降低质量和尺寸以适应 MCP 有效负载限制。
基于 resource_link 的资源感知文件输出：
- 当总响应大小超过安全阈值时，自动从内联 Base64 切换到 file 输出。
- 输出文件以 output_<time_t>_media-gen__<tool>_<id>.<ext> 命名（图像使用生成的 UUID，视频使用 OpenAI video_id），并根据 tool_result 通过 content[] 向 MCP 客户端暴露（图像使用 resource_link/image，视频下载使用 resource_link/resource）。
内置用于 MCP 客户端调试的 test-images 工具：test-images 从配置目录读取示例图像，并使用与生产工具相同的结果构建逻辑返回图像。可使用 tool_result 和 response_format 参数测试不同 MCP 客户端对 content[] 和 structuredContent 的处理方式。
结构化 MCP 错误处理：所有工具错误（验证错误、OpenAI API 失败、I/O 错误等）均以 MCP 错误形式返回，包含 isError: true 和 content: [{ type: "text", text: <错误消息> }]，便于 MCP 客户端解析和处理错误。

📦 安装指南

git clone https://github.com/strato-space/media-gen-mcp.git
cd media-gen-mcp

npm install
npm run build

构建模式如下：

npm run build：严格的 TypeScript 构建，启用所有严格标志，包括 skipLibCheck: false。通过 .tsbuildinfo 实现增量构建（热缓存下约 2 - 3 秒）。
npm run esbuild：通过 esbuild 进行快速打包（无类型检查，适用于快速迭代）。

开发模式（无需构建）

若进行开发或因内存限制导致 TypeScript 编译失败，可使用以下命令：

npm run dev  # 使用 tsx 直接运行 TypeScript

质量检查

npm run lint        # 使用 ESLint 和 typescript-eslint 进行代码检查
npm run typecheck   # 严格的 tsc --noEmit 类型检查
npm run test        # 单元测试（使用 vitest）
npm run test:watch  # 测试监听模式，用于测试驱动开发
npm run ci          # 代码检查 + 类型检查 + 单元测试

单元测试

本项目使用 vitest 进行单元测试，测试文件位于 test/ 目录下。 覆盖模块及测试数量： | 模块 | 测试数量 | 描述 | |------|----------|------| | compression | 12 | 图像格式检测、缓冲区处理、文件 I/O | | helpers | 31 | URL/路径验证、输出解析、结果放置、资源链接 | | env | 19 | 配置解析、环境验证、默认值 | | logger | 10 | 结构化日志记录 + 截断安全 | | pricing | 5 | Sora 定价估算辅助函数 | | schemas | 69 | 所有工具的 Zod 架构验证、类型推断 | | fetch-images（集成测试） | 3 | 端到端 MCP 工具调用行为 | | fetch-videos（集成测试） | 3 | 端到端 MCP 工具调用行为 |

测试类别：

compression：isCompressionAvailable、detectImageFormat、processBufferWithCompression、readAndProcessImage
helpers：isHttpUrl、isAbsolutePath、isBase64Image、ensureDirectoryWritable、resolveOutputPath、getResultPlacement、buildResourceLinks
env：MEDIA_GEN_* / MEDIA_GEN_MCP_* 设置的配置加载和验证
logger：截断和错误格式化行为
schemas：openai-images-*、openai-videos-*、fetch-images、fetch-videos、test-images 输入的验证、边界测试（提示长度、图像数量限制、路径验证）

运行测试命令：

npm run test
# ✓ test/compression.test.ts (12 个测试用例)
# ✓ test/helpers.test.ts (31 个测试用例)
# ✓ test/env.test.ts (19 个测试用例)
# ✓ test/logger.test.ts (10 个测试用例)
# ✓ test/pricing.test.ts (5 个测试用例)
# ✓ test/schemas.test.ts (69 个测试用例)
# ✓ test/fetch-images.integration.test.ts (3 个测试用例)
# ✓ test/fetch-videos.integration.test.ts (3 个测试用例)
# 测试结果：152 个测试用例通过

直接通过 npx 运行（无需本地克隆）

也可使用 npx 直接从远程仓库运行服务器：

npx -y github:strato-space/media-gen-mcp --env-file /path/to/media-gen.env

--env-file 参数用于指定服务器加载的环境文件（例如，当你将密钥存储在克隆目录之外时）。该文件应包含 OPENAI_API_KEY、可选的 Azure 变量以及任何 MEDIA_GEN_MCP_* 设置。

`secrets.yaml`（可选）

可将 API 密钥（以及可选的 Google Vertex AI 设置）存储在 secrets.yaml 文件中（与 fast-agent 密钥模板兼容）：

openai:
  api_key: <your-api-key-here>
anthropic:
  api_key: <your-api-key-here>
google:
  api_key: <your-api-key-here>
  vertex_ai:
    enabled: true
    project_id: your-gcp-project-id
    location: europe-west4

media-gen-mcp 会从当前工作目录加载 secrets.yaml 文件（或通过 --secrets-file /path/to/secrets.yaml 指定文件路径），并将其应用于环境变量。secrets.yaml 中的值会覆盖环境变量，<your-api-key-here> 占位符将被忽略。

🔧 技术细节

配置

将以下配置添加到 MCP 客户端配置文件（如 fast-agent、Windsurf、Claude Desktop、Cursor、VS Code）中：

{
  "mcpServers": {
    "media-gen-mcp": {
      "command": "npx",
      "args": ["-y", "github:strato-space/media-gen-mcp"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

同时支持 Azure 部署：

{
  "mcpServers": {
    "media-gen-mcp": {
      "command": "npx",
      "args": ["-y", "github:strato-space/media-gen-mcp"],
      "env": {
        // "AZURE_OPENAI_API_KEY": "sk-...",
        // "AZURE_OPENAI_ENDPOINT": "my.endpoint.com",
        "OPENAI_API_VERSION": "2024-12-01-preview"
      }
    }
  }
}

环境变量设置如下：

在运行 node dist/index.js 的进程环境中设置 OPENAI_API_KEY（可选设置 AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、OPENAI_API_VERSION），可在 shell、systemd 单元、Docker 环境等中进行设置。
若服务器工作目录中存在 .env 文件，服务器将可选加载该文件，但不会覆盖已设置的环境变量。
启动服务器时（包括通过 npx），可传递 --env-file /path/to/env 参数，该文件将在工具运行前通过 dotenv 加载，同样不会覆盖已设置的变量。

日志记录与 Base64 截断

为避免日志被大量图像有效负载淹没，内置日志记录器会对传递给 log.debug/info/warn/error 的结构化 data 应用仅记录的清理器：

将配置的字符串字段（如 b64_json、base64、字符串 data、image_url）截断为短预览，长度由 LOG_TRUNCATE_DATA_MAX 控制（默认 64 个字符）。默认的键列表位于 src/lib/logger.ts 中的 LOG_SANITIZE_KEYS，可通过 MEDIA_GEN_MCP_LOG_SANITIZE_KEYS（逗号分隔的字段名列表）进行覆盖。
清理仅应用于日志序列化，返回给 MCP 客户端的工具结果不会被修改。可通过环境变量进行控制：
MEDIA_GEN_MCP_LOG_SANITIZE_IMAGES（默认值：true）
- 1、true、yes、on：启用截断（默认行为）。
- 0、false、no、off：禁用截断，记录完整有效负载。字段列表和限制在 src/lib/logger.ts 中通过 LOG_SANITIZE_KEYS 和 LOG_TRUNCATE_DATA_MAX 进行配置。

安全与本地文件访问

允许的目录：所有工具仅限于访问匹配 MEDIA_GEN_DIRS 的路径。若未设置，默认值为 /tmp/media-gen-mcp（Windows 系统为 %TEMP%/media-gen-mcp）。
测试样本：MEDIA_GEN_MCP_TEST_SAMPLE_DIR 可将一个目录添加到允许列表中，并启用 test-images 工具。
本地读取：fetch-images 接受文件路径（绝对路径或相对路径）。相对路径将相对于 MEDIA_GEN_DIRS 的第一个条目进行解析，且必须匹配允许的模式。
远程读取：HTTP(S) 获取操作将根据 MEDIA_GEN_URLS 模式进行过滤。若为空，则允许所有访问。
写入操作：openai-images-generate、openai-images-edit、fetch-images 和 fetch-videos 将文件写入 MEDIA_GEN_DIRS 的第一个条目指定的目录。test-images 为只读操作，不会创建新文件。

Glob 模式

MEDIA_GEN_DIRS 和 MEDIA_GEN_URLS 均支持 Glob 通配符： | 模式 | 匹配规则 | 示例 | |------|----------|------| | * | 匹配任意单个段（不包含 /） | /home/*/media/ 可匹配 /home/user1/media/ | | ** | 匹配任意数量的段 | /data/**/images/ 可匹配 /data/a/b/images/ |

URL 示例：

MEDIA_GEN_URLS=https://*.cdn.example.com/,https://storage.example.com/**/assets/

路径示例：

MEDIA_GEN_DIRS=/home/*/media-gen/output/,/data/**/images/

⚠️ 警告：尾部通配符无分隔符（如 /home/user/* 或 https://cdn.com/**）会暴露整个子树，并在启动时触发控制台警告。

工具结果参数：`tool_result` 和 `response_format`

图像工具（openai-images-*、fetch-images、test-images）支持两个参数，用于控制 MCP 工具结果的结构： | 参数 | 值 | 默认值 | 描述 | |------|------|------|------| | tool_result | resource_link、image | resource_link | 控制 content[] 的结构 | | response_format | url、b64_json | url | 控制 structuredContent 的结构（OpenAI 图像响应格式） |

视频下载工具（openai-videos-create / openai-videos-remix 下载时、openai-videos-retrieve-content、google-videos-generate 下载时、google-videos-retrieve-content、fetch-videos）支持： | 参数 | 值 | 默认值 | 描述 | |------|------|------|------| | tool_result | resource_link、resource | resource_link | 控制 content[] 的结构 |

Google 视频工具（google-videos-*）还支持： | 参数 | 值 | 默认值 | 描述 | |------|------|------|------| | response_format | url、b64_json | url | 控制 structuredContent.response.generatedVideos[].video 的结构（uri 或 videoBytes） |

`tool_result` — 控制 `content[]`

图像工具（openai-images-*、fetch-images、test-images）
- resource_link（默认）：发出包含 file:// 或 https:// URI 的 ResourceLink 项。
- image：发出 Base64 编码的 ImageContent 块。
视频工具（下载视频数据的工具）
- resource_link（默认）：发出包含 file:// 或 https:// URI 的 ResourceLink 项。
- resource：发出包含 Base64 编码 resource.blob 的 EmbeddedResource 块。

`response_format` — 控制 `structuredContent`

对于 OpenAI 图像，structuredContent 始终包含一个类似 OpenAI 图像响应的对象：

{
  "created": 1234567890,
  "data": [
    { "url": "https://..." } // 或 { "b64_json": "..." }，取决于 response_format
  ]
}

url（默认）：data[].url 包含文件 URL。
b64_json：data[].b64_json 包含 Base64 编码的图像数据。

对于 Google 视频，response_format 控制 structuredContent.response.generatedVideos[].video 的偏好：

url（默认）：使用 video.uri（并移除 video.videoBytes）。
b64_json：使用 video.videoBytes（并移除 video.uri）。

向后兼容性（MCP 5.2.6）

根据 MCP 规范 5.2.6，为与不支持 structuredContent 的客户端保持向后兼容，content[] 中还会包含一个序列化 JSON 的 TextContent 块（始终在 data[] 中使用 URL）。

示例工具结果结构：

{
  "content": [
    // 根据 tool_result 为 ResourceLink 或 ImageContent
    { "type": "resource_link", "uri": "https://...", "name": "image.png", "mimeType": "image/png" },
    // 用于向后兼容的序列化 JSON（MCP 5.2.6）
    { "type": "text", "text": "{ \"created\": 1234567890, \"data\": [{ \"url\": \"https://...\" }] }" }
  ],
  "structuredContent": {
    "created": 1234567890,
    "data": [{ "url": "https://..." }]
  }
}

ChatGPT MCP 客户端行为（截至 2025 - 12 - 01，chatgpt.com）：

ChatGPT 当前忽略 content[] 中的图像数据，优先使用 structuredContent。
对于 ChatGPT，建议使用 response_format: "url"，并将 MEDIA_GEN_MCP_URL_PREFIXES 的第一个条目配置为公共 HTTPS 前缀（例如 MEDIA_GEN_MCP_URL_PREFIXES=https://media-gen.example.com/media）。

对于 Anthropic 客户端（如 Claude Desktop 等），默认配置即可正常工作。

通过 mcp - proxy 进行网络访问（SSE）

若要进行网络 SSE 访问，可使用 mcp - proxy 或其等效工具作为 media - gen - mcp 的前端。此设置已通过 TypeScript SSE 代理实现 [punkpeye/mcp - proxy](https://github.com/punkpeye/mcp - proxy) 进行测试。

例如，单行命令如下：

mcp - proxy --host = 0.0.0.0 --port = 99 --server = sse --sseEndpoint = / --shell 'npx - y github:strato - space/media - gen - mcp --env - file /path/to/media - gen.env'

在生产环境中，通常会通过 systemd 模板单元进行配置，该单元从 EnvironmentFile= 加载 PORT/SHELL_CMD（可参考 server/mcp/mcp@.service 风格的设置）。

💻 使用示例

openai-images-generate

// 示例代码，展示如何调用 openai-images-generate 工具
// 以下代码仅为示例，实际使用时需根据具体情况进行调整
import { server } from 'media-gen-mcp';

// 定义参数
const args = {
  prompt: 'A beautiful landscape',
  background: 'opaque',
  model: 'gpt-image-1.5',
  moderation: 'auto',
  n: 1,
  output_compression: 80,
  output_format: 'png',
  quality: 'high',
  size: '1024x1536',
  user: 'user123',
  response_format: 'url',
  tool_result: 'resource_link'
};

// 调用工具
server.registerTool(
  "openai-images-generate",
  { inputSchema: openaiImagesGenerateBaseSchema.shape, ... },
  async (args: OpenAIImagesGenerateArgs, _extra: unknown) => {
    const validated = openaiImagesGenerateSchema.parse(args);
    // 处理工具调用结果
    // ...
  },
);

openai-images-edit

// 示例代码，展示如何调用 openai-images-edit 工具
// 以下代码仅为示例，实际使用时需根据具体情况进行调整
import { server } from 'media-gen-mcp';

// 定义参数
const args = {
  image: '/path/to/image.png',
  prompt: 'Add a bird to the image',
  mask: '/path/to/mask.png',
  model: 'gpt-image-1.5',
  n: 1,
  quality: 'high',
  size: '1024x1536',
  user: 'user123',
  response_format: 'url',
  tool_result: 'resource_link'
};

// 调用工具
server.registerTool(
  "openai-images-edit",
  { inputSchema: openaiImagesEditBaseSchema.shape, ... },
  async (args: OpenAIImagesEditArgs, _extra: unknown) => {
    const validated = openaiImagesEditSchema.parse(args);
    // 处理工具调用结果
    // ...
  },
);

🛠 工具签名

openai-images-generate

参数（输入架构）：

prompt（字符串，必需）：描述所需图像的文本提示，最大长度为 32,000 个字符。
background（可选值："transparent" | "opaque" | "auto"）：背景处理模式。若 background 为 "transparent"，则 output_format 必须为 "png" 或 "webp"。
model（可选值："gpt-image-1.5" | "gpt-image-1"，默认值："gpt-image-1.5"）
moderation（可选值："auto" | "low"）：内容审核行为，传递给图像 API。
n（整数，可选）：生成的图像数量，最小值为 1，最大值为 10。
output_compression（整数，可选）：压缩级别（0 - 100），仅在 output_format 为 "jpeg" 或 "webp" 时应用。
output_format（可选值："png" | "jpeg" | "webp"）：输出图像格式。若省略，服务器将输出视为 PNG 语义。
quality（可选值："auto" | "high" | "medium" | "low"，默认值："high"）
size（可选值："1024x1024" | "1536x1024" | "1024x1536" | "auto"，默认值："1024x1536"）
user（字符串，可选）：用户标识符，转发给 OpenAI 用于监控。
response_format（可选值："url" | "b64_json"，默认值："url"）：响应格式（与 OpenAI 图像 API 一致）：
- "url"：基于文件/URL 的输出（resource_link 项、image_url 字段、api 放置方式中的 data[].url）。
- "b64_json"：内联 Base64 图像数据（图像内容、api 放置方式中的 data[].b64_json）。
tool_result（可选值："resource_link" | "image"，默认值："resource_link"）：控制 content[] 的结构：
- "resource_link" 发出 ResourceLink 项（基于文件/URL）。
- "image" 发出 Base64 ImageContent 块。

行为说明：

服务器默认使用 OpenAI gpt-image-1.5 模型（若需使用旧版行为，可设置 model: "gpt-image-1"）。
若所有 Base64 图像的总大小超过配置的有效负载阈值（默认约 50MB，通过 MCP_MAX_CONTENT_BYTES 设置），服务器将自动将有效输出模式切换为基于文件/URL 的模式，并将图像保存到 MEDIA_GEN_DIRS 的第一个条目指定的目录（默认：/tmp/media-gen-mcp）。
即使你明确请求 response_format: "b64_json"，服务器仍会将文件写入磁盘（用于静态托管、缓存或后续重用）。工具结果中文件路径/URL 的暴露取决于 MEDIA_GEN_MCP_RESULT_PLACEMENT 和每次调用的 result_placement（详见下文）。

输出（MCP CallToolResult，当放置方式包含 "content" 时）：

当有效 output 模式为 "base64" 时：
- content 是一个数组，可能包含：
  - 图像项：{ type: "image", data: <Base64 字符串>, mimeType: <"image/png" | "image/jpeg" | "image/webp"> }
  - 可选的文本项，包含图像 API 返回的修订提示（适用于支持该功能的模型，如 DALL·E 3）：{ type: "text", text: <修订提示字符串> }
当有效 output 模式为 "file" 时：
- content 包含每个文件的一个 resource_link 项，以及相同的可选 text 项（包含修订提示）：{ type: "resource_link", uri: "file:///absolute - path - 1.png", name: "absolute - path - 1.png", mimeType: <图像 MIME 类型> }
- 对于 gpt-image-1.5 和 gpt-image-1，还会包含一个额外的 text 行，显示定价估算（基于 structuredContent.usage），并且 structuredContent.pricing 包含完整的定价明细。

当 result_placement 包含 "api" 时，openai-images-generate 返回一个类似 OpenAI 图像 API 的对象，无 MCP 包装：

{
  "created": 1764599500,
  "data": [
    { "b64_json": "..." } // 或 { "url": "https://.../media/file.png" }，取决于 output 模式
  ],
  "background": "opaque",
  "output_format": "png",
  "size": "1024x1024",
  "quality": "high"
}

openai-images-edit

参数（输入架构）：

image（字符串或字符串数组，必需）：可以是单个图像文件的绝对路径（.png、.jpg、.jpeg、.webp）、Base64 编码的图像字符串（可选为 data:image/...;base64,... URL）、指向公开可访问图像的 HTTP(S) URL，或包含 1 - 16 个此类字符串的数组（用于多图像编辑）。当提供 HTTP(S) URL 时，服务器会获取图像并将其转换为 Base64 格式后再发送给 OpenAI。
prompt（字符串，必需）：描述所需编辑的文本，最大长度为 32,000 个字符。
mask（字符串，可选）：遮罩图像的绝对路径、Base64 字符串或 HTTP(S) URL（PNG 格式，大小小于 4MB，与源图像尺寸相同）。透明区域标记需要编辑的区域。
model（可选值："gpt-image-1.5" | "gpt-image-1"，默认值："gpt-image-1.5"）
n（整数，可选）：生成的图像数量，最小值为 1，最大值为 10。
quality（可选值："auto" | "high" | "medium" | "low"，默认值："high"）
size（可选值："1024x1024" | "1536x1024" | "1024x1536" | "auto"，默认值："1024x1536"）
user（字符串，可选）：用户标识符，转发给 OpenAI 用于监控。
response_format（可选值："url" | "b64_json"，默认值："url"）：响应格式（与 OpenAI 图像 API 一致）：
- "url"：基于文件/URL 的输出（resource_link 项、image_url 字段、api 放置方式中的 data[].url）。
- "b64_json"：内联 Base64 图像数据（图像内容、api 放置方式中的 data[].b64_json）。
tool_result（可选值："resource_link" | "image"，默认值："resource_link"）：控制 content[] 的结构：
- "resource_link" 发出 ResourceLink 项（基于文件/URL）。
- "image" 发出 Base64 ImageContent 块。

行为说明：

服务器接受 image 和 mask 作为绝对路径、Base64/data URL 或 HTTP(S) URL。
当提供 HTTP(S) URL 时，服务器会获取图像并将其转换为 Base64 数据 URL 后再调用 OpenAI。
对于编辑操作，服务器在发出图像时始终返回 PNG 语义（MIME 类型为 image/png）。

输出（MCP CallToolResult）：

当有效 output 模式为 "base64" 时：
- content 是一个数组，可能包含：
  - 图像项：{ type: "image", data: <Base64 字符串>, mimeType: "image/png" }
  - 可选的文本项，包含修订提示（当底层模型返回时）：{ type: "text", text: <修订提示字符串> }
当有效 output 模式为 "file" 时：
- content 包含每个文件的一个 resource_link 项，以及相同的可选 text 项（包含修订提示）：{ type: "resource_link", uri: "file:///absolute - path - 1.png", name: "absolute - path - 1.png", mimeType: "image/png" }
- 对于 gpt-image-1.5 和 gpt-image-1，还会包含一个额外的 text 行，显示定价估算（基于 structuredContent.usage），并且 structuredContent.pricing 包含完整的定价明细。

当 result_placement 包含 "api" 时，openai-images-edit 遵循与 openai-images-generate 相同的原始 API 格式（顶级 created、data[]、background、output_format、size、quality，Base64 输出使用 b64_json，文件输出使用 url）。

错误处理（两个工具）：

工具处理程序内部出现错误（验证错误、OpenAI API 失败、I/O 错误等）时，服务器返回一个标记为错误的 CallToolResult：
- isError: true
- content: [{ type: "text", text: <错误消息字符串> }]
错误消息文本直接取自底层异常消息，服务器不会添加额外注释，详细信息会记录到服务器控制台。

openai-videos-create

使用 OpenAI 视频 API（videos.create）创建视频生成作业。

参数（输入架构）：

prompt（字符串，必需）：描述视频的文本提示，最大长度为 32K 字符。
input_reference（字符串，可选）：可选的图像参考（HTTP(S) URL、Base64/data URL 或文件路径）。
input_reference_fit（可选值："match" | "cover" | "contain" | "stretch"，默认值："contain"）：控制 input_reference 如何适应请求的视频 size：
- match：要求精确匹配尺寸（不匹配时快速失败）。
- cover：调整大小并居中裁剪以填充。
- contain：调整大小并填充/加黑边以适应（默认）。
- stretch：调整大小并变形。
input_reference_background（可选值："blur" | "black" | "white" | "#RRGGBB" | "#RRGGBBAA"，默认值："blur"）：当 input_reference_fit="contain" 时使用的填充背景。
model（可选值："sora-2" | "sora-2-pro"，默认值："sora-2-pro"）
seconds（可选值："4" | "8" | "12"）
size（可选值："720x1280" | "1280x720" | "1024x1792" | "1792x1024"）：1024x1792 和 1792x1024 要求使用 sora-2-pro 模型。若省略 input_reference 和 size，则使用 API 默认值。
wait_for_completion（布尔值，默认值：true）：为 true 时，服务器会轮询 openai-videos-retrieve 直到作业完成或失败（或超时），然后下载资源。
timeout_ms（整数，默认值：900000）
poll_interval_ms（整数，默认值：2000）
download_variants（字符串数组，默认值：["video"]）：允许的值为 "video" | "thumbnail" | "spritesheet"。
tool_result（可选值："resource_link" | "resource"，默认值："resource_link"）：控制下载资源的 content[] 结构：
- "resource_link" 发出 ResourceLink 项（基于文件/URL）。
- "resource" 发出包含 Base64 resource.blob 的 EmbeddedResource 块。

输出（MCP CallToolResult）：

structuredContent：OpenAI Video 对象（作业元数据；当 wait_for_completion=true 时为最终状态）。
content：包括 resource_link（默认）或嵌入式 resource 块（当请求时）以及包含 JSON 的文本块。包括一个摘要 JSON 块：{ "video_id": "...", "pricing": { "currency": "USD", "model": "...", "size": "...", "seconds": 4, "price": 0.1, "cost": 0.4 } | null }（等待时还包括 { "video_id": "...", "assets": [...], "pricing": ... }）。

openai-videos-remix

从现有的 video_id 创建混音作业（videos.remix）。

参数（输入架构）：

video_id（字符串，必需）
prompt（字符串，必需）
wait_for_completion、timeout_ms、poll_interval_ms、download_variants、tool_result：语义与 openai-videos-create 相同（默认等待为 true）。

openai-videos-list

列出视频作业（videos.list）。

参数（输入架构）：

after（字符串，可选）：用于分页的游标（视频 ID）。
limit（整数，可选）
order（可选值："asc" | "desc"）

输出：

structuredContent：OpenAI 列表响应格式 { data, has_more, last_id }。
content：包含序列化 JSON 的文本块。

openai-videos-retrieve

检索作业状态（videos.retrieve）。

参数：

video_id（字符串，必需）

openai-videos-delete

删除视频作业（videos.delete）。

参数：

video_id（字符串，必需）

openai-videos-retrieve-content

从已完成的作业中检索资源（videos.downloadContent，REST GET /videos/{video_id}/content），将其写入允许的 MEDIA_GEN_DIRS 目录，并返回 MCP resource_link（默认）或嵌入式 resource 块（通过 tool_result）。

参数（输入架构）：

video_id（字符串，必需）
variant（可选值："video" | "thumbnail" | "spritesheet"，默认值："video"）
tool_result（可选值："resource_link" | "resource"，默认值："resource_link"）

输出（MCP CallToolResult）：

structuredContent：OpenAI Video 对象。
content：一个 resource_link（或嵌入式 resource）、一个摘要 JSON 块 { video_id, variant, uri, pricing } 以及完整的视频 JSON。

google-videos-generate

使用 Google GenAI SDK（@google/genai）的 ai.models.generateVideos 创建 Google 视频生成操作。

参数（输入架构）：

prompt（字符串，可选）
input_reference（字符串，可选）：图像到视频的输入（HTTP(S) URL、Base64/data URL 或 MEDIA_GEN_DIRS 下的文件路径）
input_reference_mime_type（字符串，可选）：覆盖 input_reference 的 MIME 类型（必须为 image/*）
input_video_reference（字符串，可选）：视频扩展输入（HTTP(S) URL 或 MEDIA_GEN_DIRS 下的文件路径；与 input_reference 互斥）
model（字符串，默认值："veo-3.1-generate-001"）
number_of_videos（整数，默认值：1）
aspect_ratio（可选值："16:9" | "9:16"）
duration_seconds（整数，可选）：
- Veo 2 模型：5 - 8 秒（默认：8 秒）
- Veo 3 模型：4、6 或 8 秒（默认：8 秒）
- 使用 referenceImages 时：8 秒
person_generation（可选值："DONT_ALLOW" | "ALLOW_ADULT" | "ALLOW_ALL"）
wait_for_completion（布尔值，默认值：true）
timeout_ms（整数，默认值：900000）
poll_interval_ms（整数，默认值：10000）
download_when_done（布尔值，可选；等待时默认值为 true）
tool_result（可选值："resource_link" | "resource"，默认值："resource_link"）：控制下载生成视频时的 content[] 结构。
response_format（可选值："url" | "b64_json"，默认值："url"）：控制 structuredContent.response.generatedVideos[].video 字段：
- "url" 优先使用 video.uri（并移除 video.videoBytes）
- "b64_json" 优先使用 video.videoBytes（并移除 video.uri）

要求：

Gemini 开发者 API：设置 GEMINI_API_KEY（或 GOOGLE_API_KEY），或在 secrets.yaml 中设置 google.api_key。
Vertex AI：设置 GOOGLE_GENAI_USE_VERTEXAI=true、GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION（或在 secrets.yaml 中设置 google.vertex_ai.*）。

输出：

structuredContent：Google 操作对象（包括 name、done 和 response.generatedVideos[]，当可用时）。
content：状态文本、可选的 .mp4 resource_link（默认）或嵌入式 resource 块（下载时）以及用于兼容的 JSON 文本块。

google-videos-retrieve-operation

检索/轮询现有的 Google 视频操作（ai.operations.getVideosOperation）。

参数：

operation_name（字符串，必需）
response_format（可选值："url" | "b64_json"，默认值："url"）

输出：

structuredContent：Google 操作对象。
content：包含简短摘要和完整操作的 JSON 文本块。

google-videos-retrieve-content

从已完成的操作中下载 .mp4 内容，并返回基于文件的 MCP resource_link（默认）或嵌入式 resource 块（通过 tool_result）。

参数：

operation_name（字符串，必需）
index（整数，默认值：0）：选择 response.generatedVideos[index]
tool_result（可选值："resource_link" | "resource"，默认值："resource_link"）
response_format（可选值："url" | "b64_json"，默认值："url"）

推荐工作流程：

调用 google-videos-generate 并设置 wait_for_completion=true（默认）以获取完成的操作并下载；仅在需要立即获取操作 ID 时将其设置为 false。
轮询 google-videos-retrieve-operation 直到 done=true。
调用 google-videos-retrieve-content 下载 .mp4 文件并接收 resource_link（或嵌入式 resource）。

fetch-images

从 URL 或本地文件路径获取并处理图像，支持可选的压缩。

参数（输入架构）：

sources（字符串数组，可选）：图像源数组，包括 HTTP(S) URL 或文件路径（绝对路径或相对于 MEDIA_GEN_DIRS 的第一个条目）。最少 1 个，最多 20 个图像。与 ids 和 n 互斥。
ids（字符串数组，可选）：要通过本地文件名匹配在 MEDIA_GEN_DIRS[0] 目录下获取的图像 ID 数组。ID 必须安全（仅包含 [A-Za-z0-9_-]，不包含 ..、*、?、斜杠）。匹配包含 _{id}_ 或 _{id}. 的文件名（支持单输出和多输出后缀，如 _1.png）。使用 ids 时，不支持 compression 和 file（不创建新文件）。与 sources 和 n 互斥。
n（整数，可选）：设置时，返回 MEDIA_GEN_DIRS[0] 目录中最后 N 个图像文件。文件按修改时间排序（最近修改的在前）。与 sources 和 ids 互斥。
compression（对象，可选）：
- max_size（整数，可选）：最大像素尺寸。大于此尺寸的图像将被调整大小。
- max_bytes（整数，可选）：目标最大文件大小（字节）。默认值：819200（800KB）。
- quality（整数，可选）：JPEG/WebP 质量，范围 1 - 100。默认值：85。
- format（可选值："jpeg" | "png" | "webp"）：输出格式。默认值：jpeg。
response_format（可选值："url" | "b64_json"，默认值："url"）：响应格式：基于文件/URL（url）或内联 Base64（b64_json）。
tool_result（可选值："resource_link" | "image"，默认值："resource_link"）：控制 content[] 的结构：
- "resource_link" 发出 ResourceLink 项（基于文件/URL）。
- "image" 发出 Base64 ImageContent 块。
file（字符串，可选）：输出文件的基本路径。若有多个图像，将添加索引后缀。

行为说明：

图像将并行处理以实现最大吞吐量。
仅当提供 compression 选项时才应用压缩。
压缩使用 sharp，启用时通过迭代降低质量和尺寸。
部分成功：若某些源失败，成功的图像仍将返回，错误信息将列在响应中。
当提供 n 时，仅当 MEDIA_GEN_MCP_ALLOW_FETCH_LAST_N_IMAGES 环境变量设置为 true 时才会生效。否则，调用将因验证错误而失败。
有时 MCP 客户端（如 ChargeGPT）可能因超时而不等待 media-gen-mcp 的响应。在需要快速检索最新 openai-images-generate / openai-images-edit 输出的创意环境中，可使用 fetch-images 并提供 n 参数。当 MEDIA_GEN_MCP_ALLOW_FETCH_LAST_N_IMAGES=true 环境变量设置时，即使 MCP 客户端侧的原始生成或编辑操作超时，fetch-images 仍将返回 MEDIA_GEN_DIRS[0] 中的最后 N 个文件。

fetch-videos

从 HTTP(S) URL 或本地文件路径获取视频。

参数（输入架构）：

sources（字符串数组，可选）：视频源数组，包括 HTTP(S) URL 或文件路径（绝对路径或相对于 MEDIA_GEN_DIRS 的第一个条目）。最少 1 个，最多 20 个视频。与 ids 和 n 互斥。
ids（字符串数组，可选）：要通过本地文件名匹配在 MEDIA_GEN_DIRS[0] 目录下获取的视频 ID 数组。ID 必须安全（仅包含 [A-Za-z0-9_-]，不包含 ..、*、?、斜杠）。匹配包含 _{id}_ 或 _{id}. 的文件名（支持单输出和多资产后缀，如 _thumbnail.webp）。使用 ids 时，不支持 file（不下载，返回现有文件）。与 sources 和 n 互斥。
n（整数，可选）：设置时，返回 MEDIA_GEN_DIRS[0] 目录中最后 N 个视频文件。文件按修改时间排序（最近修改的在前）。与 sources 和 ids 互斥。
tool_result（可选值："resource_link" | "resource"，默认值："resource_link"）：控制 content[] 的结构：
- "resource_link" 发出 ResourceLink 项（基于文件/URL）。
- "resource" 发出包含 Base64 resource.blob 的 EmbeddedResource 块。
file（字符串，可选）：输出文件的基本路径（从 URL 下载时使用）。若下载多个视频，将添加索引后缀。

输出：

content：每个解析的视频对应一个 resource_link（默认）或嵌入式 resource 块，以及一个可选的错误摘要文本块。
structuredContent：{ data: [{ source, uri, file, mimeType, name, downloaded }], errors?: string[] }。

行为说明：

仅当 URL 匹配 MEDIA_GEN_URLS（设置时）时才允许 URL 下载。
当提供 n 时，仅当 MEDIA_GEN_MCP_ALLOW_FETCH_LAST_N_VIDEOS 环境变量设置为 true 时才会生效。否则，调用将因验证错误而失败。

test-images

用于测试 MCP 结果放置的调试工具，无需调用 OpenAI API。

仅当 MEDIA_GEN_MCP_TEST_SAMPLE_DIR 设置时启用。该工具从该目录读取现有图像，不会创建新文件。

参数（输入架构）：

response_format（可选值："url" | "b64_json"，默认值："url"）
result_placement（可选值："content" | "api" | "structured" | "toplevel" 或这些值的数组）：覆盖本次调用的 MEDIA_GEN_MCP_RESULT_PLACEMENT。
compression（对象，可选）：与 fetch-images 具有相同的逻辑调整旋钮，但使用驼峰命名法：
- maxSize（整数，可选）：最大像素尺寸。
- maxBytes（整数，可选）：目标最大文件大小（字节）。
- quality（整数，可选）：JPEG/WebP 质量，范围 1 - 100。
- format（可选值："jpeg" | "png" | "webp"）：输出格式。
tool_result（可选值："resource_link" | "image"，默认值："resource_link"）：控制 content[] 的结构：
- "resource_link" 发出 ResourceLink 项（基于文件/URL）。
- "image" 发出 Base64 ImageContent 块。

行为说明：

从样本目录读取最多 10 张图像（不排序，按文件系统顺序）。
使用与 openai-images-generate 和 openai-images-edit 相同的结果构建逻辑（包括 result_placement 覆盖）。
当 output == "base64" 且提供 compression 时，使用 sharp 在内存中读取并压缩样本文件；磁盘上的原始文件不会被修改。
用于测试不同 MCP 客户端如何处理各种结果结构。
当 result_placement 包含 "api" 时，工具返回一个模拟的 OpenAI 图像 API 风格对象：
- 顶级字段：created、data[]、background、output_format、size、quality。
- 对于 response_format: "b64_json"，每个 data[i] 包含 b64_json。
- 对于 response_format: "url"，每个 data[i] 包含 url 而不是 b64_json。

`test-images` 的调试 CLI 辅助工具

对于本地调试，有两个辅助脚本可直接调用 test-images：

npm run test-images：使用 debug/debug-call.ts 并打印 MCP SDK 客户端看到的经过验证的 CallToolResult。用法：

npm run test-images -- [placement] [--response_format url|b64_json]
# 示例:
# npm run test-images -- structured --response_format b64_json
# npm run test-images -- structured --response_format url

npm run test-images:raw：使用 debug/debug-call-raw.ts 并打印原始的 JSON - RPC result（底层 CallToolResult，无额外包装）。CLI 标志与上述相同。

两个脚本都会截断大字段以提高可读性：

image_url：截断为前 80 个字符，然后显示 ...(N chars)。
b64_json 和 data（当为 Base64 字符串时）：截断为前 25 个字符，然后显示 ...(N chars)。

🧩 版本策略

语义版本控制（SemVer）

本软件包遵循 SemVer 规范：MAJOR.MINOR.PATCH（x.y.z）。

MAJOR：重大变更（工具名称、输入架构、输出结构）。
MINOR：新增工具或向后兼容的添加（新的可选参数、响应中的新字段）。
PATCH：错误修复和内部重构，无有意的行为变更。

自 1.0.0 版本起，本项目遵循 标准 SemVer 规则：重大变更会提升 MAJOR 版本（npm 的 ^1.0.0 允许 1.x 版本，但不允许 2.0.0 版本）。

依赖策略

本仓库力求与当前稳定版本保持紧密一致：

MCP SDK：目标是使用最新稳定的 @modelcontextprotocol/sdk 和架构。
OpenAI SDK：定期更新到最新稳定的 openai 软件包。
Zod：使用 Zod 4.x 系列（当前为 ^4.1.3）。在本项目中，之前使用 Zod 3.x 时，结合 MCP TypeScript SDK 类型定义，在将 .shape 传递给 inputSchema 时遇到严重的 TypeScript 错误，特别是 TS2589（"类型实例化过深，可能无限循环"）和 TS2322（"架构形状无法赋值给 AnySchema | ZodRawShapeCompat"）。我们跟踪上游讨论 modelcontextprotocol/typescript-sdk#494 以及相关的 Zod 类型定义工作 colinhacks/zod#5222，并确保堆栈组合能够可靠地通过 完全严格 的编译。
工具栈（Node.js、TypeScript 等）：针对最新的 LTS / 当前版本进行开发和测试，使用专门的 tsconfig-strict.json 启用所有严格的 TypeScript 检查（strict、noUnusedLocals、noUnusedParameters、exactOptionalPropertyTypes、noUncheckedIndexedAccess、noPropertyAccessFromIndexSignature 等）。

若你的环境需要，欢迎固定或降级 Node.js、TypeScript、OpenAI SDK、Zod 或其他堆栈组件，但请注意：

我们主要针对最新堆栈进行测试和调整。
仅在旧运行时 / SDK 版本上重现的问题可能较难调查和支持。
首先针对最新的 MCP 规范和 OpenAI 图像 API 验证上游兼容性。

本项目具有一定的 前瞻性：努力跟上 MCP 和 OpenAI 工具中出现的新功能（特别是 MCP 和 ChatGPT UI 中的强大多模态/图像支持）。在 参考资料 部分列出了一份关于 ChatGPT 中 MCP 图像渲染的详细实际案例报告和分析。

若你需要长期稳定的堆栈，请在自己的分支中固定精确版本，并在你的环境中仔细验证。

🧩 类型化工具回调

所有工具处理程序使用从 Zod 架构通过 z.input<typeof schema> 派生的强类型回调参数：

// 架构定义
const openaiImagesGenerateBaseSchema = z.object({
  prompt: z.string().max(32000),
  background: z.enum(["transparent", "opaque", "auto"]).optional(),
  // ... 更多字段
});

// 类型别名
type OpenAIImagesGenerateArgs = z.input<typeof openaiImagesGenerateBaseSchema>;

// 严格类型化的回调
server.registerTool(
  "openai-images-generate",
  { inputSchema: openaiImagesGenerateBaseSchema.shape, ... },
  async (args: OpenAIImagesGenerateArgs, _extra: unknown) => {
    const validated = openaiImagesGenerateSchema.parse(args);
    // ... 处理程序逻辑
  },
);

这种模式提供了：

静态类型安全：IDE 自动完成和编译时检查所有输入字段。
运行时验证：Zod .parse() 确保所有输入在处理前匹配架构。
MCP SDK 兼容性：inputSchema: schema.shape 为工具注册提供 JSON 架构。

所有工具（openai-images-*、openai-videos-*、fetch-images、fetch-videos、test-images）都遵循此模式。

🧩 工具注解

此 MCP 服务器通过注解提示公开以下工具： | 工具 | readOnlyHint | destructiveHint | idempotentHint | openWorldHint | |------|----------------|-------------------|------------------|-----------------| | openai-images-generate | true | false | false | true | | openai-images-edit | true | false | false | true | | openai-videos-create | true | false | false | true | | openai-videos-remix | true | false | false | true | | openai-videos-list | true | false | false | true | | openai-videos-retrieve | true | false | false | true | | openai-videos-delete | true | false | false | true | | openai-videos-retrieve-content | true | false | false | true | | fetch-images | true | false | false | false | | fetch-videos | true | false | false | false | | test-images | true | false | false | false |

这些提示帮助 MCP 客户端理解这些工具：

可能调用外部 API 或读取外部资源（开放世界）。
不会修改现有项目文件或用户数据；仅在配置的输出目录中创建新的媒体文件（图像/视频）。
即使输入相同，每次调用也可能产生不同的输出。

由于大多数工具的 readOnlyHint 设置为 true，MCP 平台（包括 chatgpt.com）可以将此服务器视为逻辑只读，通常不会显示 "此工具可以修改你的文件" 警告。

📁 项目结构

media-gen-mcp/
├── src/
│   ├── index.ts              # MCP 服务器入口点
│   └── lib/
│       ├── compression.ts    # 图像压缩（sharp）
│       ├── env.ts            # 环境解析 + 允许列表（+ glob 支持）
│       ├── helpers.ts        # URL/路径验证、结果构建
│       ├── logger.ts         # 结构化日志记录 + 截断辅助函数
│       └── schemas.ts        # 所有工具的 Zod 架构
├── test/
│   ├── compression.test.ts             # 12 个测试用例
│   ├── env.test.ts                     # 19 个测试用例
│   ├── fetch-images.integration.test.ts# 2 个测试用例
│   ├── fetch-videos.integration.test.ts# 2 个测试用例
│   ├── helpers.test.ts                 # 31 个测试用例
│   ├── logger.test.ts                  # 10 个测试用例
│   └── schemas.test.ts                 # 64 个测试用例
├── debug/                    # 本地调试辅助工具（MCP 客户端脚本）
├── plan/                     # 设计笔记 / 计划
├── dist/                     # 编译输出
├── tsconfig.json
├── vitest.config.ts
├── package.json
├── CHANGELOG.md
├── README.md
└── AGENTS.md

📝 许可证

本项目采用 MIT 许可证。

🩺 故障排除

确保你的 OPENAI_API_KEY 有效且具有图像 API 访问权限。
你必须拥有一个经过验证的 OpenAI 组织。验证后，图像 API 访问权限可能需要 15 - 20 分钟才能激活。
文件路径 [可选参数] 必须为绝对路径：
- Unix/macOS/Linux：以 / 开头（例如 /path/to/image.png）。
- Windows：以驱动器号后跟 : 开头（例如 C:/path/to/image.png 或 C:\path\to\image.png）。
对于文件输出，确保目标目录可写。
若遇到文件类型错误，请检查你的图像文件扩展名和格式。

🙏 灵感来源

本服务器最初受 SureScaleAI/openai-gpt-image-mcp 启发，但现在是一个独立实现，专注于 紧密跟踪官方规范：

与 OpenAI 图像 API 对齐：openai-images-generate 和 openai-images-edit 的参数与 images.create / gpt-image-1.5 一致：prompt、n、size、quality、background、output_format、output_compression、user，以及与 OpenAI 图像 API 语义相同的 response_format（url / b64_json）。
与 MCP 工具结果对齐（图像 + resource_link）：当 result_placement = "content" 时，服务器遵循 MCP 5.2 工具结果 部分（5.2.2 图像内容、5.2.4 资源链接），发出强类型的 content[] 项：
- 当 response_format = "b64_json" 时，`{ "type": "image

media-gen-mcp

README

🚀 media-gen-mcp

🚀 快速开始

fast-agent

Windsurf

✨ 主要特性

📦 安装指南

开发模式（无需构建）

质量检查

单元测试

直接通过 npx 运行（无需本地克隆）

secrets.yaml（可选）

🔧 技术细节

配置

日志记录与 Base64 截断

安全与本地文件访问

Glob 模式

推荐的缓解措施

工具结果参数：tool_result 和 response_format

tool_result — 控制 content[]

response_format — 控制 structuredContent

向后兼容性（MCP 5.2.6）

通过 mcp - proxy 进行网络访问（SSE）

💻 使用示例

openai-images-generate

openai-images-edit

🛠 工具签名

openai-images-generate

openai-images-edit

openai-videos-create

openai-videos-remix

openai-videos-list

openai-videos-retrieve

openai-videos-delete

openai-videos-retrieve-content

google-videos-generate

google-videos-retrieve-operation

google-videos-retrieve-content

fetch-images

fetch-videos

test-images

test-images 的调试 CLI 辅助工具

🧩 版本策略

语义版本控制（SemVer）

依赖策略

🧩 类型化工具回调

🧩 工具注解

📁 项目结构

📝 许可证

🩺 故障排除

🙏 灵感来源

运行方式说明

托管运行

本地运行 / 其它方式

`secrets.yaml`（可选）

工具结果参数：`tool_result` 和 `response_format`

`tool_result` — 控制 `content[]`

`response_format` — 控制 `structuredContent`

`test-images` 的调试 CLI 辅助工具