Tripwire

<div align="center"> # Tripwire **由 alibolly 创建** [](https://www.npmjs.com/package/tripwire-roblox) [](https://github.com/aliboIly/Tripwire/actions/workflows/ci.yml) 一个 MCP 服务器，为 AI 编程代理提供真正的 Roblox Studio 和 Roblox Open Cloud 控制权， 并具有其他 Studio MCP 没有的测试和安全层。 </div> Tripwire 允许助手读取、写入和编辑数据模型，通过模拟输入驱动 Playtest，在真正的引擎中无头运行测试， 标记游戏代码中的客户端信任漏洞，并调用 Open Cloud API（数据存储、消息服务、内存存储等）。 Studio 工具不需要 API 密钥；无头测试、资产和 Open Cloud 工具使用 Open Cloud 密钥。 --- ## 安装 Tripwire 的服务器是一个单独的二进制文件。运行它最简单的方法是使用 `npx`，它为您的平台获取预构建的二进制文件， 因此无需安装 Rust 工具链。您更喜欢手动二进制文件或源代码构建吗？请参见本节末尾的替代方法。 <details> <summary><b>Claude 代码</b></summary> 一个命令： ```bash claude mcp add --transport stdio tripwire -- npx -y tripwire-roblox ``` 或将其添加到项目 `.mcp.json`（或 `~/.claude.json`）： ```json { "mcpServers": { "tripwire": { "type": "stdio", "command": "npx", "args": ["-y", "tripwire-roblox"] } } } ``` </details> <details> <summary><b>Codex</b></summary> 添加到 `~/.codex/config.toml`： ```toml [mcp_servers.tripwire] command = "npx" args = ["-y", "tripwire-roblox"] ``` 或：`codex mcp add tripwire -- npx -y tripwire-roblox` </details> <details> <summary><b>Gemini</b></summary> 添加到 `~/.gemini/settings.json`（或项目 `.gemini/settings.json`）： ```json { "mcpServers": { "tripwire": { "command": "npx", "args": ["-y", "tripwire-roblox"] } } } ``` 或：`gemini mcp add tripwire npx -y tripwire-roblox` </details> <details> <summary><b>其他 MCP 客户端</b></summary> 任何通过 stdio 使用 MCP 的客户端都可以运行它： ``` command: npx args: ["-y", "tripwire-roblox"] ``` </details> <details> <summary><b>替代方法：预构建二进制文件或从源代码构建</b></summary> **预构建二进制文件（无 Node）。** 从 [Releases](https://github.com/aliboIly/Tripwire/releases) 页面下载适用于您平台的存档（例如 `tripwire-server-vX.Y.Z-aarch64-apple-darwin.tar.gz`），解压它，并将您的客户端的 `command` 指向解压的 `tripwire-server`，参数为空。 **从源代码构建**（需要 [Rust](https://rustup.rs)）： ```bash git clone https://github.com/aliboIly/Tripwire.git cd Tripwire/server cargo build --release # 生成 server/target/release/tripwire-server ``` 然后将您的客户端的 `command` 指向该二进制文件路径。 </details> <details> <summary><b>Studio 插件（适用于 Studio 工具）</b></summary> Studio 工具通过一个小插件访问 Studio，该插件会长轮询本地服务器。从 [Releases](https://github.com/aliboIly/Tripwire/releases) 页面获取 `Tripwire.rbxmx`， 或构建它： ```bash cd Tripwire/plugin npm install npx rbxtsc rojo build --output Tripwire.rbxmx cp Tripwire.rbxmx ~/Documents/Roblox/Plugins/ # macOS；Windows：%LOCALAPPDATA%\Roblox\Plugins ``` 重启 Studio，点击 **Tripwire** 工具栏按钮，并启用 **游戏设置 > 安全 > 允许 HTTP 请求**。输出显示 `[Tripwire v...] 已连接`。 </details> <details> <summary><b>Open Cloud 密钥（适用于无头测试、资产和 Open Cloud 工具）</b></summary> Studio 工具不需要密钥。Open Cloud 工具需要。请参阅下面的 [Open Cloud 设置](#open-cloud-设置) 以获取完整的操作指南。 </details> --- ## Open Cloud 设置 Tripwire 的大部分功能不需要凭证。这些工具需要，因为它们调用 Roblox Open Cloud： `run_luau`，无头测试（`run_tests`、`run_test_file`、`list_tests`），`upload_asset`， `publish_place`，以及数据存储、有序数据存储、消息服务、内存存储、平台和参与度工具。 它们使用 Roblox Open Cloud API 密钥进行身份验证。 > **自担风险。** Open Cloud 密钥是具有真实权限的真实凭证，可对您的体验进行控制。 > 根据您授予的范围，它可以读取和覆盖您的实时数据存储，发布您体验的新版本，上传资产到您的帐户，并向您的服务器发送消息。 > 请像对待密码一样谨慎：仅授予您实际使用的范围，限制为您的 IP 地址，永不提交，并在密钥泄露时撤销。 > 您应对使用密钥的行为负责。Tripwire 与 Roblox 无关，也未得到 Roblox 的认可。 ### 1. 创建密钥 1. 前往 [create.roblox.com/dashboard/credentials](https://create.roblox.com/dashboard/credentials) 并登录。 2. 点击 **创建 API 密钥** 并命名它（例如 `Tripwire`）。 3. 在 **访问权限** 下，仅添加您要使用的 API 系统的工具，并授予每个工具所需的权限，范围限定为您的体验： - **Luau 执行**（写入）：`run_luau` 和无头测试。 - **universe-places**（写入）：`publish_place`。 - **资产**（读取 + 写入）：`upload_asset`。 - **数据存储** 和 **有序数据存储**：数据存储工具。 - **消息服务**（发布）和 **内存存储**：这些工具。 - **用户/组/库存/订阅/通知**：平台和参与度工具。 4. 在 **安全** 下，将 **接受的 IP 地址** 设置为您的机器的 IP 地址，或 `0.0.0.0/0` 以允许任意地址（最适合本地使用）。如果需要，请设置过期时间。 5. 点击 **保存并生成密钥** 并复制密钥字符串。它只显示一次。 ### 2. 查找您的宇宙和地点 ID 在 Studio 命令栏（视图，然后命令栏）中运行： ```lua print("universe", game.GameId, "place", game.PlaceId) ``` `GameId` 是您的 `ROBLOX_UNIVERSE_ID`；`PlaceId` 是您的 `ROBLOX_PLACE_ID`。该地点必须 **发布** 到 Roblox 以便 Open Cloud 对其生效。 ### 3. 为 Tripwire 提供凭证 在存储库根目录下创建一个 `.env` 文件。它是 gitignore 的，服务器会自动加载它： ```bash ROBLOX_OPEN_CLOUD_KEY=粘贴密钥 ROBLOX_UNIVERSE_ID=000000 ROBLOX_PLACE_ID=000000 ROBLOX_CREATOR_USER_ID=000000 # 仅适用于 upload_asset（您的用户 ID） ``` 或者，将相同的变量放在您的 MCP 客户端的 `env` 块中（这些变量优先）。在更改任一变量后重新连接 MCP 服务器。 每个工具在密钥授予其范围并返回 Roblox 自己的错误时都会生效，因此您可以根据需要添加范围。 --- ## 工具 ### 连接 <details><summary><code>studio_status</code></summary>Studio 是否已连接，活跃地点以及其他已连接的 Studio。</details> <details><summary><code>ping_studio</code></summary>通过插件循环 ping 以确认实时桥接是否正常工作。</details> <details><summary><code>list_studios</code></summary>列出每个已连接（或最近看到）的 Studio：地点，是否活跃，最后看到的时间以及 Playtest 状态。</details> <details><summary><code>set_active_studio</code></summary>选择哪个已连接的 Studio 是工具的目标（按 ID，ID 前缀或地点名称）。单个 Studio 自动。</details> ### 读取和检查 <details><summary><code>get_file_tree</code></summary>从路径（默认为整个游戏）列出实例树，限定深度。</details> <details><summary><code>get_instance_children</code></summary>列出实例的直接子实例（名称和类）。</details> <details><summary><code>get_instance_properties</code></summary>读取实例的名称，类，完整路径和属性。</details> <details><summary><code>search_objects</code></summary>查找名称包含查询的字符串的实例，可选按类过滤。</details> <details><summary><code>search_by_property</code></summary>查找属性等于值的实例，可选按类过滤。</details> <details><summary><code>get_script_source</code></summary>读取 Script，LocalScript 或 ModuleScript 的源代码。</details> <details><summary><code>grep_scripts</code></summary>在脚本源代码中搜索字符串；返回路径，行号和行。</details> <details><summary><code>get_output_log</code></summary>最近的 Studio 输出条目（消息，类型，时间戳）。</details> <details><summary><code>get_selection</code></summary>Studio 中当前选定的实例。</details> ### 编辑（每个是一个撤销步骤） <details><summary><code>create_instance</code></summary>创建具有可选名称和初始属性的类实例。</details> <details><summary><code>delete_instance</code></summary>销毁实例及其后代。</details> <details><summary><code>set_property</code></summary>设置类型化的属性（原始，Vector3，Color3，UDim2，CFrame，EnumItem 或实例引用）。</details> <details><summary><code>update_script_source</code></summary>通过脚本编辑器替换脚本的源代码（支持的写入路径）。</details> <details><summary><code>insert_model</code></summary>插入 ID 资产，具有可选的重定位或解包。</details> <details><summary><code>mass_create</code></summary>一次性创建多个实例（原子或尽力而为，带有每个项目的返回结果）。</details> <details><summary><code>mass_set_property</code></summary>一次性对多个实例设置一个属性（原子或尽力而为）。</details> ### Playtest 和输入 <details><summary><code>start_playtest</code></summary>启动 F5 Playtest（具有玩家的数据模型和 DataModels）；注入运行时。</details> <details><summary><code>stop_playtest</code></summary>停止 F5 Playtest（尽力而为；F5 拆除可能会持续超过确认时间）。</details> <details><summary><code>start_simulation</code></summary>启动 F8 运行（仅服务器模拟，无客户端或玩家）。</details> <details><summary><code>stop_simulation</code></summary>停止 F8 运行（干净）。</details> <details><summary><code>simulate_mouse_input</code></summary>在 F5 Playtest 期间单击或移动鼠标到屏幕坐标。</details> <details><summary><code>simulate_keyboard_input</code></summary>在 F5 Playtest 期间按下键（点击/按下/释放）或输入文本。</details> <details><summary><code>character_navigation</code></summary>将本地角色移动到世界位置；报告是否达到目标。</details> <details><summary><code>get_playtest_output</code></summary>运行的 Playtest 的输出日志，在服务器和客户端对等方之间聚合。</details> ### 测试和无头执行（Open Cloud） <details><summary><code>run_luau</code></summary>无头地在发布的地点运行 Luau 脚本；返回结果和日志。</details> <details><summary><code>run_tests</code></summary>在发布的地点运行无头测试套件，并报告通过/失败以及消息。</details> <details><summary><code>run_test_file</code></summary>无头运行单个规范按名称。</details> <details><summary><code>list_tests</code></summary>列出发布的地点中发现的规范文件及其案例。</details> <details><summary><code>write_test</code></summary>将 roblox-ts 测试规范写入磁盘；重建并发布，然后 run_tests 选取它。</details> ### 安全审查（静态分析，无密钥） <details><summary><code>review_security</code></summary>审查游戏源代码的客户端信任和未验证远程问题，每个问题都有建议的服务器端修复。</details> <details><summary><code>scan_remotes</code></summary>列出服务器远程处理程序和客户端控制的参数。</details> <details><summary><code>scan_client_trust</code></summary>标记使用客户端提供的值但未验证它们的服务器处理程序。</details> ### 资产和发布（Open Cloud） <details><summary><code>upload_asset</code></summary>将本地文件上传为 Roblox 资产（Decal，Audio，Model，Animation 或 Video）；返回 assetId。</details> <details><summary><code>publish_place</code></summary>将本地地点文件（.rbxl/.rbxlx）发布为体验的新版本。</details> ### 数据存储（Open Cloud） <details><summary><code>list_datastores</code></summary>列出宇宙中的标准数据存储。</details> <details><summary><code>list_datastore_entries</code></summary>列出数据存储中的条目键。</details> <details><summary><code>get_datastore_entry</code></summary>读取条目的值和元数据。</details> <details><summary><code>set_datastore_entry</code></summary>创建或覆盖条目（值加可选用户/属性）。</details> <details><summary><code>delete_datastore_entry</code></summary>软删除条目（30 天后清除）。</details> <details><summary><code>increment_datastore_entry</code></summary>原子增加数值条目。</details> <details><summary><code>list_ordered_entries</code></summary>按值升序或降序列出有序数据存储条目。</details> <details><summary><code>get_ordered_entry</code></summary>读取有序数据存储条目。</details> <details><summary><code>set_ordered_entry</code></summary>将有序数据存储条目设置为非负整数。</details> <details><summary><code>increment_ordered_entry</code></summary>原子增加有序数据存储条目。</details> ### 消息和内存（Open Cloud） <details><summary><code>publish_message</code></summary>向 MessagingService 主题发布消息（到达正在运行的生产服务器）。</details> <details><summary><code>memory_sorted_map_set</code></summary>设置具有 TTL 和排序键的 Memory Store 排序映射项。</details> <details><summary><code>memory_sorted_map_get</code></summary>读取 Memory Store 排序映射项。</details> <details><summary><code>memory_sorted_map_list</code></summary>按排序顺序列出排序映射项。</details> <details><summary><code>memory_sorted_map_delete</code></summary>删除排序映射项。</details> <details><summary><code>memory_queue_add</code></summary>将项目添加到 Memory Store 队列，具有优先级和 TTL。</details> <details><summary><code>memory_queue_read</code></summary>从队列中读取项目；返回 readId 以便丢弃调用。</details> <details><summary><code>memory_queue_discard</code></summary>永久删除已读取的批次及其 readId。</details> ### 平台和参与度（Open Cloud） <details><summary><code>get_universe</code></summary>配置的宇宙的元数据。</details> <details><summary><code>get_place</code></summary>配置的地点的元数据。</details> <details><summary><code>get_user</code></summary>用户的公共个人资料。</details> <details><summary><code>get_group</code></summary>组的元数据。</details> <details><summary><code>list_inventory</code></summary>用户的库存项目，按类型或 ID 过滤。</details> <details><summary><code>send_notification</code></summary>向用户发送体验通知（来自 Creator Dashboard 模板）。</details> <details><summary><code>get_subscription</code></summary>读取用户的订阅产品。</details> --- ## 你可以做的事 - **从提示构建场景。** 创建和批量创建实例，设置类型属性，插入模型，编写脚本，每个都是一个干净的撤销步骤。 - **在 CI 中测试游戏玩法。** 编写规范，无头运行它们，使用 Open Cloud，并在结果上阻塞拉取请求。 - **在发货前捕获漏洞。** 安全审查员标记信任客户端输入的服务器处理程序，并建议服务器端修复；相同的检查自动运行每个 PR。 - **驱动实时 Playtest。** 进入 Play 模式，发送键盘和鼠标输入，移动角色到一个位置，读取组合的服务器/客户端输出，然后停止。 - **检查实时地点。** 读取实例树，按名称或属性搜索，读取和 grep 脚本，并拉取输出日志。 - **自动化 Open Cloud。** 为测试夹具种子 DataStores，发布地点，广播 MessagingService 主题，或查找用户，组和库存。 --- ## 先前的工作 Studio 运行时方法（插件长轮询本地服务器，注入运行时）遵循 [boshyxd/robloxstudio-mcp](https://github.com/boshyxd/robloxstudio-mcp) 和 [Chrrxs/robloxstudio-mcp](https://github.com/Chrrxs/robloxstudio-mcp)。Tripwire 是一个独立的，从零开始的实现；无头测试套件，CI 安全审查员和 Open Cloud 工具都是它自己的。 --- ## 许可证 MIT。参见 [LICENSE](LICENSE)。</details>