Vibe Blocks MCP

Roblox Studio 的 Vibe Blocks MCP

通过模型上下文协议 (MCP) 将 Roblox Studio 连接到 AI 编码编辑器（如 Cursor、Windsurf、Claude 等），从而实现 Roblox Studio 环境中的 AI 辅助游戏开发。

概述

该项目主要由两部分组成：

1. **Python MCP 服务器：**一个在本地运行的 FastAPI 服务器。它通过 MCP（使用服务器发送事件 - SSE）将 Roblox Studio 操作作为工具公开。如果已配置，它可以选择性地与 Roblox Open Cloud API 进行交互。
2. Lua Companion 插件： Roblox Studio 插件 ( roblox_mcp_plugin/src/Plugin.server.lua )，在 Studio 内部运行。它会轮询本地 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 访问的任务很有用）。
  • **数据存储：**列出存储，获取、设置和删除标准数据存储中的键值条目。
  • **资产：**从本地文件上传新资产（模型、图像、音频）。
  • **发布：**发布某个地点当前保存或发布的版本。
  • **（计划）：**获取资产详情，列出用户资产。

设置

1. 先决条件：

• Python >= 3.10
• uv包管理器（安装 uv ）。强烈建议使用这个，以便更快地管理依赖项。
• Roblox工作室
• **（可选）**用于 Open Cloud 功能的 Roblox API 密钥。请前往Roblox Creator 控制面板 > 凭据 获取。您需要获得所需 API 的权限（例如数据存储、资源上传、发布、Luau 执行等）。
• **（可选）**您的 Roblox Universe ID 和目标地点 ID（开放云功能所需）。

2.克隆存储库：

3.安装依赖项：

使用uv （推荐）：

或者，使用pip ：

4.配置环境（可选 - 对于云功能）：

• 如果您计划使用 Open Cloud 工具（DataStores、Asset Upload、Publishing、Cloud Luau），请复制示例环境文件：
  cp .env.example .env
• 编辑.env文件：
  • 用您的 Roblox API 密钥替换"YOUR_API_KEY_HERE" 。
  • 将ROBLOX_UNIVERSE_ID中的0替换为您的 Universe ID。
  • 将ROBLOX_PLACE_ID中的0替换为目标地点 ID。
• **如果您不需要云功能，可以跳过创建.env文件。**服务器仍会运行，但与云相关的工具将返回错误。

5.在 Roblox Studio 中安装 Companion 插件：

• **安装 Rojo：**如果您尚未安装 Rojo，请按照Rojo 网站上的说明进行操作。
• **构建插件（可选）：**导航到终端中的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）连接：

• 该服务可与任何通过服务器发送事件 (SSE) 支持模型上下文协议 (MCP) 的 AI 客户端配合使用，例如 Cursor、Windsurf 或 Claude Desktop 的未来版本。
• 使用游标的示例：
  • 转到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 下查找所有类名为‘Script’的实例。”
• “在 Studio 中执行此脚本： print(game:GetService('Lighting').ClockTime) ”
• “将 Lighting 的ClockTime属性设置为 14。”
• 克隆“ReplicatedStorage.Templates.EnemyNPC”，并将其命名为“Guard1”。将其设置为 Workspace 的父级。
• “让名为‘Workspace.Guard1’的模型播放动画资产 123456789。”
• “修改‘Workspace.DecorationFolder’类名中所有名为‘Part’的子项，将其材质设置为‘Neon’。”
• （云示例） “将‘./assets/MyCoolModel.fbx’上传为名为‘Cool Character Model’的模型。”
• （云示例） “从‘PlayerData’数据存储中获取键‘player_123_score’的值。”
• （云示例） “发布当前地点。”
• “显示 Studio 输出的最新日志。”

可用工具

（工具可以直接与 Studio 插件或 Roblox Open Cloud API 交互）

工作室插件工具（实时互动）：

• 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 输出窗口捕获的最新日志。

打开云 API 工具（可选 - 需要.env设置）：

• execute_luau_in_cloud ：通过 Roblox Cloud API 执行任意 Luau 脚本（在单独的云环境中运行，而不是实时 Studio）。
• list_datastores_in_cloud ：通过云 API 列出标准数据存储。
• get_datastore_value_in_cloud ：通过云 API 从标准数据存储中获取条目的值。
• set_datastore_value_in_cloud ：通过云 API 设置标准数据存储区中条目的值。
• delete_datastore_value_in_cloud ：通过云 API 从标准数据存储中删除条目。
• upload_asset_via_cloud ：通过 Cloud API 将文件从本地系统上传为新的 Roblox 资产。
• publish_place_via_cloud ：通过云 API 发布指定地点。
• get_asset_details_via_cloud ：（未实现）通过云 API 获取有关特定资产的详细信息。
• list_user_assets_via_cloud ：（未实现）通过云 API 列出经过身份验证的用户拥有的资产。
• send_chat_via_cloud ：通过云 API（execute_luau）向游戏内聊天发送消息。
• teleport_player_via_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 所需的权限。
• **权限：**如果您从本地文件加载而不是正确安装，则配套插件需要脚本注入权限才能正常运行。