OpenAI Image

@mindstone/mcp-server-openai-image

OpenAI 画像生成 MCP サーバー — OpenAI の gpt-image-2 を使ったテキストからの画像生成と画像編集に対応し、鮮明なテキスト描画、多言語プロンプト、4 段階の品質、3 種類のアスペクト比を備えています。

ワークスペース内に制限された OpenAI 画像 MCP です。生成された PNG は MCP_WORKSPACE_PATH の配下にのみ保存され、すべてのエラーは構造化された復旧コードを返します。また、API キーは api.openai.com に厳格に固定されています。

ステータス

• バージョン： 0.3.2 · npm
• 認証： API キー（OPENAI_API_KEY）
• ツール： 2（画像生成、画像編集）
• 提供形態： クラウド API
• 機械可読情報： STATUS.json

このプロジェクトの目的

2026 年初頭にこのコネクターの開発を始めた時点では、OpenAI は画像生成機能向けの MCP サーバーを公開していませんでした。また、利用可能なコミュニティ製の選択肢は、独自のダウンロードデーモンを組み込むか、ホスト上の制限のないパスに生成データを書き込むものでした。そこで、リポジトリの他の部分で適用しているものと同じサンドボックス化、復旧契約、キー取り扱いの保証のもとで、MCP ホストから generate_image と edit_image を呼び出せるよう、独自のサーバーを作成しました。保存される PNG は realpath によって境界を制限したワークスペース配下に置かれ、すべてのエラーは構造化された { ok, code, error, resolution } オブジェクトとして返されます。また、OpenAI API キーは https://api.openai.com に厳格に固定されているため、攻撃者が制御する環境によって、プロンプト、画像データ、ベアラートークンが別の場所にリダイレクトされることはありません。

やり取りの例

「ベルギー産のドラフトホースが醸造所の荷車を引く、柔らかな朝の光に包まれた 1024x1536 のポートレートを生成してください。」

ホストが呼び出すツール：

1. generate_image — size: portrait、quality: high、count: 1 を指定してプロンプトを送信します。

レスポンス（一部省略）：

{
  "ok": true,
  "saved_paths": [
    "/Users/me/workspace/Chief-of-Staff/generated-images/20260519-1530-a1b2c3.png"
  ],
  "model": "gpt-image-2",
  "size": "1024x1536",
  "quality": "high"
}

失敗した場合：

{
  "ok": false,
  "code": "WORKSPACE_FENCE_VIOLATION",
  "error": "Reference image is outside your workspace and folders linked as Spaces. Path: <workspace>/linked.png. Workspace: /Users/me/workspace.",
  "resolution": "Move or copy the file into your workspace or a folder linked as a Space, then try again."
}

必要条件

• Node.js 20.3+
• npm
• 画像生成アクセス権のある OpenAI API キー

ワンクリックインストール

ボタンをクリックすると、ホストから OPENAI_API_KEY、OPENAI_IMAGE_MODEL、OPENAI_IMAGE_REQUEST_TIMEOUT_MS の入力を求められます。

{
  "mcpServers": {
    "OpenAI Image": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-openai-image"
      ],
      "env": {
        "OPENAI_API_KEY": "",
        "OPENAI_IMAGE_MODEL": "gpt-image-2",
        "OPENAI_IMAGE_REQUEST_TIMEOUT_MS": "180000"
      }
    }
  }
}

クイックスタート

インストールとビルド

cd <path-to-repo>/connectors/openai-image
npm install
npm run build

npx（公開後）

npx -y @mindstone/mcp-server-openai-image

ローカル

node dist/index.js

設定

環境変数

• OPENAI_API_KEY — OpenAI API キーです。ツール呼び出しに必須です。設定されていない場合、サーバーは未設定モードで起動し、各ツール呼び出しはクラッシュする代わりに、構造化された NOT_CONFIGURED レスポンスを返します。
• MCP_WORKSPACE_PATH — 任意のワークスペースパスです。生成された画像は <workspace>/Chief-of-Staff/generated-images/ の下に保存されます。未設定の場合は ~/Pictures/MCP-Generated-Images/ がデフォルトになります。
• OPENAI_IMAGE_MODEL — 任意のモデルの上書き指定です。デフォルトは gpt-image-2 です。
• OPENAI_IMAGE_REQUEST_TIMEOUT_MS — OpenAI 画像 API のタイムアウトを上書きする任意の設定です（正の整数ミリ秒、最大 30 分）。デフォルトは 180000（3 分）です。OpenAI のドキュメントによると、複雑なプロンプトでは最大約 2 分かかる quality: 'high' の生成に合わせた値です。より厳密な時間制限が必要な場合は、値を小さくしてください。
• MCP_ALLOWED_SYMLINK_ROOTS — 絶対パスの任意の JSON 配列です。コネクターは、正規化後のリンク先が MCP_WORKSPACE_PATH またはここで宣言したルート（ホストの組み込みファイルツールが、宣言済みの Spaces に対して信頼するルートと同じです）のいずれかに含まれる、ワークスペース内のシンボリックリンクを介して読み取り（および生成画像の書き込み）を行います。フェイルクローズ方式です。この値が未指定、空、JSON の形式が不正、配列ではない、またはいずれかのエントリが文字列以外／空／相対パスの場合、値全体を拒否し、コネクターは厳格なワークスペース内限定の制約にフォールバックして、構造化された警告を stderr に 1 件出力します。スタンドアロンの OSS ユーザーは省略してください。Rebel のホストでは、宣言した Spaces から自動的に設定されます。
• MCP_HTTP_PORT — 任意です。設定すると、サーバーは stdio の代わりに、このポートで 127.0.0.1 にバインドして HTTP 経由で MCP を使用します（ループバックのみ。ループバック以外の Host ヘッダーは拒否されます）。ホスト管理のローカルデプロイを想定しています。stdio を使用するホストでは省略してください。

ホスト設定の例

Claude Desktop / Cursor

{
  "mcpServers": {
    "OpenAIImage": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-openai-image"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

Mindstone Rebel

Rebel のコネクタ選択画面でカタログの項目を使用してください。Rebel は、設定済みのプロバイダーキーから OPENAI_API_KEY を注入し、アクティブなワークスペースを MCP_WORKSPACE_PATH に設定します。

ローカル開発（npm への公開は不要）

{
  "mcpServers": {
    "OpenAIImage": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/openai-image/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MCP_WORKSPACE_PATH": "/absolute/path/to/workspace"
      }
    }
  }
}

ツール（2）

generate_image

入力：

• prompt（文字列、必須）— 生成する画像のテキストによる説明です。
• size（square | portrait | landscape、任意）— 1024x1024、1024x1536、1536x1024。
• quality（low | medium | high | auto、任意）— デフォルトは high です。medium は通常約 50 秒、$0.04 です。high は最大 3 分かかり、約 $0.21 です。低い品質ではコストが大幅に下がります。
• count（整数 1～8、任意）— デフォルトは 1 です。コストは枚数に比例して増加します。
• moderation（auto | low、任意）— コンテンツモデレーションの厳格さです。デフォルトは auto です。low にすると、アカウントの OpenAI コンテンツフィルタリングが緩和され、ほかのツール入力と同様にそのまま渡されます。呼び出しの制御はホストのツール承認レイヤーが担います。
• output_format（png | jpeg | webp、任意）— 出力ファイル形式です。デフォルトは png です。保存されるファイルの拡張子とインラインプレビューの MIME タイプは、選択した形式（.png / .jpg / .webp）に従います。
• output_compression（整数 0～100、任意）— 圧縮レベルです。jpeg または webp 出力の場合のみ有効です。png と組み合わせると、API 呼び出し前に構造化された INVALID_INPUT エラーを返して即座に失敗します。
• background（transparent | opaque | auto、任意）— 背景のスタイルです。transparent はアルファチャンネル付きの切り抜きを生成するため、出力形式に png / webp を指定し、透明背景に対応したモデルを使用する必要があります。gpt-image-2 は上流で透明背景を拒否するため、ツールは構造化された INVALID_INPUT エラーを返して即座に失敗し、OPENAI_IMAGE_MODEL=gpt-image-1.5（または gpt-image-1）を指定するよう案内します。不明なモデルの上書き指定は上流の検証に渡されます。これは、既存の OPENAI_IMAGE_MODEL の方針と一致しています。

保存先パスと、最大 5 件のインライン image コンテンツブロックを含むテキストコンテンツブロックを返します。失敗時は、構造化された { ok: false, code, error, resolution } レスポンスを返します。このツールには destructiveHint: true, openWorldHint: true, idempotentHint: false の注釈が付いています。

edit_image

入力：

• prompt（文字列、必須） — 入力画像の何を変更するかを指定します。
• image_paths（絶対ファイルパスの配列、1〜4 件、必須） — 元画像です。各パスは検証されます。パスは字句的に MCP_WORKSPACE_PATH 内を指し、正規の realpath が正規化されたワークスペース内 または MCP_ALLOWED_SYMLINK_ROOTS で宣言されたルートのいずれかに収まる必要があります（ホストに組み込まれたファイルツールの包含判定に準拠）。どちらの範囲にも収まらないパスは、読み取りを行う前に WORKSPACE_FENCE_VIOLATION で拒否されます。
• mask_path（PNG パス、省略可能） — 編集する領域を示すアルファチャンネルマスクです。
• size、quality、count、moderation、output_format、output_compression、background — generate_image と同じ形式です。

generate_image と同じコンテンツ形式を返します。destructiveHint／openWorldHint／idempotentHint の注釈も同じです。

復旧に関する契約

すべてのツールエラーは、次のフィールドを含む構造化 JSON として返されます。

{
  "ok": false,
  "code": "NOT_CONFIGURED | INVALID_API_KEY | RATE_LIMITED | CONTENT_POLICY | WORKSPACE_FENCE_VIOLATION | MODEL_UNAVAILABLE | NETWORK_ERROR | TIMEOUT | WRITE_FAILED | INVALID_INPUT | INVALID_IMAGE_DATA",
  "error": "Human-readable message",
  "resolution": "Concrete next step for the operator"
}

この構造化された形式により、エージェント型ホストは未加工の例外テキストを表示する代わりに、復旧フローへ振り分けることができます。

セキュリティに関する注意

• ローカルファイルを指定するツール入力（edit_image.image_paths、edit_image.mask_path）は、読み取りの前に二段階のフェンスを通過します。まず、ワークスペースの字句的な事前ゲート（パスが字句的に MCP_WORKSPACE_PATH 内に解決されること）、次に、正規化された包含ゲート（パスの realpath が正規化されたワークスペース または MCP_ALLOWED_SYMLINK_ROOTS で宣言されたルートのいずれかに含まれること）です。判定には path.relative のセグメント単位の意味論を使用し、startsWith は決して使用しません。どちらの範囲外にあるパスも、シンボリックリンクによる脱出やパストラバーサルを防ぐため、WORKSPACE_FENCE_VIOLATION で拒否されます。生成画像の出力ディレクトリにも、ホスト組み込みの Write ツールと同様に、書き込み前に同じ包含判定が適用されます。
• 読み取りは、開いてから検証します。フェンスの判定は、開いた inode にひも付けられます。フェンスが正規化されたパスを承認した後、コネクターはファイル記述子を開き、fstat で開いた inode が基準となる stat と一致することを確認します。続いて、開いた後に正規化されたパスを再解決し（フェンスが承認したパスとバイト単位で一致することを必須とします）、さらに lstat でそのパスが引き続き固定された inode を指していることを確認します。2 回の確認の間にリーフがシンボリックリンクへ切り替わって戻る場合も、たどらずに検出されます。Linux ではその後、記述子自体を /proc/self/fd/<fd> 経由で解決します（これは固定された inode のカーネルによる正規パスであり、パス名の競合状態の影響を受けません）。そして、そのパスにも包含判定を再適用します。読み取りは固定された記述子を介して行われるため、どの時点でパスが切り替わっても、フェイルクローズで WORKSPACE_FENCE_VIOLATION になります。プラットフォームに関する注意： macOS／Windows（/proc がなく、Node も openat／F_GETPATH を公開していません）では、限定的なリスクが残ります。ローカルの攻撃者が、開いた後のパス再解決と識別確認の間に、ワークスペース内の ディレクトリ コンポーネントをアトミックに切り替えると、その確認を別の場所へ誘導できる可能性があります。これは対象ファイルがワークスペースとは異なるファイルシステム上にある場合に限って現実的です（そうでなければ、通常のハードリンクだけで競合状態なしにフェンスを回避できます。これはすべての OS において、正規化されたプレフィックスによる包含判定に既存の制約があるためです）。失敗した試行はすべて、フェンス違反エラーとして明示されます。Linux では、この種の問題は完全に解消されています。
• 書き込みでは、検証済みのパス名を再び信頼することはありません。フェンスが出力ディレクトリの正規化されたパスを承認した後（mkdir によって作成されたディレクトリを含め、全体を再確認します）、正規化されたディレクトリ内に新規かつ予測不能な mkdtemp ディレクトリをアトミックに作成し（モード 0700）、そこにバイト列を一時保存します。このディレクトリにはシンボリックリンクのコンポーネントが含まれないため、パスコンポーネントを確認と使用の間にシンボリックリンクへ切り替えても、書き込み先を誘導できません。ファイルは wx（モード 0600）で開き、単一の記述子を介して書き込んだ後、ハードリンクで配置します（実ファイルまたは仕掛けられたシンボリックリンクのいずれかによって配置先の名前が使用済みの場合、link は EEXIST で失敗します。ハードリンクに対応していないファイルシステムでは、配置先に対する排他的な作成にフォールバックします）。ディレクトリの正規化された識別情報は、バイト列が流れる前に再検証します。具体的には、一時保存への書き込みの直前、ハードリンクの直前と直後、そしてフォールバック時の排他的な作成の直前と直後です。処理の途中で切り替わりが発生した場合は、フェイルクローズで WORKSPACE_FENCE_VIOLATION となり、一時保存用ディレクトリは削除されます。
• フェンスエラーに含めるのは、モデルが指定した入力パスとワークスペースのルートだけです。シンボリックリンク先の正規化された realpath は含めません。これにより、リンク先の Space を漏らすことなく、エージェントが入力を修正できます。エラーにエコーバックされる呼び出し元が制御する値（ツール入力のパス、設定されたモデル）は、終了タグの突破をエスケープしたうえで <untrusted-content source="…"> で囲まれます（src/untrusted-content.ts を参照）。そのため、細工された値によって結果のエンベロープが閉じられることはありません。
• 上流の成功ペイロードはスキーマ検証されます（不正な形式の本文はフェイルクローズで NETWORK_ERROR になります）。また、返される画像バイト列には、要求された形式のマジックバイトが含まれていなければなりません。形式が一致しないペイロードは、誤った拡張子／MIME タイプで保存するのではなく、INVALID_IMAGE_DATA で拒否されます。上流のエラー本文とステータステキストは分類にのみ使用され、モデルから見えるエラーには含まれません。
• 生成ファイルはモード 0o600 で書き込まれます。
• OPENAI_API_KEY の値は、ログ、構造化エラーペイロード、スタックトレースから秘匿されます。src/index.ts の sanitizeUserFacingText を参照してください。
• プロンプトと絶対ファイルパスは、デフォルトでログ出力から秘匿されます。記録されるのはメタデータ（件数、サイズ、処理時間、ステータスコード）のみです。
• OpenAI API のベース URL は https://api.openai.com に固定されており、環境変数による上書きはできません。

レガシーフォルダーの移行

以前、ワークスペース内で RebelImages/ という名前のフォルダーを使用していたホストでは、初回実行時にシンボリックリンクを安全に扱う一度限りの名前変更が行われ、MCP-Generated-Images/ に移行されます。この移行は冪等で、移行先がすでに存在する場合はスキップされます。どちらかのパスにシンボリックリンクがある場合、名前変更は中止されます。この移行は既存のユーザーファイルを保持するためだけに行われます。新規インストールでは、最初から MCP-Generated-Images/ が使用されます。

ライセンス

FSL-1.1-MIT — Functional Source License バージョン 1.1。MIT ライセンスへの将来的な移行が定められています。このソフトウェアは 2030-04-08 に MIT ライセンスへ移行します。