🎮 Roblox Studio Ultimate MCP 服务器

English | 日本語

最全面的 Roblox Studio MCP（模型上下文协议）服务器。提供 41 种工具，可从 Claude Code 或任何兼容 MCP 的 AI 助手实现对 Studio 的完全控制。

✨ 为什么需要它

默认的 Roblox Studio MCP 仅提供 run_code —— 这迫使你通过字符串操作 (gsub) 来处理脚本源码。这会导致：

❌ 模式匹配失败
❌ end) 语句损坏
❌ 脚本回滚时的静默丢失
❌ 写入前没有语法检查
❌ 在简单的编辑上浪费数小时

此 MCP 解决了所有这些问题。

🚀 功能

脚本操作（游戏规则改变者）

工具	描述
`getScript`	获取完整源代码
`setScript`	替换整个源码（带语法检查 + 自动备份）
`editScript`	编辑特定行范围（部分编辑！）
`insertCode`	在特定行后插入代码
`removeLines`	删除特定行
`replaceInScript`	查找并替换文本（纯文本，安全）
`getLines`	仅获取特定行范围（轻量级）
`getFunctionList`	列出所有带有行号的函数
`getScriptSummary`	概览：函数、require、全局变量
`listScripts`	列出游戏中的所有脚本
`getAllScripts`	一次性获取所有脚本源码
`searchInScripts`	在所有脚本中搜索关键字
`getReferences`	查找变量/函数的所有用法
`getModuleDependencies`	列出 require() 依赖项

安全机制

功能	描述
🔒 语法检查	写入前自动验证。拒绝错误代码。
💾 自动备份	每次编辑前保存上一个版本（10 个世代）
🛑 运行模式保护	在运行模式下阻止写入（防止静默回滚）
📝 UpdateSourceAsync	使用 ScriptEditorService 进行无冲突写入

备份与恢复

工具	描述
`restoreBackup`	从自动保存的备份中恢复
`listBackups`	列出可用备份

验证

工具	描述
`checkSyntax`	在不写入的情况下检查语法
`verifyScript`	验证行数 / 源码长度
`validateAllScripts`	批量语法检查所有脚本

实例操作

工具	描述
`getTree`	获取实例层级结构
`getChildren`	列出子项（轻量级）
`getProperty` / `setProperty`	获取/设置属性
`createInstance`	创建新实例
`deleteInstance`	删除实例
`cloneInstance`	克隆实例
`renameInstance`	重命名实例
`moveInstance`	移动到不同的父级
`findInstances`	按名称/类搜索实例

其他

工具	描述
`runCode`	执行 Luau 代码（带输出捕获）
`batch`	一次执行多个命令
`getAttribute` / `setAttribute`	属性操作
`getErrors` / `clearErrors`	错误日志管理
`undo` / `redo`	撤销/重做操作
`getSelection`	获取当前选定项
`getStudioInfo`	获取 Studio 信息

📦 安装

1. 克隆并构建

git clone https://github.com/YOUR_USERNAME/roblox-studio-ultimate-mcp.git
cd roblox-studio-ultimate-mcp
npm install
npm run build

2. 安装 Studio 插件

将插件文件复制到你的 Roblox 插件文件夹：

Mac:

cp plugin/UltimateMCP.rbxmx ~/Documents/Roblox/Plugins/

Windows:

copy plugin\UltimateMCP.rbxmx %LOCALAPPDATA%\Roblox\Plugins\

或者从源码生成：

bash generate-plugin.sh

3. 在 Studio 中启用 HTTP

打开 Roblox Studio，然后在命令栏（视图 → 命令栏）中输入：

game:GetService("HttpService").HttpEnabled = true

4. 在 Claude Code 中注册

在相应的项目下添加到你的 ~/.claude.json：

{
  "mcpServers": {
    "roblox_ultimate": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/roblox-studio-ultimate-mcp/dist/index.js"],
      "env": {}
    }
  }
}

5. 重启

重启 Roblox Studio（以加载插件）
重启 Claude Code（以连接到 MCP）

🏗️ 架构

Claude Code ←(stdio)→ MCP Server (Node.js) ←(HTTP)→ Studio Plugin (Luau)
                         Port 3002

MCP 服务器 (src/index.ts): 将 MCP 工具调用转换为 HTTP 命令
Studio 插件 (plugin/RobloxMCP.lua): 轮询服务器，在 Studio 内执行命令
通信：HTTP 轮询（300ms 间隔）

🔧 与其他 MCP 服务器配合使用

此服务器旨在与官方 Roblox Studio MCP 协同工作：

使用场景	使用哪个 MCP
脚本读/写	Ultimate (getScript/setScript)
运行测试	Official (start_stop_play)
控制台输出	Official (get_console_output)
实例操作	Ultimate
属性更改	Ultimate

📝 实际影响

在使用此 MCP 之前，在 260 行的脚本中进行简单的单行修复需要：

run_code 获取源码
gsub 模式匹配（经常失败）
run_code 写回
祈祷它能工作
重复 3-5 次

现在： editScript(path, 103, 103, "new code") → 完成。一次成功。

🤝 贡献

欢迎提交 PR！特别是在以下方面：

新工具
更好的错误处理
性能改进
文档

📄 许可证

MIT

Roblox Studio Ultimate MCP Server