Mcp Image Server

MCP Image Server

AI（GPT Image 1）を使用してカスタム画像やアイコンを生成する、TypeScript ベースの MCP サーバーです。.png、.svg、.ico などの出力形式に対応しています。Vibe Coding とのシームレスな統合を想定して設計されており、プロジェクト用のビジュアルアセットを必要なときに生成できます。クロスプラットフォームに対応し、npx で実行できます。

特長

• GPT Image 1（OpenAI）を使用したカスタム画像の生成
• .png、.svg（画像を base64 で埋め込み）、.ico（実際に変換）形式でファイルを提供
• 画像サイズを設定可能：1024×1024（正方形）、1536×1024（横長）、1024×1536（縦長）
• 背景を制御可能：「transparent」または「opaque」
• 高速生成のため、品質を「low」、モデレーションを「low」に設定
• 使用例を含む MCP ツールのドキュメントをリソースから参照可能
• 対応形式を照会するためのリソース
• MCP クライアント、エージェント、Vibe Coding のワークフローとの統合に対応
• クロスプラットフォーム（Windows/Linux/Mac）に対応し、npx ですぐに実行可能

プロジェクト構成

• src/index.ts：MCP サーバー、ツール、リソースの主な実装
• package.json：プロジェクトの設定、依存関係、クロスプラットフォーム用スクリプト
• README.md：このドキュメント
• test-mcp-client.js：MCP クライアント統合テストスクリプト
• tsconfig.json：TypeScript の設定
• sample_config.json：MCP クライアント設定の例

このサーバーを使用するための MCP クライアントの設定方法

MCP サーバーの設定ファイルに次の設定を追加してください（sample_config.json の例）：

{
    "servers": {
        "mcp-image-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@ricardopera/mcp-image-server@latest"
            ],
            "env": {
                "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
            }
        }
    }
}

これにより、事前にインストールすることなく、npx から画像サーバーを直接実行できます。また、OpenAI 認証に必要な環境変数も設定されます。

ローカルでの実行方法

1. 依存関係をインストールします：

   npm install
   

2. プロジェクトをビルドします：

   npm run build
   

3. OPENAI_API_KEY 環境変数に OpenAI キーを設定します：

   • Windows（PowerShell）の場合：

     $env:OPENAI_API_KEY="your-key-here"
     

   • Linux/Mac の場合：

     export OPENAI_API_KEY="your-key-here"
     

4. npx で実行します：

   npx mcp-image-server
   

MCP.so への登録方法

1. プロジェクトがビルド、テスト、ドキュメント化されていることを確認します
2. https://mcp.so/ に記載されている登録手順に従います

進捗とドキュメント

• 初期プロジェクト構成
• MCP サーバーの実装
• GPT Image 1 の実際の統合
• .png、.svg、.ico 形式のファイル変換と提供
• MCP ツールのドキュメント化と注釈付け
• 使用例のリソース（resource://tool-examples）
• 対応形式のリソース（formats://supported）
• MCP クライアントとの統合テスト
• 自動テストとエッジケースの検証
• 最終的な詳細ドキュメント（使用例、トラブルシューティング）

---

ビジュアル例

以下は、MCP Image Server のツールで生成した実際の画像の例です。すべての画像は、ツールの fileName パラメーターと directory パラメーターを使用して、examples/ フォルダーに自動保存されました。

例 1：ミニマルなロケットアイコン（PNG）

使用したプロンプト：

{
  "prompt": "minimalist rocket icon transparent background",
  "format": "png",
  "size": "1024x1024",
  "background": "transparent",
  "fileName": "rocket-icon",
  "directory": "examples"
}

結果：

---

例 2：文字 A の入った青い円形ロゴ（SVG）

使用したプロンプト：

{
  "prompt": "blue circular logo with letter A",
  "format": "svg",
  "size": "1536x1024",
  "background": "transparent",
  "fileName": "blue-logo-letter-a",
  "directory": "examples"
}

結果：

---

例 3：金色の星のアイコン（ICO）

使用したプロンプト：

{
  "prompt": "golden star icon",
  "format": "ico",
  "size": "1024x1024",
  "background": "opaque",
  "fileName": "golden-star",
  "directory": "examples"
}

結果：

---

例 4：黄色い星のファビコン（ICO）

使用したプロンプト：

{
  "prompt": "yellow star favicon transparent background",
  "size": "1024x1024",
  "background": "transparent",
  "fileName": "yellow-star-favicon",
  "directory": "examples"
}

結果：

---

例 5：赤いハートのアイコン（SVG）

使用したプロンプト：

{
  "prompt": "red heart icon",
  "size": "1024x1536",
  "background": "opaque",
  "fileName": "red-heart-icon",
  "directory": "examples"
}

結果：

---

これらの例は、サーバーがさまざまな形式やディレクトリにカスタム画像を生成・保存できる柔軟性を示しています。これにより、Web プロジェクト、アプリケーション、さまざまなシステムへの統合が容易になります。

利用可能なツール

generate-image

AI（GPT Image 1）を使用してカスタム画像を生成し、指定された形式で出力します。

パラメーター：

• prompt (string)：希望する画像のテキストによる説明
• format ("png" | "svg" | "ico)：出力形式（デフォルト："png"）
• size ("1024x1024" | "1536x1024" | "1024x1536")：画像サイズ（デフォルト："1024x1024"）
• background ("transparent" | "opaque")：背景の種類（デフォルト："transparent"）

例：

{
  "prompt": "minimalist rocket icon transparent background",
  "format": "png",
  "size": "1024x1024",
  "background": "transparent"
}

{
  "prompt": "blue circular logo with letter A",
  "format": "svg",
  "size": "1536x1024",
  "background": "transparent"
}

{
  "prompt": "golden star icon",
  "format": "ico",
  "size": "1024x1024",
  "background": "opaque"
}

generate-favicon

テキストプロンプトからカスタムの favicon.ico を生成します。

パラメーター：

• prompt (string)：ファビコンのテキストによる説明
• size ("1024x1024" | "1536x1024" | "1024x1536")：画像サイズ（デフォルト："1024x1024"）
• background ("transparent" | "opaque")：背景の種類（デフォルト："transparent"）

例：

{
  "prompt": "yellow star favicon transparent background",
  "size": "1024x1024",
  "background": "transparent"
}

generate-svg（一時的に利用できません）

⚠️ SVG 生成ツールは、SVG コンテンツをテキストとして処理する際の技術的な問題により、一時的に無効になっています。SVG を画像ファイルとしてのみ扱えることが保証され次第、今後のバージョンで再び有効にする予定です。

それまでは、画像の生成には PNG または ICO 形式をご利用ください。

リソース

• resource://tool-examples：JSON 形式のツール使用例
• formats://supported：サポートされている形式の一覧（["png", "svg", "ico"]）

環境変数

• OPENAI_API_KEY：OpenAI API キー（画像生成に必須）

トラブルシューティング

• OPENAI_API_KEY が定義されていない、または無効というエラー：実行前に環境変数を正しく設定してください。
• GPT Image 1 画像の生成エラー：API キー、接続、および OpenAI の利用制限を確認してください。
• Windows での権限の問題：このプロジェクトはクロスプラットフォームですが、権限エラーが発生した場合は、ターミナルを管理者として実行してください。

---

MCP エージェントのベストプラクティスに従って開発されており、MCP.so への統合と公開に対応しています。

---

高度な画像生成の例

以下は、このプロジェクトのツールの柔軟性と性能を示す追加の例です。すべての画像は生成後、自動的に examples/ フォルダーに保存されます。

例 6：親しみやすいロボットのアバター（PNG）

使用したプロンプト：

{
  "prompt": "friendly robot avatar, white background, cartoon style, soft colors",
  "format": "png",
  "size": "1024x1024",
  "background": "opaque",
  "fileName": "friendly-robot-avatar",
  "directory": "examples"
}

結果：

---

例 7：山のある未来的な風景（PNG）

使用したプロンプト：

{
  "prompt": "futuristic landscape with mountains and starry sky, digital art, transparent background",
  "format": "png",
  "size": "1536x1024",
  "background": "transparent",
  "fileName": "futuristic-landscape",
  "directory": "examples"
}

結果：

---

これらの高度な例から、MCP Image Server を使って、ミニマルなアイコンから複雑なイラストまで、ウェブ、モバイル、デスクトップアプリケーションですぐに使える画像を生成できることがわかります。

ツールのドキュメント

generate-image

AI（GPT Image 1）を使用してカスタム画像を生成し、指定された形式で保存します。

必須パラメーター：

• prompt (string)：希望する画像のテキストによる説明
• format ("png" | "svg" | "ico")：出力形式（デフォルト："png"）
• size ("1024x1024" | "1536x1024" | "1024x1536")：画像サイズ（デフォルト："1024x1024"）
• background ("transparent" | "opaque")：背景の種類（デフォルト："transparent"）
• fileName (string)：保存するファイルの名前（拡張子なし）
• directory (string)：ファイルを保存するディレクトリのフルパス（オペレーティングシステムに応じた形式で指定する必要があります。例：Windows では C:\Users\user\project\folder、Linux/Mac では /home/user/project/folder）

重要： ファイルが正しく保存されるよう、directory パラメーターには必ずフルパスを指定してください。パスは、サーバーが実行されているオペレーティングシステムの形式にする必要があります。

使用例（Windows）：

{
  "prompt": "minimalist rocket icon transparent background",
  "format": "png",
  "size": "1024x1024",
  "background": "transparent",
  "fileName": "rocket-icon",
  "directory": "c:\\Users\\ricar\\Desktop\\projetos\\mcp-image-server\\examples"
}

使用例（Linux/Mac）：

{
  "prompt": "minimalist rocket icon transparent background",
  "format": "png",
  "size": "1024x1024",
  "background": "transparent",
  "fileName": "rocket-icon",
  "directory": "/home/user/projects/mcp-image-server/examples"
}

generate-favicon

テキストプロンプトからカスタム favicon.ico を生成します。

必須パラメーター：

• prompt（string）：favicon のテキストによる説明
• size（"1024x1024" | "1536x1024" | "1024x1536"）：画像サイズ（デフォルト："1024x1024"）
• background（"transparent" | "opaque"）：背景の種類（デフォルト："transparent"）
• fileName（string）：保存するファイル名（拡張子を除く）
• directory（string）：ファイルを保存するディレクトリのフルパス（オペレーティングシステムの形式）

使用例（Windows）：

{
  "prompt": "yellow star favicon transparent background",
  "size": "1024x1024",
  "background": "transparent",
  "fileName": "yellow-star-favicon",
  "directory": "c:\\Users\\ricar\\Desktop\\projetos\\mcp-image-server\\examples"
}

generate-svg

AI 画像を埋め込んだ（base64）SVG ファイルを生成します。

必須パラメーター：

• prompt（string）：希望する画像のテキストによる説明
• size（"1024x1024" | "1536x1024" | "1024x1536"）：画像サイズ（デフォルト："1024x1024"）
• background（"transparent" | "opaque"）：背景の種類（デフォルト："transparent"）
• fileName（string）：保存するファイル名（拡張子を除く）
• directory（string）：ファイルを保存するディレクトリのフルパス（オペレーティングシステムの形式）

使用例（Linux/Mac）：

{
  "prompt": "red heart icon",
  "size": "1024x1536",
  "background": "opaque",
  "fileName": "red-heart-icon",
  "directory": "/home/user/projects/mcp-image-server/examples"
}

より実用的な JSON の例については、リソース resource://tool-examples を参照してください。

---

MCP ツールの実装とドキュメント化

MCP（Model Context Protocol）ツールは、モデルやエージェントが正しく検出、理解、使用できるよう、定義とドキュメント化に関する国際標準に準拠する必要があります。ベストプラクティスと実際の例を以下に示します。

MCP ツール定義の構造

{
  name: string;          // Unique identifier of the tool
  description?: string;  // Human-readable description
  inputSchema: {         // JSON Schema of the tool parameters
    type: "object",
    properties: { ... }  // Specific tool parameters
  }
}

• name：ツールの一意な名前（例："generate-image"）
• description：ツールの機能を明確に説明します
• inputSchema：必須および任意のパラメーター、型、説明を定義します

実用例（TypeScript）

server.registerTool(
  "generate-image",
  {
    title: "Generate Image with GPT Image 1",
    description: "Generates a custom image using AI (GPT Image 1) and delivers it in the requested format (.png, .svg, .ico).",
    inputSchema: {
      prompt: z.string().describe("Textual prompt describing the desired image"),
      format: z.enum(["png", "svg", "ico"]).default("png").describe("Output format of the image"),
      size: z.enum(["1024x1024", "1536x1024", "1024x1536"]).default("1024x1024").describe("Image size"),
      background: z.enum(["transparent", "opaque"]).default("transparent").describe("Background type"),
      fileName: z.string().default("image").describe("Name of the file to be saved (without extension)"),
      directory: z.string().default("./output").describe("Directory where the file will be saved")
    },
    annotations: {
      usage: "Use this tool to generate custom images and icons for your project. The prompt should be detailed for better results. The format defines the extension of the generated file."
    }
  },
  async ({ prompt, format, size, background, fileName, directory }) => { /* ... */ }
);

ツールのドキュメント化に関するベストプラクティス

• 常に明確で客観的な説明を含めます
• 型や例を含む、すべての inputSchema パラメーターをドキュメント化します
• 各ツールの JSON 使用例を提示します
• 使用上のヒントやコンテキストには annotations.usage フィールドを使用します
• 堅牢なエラー処理を実装し、必要に応じてわかりやすいメッセージと isError フィールドを返します

エラー処理の例

try {
  // Tool operation
  const result = performOperation();
  return {
    content: [
      { type: "text", text: `Operation successful: ${result}` }
    ]
  };
} catch (error) {
  return {
    isError: true,
    content: [
      { type: "text", text: `Error: ${error.message}` }
    ]
  };
}

モデルによる自動検出と使用

この標準に従うことで、あらゆる MCP モデルまたはエージェントが利用可能なツールを一覧表示し、そのスキーマと説明を読み取り、自動的なパラメーター検証を含めて正しく呼び出せるようになります。

さらに詳しい例や詳細については、MCP 公式ドキュメントを参照してください。

---