roblox-studio-mcp

Roblox Studio MCP：远程控制 Studio

Studio MCP 可让你在正在运行的 Studio 中执行代码、检查／修改数据模型、截屏并生成内容。本文是工具箱参考；如需了解磁盘→Rojo→测试开发循环，请参阅 roblox-studio-workflow 技能。

连接（以及修复失效的连接）

• Studio 会主动连接到 MCP hub 并注册其工具。如果 Studio 从未连接，MCP 会返回 0 个工具——ToolSearch/mcp__Roblox_Studio__* 找不到任何内容。
• 在 Studio 中启用： Assistant 面板 → Assistant Settings → "Enable Studio as MCP server"。在 "Manage MCP Servers" 下看到绿色指示灯 = 已连接。文档：create.roblox.com/docs/studio/mcp
• 修复失效连接（按顺序）：（1）在 Codex 会话运行期间关闭再开启 "Enable Studio as MCP server"；（2）保存该设置后重启 Studio；（3）已经打开的 Codex 会话可能仍保留空的工具列表——通过 /mcp 重新连接，或启动新会话。在 MCP 尚不存在时就自动更新并重新启动的 Studio，是典型的“已启用但未连接”情况。
• MCP 连接可能在会话中途悄然断开（服务断开连接）——断开后，工具会消失，直到 Studio 重新连接。如果工具调用开始失败，请先检查连接是否已断开，再判断是否为代码问题。

核心工具（已验证，频繁使用）

• execute_luau — 在 Studio 中运行 Luau。需要设置 datamodel_type：Edit | Server | Client。它运行在独立的 Lua VM 中：数据模型是共享的（Instances、PlayerGui、Workspace、Net 远程对象），但 require() 模块状态不共享——你会得到一个全新副本，因此无法读取或修改运行中模块的单例。FireAllClients 只能从 Server 调用。此处可使用合成输入测试纯函数。
• start_stop_play — is_start 布尔值（true=开始，false=停止）。应配合等待 Rojo 同步（见工作流技能），避免测试过期代码。
• get_console_output — 读取输出／错误。每次启动后都要检查，以发现未显现的故障（例如 "Out of local registers"、卡住的 WaitForChild、服务错误）。
• screen_capture — 需要 capture_id。需要注意的情况：自由摄像机／脚本控制的摄像机可能会隐藏 ScreenGui；远处的 SurfaceGui 特写可能渲染为空白——这些是截屏问题，不是游戏问题（可通过实例查询交叉核对）。点击坐标使用 GUI 的 AbsolutePosition 坐标空间，而非截图像素——请先读取 AbsolutePosition + AbsoluteSize/2。
• user_mouse_input / user_keyboard_input — 模拟输入。两者也需要设置 datamodel_type（从架构中不容易看出）。user_mouse_input 支持使用 instance_path 形式点击 GUI 对象，无需坐标。当核心 UI（聊天、菜单）占有焦点时，键盘输入会因 "CoreGUI has keyboard focus" 而失败。注意：在 execute_luau 中调用 VirtualInputManager:SendMouseButtonEvent 会失败（"lacking capability"）——请改用这些 MCP 输入工具。
• inspect_instance / search_game_tree — 检查／查找数据模型中的实例。
• script_read / script_grep / script_search — 读取／搜索当前数据模型中的脚本。可用于确认 Rojo 确实已同步最新修改：先用 script_grep 搜索新添加的注释字符串，再进行游戏测试。

内容生成与资源工具（此处大多尚未尝试——请探索并验证行为）

• generate_mesh — 根据提示词由 AI 生成 MeshPart。generate_material — AI 生成材质/SurfaceAppearance。generate_procedural_model — 生成完整的程序化模型。这些操作可能是异步的 → 搭配 wait_job_finished 使用。适合制作道具/地形/初版模型；尚未实际测试——请验证质量以及结果如何写入数据模型。
• insert_asset（接受 assetId）— 插入 Creator Store 资源。search_asset — 仅搜索 Creator Store（Models/Images/Decals 等），不搜索 Avatar Marketplace（服装/头发需要使用目录 Web API——参见 roblox-avatar-appearance）。
• upload_image / store_image — 上传本地 PNG → rbxassetid://。upload_image 接受 imagePaths，且需要 http/https URL（本地路径会失败）：通过 localhost 提供文件夹服务（python3 -m http.server 8777），传入 http://localhost:8777/foo.png，获取返回的 id；完成后关闭服务（pkill -f "http.server 8777"）。字节完全相同的图片会去重为同一个 id（重新上传是安全的）。支持批量上传（可一次上传多张）。http_get — 从 Studio 获取 URL。
• character_navigation — 移动/导航玩家角色（尚未尝试；可用于在截图或触发近距离交互前走到指定位置）。
• get_studio_state / list_roblox_studios / set_active_studio — 多 Studio 管理；当有多个 Studio 正在运行时，将工具指向特定的已打开 Studio。
• multi_edit — 编辑数据模型中的脚本。避免用于在磁盘上编写的（Rojo）脚本——这会造成偏差/重复实例（这些脚本应在磁盘上编写；参见 roblox-studio-workflow）。仅用于只存在于数据模型中的脚本。

黄金规则

• execute_luau 和输入工具都必须指定 datamodel_type——服务器 API（DataStore、MessagingService、FireAllClients、LoadAsset）选择 Server，PlayerGui/本地检查选择 Client，播放前的数据模型/属性更改选择 Edit。
• 在 Edit 模式下设置 place 属性/几何体，以确保其持久化（要使其永久生效，需要保存 place）；代码应通过 Rojo 写入磁盘，而不是通过 MCP。
• 通过可观察到的 Instance 副作用进行验证，绝不要读取正在运行的模块内部字段（跨 VM）。参见 roblox-studio-workflow 中的测试策略。
• 如果任务中途工具消失，请先怀疑链接中断（见上文），而不是代码错误。