Vibe Blocks MCP

Roblox Studio 向け Vibe Blocks MCP

モデル コンテキスト プロトコル (MCP) を介して Roblox Studio を AI コーディング エディター (Cursor、Windsurf、Claude など) に接続し、Roblox Studio 環境内で AI 支援ゲーム開発を可能にします。

概要

このプロジェクトは主に 2 つの部分から構成されます。

1. **Python MCPサーバー：**ローカルで動作するFastAPIサーバーです。Roblox StudioのアクションをMCP（Server-Sent Events - SSE）経由でツールとして公開します。設定により、Roblox Open Cloud APIと連携することも可能です。
2. Luaコンパニオンプラグイン： Studio内で実行されるRoblox Studioプラグイン（ roblox_mcp_plugin/src/Plugin.server.lua ）。ローカルPythonサーバーからコマンドをポーリングし、Studioのコンテキストで実行（インスタンスの操作、プロパティの読み取り、Luauの実行）し、結果とStudioのログをサーバーに送信します。

これにより、MCP 経由で接続された AI エージェントがライブ Roblox Studio セッションを理解し、対話できるようになります。

特徴

• ライブスタジオインタラクション:
  • シーン操作: Studio シーン内で直接、オブジェクト (パーツ、モデル、スクリプトなど) のプロパティ (PrimaryPart を含む) を作成、削除、複製、移動、スケール、設定します。
  • **シーン検査:**オブジェクトのプロパティを取得し、子オブジェクトを一覧表示し、Studio 内でクラスまたは名前でインスタンスを検索します。
  • **スクリプト：**スクリプト/ローカルスクリプトを作成、編集、削除します。Studio環境内で任意の Luau コードを直接実行し、出力/エラーをキャプチャします。
  • **環境:**照明または地形サービスのプロパティを設定します。
  • アニメーション: Humanoids/AnimationControllers でアニメーションを再生します。
  • **NPC:**既存のテンプレートを複製するか、アセット ID から挿入して NPC を生成します。
  • **子の変更:**フィルターに基づいて、オブジェクトの複数の子にプロパティの変更を適用します。
  • Studio ログ: Studio 出力ウィンドウから最近のログを取得します。
• Roblox オープンクラウド統合 (オプション - API キーが必要):
  • **Luau 実行 (クラウド):**別のクラウド環境で Luau コードを実行します (ライブ Studio アクセスを必要としないタスクに役立ちます)。
  • **DataStores:**標準 DataStore 内のストアを一覧表示し、キー値エントリを取得、設定、削除します。
  • **アセット:**ローカル ファイルから新しいアセット (モデル、画像、オーディオ) をアップロードします。
  • **公開:**現在保存または公開されている場所のバージョンを公開します。
  • **(計画中):**資産の詳細を取得し、ユーザー資産を一覧表示します。

設定

1. 前提条件:

• Python >= 3.10
• uvパッケージマネージャー（ uv をインストール）。依存関係管理を高速化するために、これを強くお勧めします。
• ロブロックススタジオ
• （オプション） Open Cloud機能用のRoblox APIキー。Roblox Creator Dashboard > Credentialsから取得してください。使用するAPI（データストア、アセットアップロード、パブリッシング、Luau実行など）への権限が必要です。
• (オプション) Roblox Universe ID とターゲットの場所 ID (Open Cloud 機能に必要)。

2. リポジトリのクローンを作成します。

3. 依存関係をインストールします。

uvを使用する (推奨):

あるいは、 pipを使用します。

4. 環境を構成する (オプション - クラウド機能の場合):

• Open Cloud ツール (DataStores、Asset Upload、Publishing、Cloud Luau) を使用する予定の場合は、サンプル環境ファイルをコピーします。
  cp .env.example .env
• .envファイルを編集します。
  • "YOUR_API_KEY_HERE"をRoblox APIキーに置き換えます。
  • ROBLOX_UNIVERSE_IDの0自分の Universe ID に置き換えます。
  • ROBLOX_PLACE_IDの0対象の Place ID に置き換えます。
• **クラウド機能が必要ない場合は、 .envファイルの作成をスキップできます。**サーバーは引き続き実行されますが、クラウド関連ツールはエラーを返します。

5. Roblox StudioにCompanionプラグインをインストールします。

• Rojo をインストールします。Rojoがインストールされていない場合は、 Rojo Web サイトの指示に従ってください。
• **プラグインをビルドする (オプション):**ターミナルでroblox_mcp_pluginディレクトリに移動し、次のコマンドを実行します。
  rojo build default.project.json --output VibeBlocksMCP_Companion.rbxm
  これにより、 VibeBlocksMCP_Companion.rbxmファイルが作成されますが、リポジトリで提供されているファイルを使用することもできます。
• Studio にインストール:
  • Roblox Studio プラグイン フォルダーを見つけます。
    • Windows: %LOCALAPPDATA%\Roblox\Plugins
    • macOS: ~/Documents/Roblox/Plugins (Finder でCmd+Shift+Gを使用してパスを貼り付けて移動するか、Roblox Studio でプラグイン フォルダーをクリックする必要がある場合があります)。
  • 生成されたVibeBlocksMCP_Companion.rbxmファイルをこのプラグイン フォルダーに移動またはコピーします。
• **Roblox Studio を再起動します。**これで、Studio を開いたときにプラグインが自動的に読み込まれるようになります。
  • **注:**プラグインはhttp://localhost:8000/plugin_commandをポーリングします。サーバーポートを変更する場合は、Luaスクリプト（ roblox_mcp_plugin/src/Plugin.server.lua ）の先頭にあるSERVER_URL変数を更新し、プラグインを再構築する必要があります。

6. Python サーバーを実行します。

• プロジェクトのルート ディレクトリでターミナルを開きます。
• サーバー スクリプトを実行可能にします (まだ実行していない場合)。
  chmod +x server.sh
• サーバーを実行します。
  ./server.sh
• サーバーが起動し、必要に応じてuvicornチェック/インストールし、 http://localhost:8000で実行中であることをログに記録します。
• サービスを使用している間は、このターミナル ウィンドウを開いたままにしておきます。

7. MCP クライアント (例: カーソル) から接続します。

• このサービスは、Cursor、Windsurf、または将来のバージョンの Claude Desktop など、Server-Sent Events (SSE) を介して Model Context Protocol (MCP) をサポートするすべての AI クライアントで動作します。
• カーソルを使用する例:
  • File > Settings > MCP (Mac の場合はCode > Settings > MCP ) に移動します。
  • 「新しいグローバル MCP サーバーの追加」をクリックします。
  • SSE URL を入力します: http://localhost:8000/sse (末尾の/sseを必ず含めてください)。
  • mcp.jsonファイルGXP8を編集する必要があるかもしれません
• これで、クライアントは「Vibe Blocks MCP」ツール ソースと使用可能なツールを検出するはずです。

使用法

サーバーが実行中になり、プラグインが Studio にインストールされ、MCP クライアントが接続されると、AI を介して Studio セッションと対話できるようになります。

エージェントに話しかけ（クライアントが要求する場合はツールを @ メンションします（例： list_children ）、アクションを実行するように依頼します）。

プロンプトの例:

• 「ワークスペースに「Floor」という名前の明るい赤色のパーツを作成します。サイズを (100, 2, 100)、位置を (0, -1, 0) に設定します。アンカーします。」
• 「'Workspace.OldPlatform' という名前のオブジェクトを削除します」
• 「'Workspace.SpawnLocation' の Position プロパティとは何ですか?」
• 「ServerScriptService の子の一覧を表示します。」
• 「ServerScriptService の下で、className が 'Script' であるすべてのインスタンスを検索します。」
• 「Studioでこのスクリプトを実行します: print(game:GetService('Lighting').ClockTime) 」
• 「Lighting のClockTimeプロパティを 14 に設定します。」
• 「'ReplicatedStorage.Templates.EnemyNPC' のクローンを作成し、クローンの名前を 'Guard1' にします。Workspace に親を設定します。」
• 「'Workspace.Guard1' というモデルでアニメーション アセット 123456789 を再生します。」
• 「クラス名が「Part」である「Workspace.DecorationFolder」のすべての子のマテリアルを「ネオン」に設定するように変更します。」
• (クラウドの例) 「./assets/MyCoolModel.fbx」を「Cool Character Model」という名前のモデルとしてアップロードします。
• (クラウドの例) 「'PlayerData' データストアからキー 'player_123_score' の値を取得します。」
• (クラウド例) 「現在の場所を公開します。」
• 「Studio 出力からの最新のログを表示してください。」

利用可能なツール

(ツールは、Studio プラグインまたは Roblox Open Cloud API と直接対話します)

Studio プラグイン ツール (ライブ インタラクション):

• get_property : Studio 内のオブジェクトから特定のプロパティの値を取得します。
• list_children : Studio 内のオブジェクトの直接の子を取得します。
• find_instances : Studio 内のクラス名またはテキストを含む名前に基づいて、指定されたルート内のインスタンスを検索します。
• create_instance : Studio で新しいインスタンス (パーツ、モデル、スクリプトなど) を作成します。
• delete_instance : Studio シーンからオブジェクトを削除します。
• set_property : Studio 内のオブジェクトの特定のプロパティを設定します (値には JSON 文字列を使用します)。
• set_primary_part : モデルの PrimaryPart プロパティを設定します。
• move_instance : オブジェクト (モデルまたは BasePart) を Studio 内の新しい位置に移動します。
• clone_instance : Studio 内の既存のオブジェクトを複製します。
• create_script : Studio で提供されたコードを使用して新しい Script または LocalScript インスタンスを作成します。
• edit_script : Studio 内の既存のスクリプトまたは LocalScript のソース コードを編集します。
• delete_script : Studio 内の既存のスクリプトまたは LocalScript インスタンスを削除します。
• set_environment : Studio の環境サービス (照明または地形) のプロパティを設定します。
• spawn_npc : アセット ID からモデルを挿入するか、既存のテンプレート モデルを複製して、Studio で NPC を生成します。
• play_animation : Studio 内のターゲット オブジェクトの Humanoid または AnimationController にアニメーションを読み込んで再生します。
• execute_luau_in_studio : プラグインを介して LIVE Studio セッションで任意の Luau スクリプトを実行し、出力/戻り値/エラーをキャプチャします。
• modify_children : オプションのフィルター (名前/クラス) に一致する親の直下の子を見つけ、指定されたプロパティを設定します。
• get_studio_logs : プラグインを介して Roblox Studio 出力ウィンドウからキャプチャされた最新のログを取得します。

Cloud API ツールを開きます (オプション - .env設定が必要です):

• execute_luau_in_cloud : Roblox Cloud API 経由で任意の Luau スクリプトを実行します (ライブ Studio ではなく、別のクラウド環境で実行されます)。
• list_datastores_in_cloud : Cloud API 経由で標準データストアを一覧表示します。
• get_datastore_value_in_cloud : Cloud API を介して標準データストアからエントリの値を取得します。
• set_datastore_value_in_cloud : Cloud API を介して標準データストア内のエントリの値を設定します。
• delete_datastore_value_in_cloud : Cloud API を介して標準データストアからエントリを削除します。
• upload_asset_via_cloud : Cloud API 経由で、ローカル システムからファイルを新しい Roblox アセットとしてアップロードします。
• publish_place_via_cloud : 指定された場所を Cloud API 経由で公開します。
• get_asset_details_via_cloud : (未実装) Cloud API 経由で特定のアセットの詳細を取得します。
• list_user_assets_via_cloud : (未実装) 認証されたユーザーが所有するアセットを Cloud API 経由で一覧表示します。
• send_chat_via_cloud : Cloud API (execute_luau) 経由でゲーム内チャットにメッセージを送信します。
• teleport_player_via_cloud : Cloud API (execute_luau) 経由でプレイヤーをテレポートします。

内部/キューイングツール:

• queue_studio_command : (下位レベル) Studio プラグインの単一の生のコマンド辞書をキューに追加します。
• queue_studio_command_batch : (下位レベル) Studio プラグインの生のコマンド辞書のバッチをキューに追加します。

トラブルシューティング

• サーバーが起動しません: Pythonとuvが正しくインストールされていることを確認してください。ターミナルでエラーメッセージを確認してください。依存関係がインストールされていることを確認してください（ uv pip sync pyproject.toml ）。
• プラグインが接続できません： Pythonサーバーが起動していることを確認してください。LuaプラグインスクリプトのSERVER_URLサーバーのアドレスとポート（デフォルトはhttp://localhost:8000/plugin_command ）と一致していることを再確認してください。Studioの出力ウィンドウで、プラグインスクリプトのエラーを確認してください。
• **MCPクライアントが接続できません：**サーバーが稼働していることを確認してください。MCPクライアント設定でSSE URL（ http://localhost:8000/sse ）が正しく入力されていることを確認してください。
• **クラウドツールが機能しません：**有効なAPIキー、Universe ID、Place IDを含む.envファイルが作成されていることを確認してください。また、APIキーに、使用しようとしている特定のクラウドAPIに必要な権限が付与されていることを確認してください。
• **権限:**コンパニオン プラグインを適切にインストールするのではなく、ローカル ファイルからロードする場合、正しく機能するにはスクリプト インジェクション権限が必要です。