Robloxstudio MCP

🚀 Roblox Studio MCP Server

強力なMCP（Model Context Protocol）サーバーで、AIアシスタントにRoblox Studioプロジェクトへの包括的なアクセスを提供します。ゲームアーキテクチャを探索し、スクリプトを分析し、問題をデバッグし、大量編集用の一括操作を含む18の専用AIツールを通じて複雑なRobloxプロジェクトを理解できます。

🚀 クイックスタート

⚡ クイックスタート（1コマンド）

Claude Codeユーザー向け:

claude mcp add robloxstudio -- npx -y robloxstudio-mcp

その他のMCPクライアント（Claude Desktopなど）向け:

{
  "mcpServers": {
    "robloxstudio-mcp": {
      "command": "npx",
      "args": ["-y", "robloxstudio-mcp"],
      "description": "Advanced Roblox Studio integration for AI assistants"
    }
  }
}

✨ 主な機能

このシステムは、Roblox StudioとAIアシスタントを橋渡しする2コンポーネントシステムです。以下のような機能を備えています。

• 18の強力なAIツール：ファイルシステム、スタジオコンテキスト、インスタンスとプロパティ、オブジェクト作成、プロジェクト分析など、様々な分野で利用できます。
• 一括操作機能：大量のオブジェクトに対する一括プロパティ編集やオブジェクト作成が可能です。
• スマートなプロジェクト構造：サービスの概要表示、パスベースの探索、スクリプトのみのフィルタリングなど、柔軟なプロジェクト探索ができます。
• 豊富なメタデータ：スクリプトの状態、GUIの情報など、詳細なメタデータを提供します。

📦 インストール

🔌 スタジオプラグインのセットアップ（必須）

MCPサーバーには、Roblox Studio用のコンパニオンプラグインが必要です。

1. Roblox Creator Store (最も簡単 ⭐):

   • こちらからインストールします: https://create.roblox.com/store/asset/132985143757536
   • "Install"をクリックすると、自動的にスタジオで開きます。

2. 手動ダウンロード:

   • MCPPlugin.rbxmxをダウンロードします。
   • %LOCALAPPDATA%/Roblox/Pluginsフォルダに保存します。

3. 高度なセットアップ:

   • 他の方法については、studio-plugin/INSTALLATION.mdを参照してください。

インストール後:

• ✅ ゲーム設定 → セキュリティで"Allow HTTP Requests"を有効にします。
• 🔘 プラグインツールバーの"MCP Server"ボタンをクリックします。
• 🟢 正常に動作している場合は、ステータスが"Connected"と表示されます。

🔧 技術詳細

🏗️ アーキテクチャの概要

%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#718096', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#2b6cb0', 'tertiaryColor':'#319795'}}}%%
graph TB
    subgraph AI_ENV ["🤖 AI Environment"]
        AI["🤖 AI Assistant<br/>Claude Code/Desktop"]
        MCP["📡 MCP Server<br/>Node.js + TypeScript"]
    end
    
    subgraph COMM_LAYER ["🔗 Communication Layer"]
        HTTP["🌐 HTTP Bridge<br/>localhost:3002"]
        QUEUE["📋 Request Queue<br/>UUID tracking"]
    end
    
    subgraph STUDIO_ENV ["🎮 Roblox Studio Environment"]
        PLUGIN["🎮 Studio Plugin<br/>Luau Script"]
        STUDIO["🎯 Roblox Studio<br/>APIs & Data"]
    end
    
    subgraph TOOLS ["🛠️ 18 AI Tools"]
        FILE["📁 File System<br/>Trees, Search"]
        CONTEXT["🎯 Studio Context<br/>Services, Objects"]
        PROPS["🔍 Properties<br/>Get, Set, Mass Ops"]
        CREATE["🏗️ Object Creation<br/>Single, Mass, Properties"]
        PROJECT["🏢 Project Analysis<br/>Smart Structure"]
    end
    
    AI -->|stdio| MCP
    MCP -->|HTTP POST| HTTP
    HTTP -->|Queue Request| QUEUE
    PLUGIN -->|Poll every 500ms| HTTP
    HTTP -->|Pending Work| PLUGIN
    PLUGIN -->|Execute APIs| STUDIO
    STUDIO -->|Return Data| PLUGIN
    PLUGIN -->|HTTP Response| HTTP
    HTTP -->|Resolve Promise| MCP
    MCP -->|Tool Result| AI
    
    MCP -.->|Exposes| FILE
    MCP -.->|Exposes| CONTEXT  
    MCP -.->|Exposes| PROPS
    MCP -.->|Exposes| CREATE
    MCP -.->|Exposes| PROJECT
    
    classDef aiStyle fill:#1e40af,stroke:#3b82f6,stroke-width:2px,color:#ffffff
    classDef mcpStyle fill:#7c3aed,stroke:#8b5cf6,stroke-width:2px,color:#ffffff
    classDef httpStyle fill:#ea580c,stroke:#f97316,stroke-width:2px,color:#ffffff
    classDef pluginStyle fill:#059669,stroke:#10b981,stroke-width:2px,color:#ffffff
    classDef studioStyle fill:#dc2626,stroke:#ef4444,stroke-width:2px,color:#ffffff
    classDef toolStyle fill:#0891b2,stroke:#06b6d4,stroke-width:2px,color:#ffffff
    
    class AI aiStyle
    class MCP mcpStyle
    class HTTP,QUEUE httpStyle
    class PLUGIN pluginStyle
    class STUDIO studioStyle
    class FILE,CONTEXT,PROPS,CREATE,PROJECT toolStyle

主要コンポーネント:

• 🧠 MCPサーバー (Node.js/TypeScript) - 18のツールをstdio経由でAIと統合します。
• 🔗 HTTPブリッジ - localhost:3002でリクエスト/レスポンスキューを管理し、30秒のタイムアウトが設定されています。
• 🎮 スタジオプラグイン (Luau) - 500ミリ秒ごとにポーリングし、スタジオAPI呼び出しを実行し、エラーを処理します。
• 📊 スマートキャッシング - インテリジェントなレスポンス制限により、効率的なデータ転送を実現します。

🛠️ 18の強力なAIツール

📁 ファイルシステムツール

• get_file_tree - スクリプト、モデル、フォルダを含む完全なプロジェクト階層を取得します。
• search_files - 名前、タイプ、または内容のパターンでファイルを検索します。

🎯 スタジオコンテキストツール

• get_place_info - 場所のID、名前、ゲーム設定、ワークスペース情報を取得します。
• get_services - すべてのRobloxサービスとその子要素の数を取得します。
• search_objects - 名前、クラス、またはプロパティでインスタンスを検索します。

🔍 インスタンスとプロパティツール

• get_instance_properties - 任意のオブジェクトの完全なプロパティダンプを取得します。
• get_instance_children - メタデータ（スクリプト、GUIタイプなど）付きの子オブジェクトを取得します。
• search_by_property - 特定のプロパティ値を持つオブジェクトを検索します。
• get_class_info - Robloxクラスの利用可能なプロパティ/メソッドを取得します。

⚡ プロパティ変更ツール

• set_property - 任意のRobloxインスタンスのプロパティを設定します。
• mass_set_property - 🆕 新機能! 複数のインスタンスに同時に同じプロパティを設定します。
• mass_get_property - 🆕 新機能! 複数のインスタンスから同時に同じプロパティを取得します。

🏗️ オブジェクト作成ツール

• create_object - 新しいRobloxオブジェクトインスタンスを作成します（基本）。
• create_object_with_properties - 🆕 新機能! 初期プロパティを持つオブジェクトを作成します。
• mass_create_objects - 🆕 新機能! 一度に複数のオブジェクトを作成します（基本）。
• mass_create_objects_with_properties - 🆕 新機能! プロパティを持つ複数のオブジェクトを作成します。
• delete_object - Robloxオブジェクトインスタンスを削除します。

🏢 プロジェクト分析ツール

• get_project_structure - 🔥 強化版! 改善された深さ制御を備えたスマートな階層構造を取得します（推奨: 深さ5 - 10）。

⚠️ 注意: 以前のツールである get_file_content、get_file_properties、get_selection、get_dependencies、validate_references は削除されました。より良いパフォーマンスのために、Rojo/Argonワークフローまたはファイルシステムの読み取りを使用してください。

🧠 AI最適化機能

🚀 一括操作（v1.3.0での新機能）

• 一括プロパティ編集: 数百のインスタンスに対して同じプロパティを瞬時に設定できます。
• 大量オブジェクト作成: 1回の呼び出しで複雑なオブジェクト階層を作成できます。
• バッチプロパティ読み取り: 複数のオブジェクトから効率的にプロパティを取得できます。
• アトミック操作: すべての一括操作は、単一のアンドゥ/リドゥポイントにグループ化されます。

使用例:

// ワークスペース内のすべてのパーツを赤色に設定する
mass_set_property(["game.Workspace.Part1", "game.Workspace.Part2"], "BrickColor", "Really red")

// プロパティ付きで10個のパーツを作成する
mass_create_objects_with_properties([
  {className: "Part", parent: "game.Workspace", name: "RedPart", properties: {BrickColor: "Really red"}},
  {className: "Part", parent: "game.Workspace", name: "BluePart", properties: {BrickColor: "Really blue"}}
])

スマートなプロジェクト構造

• サービス概要モード: 子要素の数を含むクリーンなサービスリストを表示します。
• パスベースの探索: get_project_structure("game.ServerStorage", maxDepth=5) のように、特定のパスを指定して探索できます。
• スクリプトのみのフィルタリング: scriptsOnly=true を指定することで、コード分析に特化した探索ができます。
• インテリジェントなグルーピング: 大きなフォルダはクラスタイプで自動的にグループ化されます。
• 強化された深さ制御: 推奨maxDepth=5 - 10 で、包括的な探索が可能です。

豊富なメタデータ

• スクリプトの状態: 有効/無効、ソース検出、スクリプトタイプなどの情報を提供します。
• GUIのインテリジェンス: テキスト内容、可視性、コンテナとインタラクティブの区別などの情報を提供します。
• パフォーマンス最適化: 冗長なツールを削除し、高速な操作を実現します。

🚀 開発とテスト

コマンド

npm run dev         # ホットリロード付きの開発サーバーを起動します
npm run build       # 本番用のビルドを行います
npm start           # ビルドされたサーバーを実行します
npm run lint        # ESLintによるコード品質チェックを行います
npm run typecheck   # TypeScriptのバリデーションを行います

プラグイン開発

• ライブリロード: プラグインはサーバーの変更を自動的に検出して更新します。
• エラーハンドリング: 堅牢なタイムアウトとリトライメカニズムが備わっています。
• デバッグモード: スタジオの出力ウィンドウに詳細なログが表示されます。
• 接続ステータス: プラグインのUIに視覚的なインジケーターが表示されます。

📊 通信プロトコル

%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#10b981', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#3b82f6', 'tertiaryColor':'#8b5cf6', 'background':'#1a202c', 'mainBkg':'#2d3748', 'secondBkg':'#374151', 'tertiaryColor':'#6366f1'}}}%%
sequenceDiagram
    participant AI as 🤖 AI Assistant
    participant MCP as 📡 MCP Server  
    participant HTTP as 🌐 HTTP Bridge
    participant PLUGIN as 🎮 Studio Plugin
    participant STUDIO as 🎯 Roblox Studio
    
    Note over AI,STUDIO: 🚀 ツールリクエストフロー
    
    AI->>+MCP: Call tool (e.g., get_file_tree)
    MCP->>+HTTP: Queue request with UUID
    HTTP->>HTTP: Store in pending requests map
    HTTP-->>-MCP: Request queued ✅
    
    Note over PLUGIN: 🔄 500ミリ秒ごとにポーリング
    PLUGIN->>+HTTP: GET /poll
    HTTP->>-PLUGIN: Return pending request + UUID
    
    PLUGIN->>+STUDIO: Execute Studio APIs
    Note over STUDIO: 🎯 game.ServerStorage<br/>📋 Selection:Get()<br/>🔍 Instance properties
    STUDIO->>-PLUGIN: Return Studio data 📊
    
    PLUGIN->>+HTTP: POST /response with UUID + data
    HTTP->>-MCP: Resolve promise with data
    MCP->>-AI: Return tool result 🎉
    
    Note over AI,STUDIO: ⚠️ エラーハンドリング
    
    alt Request Timeout (30s)
        HTTP->>MCP: Reject promise with timeout ⏰
        MCP->>AI: Return error message ❌
    end
    
    alt Plugin Disconnected
        PLUGIN->>HTTP: Connection lost 🔌
        HTTP->>HTTP: Exponential backoff retry 🔄
        Note over PLUGIN: Status: "Waiting for server..." ⏳
    end

特徴:

• 🕐 30秒のタイムアウト と指数バックオフ機能が備わっています。
• 🔄 ネットワーク問題に対する自動リトライ 機能があります。
• 📏 レスポンス制限 により、コンテキストオーバーフローを防止します。
• 🎯 リクエストの重複排除 により、効率的な処理が可能です。

💻 使用例

// サービスの概要を取得する
get_project_structure()

// 武器フォルダを探索する
get_project_structure("game.ServerStorage.Weapons", maxDepth=2)

// すべてのSoundオブジェクトを検索する
search_by_property("ClassName", "Sound")

// スクリプトの依存関係を確認する
get_dependencies("game.ServerScriptService.MainScript")

// 壊れた参照を検索する
validate_references()

// UIコンポーネントの詳細を取得する
get_instance_properties("game.StarterGui.MainMenu.SettingsFrame")

🔧 設定

環境変数:

• MCP_SERVER_PORT - MCPサーバーのポート（デフォルト: stdio）
• HTTP_SERVER_PORT - HTTPブリッジのポート（デフォルト: 3002）
• PLUGIN_POLL_INTERVAL - プラグインのポーリング頻度（デフォルト: 500ミリ秒）
• REQUEST_TIMEOUT - リクエストのタイムアウト（デフォルト: 30000ミリ秒）

スタジオ設定:

• ✅ HTTPリクエストを許可する（ゲーム設定 → セキュリティ）
• 🌐 HttpService.HttpEnabled = true
• 🔌 ツールバーのボタンをクリックして、プラグインをアクティブにする

📋 変更履歴

v1.3.0 - 一括操作アップデート（最新）

• ➕ 新機能: mass_set_property - 一括プロパティ変更
• ➕ 新機能: mass_get_property - バッチプロパティ読み取り
• ➕ 新機能: create_object_with_properties - 初期プロパティ付きのオブジェクト作成
• ➕ 新機能: mass_create_objects - 大量オブジェクト作成
• ➕ 新機能: mass_create_objects_with_properties - プロパティ付きの大量オブジェクト作成
• 🔥 強化: get_project_structure の深さパラメータのドキュメントが改善されました。
• 🗑️ 削除: get_file_content、get_file_properties、get_selection、get_dependencies、validate_references（代わりにRojo/Argonワークフローを使用してください）
• ⚡ パフォーマンス: 18の重点的なツールによりAPIが合理化され、以前の15の汎用ツールから改善されました。

v1.2.0 - プロパティ変更

• ➕ set_property ツールを追加して、インスタンスの変更を可能にしました。
• ➕ create_object と delete_object ツールを追加しました。
• 🔧 エラーハンドリングとバリデーションを強化しました。

v1.1.0 - 強化された探索機能

• 🔍 プロジェクト構造の分析を改善しました。
• 📊 メタデータの抽出を向上させました。
• 🎯 スクリプトとGUIのインテリジェンスを強化しました。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。商用および個人プロジェクトで自由に使用できます！