MCP Combined Server: 3D Cartoon Generator & File System Tools

MCP 統合サーバー：3D カートゥーン生成とファイルシステムツール

主に2つの機能を提供する、プロフェッショナル品質のサーバーです。

1. Google の Gemini AI を使用した高品質な 3D スタイルのカートゥーン画像生成
2. ファイルの読み取り、書き込み、管理を行う安全なファイルシステム操作

🌟 機能

画像生成

• 3D カートゥーン生成：高品質な 3D スタイルのカートゥーン画像を作成します
• 子ども向けデザイン：カラフルで楽しく、魅力的なビジュアルを重視しています
• 即時プレビュー：生成した画像をデフォルトのブラウザーで自動的に開きます
• ローカルストレージ：画像とプレビューを整理された出力ディレクトリに保存します

ファイルシステム操作

• 安全なファイルアクセス：パスの検証とセキュリティチェックを行います
• ファイルの読み取り／書き込み：テキストファイルの内容を読み取り、書き込みます
• ディレクトリ操作：ディレクトリの一覧表示、作成、移動を行います
• ファイル検索：パターンに一致するファイルを検索します

システム機能

• プロフェッショナルな設定：堅牢なエラー処理と制御されたログ記録
• クロスプラットフォーム対応：Windows、macOS、Linux 向けにファイルパスをインテリジェントに処理します
• スマートな OS 検出：各オペレーティングシステムに最適な保存先を自動的に見つけます
• セキュリティ制御：設定によってディレクトリへのアクセスを制限します

🛠️ 技術スタック

• コアフレームワーク：Model Context Protocol（MCP）SDK
• AI 連携：Google Generative AI（Gemini）
• ランタイム：Node.js v14+
• 言語：TypeScript
• パッケージマネージャー：npm

📋 前提条件

• Node.js（v14 以降）
• Google Gemini API キー
• TypeScript

⚙️ インストール

1. リポジトリをクローンします：

git clone https://github.com/falahgs/mcp-3d-style-cartoon-gen-server.git
cd mcp-3d-style-cartoon-gen-server

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

npm install

3. 環境を設定します： ルートディレクトリに .env ファイルを作成します：

GEMINI_API_KEY=your_api_key_here
ALLOWED_DIRECTORIES=/path/to/allowed/dir1,/path/to/allowed/dir2

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

npm run build

🔧 Claude Desktop での MCP サーバーの設定

この統合サーバーを Claude Desktop と連携するには：

1. 設定ファイルを探します：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 次の設定を追加します：

{
  "mcpServers": {
    "mcp-3d-cartoon-generator": {
      "command": "node",
      "args": [
        "path/to/your/build/index.js"
      ],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here",
        "IS_REMOTE": "true",
        "SAVE_TO_DESKTOP": "true",
        "DETECT_OS_PATHS": "true",
        "ALLOWED_DIRECTORIES": "C:\\Users\\YourUsername\\Desktop,C:\\Users\\YourUsername\\Documents",
        "DEBUG": "false"
      }
    }
  }
}

Windows PowerShell ヘルパースクリプト

Windows ユーザーは、同梱の fix_claude_config.ps1 スクリプトを使用して Claude Desktop を自動的に設定できます：

1. スクリプトを編集し、サーバービルドへのパスと Gemini API キーを更新します
2. PowerShell でスクリプトを実行します：

powershell -ExecutionPolicy Bypass -File .\fix_claude_config.ps1

これにより、適切なエンコードと設定で構成ファイルが作成または更新されます。

🚀 利用可能なツール

1. 画像生成ツール

{
  "name": "generate_3d_cartoon",
  "description": "Generates a 3D style cartoon image for kids based on the given prompt",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "The prompt describing the 3D cartoon image to generate"
      },
      "fileName": {
        "type": "string",
        "description": "The name of the output file (without extension)"
      }
    },
    "required": ["prompt", "fileName"]
  }
}

2. ファイルシステムツール

ファイルの読み取り

{
  "name": "read_file",
  "description": "Read the contents of a file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the file to read"
      }
    },
    "required": ["path"]
  }
}

ファイルの書き込み

{
  "name": "write_file",
  "description": "Write content to a file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the file to write"
      },
      "content": {
        "type": "string",
        "description": "Content to write to the file"
      }
    },
    "required": ["path", "content"]
  }
}

ディレクトリの一覧表示

{
  "name": "list_directory",
  "description": "List the contents of a directory",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the directory to list"
      }
    },
    "required": ["path"]
  }
}

ディレクトリの作成

{
  "name": "create_directory",
  "description": "Create a new directory",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the directory to create"
      }
    },
    "required": ["path"]
  }
}

ファイルの検索

{
  "name": "search_files",
  "description": "Search for files matching a pattern",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Base directory to search from"
      },
      "pattern": {
        "type": "string",
        "description": "Search pattern (glob format)"
      },
      "excludePatterns": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Patterns to exclude from search (glob format)"
      }
    },
    "required": ["path", "pattern"]
  }
}

📄 使用例

画像生成の例

// Generate a 3D cartoon
{
  "name": "generate_3d_cartoon",
  "arguments": {
    "prompt": "A friendly robot playing with a cat",
    "fileName": "robot_cat_play"
  }
}

ファイルシステムの例

// Read a file
{
  "name": "read_file",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/example.txt"
  }
}

// Write a file
{
  "name": "write_file",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/new-file.txt",
    "content": "This is the content of the file."
  }
}

// List directory contents
{
  "name": "list_directory",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents"
  }
}

// Create a directory
{
  "name": "create_directory",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/new-folder"
  }
}

// Search for files
{
  "name": "search_files",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents",
    "pattern": "*.txt",
    "excludePatterns": ["temp*", "*.tmp"]
  }
}

🔒 セキュリティ機能

このサーバーでは、次のようなセキュリティ対策を実施しています：

1. パスの検証：すべてのファイルパスを検証し、許可されたディレクトリ内にあることを確認します。
2. 許可されたディレクトリ：ALLOWED_DIRECTORIES 環境変数で明示的に指定されたディレクトリのみアクセスできます。
3. シンボリックリンク保護：シンボリックリンクを経由して許可範囲外のディレクトリにアクセスすることを防ぎます。
4. 制御されたログ記録：情報漏えいを防ぐため、デバッグログはデフォルトで無効になっています。

⚙️ 設定オプション

環境変数

変数	説明	デフォルト
GEMINI_API_KEY	画像生成用の Google Gemini API キー	（必須）
ALLOWED_DIRECTORIES	許可するファイルシステムパスをカンマ区切りで指定したリスト	ユーザーのホームディレクトリ、現在のディレクトリ
IS_REMOTE	ブラウザーを開かずにリモートモードで実行します	false
SAVE_TO_DESKTOP	デスクトップディレクトリへの保存を強制します	false
DETECT_OS_PATHS	OS 固有のパス検出を有効にします	true
DEBUG	詳細なデバッグログ記録を有効にします	false

🛠️ トラブルシューティング

よくある問題：

1. Claude での JSON 解析エラー：

   • ログが JSON 通信に干渉しないように、DEBUG が "false" に設定されていることを確認してください。
   • Claude の設定で JSON の書式が正しいことを確認してください。

2. ファイルへのアクセスが拒否される：

   • アクセスしようとしているパスが ALLOWED_DIRECTORIES に含まれていることを確認してください。
   • 対象のファイルやディレクトリのアクセス権を確認してください。

3. 画像が保存されない：

   • 画像がデスクトップに保存されるように、SAVE_TO_DESKTOP を "true" に設定してください。
   • サーバーログでデスクトップパスの検出状況を確認してください（DEBUG を一時的に有効にします）。

📄 ライセンス

MIT ライセンス

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。