⚡ Universal Roblox AI Studio — 自律型マルチモード機能MCPプラットフォーム

Universal Roblox AI Studio は、Roblox Studioを外部AIコーディングアシスタント（Claude Desktop、Cursor、Antigravity、VS Codeなど）向けのAIネイティブで自律的かつ双方向の開発プラットフォームへと変革する、次世代Model Context Protocol（MCP）ランタイムです。

📖 目次

• 🌟 主な機能

• 🏛️ アーキテクチャと11の専用プロバイダー

• 🧱 階層＆コンポーネント優先構築（「+ 記号」パラダイム）

• 🛡️ 制限付き・公式MCPルーティングツリー（Restricted Taxonomy）

• 🧠 自己修復型診断エンジン（Self-Healing Diagnostics）

• 🛠️ 包括的なMCPツール一覧（63+ツール）

• 🚀 クイックセットアップ＆はじめに

• 🤖 AIクライアント設定（Claude Desktop / Cursor）

• 📊 ライブテレメトリとStudioインターフェース

• 🧪 テストと検証

🌟 主な機能

1. 63以上のファーストクラス汎用MCPツール: DataModel階層、Instanceライフサイクル、Luauスクリプト管理、PBRマテリアル、Voxel Terrain、Playtestシミュレーション、3D Generative AI、仮想ハードウェア入力。

2. 公式Roblox Studio MCP（StudioMCP.exe）ローカル統合: Roblox公式のMCPクライアント（%LOCALAPPDATA%\Roblox\Versions\...\StudioMCP.exe および mcp.bat）を自動検出し、制限付き3D/Asset/Playtestコマンドを公式エンジンへ直接ルーティングします。

3. コンポーネント＆階層優先構築（VisualConstructionEngine）: すべてを巨大なスクリプトで生成するのではなく、Studio Explorerの+（Insert Object）ロジックで、物理オブジェクト、制約（Constraints）、ライト、パーティクル、サウンドをレイヤーごとに構築します。

4. 高度なアニメーション＆ハードウェアキャリブレーション（AnimationAuthoringEngine）: R15/R6リグのポージング（Motor6D）、関節の安全性、KeyframeSequenceの作成、ツールがキャラクターの手に正しく収まるようにするTool.Gripキャリブレーション。

5. 自己修復型エラー診断（DiagnosticsEngine）: Luauエンジンエラー（C0 is read only、attempt to index nil、HttpDisabledなど）を即座に分析し、AIアシスタントに修正済みコード（suggestedFix）と推奨事項を提供します。

6. 4段階の動的機能解決（UniversalCapabilityEngine）: コマンドを直接ツール、ワークフローテンプレート、コンパイル済みプリミティブ、または自律プランナーで解決します。

7. 双方向セキュアHTTP/HTTPSブリッジ: StudioプラグインとNode.jsサーバー間で、即時イベントリスニング（LogService、エラー、選択変更）とChangeHistoryServiceによるUndo/Redo（Ctrl+Z）安全性を実現します。

🏛️ アーキテクチャと11の専用プロバイダー

Universal Roblox MCPは、単一の静的ツールリストではなく、11の専門プロバイダー（IProvider）と**中央機能ルーター（CapabilityRouter）**を通じて動作します：

                      ┌────────────────────────────────────────────────────────┐
                      │             AI Client (Claude / Cursor)                │
                      └──────────────────────────┬─────────────────────────────┘
                                                 │ MCP (JSON-RPC)
                                                 ▼
                      ┌────────────────────────────────────────────────────────┐
                      │         Universal Roblox Studio MCP Router             │
                      │           (UniversalCapabilityEngine)                  │
                      └───────┬──────────────────┬───────────────────┬─────────┘
                              │                  │                   │
         ┌────────────────────┴───┐     ┌────────┴────────┐   ┌──────┴────────────────┐
         │ 1. Embedded Plugin     │     │ 2. Official MCP │   │ 3-11. Specialized     │
         │    (HTTP/HTTPS Bridge) │     │ (StudioMCP.exe) │   │       Domain Engines  │
         └────────────┬───────────┘     └────────┬────────┘   └──────┬────────────────┘
                      │                          │                   │
                      │ Polling RPC              │ Stdio / WS        │ Logic & Templates
                      ▼                          ▼                   ▼
    ┌──────────────────────────────────────────────────────────────────────────────────┐
    │                               Roblox Studio Session                              │
    │  • DataModel Tree    • Luau ScriptEditor    • Viewport Framebuffer  • Simulation │
    └──────────────────────────────────────────────────────────────────────────────────┘

11のプロバイダーレイヤー：

1. EmbeddedPluginProvider: Roblox Studio内のローカルプラグインと通信し、36の基本プリミティブを管理します。

2. OfficialRobloxMCPProvider: Roblox公式のStudioMCP.exeバイナリに接続し、制限付き3D、Asset、Playtestコマンドを実行します。

3. ModelingProvider: 3Dメッシュ、PBRマテリアル、プロシージャルパーツの組み立てを調整します。

4. AnimationProvider: アニメーションパーツ、プレイヤーコントロール、リグポーズを管理します。

5. LuauProvider: Luau静的解析、構文検証、安全なコード実行を提供します。

6. WorkflowProvider: 複合ゲームシステム（昼夜、Leaderstats、島ジェネレーターなど）をテンプレートとして適用します。

7. AssetProvider: Creator StoreとCloudインベントリからモデル、サウンド、ビジュアルアセットを取得・挿入します。

8. TestingProvider: 自動シナリオテスト、仮想キーボード/マウス入力、検証プロセスを管理します。

9. DiagnosticsProvider: Studio出力を監視し、根本原因分析を行い、安全な修復を提案します。

10. ObservationProvider: Viewportのスクリーンキャプチャと視覚的検査を管理します。

11. DesignProvider: 空間的美観、色彩調和、デザインルールを監査します。

🧱 階層＆コンポーネント優先構築（「+ 記号」パラダイム）

Roblox Studioの経験豊富な開発者は、すべてを単一の巨大なLuauスクリプトでプロシージャルに生成しません。代わりに**コンポーネント＆階層ベース（Component-Driven）**の開発を行います。本システムは、オブジェクトを5段階の業界標準レイヤーで構築します：

[Katman 1: Mekansal İskelet]  ───▶ Model / Folder / Frame / Parts / Meshes / PrimaryPart
            ↓
[Katman 2: Görsel & Duyusal]  ───▶ PBR Materials / PointLight / Particles / Sounds / SurfaceGui
            ↓
[Katman 3: Etkileşim & Fizik] ───▶ ProximityPrompt / HingeConstraint / WeldConstraint / Attachments
            ↓
[Katman 4: Animasyon & Donanım]──▶ KeyframeSequence / Motor6D Poses / Tool Grip Calibration
            ↓
[Katman 5: Ayrık Mantık]      ───▶ Sadece sinyalleri dinleyen hafif ve modüler Luau Controller

既製コンポーネントテンプレート（component_compose）：

• interactive_door: 木製フレーム（Frame）、ヒンジ（HingePart）、ドアパネル（DoorPanel）、ProximityPrompt、開閉音（Sound）、TweenServiceコントローラー、カスタムAttributes（IsOpen、OpenAngle）。

• collectible_coin: 回転する円柱コイン、メタルマテリアル、ゴールドPointLight、Sparkles、収集音、CollectionServiceタグ。

• equippable_weapon: キャリブレーション済みTool.Grip、RightGripAttachment、Handle、振り回し音、軌跡（Trail）、アクティベーションスクリプト。

• interactive_chest: 固定チェスト本体、開閉式リッド（ChestLid）、HingeConstraint、ProximityPrompt、ゴールドの輝き、LootTable属性。

• streetlamp_fixture: 金属ポール、ガラスランプヘッド、PointLight、SpotLight、Neonマテリアル、昼夜自動ライトセンサー。

• teleporter_pad: テレポートプラットフォーム、パーティクルビーム（ParticleEmitter & Beam）、テレポート音、目標座標。

• dialogue_npc: ポージング済みR15/R6キャラクター、BillboardGuiネームタグ、ダイアログProximityPrompt、会話ツリー。

🛡️ 制限付き・公式MCPルーティングツリー（Restricted Taxonomy）

Robloxエンジンは、セキュリティ上の理由からサードパーティプラグインに対していくつかのAPI（RobloxSecurity、RobloxScriptSecurity、SensitiveInput、Capture）を制限しています。本システムは、これらの制限を**RestrictedCapabilityRegistryを通じて自動認識し、公式のStudioMCP.exe**プロキシへ直接ルーティングします：

RESTRICTED / OFFICIAL-ONLY (12 Kategori)
├── 1. RobloxSecurity                   ──▶ official-roblox-mcp (execute_luau / search_game_tree)
├── 2. RobloxScriptSecurity             ──▶ official-roblox-mcp (script_grep / execute_luau)
├── 3. Internal Studio APIs             ──▶ official-roblox-mcp (get_studio_state, list_roblox_studios)
├── 4. Internal Engine APIs             ──▶ official-roblox-mcp (generate_mesh / get_console_output)
├── 5. Internal Plugin APIs             ──▶ official-roblox-mcp (internal plugin manager)
├── 6. Protected Debug APIs             ──▶ official-roblox-mcp (get_console_output)
├── 7. Protected Studio Control APIs    ──▶ official-roblox-mcp (start_stop_play [Play/Run/Stop])
├── 8. Missing Sandbox Capabilities     ──▶ official-roblox-mcp (screen_capture, keyboard/mouse input)
├── 9. Restricted Asset APIs            ──▶ official-roblox-mcp (generate_mesh, generate_material, search_asset)
├── 10. Restricted HTTP APIs            ──▶ official-roblox-mcp (Cloud Auth HTTP)
├── 11. Internal Network APIs           ──▶ official-roblox-mcp (Replication diagnostics)
└── 12. Provider-Specific Capabilities  ──▶ official-roblox-mcp (subagent, execute_luau)

🧠 自己修復型診断エンジン（Self-Healing Diagnostics）

AIモデルはコード実行時に一般的なRoblox APIエラーに遭遇することがあります。DiagnosticsEngineはこれらのエラーを捕捉し、AIに直接動作する解決策を生成します：

🛠️ 包括的なMCPツール一覧（63+ツール）

1. ビジュアル構築＆アニメーションツール

• component_compose: 既製テンプレートで完全なコンポーネント（ドア、チェスト、コイン、NPCなど）を構築します。

• component_template_list: 利用可能なすべてのコンポーネントテンプレートと階層ツリーを一覧表示します。

• hierarchy_scaffold: Studioプロジェクトをプロフェッショナルな業界標準のフォルダーに整理します。

• tool_grip_calibrate: 武器やアイテムのキャラクターの手での保持角度（Tool.Grip）を自動キャリブレーションします。

• rig_pose_and_animate: R15/R6キャラクターの関節（Motor6D）を安全にポージングします。

2. 公式Roblox MCPツール（StudioMCP.exe統合）

• generate_mesh: 自然言語プロンプトからRoblox Cloud AI 3Dメッシュを生成します。

• generate_material: 自然言語プロンプトからPBRマテリアルとテクスチャを生成します。

• generate_procedural_model: プロシージャルパーツの組み立てを作成します。

• search_asset & insert_asset: Creator StoreとCloudライブラリからアセットを検索・配置します。

• screen_capture: Studio 3D Viewportから高解像度スクリーンショットを取得します。

• start_stop_play: ゲームを物理的に開始（Play/Run）または編集モードに戻します（Stop）。

• get_studio_state: Studioセッション、開いているドキュメント、アクティブなシミュレーションモードを照会します。

• list_roblox_studios & set_active_studio: 実行中のStudioウィンドウを一覧表示し、アクティブなものを選択します。

• character_navigation: シミュレーション中にキャラクターを3Dワールド座標へ移動させます。

• user_keyboard_input & user_mouse_input: シミュレーションにハードウェアレベルのキー入力とマウスクリックを注入します。

• script_read、multi_edit、script_search、script_grep: Studio Script Editor経由でローカル複数ファイルの編集と検索を行います。

• subagent & execute_luau: RobloxのローカルサブエージェントとLuauコード実行エンジンを実行します。

3. 基本DataModel＆プリミティブツール

• studio_info、studio_get_tree、studio_search、studio_inspect: DataModel階層スキャンと詳細プロパティ検査。

• instance_create、instance_delete、instance_clone、instance_reparent、instance_rename、instance_move: オブジェクトライフサイクルと3D配置。

• property_get、property_set、property_get_all: 自動Luau型変換付きプロパティの読み書き。

• attribute_get、attribute_set、attribute_delete、attribute_get_all: 属性（Attribute）管理。

• script_get_source、script_set_source、script_patch_source、script_search_code: スクリプトソースの読み取り、行ベースのパッチ、コード検索。

• selection_get、selection_set、selection_add、selection_clear: Studio Explorerの選択制御。

• output_get、output_get_errors、output_clear: 出力ログとエラー捕捉。

• terrain_fill_block、terrain_fill_ball、terrain_clear: Voxel Terrainの生成とクリア。

• batch_execute: 単一操作で原子的に複数コマンドを実行（Undo/Redoウェイポイント対応）。

🚀 クイックセットアップ＆はじめに

1. 要件

• Node.js: v18.0.0以上（v20+ / v24推奨）。

• Roblox Studio: WindowsまたはmacOSにインストール済み。

2. リポジトリのクローンとビルド

git clone <repo-url>
cd "Roblox Studio MCP"
npm install
npm run build

3. Roblox Studioプラグインのインストール

プラグインは次の2つの方法のいずれかでインストールできます：

方法A：ビルド済みプラグインファイルをコピー（推奨）

npm run bundle:plugin と node scripts/build-rbxmx.js コマンドを実行します（またはビルド済みファイルをコピーします）：

• Windows: plugin-build\RobloxUniversalMCP.rbxmx ファイルを %LOCALAPPDATA%\Roblox\Plugins\ ディレクトリにコピーします。

• macOS: plugin-build/RobloxUniversalMCP.rbxmx ファイルを ~/Library/Application Support/Roblox/Plugins/ ディレクトリにコピーします。

方法B：Studio内での手動インストール

1. Roblox Studioで任意のPlaceを開きます。

2. plugin-build/RobloxUniversalMCP.luau ファイルの内容をScriptに貼り付けます。

3. Scriptを右クリックして "Save as Local Plugin..." オプションを選択します。

4. Home > Game Settings > Security セクションから "Allow HTTP Requests" オプションを有効にします。

🤖 AIクライアント設定（全コンピューター対応のユニバーサル設定）

どのコンピューターでも固定かつポータブルに動作させるための 3つの異なるユニバーサル方法 を提供しています：

🌟 方法1：グローバルCLI登録（推奨 — 全コンピューターで1行！）

プロジェクトフォルダーで一度 npm link を実行して、システムをグローバルコマンドとして登録します：

npm run build
npm link

これで Claude Desktop、Cursor、または任意のMCPクライアントでファイルパスを入力する必要がなくなります：

Claude Desktop（claude_desktop_config.json）

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "roblox-studio-mcp"
    }
  }
}

🚀 方法2：Cursor / VS Codeユニバーサルワークスペース（${workspaceFolder}）

プロジェクトをCursorまたはVS Codeで開いたときに、.cursor/mcp.json または .vscode/mcp.json ファイルに追加します。どのコンピューターで開いても ${workspaceFolder} が自動的に検出されます：

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "node",
      "args": [
        "${workspaceFolder}/dist/index.js"
      ]
    }
  }
}

📁 方法3：ファイルパスを直接指定して実行

グローバルCLIの代わりに、ビルド済みの dist/index.js ファイルを直接呼び出す場合：

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "node",
      "args": [
        "<PROJE_KLASORUNUZ_TAM_YOLU>/dist/index.js"
      ]
    }
  }
}

（例 Windows: C:\\Projects\\Roblox-Studio-MCP\\dist\\index.js | macOS: /Users/username/Projects/Roblox-Studio-MCP/dist/index.js）

📊 ライブテレメトリーとStudioインターフェース

プラグインが読み込まれると、Roblox Studio内に専用の DockWidget（DiagnosticsView） が開きます：

• Plugin Runtime: ONLINE / STANDALONE

• MCP Bridge: CONNECTED（緑）/ DISCONNECTED（赤）

• Capabilities Discovered: 80以上のライブ機能（全プロバイダーとサブシステム）

• Low-Level Tools: 57のプリミティブツール

• High-Level Workflows: 19の複合ワークフロー

• Total Universal Tools: 76のユニバーサルツール

• Active Mode: CHAT | OBSERVE | BUILD | PLAYTEST | AUTONOMOUS

🧪 テストと検証

すべてのテストスイートを実行するには：

npm test

テスト出力：

✔ Tool Registry contains all universal tools
✔ HTTP Bridge Status returns disconnected when no session is active
✔ HTTP Bridge Handshake registers studio session
✔ Executing a command dispatches over polling RPC and resolves with response
✔ 11 Providers are registered and operational in ProviderRegistry
✔ Universal Capability Engine resolves across 4-tier hierarchy
✔ MultiModeEngine handles operating mode transitions and permissions
✔ Live Dashboard endpoint returns comprehensive real-time telemetry
✔ Visual Construction Engine lists rich archetypes and templates
✔ Animation Authoring Engine calibrates tool grips and keyframe sequences

📄 ライセンス

このプロジェクトは MITライセンス の下でライセンスされています。Roblox StudioでのAIネイティブなゲーム開発体験をお楽しみください！ 🎮⚡