Media Gen MCP

🚀 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 圖像的 create API，支持 gpt-image-1.5（未來版本計劃支持 gpt-image-1 及 DALL·E），可處理背景、審核、尺寸、質量、輸出格式、輸出壓縮、生成數量、用戶標識等參數。
  • 模擬 OpenAI 圖像的 createEdit API，支持 gpt-image-1.5（未來版本計劃支持 gpt-image-1），可處理圖像、遮罩、生成數量、質量、尺寸、用戶標識等參數。
• OpenAI 視頻（Sora）作業工具（創建 / 混音 / 列表 / 檢索 / 刪除 / 內容獲取）：
  • 模擬 videos/create，可選擇等待作業完成。
  • 模擬 videos/remix。
  • 模擬 videos/list。
  • 模擬 videos/retrieve。
  • 模擬 videos/delete。
  • 模擬 videos/content，可將 video / thumbnail / spritesheet 資源下載到磁盤，並返回 MCP resource_link（默認）或嵌入式 resource 塊（通過 tool_result）。
• Google GenAI（Veo）操作與下載（生成 / 檢索操作 / 檢索內容）：
  • 啟動一個長時間運行的操作（ai.models.generateVideos），可選擇等待操作完成並下載 .mp4 輸出文件。Veo 模型參考
  • 輪詢現有操作。
  • 從已完成的操作中下載 .mp4 文件，並返回 MCP resource_link（默認）或嵌入式 resource 塊（通過 tool_result）。
• 從 URL 或文件獲取並處理圖像： 工具可從 HTTP(S) URL 或本地文件路徑加載圖像，並支持可選的用戶控制壓縮（默認禁用），最多可並行處理 20 張圖像。
• 從 URL 或文件獲取視頻： 工具可列出本地視頻或從遠程視頻 URL 下載視頻到磁盤，並返回 MCP resource_link（默認）或嵌入式 resource 塊（通過 tool_result）。
• 混合與編輯多達 16 張圖像： 支持將 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 工具： 從配置目錄讀取示例圖像，並使用與生產工具相同的結果構建邏輯返回圖像。可使用 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/**）會暴露整個子樹，並在啟動時觸發控制檯警告。

推薦的緩解措施

1. 使用專用的操作系統用戶運行服務器，該用戶僅可訪問允許的目錄。
2. 儘量減少允許列表的範圍，避免在主目錄或系統路徑中使用 *。
3. 為遠程獲取操作使用明確的 MEDIA_GEN_URLS 前綴。
4. 通過操作系統訪問控制列表（ACL）或備份監控允許的目錄。

工具結果參數：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"）

推薦工作流程：

1. 調用 google-videos-generate 並設置 wait_for_completion=true（默認）以獲取完成的操作並下載；僅在需要立即獲取操作 ID 時將其設置為 false。
2. 輪詢 google-videos-retrieve-operation 直到 done=true。
3. 調用 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