Robloxstudio Mcp

Robloxstudio Mcp

娱乐 TypeScript

🚀 Roblox Studio MCP Server

Roblox Studio MCP Server 是一个强大的 MCP（模型上下文协议）服务器，它使 AI 助手能够全面访问 Roblox Studio 项目。借助 18 种专业的 AI 工具，包括用于批量编辑的批量操作功能，用户可以探索游戏架构、分析脚本、调试问题并深入理解复杂的 Roblox 项目。

🚀 快速开始

⚡ 一键启动

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"
}
}
}

📦 安装指南

🔌 工作室插件设置（必需）

MCP 服务器需要一个配套的 Roblox Studio 插件，你可以通过以下方式进行安装：

  1. Roblox 创作者商店（最简单 ⭐）：

    • 从 此处 安装。
    • 点击“安装”，插件将自动在 Studio 中打开。

  2. 手动下载：

    • 下载 MCPPlugin.rbxmx。
    • 将其保存到 %LOCALAPPDATA%/Roblox/Plugins 文件夹中。

  3. 高级设置：

    • 更多方法请参考 [studio - plugin/INSTALLATION.md](studio - plugin/INSTALLATION.md)。

安装完成后：

  • ✅ 在游戏设置的“安全”选项中启用“允许 HTTP 请求”。
  • 🔘 点击插件工具栏中的“MCP 服务器”按钮。
  • 🟢 当一切正常时，状态应显示为“已连接”。

🏗️ 架构概述

这是一个将 Roblox Studio 与 AI 助手连接起来的双组件系统：

%%{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 环境"]
AI["🤖 AI 助手
Claude Code/Desktop"]
MCP["📡 MCP 服务器
Node.js + TypeScript"]
end

subgraph COMM_LAYER ["🔗 通信层"]
HTTP["🌐 HTTP 桥接
localhost:3002"]
QUEUE["📋 请求队列
UUID 跟踪"]
end

subgraph STUDIO_ENV ["🎮 Roblox Studio 环境"]
PLUGIN["🎮 工作室插件
Luau 脚本"]
STUDIO["🎯 Roblox Studio
API 与数据"]
end

subgraph TOOLS ["🛠️ 18 种 AI 工具"]
FILE["📁 文件系统
树状结构、搜索"]
CONTEXT["🎯 工作室上下文
服务、对象"]
PROPS["🔍 属性
获取、设置、批量操作"]
CREATE["🏗️ 对象创建
单个、批量、属性设置"]
PROJECT["🏢 项目分析
智能结构"]
end

AI -->|stdio| MCP
MCP -->|HTTP POST| HTTP
HTTP -->|队列请求| QUEUE
PLUGIN -->|每 500ms 轮询一次| HTTP
HTTP -->|待处理工作| PLUGIN
PLUGIN -->|执行 API| STUDIO
STUDIO -->|返回数据| PLUGIN
PLUGIN -->|HTTP 响应| HTTP
HTTP -->|解析承诺| MCP
MCP -->|工具结果| AI

MCP -.->|暴露| FILE
MCP -.->|暴露| CONTEXT
MCP -.->|暴露| PROPS
MCP -.->|暴露| CREATE
MCP -.->|暴露| 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 种工具，用于 AI 集成。
  • 🔗 HTTP 桥接：在 localhost:3002 上的请求/响应队列，超时时间为 30 秒。
  • 🎮 工作室插件（Luau）：每 500 毫秒轮询一次，执行 Studio 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 新增）

  • 批量属性编辑：瞬间为数百个实例设置相同的属性。
  • 批量对象创建：通过一次调用创建复杂的对象层次结构。
  • 批量属性读取：高效地从多个对象获取属性。
  • 原子操作：所有批量操作都被分组为单个撤销/重做关键点。

示例用例：

// 将工作区中的所有部件设置为红色
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 用于代码分析。
  • 智能分组：大型文件夹按类类型自动分组。
  • 增强的深度控制：建议最大深度为 5 - 10，以进行全面探索。

丰富的元数据

  • 脚本状态：启用/禁用、源检测、脚本类型。
  • GUI 智能：文本内容、可见性、容器与交互式。
  • 性能优化：移除冗余工具以实现更快的操作。

💻 使用示例

// 获取服务概述
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")

🚀 开发与测试

命令

npm run dev         # 带有热重载的开发服务器
npm run build       # 生产构建
npm start           # 运行构建后的服务器
npm run lint        # ESLint 代码质量检查
npm run typecheck   # TypeScript 验证

插件开发

  • 实时重载：插件更新会自动检测服务器更改。
  • 错误处理：强大的超时和重试机制。
  • 调试模式：在 Studio 输出窗口中进行详细日志记录。
  • 连接状态：插件 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 助手
participant MCP as 📡 MCP 服务器
participant HTTP as 🌐 HTTP 桥接
participant PLUGIN as 🎮 工作室插件
participant STUDIO as 🎯 Roblox Studio

Note over AI,STUDIO: 🚀 工具请求流程

AI->>+MCP: 调用工具（例如，get_file_tree）
MCP->>+HTTP: 使用 UUID 对请求进行排队
HTTP->>HTTP: 存储在待处理请求映射中
HTTP-->>-MCP: 请求已排队 ✅

Note over PLUGIN: 🔄 每 500ms 轮询一次
PLUGIN->>+HTTP: GET /poll
HTTP->>-PLUGIN: 返回待处理请求 + UUID

PLUGIN->>+STUDIO: 执行 Studio API
Note over STUDIO: 🎯 game.ServerStorage
📋 Selection:Get()
🔍 实例属性
STUDIO->>-PLUGIN: 返回 Studio 数据 📊

PLUGIN->>+HTTP: POST /response 并附带 UUID + 数据
HTTP->>-MCP: 使用数据解析承诺
MCP->>-AI: 返回工具结果 🎉

Note over AI,STUDIO: ⚠️ 错误处理

alt 请求超时（30 秒）
HTTP->>MCP: 因超时而拒绝承诺 ⏰
MCP->>AI: 返回错误消息 ❌
end

alt 插件断开连接
PLUGIN->>HTTP: 连接丢失 🔌
HTTP->>HTTP: 指数退避重试 🔄
Note over PLUGIN: 状态：“等待服务器...” ⏳
end

特性：

  • 🕐 30 秒超时：采用指数退避机制。
  • 🔄 自动重试：处理网络问题。
  • 📏 响应限制：防止上下文溢出。
  • 🎯 请求去重：提高效率。

🔧 配置

环境变量：

  • MCP_SERVER_PORT：MCP 服务器端口（默认：标准输入输出）。
  • HTTP_SERVER_PORT：HTTP 桥接端口（默认：3002）。
  • PLUGIN_POLL_INTERVAL：插件轮询频率（默认：500 毫秒）。
  • REQUEST_TIMEOUT：请求超时时间（默认：30000 毫秒）。

Studio 设置：

  • ✅ 允许 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 工作流代替）。
  • ⚡ 性能：简化 API，从 15 个多用途工具精简为 18 个专注工具。

v1.2.0 - 属性修改

  • ➕ 新增 set_property 工具，用于实例修改。
  • ➕ 新增 create_object 和 delete_object 工具。
  • 🔧 增强错误处理和验证。

v1.1.0 - 增强发现功能

  • 🔍 改进项目结构分析。
  • 📊 更好的元数据提取。
  • 🎯 脚本和 GUI 智能。

📄 许可证

本项目采用 MIT 许可证，你可以自由地将其用于商业和个人项目！

默认排序 时间排序

0 个评论

« 上一篇
Mcp Pokeapi Server
下一篇 »
Amanasmuei_mcp Server Malaysia Prayer Time
  • 0 关注
  • 0 收藏，32 浏览
  • system 提出于 2025-10-07 04:57

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »