Cocos MCP Server

🚀 Cocos Creator MCP Server Plugin

このプラグインは、Cocos Creator 3.8+向けの包括的なMCP（Model Context Protocol）サーバープラグインです。標準化されたプロトコルを通じて、AIアシスタントがCocos Creatorエディタとやり取りできるようにします。ワンクリックでインストールして使用でき、面倒な環境設定や構成を一切不要にします。ClaudeクライアントであるClaude CLIとCursorでの動作をテスト済みで、理論的には他のエディタも完全にサポートされています。

🚀 現在、13カテゴリーで151のツールを提供し、エディタの98％をコントロールできます！（プレハブのインスタンス化には既知の子ノード復元問題があります）

クイックリンク

• 📖 完全機能ガイド (英語) - 全151個のツールの詳細ドキュメント(To be completed)
• 📖 完整功能指南 (中国語) - 所有151个工具的详细文档(To be completed)

Claude cliの設定:

claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp (自分で設定したポート番号を使用)

Claudeクライアントの設定:

{
    "mcpServers": {
        "cocos-creator": {
            "type": "http",
            "url": "http://127.0.0.1:3000/mcp"
        }
    }
}

CursorまたはVSクラスのMCP設定

{
    "mcpServers": {
        "cocos-creator": {
            "url": "http://localhost:3000/mcp"
        }
    }
}

✨ 主な機能

🎯 シーン操作

• 現在のシーン情報と完全なシーンリストを取得
• パスでシーンを開き、現在のシーンを保存
• カスタム名で新しいシーンを作成
• コンポーネント情報を含む完全なシーン階層を取得

🎮 ノード操作

• 異なるタイプ（Node、2DNode、3DNode）のノードを作成
• UUIDでノード情報を取得し、名前パターンでノードを検索
• ノードのプロパティ（位置、回転、スケール、アクティブ状態）を設定
• 完全な階層をサポートしたノードの削除、移動、複製

🔧 コンポーネント操作

• ノードからコンポーネントを追加/削除
• プロパティを含むノードのすべてのコンポーネントを取得
• コンポーネントのプロパティを動的に設定
• アセットパスからスクリプトコンポーネントをアタッチ
• カテゴリ別に利用可能なコンポーネントタイプをリスト表示

📦 プレハブ操作

• フォルダ構成でプロジェクト内のすべてのプレハブをリスト表示
• プレハブをロード、インスタンス化、作成
• 既存のプレハブを更新し、プレハブインスタンスを元に戻す
• 依存関係を含む詳細なプレハブ情報を取得
• ⚠️ 既知の問題: Cocos Creator APIの制限により、プレハブのインスタンス化時に子ノードが正しく復元されない場合があります。

🚀 プロジェクトコントロール

• プレビューモード（ブラウザ/シミュレータ）でプロジェクトを実行
• 異なるプラットフォーム（ウェブ、モバイル、デスクトップ）向けにプロジェクトをビルド
• プロジェクト情報と設定を取得
• アセットデータベースを更新し、新しいアセットをインポート
• 詳細なアセット情報を取得

🔍 デバッグツール

• フィルタリング付きでエディタのコンソールログを取得
• コンソールをクリアし、シーンコンテキストでJavaScriptを実行
• デバッグ用の詳細なノードツリーを取得
• パフォーマンス統計とシーン検証
• エディタと環境情報を取得

⚙️ 追加機能

• 設定管理: エディタの設定とグローバル設定を取得/設定
• サーバーコントロール: サーバー情報、プロジェクト詳細、エディタコントロール
• メッセージブロードキャスト: カスタムメッセージのリッスンとブロードキャスト
• アセット管理: アセットの作成、コピー、移動、削除、クエリ
• ビルドシステム: プロジェクトのビルドとプレビューサーバーのコントロール
• 参照画像管理: シーンビューで参照画像の追加、削除、管理
• シーンビューコントロール: ギズモツール、座標系、ビューモードのコントロール
• 高度なシーン操作: 元に戻す/やり直す、スナップショット、高度なノード操作

📦 インストール

1. プラグインファイルのコピー

cocos-mcp-serverフォルダ全体をCocos Creatorプロジェクトのextensionsディレクトリにコピーします。

YourProject/
├── assets/
├── extensions/
│   └── cocos-mcp-server/          <- プラグインをここに配置
│       ├── source/
│       ├── dist/
│       ├── package.json
│       └── ...
├── settings/
└── ...

2. 依存関係のインストール

cd extensions/cocos-mcp-server
npm install

3. プラグインのビルド

npm run build

4. プラグインの有効化

1. Cocos Creatorを再起動するか、拡張機能を更新します。
2. 拡張機能メニューにプラグインが表示されます。
3. 拡張機能 > Cocos MCP Serverをクリックしてコントロールパネルを開きます。

💻 使用例

サーバーの起動

1. 拡張機能 > Cocos MCP ServerからMCPサーバーパネルを開きます。
2. 設定を構成します。
   • ポート: HTTPサーバーのポート（デフォルト: 3000）
   • 自動起動: エディタを開いたときにサーバーを自動的に起動
   • デバッグログ: 開発用の詳細ログを有効にする
   • 最大接続数: 許可される最大同時接続数
3. 「サーバーを起動」をクリックして接続を受け入れます。

AIアシスタントの接続

サーバーはhttp://localhost:3000/mcp（または自分で設定したポート）のHTTPエンドポイントを公開しています。 AIアシスタントはMCPプロトコルを使用して接続し、利用可能なすべてのツールにアクセスできます。

ツールカテゴリ

ツールはカテゴリ別に整理され、命名規則はcategory_toolnameです。

• scene_*: シーン関連の操作（8つのツール）
• node_*: ノード操作（9つのツール）
• component_*: コンポーネント管理（7つのツール）
• prefab_*: プレハブ操作（11つのツール）
• project_*: プロジェクトコントロール（22つのツール）
• debug_*: デバッグユーティリティ（10つのツール）
• preferences_*: エディタの設定（7つのツール）
• server_*: サーバー情報（6つのツール）
• broadcast_*: メッセージブロードキャスト（5つのツール）
• assetAdvanced_*: 高度なアセット操作（10つのツール）
• referenceImage_*: 参照画像管理（12つのツール）
• sceneAdvanced_*: 高度なシーン操作（23つのツール）
• sceneView_*: シーンビューコントロール（14つのツール）

📖 完全なツールドキュメントを表示 で詳細な使用例とパラメータを確認できます。

新しいスプライトノードの作成

{
    "tool": "node_create_node",
    "arguments": {
        "name": "MySprite",
        "nodeType": "2DNode",
        "parentUuid": "parent-node-uuid"
    }
}

スプライトコンポーネントの追加

{
    "tool": "component_add_component",
    "arguments": {
        "nodeUuid": "node-uuid",
        "componentType": "cc.Sprite"
    }
}

プレハブのインスタンス化

{
    "tool": "prefab_instantiate_prefab",
    "arguments": {
        "prefabPath": "db://assets/prefabs/Enemy.prefab",
        "position": { "x": 100, "y": 200, "z": 0 }
    }
}

⚠️ 注意: 子ノードを持つ複雑なプレハブは、Cocos Creator APIの制限により正しくインスタンス化されない場合があります。インスタンス化されたプレハブに子ノードが欠落することがあります。

ブラウザでプロジェクトを実行

{
    "tool": "project_run_project",
    "arguments": {
        "platform": "browser"
    }
}

📚 ドキュメント

設定

設定はYourProject/settings/mcp-server.jsonに保存されます。

{
    "port": 3000,
    "autoStart": false,
    "enableDebugLog": true,
    "allowedOrigins": ["*"],
    "maxConnections": 10
}

アイコンの設定

プラグインパネルにアイコンを追加するには、以下の手順を実行します。

1. PNGアイコンファイルを作成します（推奨サイズ: 32x32または64x64）。
2. static/ディレクトリに配置します: static/icon.png。
3. アイコンパスはpackage.jsonですでに設定されています。

開発

プロジェクト構造

cocos-mcp-server/
├── source/                    # TypeScriptソースファイル
│   ├── main.ts               # プラグインのエントリポイント
│   ├── mcp-server.ts         # MCPサーバーの実装
│   ├── settings.ts           # 設定管理
│   ├── types/                # TypeScriptの型定義
│   ├── tools/                # ツールの実装
│   │   ├── scene-tools.ts
│   │   ├── node-tools.ts
│   │   ├── component-tools.ts
│   │   ├── prefab-tools.ts
│   │   ├── project-tools.ts
│   │   ├── debug-tools.ts
│   │   ├── preferences-tools.ts
│   │   ├── server-tools.ts
│   │   ├── broadcast-tools.ts
│   │   ├── scene-advanced-tools.ts
│   │   ├── scene-view-tools.ts
│   │   ├── reference-image-tools.ts
│   │   └── asset-advanced-tools.ts
│   ├── panels/               # UIパネルの実装
│   └── test/                 # テストファイル
├── dist/                     # コンパイルされたJavaScript出力
├── static/                   # 静的アセット（アイコンなど）
├── i18n/                     # 国際化ファイル
├── package.json              # プラグインの設定
└── tsconfig.json             # TypeScriptの設定

ソースからのビルド

# 依存関係のインストール
npm install

# ウォッチモードで開発用にビルド
npm run watch

# 本番用にビルド
npm run build

新しいツールの追加

1. source/tools/に新しいツールクラスを作成します。
2. ToolExecutorインターフェースを実装します。
3. mcp-server.tsの初期化にツールを追加します。
4. ツールはMCPプロトコルを通じて自動的に公開されます。

TypeScriptのサポート

このプラグインは完全にTypeScriptで記述されており、以下の機能を備えています。

• 厳格な型チェックが有効になっています。
• すべてのAPIに対する包括的な型定義があります。
• 開発時のIntelliSenseサポートがあります。
• JavaScriptへの自動コンパイルが行われます。

テストの実行

# 包括的なテストスイートを実行
node comprehensive-test.js

# 機能別のテストを実行
./test-all-features.sh

# Node.jsのテストスクリプトを実行
node test-mcp-server.js

トラブルシューティング

一般的な問題

1. サーバーが起動しない: ポートの可用性とファイアウォールの設定を確認してください。
2. ツールが機能しない: シーンがロードされていることとUUIDが有効であることを確認してください。
3. ビルドエラー: npm run buildを実行してTypeScriptのエラーを確認してください。
4. 接続問題: HTTP URLとサーバーの状態を確認してください。

デバッグモード

プラグインパネルでデバッグログを有効にすると、詳細な操作ログが表示されます。

デバッグツールの使用

{
    "tool": "debug_get_console_logs",
    "arguments": {"limit": 50, "filter": "error"}
}

{
    "tool": "debug_validate_scene",
    "arguments": {"checkMissingAssets": true}
}

必要条件

• Cocos Creator 3.8.6以上
• Node.js（Cocos Creatorに同梱）
• TypeScript（開発依存パッケージとしてインストール）

🔧 技術詳細

このプラグインは、Cocos CreatorのCommonJS環境と互換性のある簡略化されたMCPプロトコルを使用しています。HTTPサーバーは、AIアシスタントがエディタとやり取りできるようにJSON-RPCインターフェースを提供します。

プロトコルサポート

• HTTP接続: http://localhost:3000/mcp（設定可能なポート）
• JSON-RPC 2.0: 標準のリクエスト/レスポンス形式
• ツールの探索: tools/listメソッドで利用可能なツールを返します。
• ツールの実行: tools/callメソッドで特定のツールを実行します。

📄 ライセンス

このプラグインはCocos Creatorプロジェクト用で、ソースコードは一緒にパッケージ化されており、学習やコミュニケーションに使用できます。暗号化されていません。独自の二次開発や最適化をサポートします。このプロジェクトのコードまたはその派生コードは、いかなる商業目的や転売にも使用できません。商業利用が必要な場合は、お問い合わせください。