Roblox-MCP

<p align="center"> <img src="docs/banner.svg" alt="Roblox Executor MCP" width="900"/> </p> # Roblox Executor MCP 服务器 一款高级的模型上下文协议（MCP）服务器，允许 AI 代理与正在运行的 Roblox 游戏客户端交互。该服务器支持代码执行、脚本反编译、实例层次查询、远程事件监视和触发，以及实时日志流媒体。 --- ## 🚀 主要功能 * **代码执行** — 动态地在客户端运行 Luau 代码，可选返回值为 yield。 * **脚本检查** — 反编译脚本、搜索源代码、执行语义搜索。 * **实例搜索和操作** — 使用类似 CSS 的选择器，遍历实例层次树，查询动态属性/属性。 * **远程监视和触发** — 拦截、记录、阻止、忽略并触发 `RemoteEvents` / `RemoteFunctions`（由 [Cobalt](https://github.com/notpoiu/cobalt) 支持）。 * **实时日志流媒体** — 通过 WebSockets 捕获客户端控制台输出并实时查看。 * **GUI 交互** — 通过点击按钮和在 UI 元素中输入文本来自动化输入。 * **操作系统集成** — 获取 Roblox 进程列表并捕获客户端窗口截图（仅限 Windows）。 * **多客户端路由** — 在多个运行的客户端之间协调，自动提升主/从客户端并中继。 * **本地脚本中心** — 保存、加载和执行预配置的 Luau 脚本。 --- ## 🖥️ 本地 Web 控制台 Roblox Executor MCP 包含一个丰富的、响应式的本地 Web 控制台，托管在： ```text http://localhost:16384/ ``` 使用控制台监控连接的客户端、调试可执行文件并检查游戏： 1. **控制台选项卡** *(新)*：Roblox 客户端控制台日志的实时流媒体（`LogService.MessageOut`），按日志级别颜色编码：**信息（白色）**、**警告（黄色）** 和 **错误（红色）**。 2. **执行器选项卡** *(新)*：一个开发者集中的套件，用于直接编写 Luau 代码，切换 **"获取返回值"** 以 yield 并打印结果，并立即执行保存在 `user-scripts/` 中心的脚本。 3. **工具选项卡**：一个控制中心，用于手动运行所有已注册的 MCP 工具并查看输入/输出。 4. **脚本选项卡**：浏览本地和反编译的脚本、搜索源代码、索引游戏层次并设置语义向量搜索。 --- ## 🛠️ 完整工具目录 服务器为连接的 AI 代理注册了一个全面的工具列表： ### 1. 客户端管理 * `list-clients` — 列出所有当前连接的 Roblox 游戏客户端。 * `set-active-client` — 选择后续工具操作的活动目标客户端。 ### 2. 执行工具 * `execute` — 在活动 Roblox 客户端上执行原始 Luau 代码。 * `execute-file` — 从服务器的本地路径执行 Luau 文件。 * `teleport-player` *(新)* — 将玩家重定位到特定坐标、偏移量或目标玩家。 * `set-player-property` *(新)* — 修改角色统计数据（例如，WalkSpeed、JumpPower、HipHeight、Gravity）或切换 Noclip。 ### 3. 检查和搜索工具 * `get-script-content` — 检索特定脚本的源代码/反编译代码。 * `get-data-by-code` — 使用 Luau 查找脚本查询客户端元数据。 * `get-console-output` — 返回客户端控制台打印和警告的历史记录。 * `search-instances` — 使用选择器或名称查找实例。 * `get-descendants-tree` — 转储特定实例的子级层次树。 * `script-grep` — 对所有加载的脚本源进行文本搜索。 * `semantic-search-scripts` — 对脚本内容执行基于向量的搜索（需要 Ollama 设置）。 * `get-game-info` — 查询游戏详细信息（例如，PlaceId、JobId、玩家数量）。 * `get-executor-environment` *(新)* — 返回连接的 Roblox 执行器支持的自定义 API 的检查清单（例如，`getgc`、`hookfunction`）。 * `get-instance-properties` *(新)* — 动态探测实例的属性、CollectionService 标签和属性。 ### 4. 远程监视和网络工具 * `ensure-remote-spy` — 启动 Cobalt 支持的远程监视管道。 * `get-remote-spy-logs` — 检索捕获的远程调用。 * `clear-remote-spy-logs` — 清除捕获的日志。 * `block-remote` — 阻止特定的 RemoteEvent 或 RemoteFunction。 * `ignore-remote` — 从活动日志流中过滤远程。 * `fire-remote` *(新)* — 触发 RemoteEvent 或调用 RemoteFunction。支持以 `loadstring:` 开头的动态评估参数。 ### 5. GUI 和操作系统工具 * `click-button` — 在屏幕上触发特定 GUI 按钮的点击。 * `type-text-box` — 聚焦并向游戏 TextBoxes 发送文本输入。 * `list-roblox-windows` — 列出活动的 Roblox 操作系统窗口句柄。 * `screenshot-window` — 捕获并保存游戏客户端的截图（仅限 Windows）。 --- ## 📋 前提条件 * **Node.js** ≥ 18 * **Bun** ≥ 1.3（用于交互式 OpenTUI 工具安装程序） * **Roblox 执行器** — 任何支持 `loadstring`、`request` 和（最好）`WebSocket` 的执行器。 --- ## ⚡ 快速入门 ### 1. 克隆仓库 ```bash git clone https://github.com/notpoiu/roblox-executor-mcp.git cd roblox-executor-mcp ``` ### 2. 运行工具安装程序 安装程序处理服务器构建、为选择的 AI 客户端生成配置，并打印加载器脚本： ```bash npm run install:harnesses ``` > [!TIP] > 如果终端在渲染交互式 OpenTUI 选择器时遇到问题，请在纯文本提示模式下运行： > ```bash > npm run install:harnesses -- --plain > ``` 要自动将 Roblox 加载器放入检测到的执行器的 `autoexec` 文件夹中（例如 MacSploit 或支持的 Windows 执行器），请运行： ```bash npm run getscript -- --autoexec ``` ### 3. 从 Roblox 连接 将此脚本粘贴到执行器中或放入 `autoexec` 文件夹中： ```lua local bridgeUrl = getgenv().BridgeURL or "localhost:16384" loadstring(game:HttpGet("http://" .. bridgeUrl .. "/script.luau"))() ``` #### 可选环境配置 在运行加载器脚本之前配置这些全局变量以自定义行为： ```lua getgenv().BridgeURL = "10.0.0.4:16384" -- 默认：localhost:16384 getgenv().DisableWebSocket = true -- 强制 HTTP 回退轮询 getgenv().DisableInitialScriptDecompMapping = true -- 跳过初始项目脚本索引 ``` --- ## ⚙️ 客户端配置和手动设置 如果您更喜欢手动配置 AI 接口，请参考以下指南： | 客户端 | 配置指南 | |---|---| | **Cursor** | [设置指南](docs/setup-cursor.md) | | **Claude Desktop** | [设置指南](docs/setup-claude-desktop.md) | | **Claude Code** | [设置指南](docs/setup-claude-code.md) | | **Codex CLI** | [设置指南](docs/setup-codex.md) | | **Windsurf** | [设置指南](docs/setup-windsurf.md) | | **Antigravity** | [设置指南](docs/setup-antigravity.md) | --- ## 🛠️ 开发者命令 使用以下项目脚本维护、运行或更新服务器： * **构建项目** （编译 TypeScript 并将资产复制到 `dist/`）： ```bash npm run build ``` * **启动服务器**： ```bash npm run start ``` * **更新现有安装** （拉取更新、停止运行的进程并重建）： ```bash npm run update ``` --- ## 🔒 安全和安全操作 > [!CAUTION] > **此服务器允许任意本地代码执行。** 仅连接受信任的 AI 客户端。端口 `16384` 不强制执行身份验证 — **绝不将此端口暴露给公共互联网**。对于跨机器或局域网设置，请使用本地 VPN 或 SSH 隧道安全连接。 --- ## 📄 许可证 该项目在 [MIT 许可证](LICENSE) 下获得许可。