振动块MCP服务器

Name: 振动块MCP服务器
Author: majidmanzarpour

作者：majidmanzarpour62 星标更新：2025-05-25

安装使用来源：spider==github.com

项目介绍

Vibe Blocks MCP for Roblox Studio

将Roblox Studio连接到AI编码编辑器（如Cursor、Windsurf、Claude等）通过模型上下文协议（MCP），使AI辅助游戏开发在您的Roblox Studio环境中成为可能。

概述

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

Python MCP服务器： 运行在本地的FastAPI服务器。它通过MCP（使用服务端发送事件 - SSE）公开Roblox Studio操作作为工具。如果已配置，它可以可选地与Roblox Open Cloud API进行交互。
Lua伴随插件： 运行在Studio内的Roblox Studio插件（roblox_mcp_plugin/src/Plugin.server.lua）。它轮询本地Python服务器获取命令，在Studio上下文中执行这些命令（操纵实例、读取属性、执行Luau），并将结果和Studio日志返回给服务器。

这允许通过MCP连接的AI代理理解并与其实时Roblox Studio会话进行交互。

功能

实时Studio交互：
- 场景操作： 在Studio场景中直接创建、删除、克隆、移动、缩放对象（部件、模型、脚本等）的属性（包括PrimaryPart）。
- 场景检查： 获取对象属性，列出子项，根据类或名称在Studio内查找实例。
- 脚本： 创建、编辑和删除脚本/局部脚本。直接在Studio环境中执行任意Luau代码并捕获输出/错误。
- 环境： 设置光照或地形服务的属性。
- 动画： 在人形或动画控制器上播放动画。
- NPC： 通过克隆现有模板或从资产ID插入来生成NPC。
- 修改子项： 根据过滤条件对对象的多个子项应用属性更改。
- Studio日志： 从Studio输出窗口检索最近的日志。
Roblox Open Cloud集成（可选 - 需要API密钥）：
- Luau执行（云）： 在单独的云环境中运行Luau代码（适用于不需要实时Studio访问的任务）。
- 数据存储： 列出存储，获取、设置和删除标准数据存储中的键值条目。
- 资产： 从本地文件上传新的资产（模型、图像、音频）。
- 发布： 发布当前保存或发布的地点版本。
- （计划）： 获取资产详情，列出用户资产。

安装

1. 先决条件：

Python >= 3.10
uv 包管理器（安装uv）。强烈推荐用于更快的依赖管理。
Roblox Studio
（可选） Roblox API密钥以启用Open Cloud功能。从Roblox创作者仪表板 > 凭证获取。您需要为打算使用的API（数据存储、资产上传、发布、Luau执行等）获取权限。
（可选） 您的Roblox宇宙ID和目标地点ID（用于Open Cloud功能）。

2. 克隆仓库：

git clone https://github.com/majidmanzarpour/vibe-blocks-mcp 
cd vibe-blocks-mcp

3. 安装依赖：

使用uv（推荐）：

uv pip sync pyproject.toml

或者使用pip：

pip install -r requirements.lock # 或者根据需要从pyproject.toml创建requirements.txt

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

如果您计划使用Open Cloud工具（数据存储、资产上传、发布、云Luau），复制示例环境文件：
```
cp .env.example .env
```
编辑.env文件：
- 将"YOUR_API_KEY_HERE"替换为您的Roblox API密钥。
- 将ROBLOX_UNIVERSE_ID的0替换为您自己的宇宙ID。
- 将ROBLOX_PLACE_ID的0替换为目标地点ID。
如果您不需要云功能，可以跳过创建.env文件。 服务器仍然可以运行，但与云相关的工具将返回错误。

5. 在Roblox Studio中安装伴随插件：

安装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脚本顶部的SERVER_URL变量（roblox_mcp_plugin/src/Plugin.server.lua）并重新构建插件。

6. 运行Python服务器：

在项目根目录中打开终端。
将服务器脚本设为可执行（如果尚未这样做）：
```
chmod +x server.sh 
```
运行服务器：
```
./server.sh
```
服务器将启动，检查/安装uvicorn（如有必要），并在日志中显示正在http://localhost:8000运行。
使用服务期间请保持此终端窗口打开。

7. 从MCP客户端连接（例如，Cursor）：

此服务支持任何通过服务端发送事件（SSE）支持模型上下文协议（MCP）的AI客户端，如Cursor、Windsurf或未来版本的Claude Desktop。
使用Cursor的示例：
- 转到文件 > 设置 > MCP（或Mac上的代码 > 设置 > MCP）。
- 点击“添加新全局MCP服务器”。
- 输入SSE URL: http://localhost:8000/sse（确保包含末尾的/sse）。
- 您可能需要编辑mcp.json文件
```
{
"mcpServers": {
  "Vibe Blocks MCP": {
    "url": "http://localhost:8000/sse"
    }
  }
}
```
客户端现在应该检测到“Vibe Blocks MCP”工具源及其可用工具。

使用

一旦服务器运行，插件安装在Studio中，并且您的MCP客户端已连接，您可以通过AI与您的Studio会话进行交互。

向代理（如果您的客户端需要提及工具，例如list_children）发出指令，请求其执行操作。

示例提示：

“在工作区中创建一个名为‘Floor’的亮红色部件。将其大小设置为（100, 2, 100），位置设置为（0, -1, 0）。将其锚定。”
“删除名为‘Workspace.OldPlatform’的对象。”
“‘Workspace.SpawnLocation’的位置属性是什么？”
“列出ServerScriptService的子项。”
“找到ServerScriptService下所有类名为‘Script’的实例。”
“在Studio中执行此脚本：print(game:GetService('Lighting').ClockTime)”
“将照明的ClockTime属性设置为14。”
“克隆‘ReplicatedStorage.Templates.EnemyNPC’并命名为‘Guard1’。将其父级设置为工作区。”
“让名为‘Workspace.Guard1’的模型播放动画资产123456789。”
“修改‘Workspace.DecorationFolder’的所有子项，类名为‘Part’，将其材质设置为‘Neon’。”
（云示例） “上传‘./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：根据类名或名称在指定根内查找实例。
create_instance：在Studio中创建一个新的实例（部件、模型、脚本等）。
delete_instance：从Studio场景中删除对象。
set_property：在Studio中的对象上设置特定属性（使用JSON字符串作为值）。
set_primary_part：设置模型的PrimaryPart属性。
move_instance：将对象（模型或基本部件）移动到Studio中的新位置。
clone_instance：在Studio中克隆现有对象。
create_script：在Studio中创建一个新的脚本或局部脚本实例，带有提供的代码。
edit_script：编辑Studio中现有脚本或局部脚本的源代码。
delete_script：删除Studio中的现有脚本或局部脚本实例。
set_environment：在Studio中设置环境服务（光照或地形）的属性。
spawn_npc：在Studio中生成NPC，通过插入资产ID的模型或克隆现有模板模型。
play_animation：在目标对象的人形或动画控制器上加载并播放动画。
execute_luau_in_studio：通过插件在LIVE Studio会话中执行任意Luau脚本，并捕获输出/返回值/错误。
modify_children：找到匹配可选过滤条件（名称/类）的直接子项，并在其上设置指定属性。
get_studio_logs：通过插件从Roblox Studio输出窗口检索最近的日志。

Open 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（执行Luau）发送消息到游戏中聊天。
teleport_player_via_cloud：通过Cloud API（执行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密钥、宇宙ID和地点ID的.env文件。确保您的API密钥具有尝试使用的特定云API所需的权限。
权限： 如果您从本地文件加载伴随插件而不是正确安装，它需要脚本注入权限才能正常工作。