Yippieblox MCP Server

YippieBlox MCP服务器

一个MCP（模型上下文协议）服务器，连接AI编码助手，如 克劳德代码 随着 Roblox工作室它允许AI代理执行Luau代码、管理撤销检查点、控制播放测试、模拟输入、捕获屏幕截图和流式日志——所有这些都可以在Studio中完成。

建筑

Claude Code (AI client)
    │  MCP over STDIO (JSON-RPC 2.0)
    ▼
┌────────────────────────────┐
│  Rust MCP Server           │
│  • stdin/stdout ↔ MCP      │
│  • localhost HTTP bridge    │
└────────────────────────────┘
    │  HTTP on 127.0.0.1:3334
    ▼
┌────────────────────────────┐
│  Roblox Studio Plugin      │
│  • Polls for tool requests │
│  • Executes inside Studio  │
│  • Pushes results back     │
└────────────────────────────┘

先决条件

• Roblox工作室 --已安装并能够打开场所

快速开始

1.下载服务器二进制+插件

从下载最新版本 ****:

提取服务器二进制文件并将其放置在PATH中的某个位置，或者为MCP配置记录其位置。

Build from source instead

需要 防锈工具链.

# Build the server
cd server && cargo build --release
# Binary is at server/target/release/roblox-studio-yippieblox-mcp-server

# Build the plugin
cd plugin && ./build_plugin.sh

2.安装Studio插件

复制 YippieBlox.rbxmx 到您的Studio插件目录：

macOS：

cp YippieBlox.rbxmx ~/Documents/Roblox/Plugins/YippieBlox.rbxmx

Windows（PowerShell）：

Copy-Item YippieBlox.rbxmx "$env:LOCALAPPDATA\Roblox\Plugins\YippieBlox.rbxmx"

3.在Studio中启用HTTP请求

1. 在Roblox工作室开一个地方
2. 首选 游戏设置 → 安全
3. 启用 允许HTTP请求

4.启动服务器

# With a specific token:
YIPPIE_TOKEN=mysecrettoken ./server/target/release/roblox-studio-yippieblox-mcp-server

# Or let the server generate a random token (printed to stderr):
./server/target/release/roblox-studio-yippieblox-mcp-server

5.连接插件

1. 在Studio中，打开 YippieBlox MCP dock小部件（出现在底部）
2. 设置服务器URL（默认值： http://localhost:3334)
3. 从服务器输出粘贴身份验证令牌
4. 点击 连接

6.连接您的AI客户端

克劳德代码（CLI）

从项目目录运行以下命令：

claude mcp add roblox-studio-yippieblox \
  --env YIPPIE_TOKEN=mysecrettoken \
  --env YIPPIE_PORT=3334 \
  -- /absolute/path/to/server/target/release/roblox-studio-yippieblox-mcp-server --stdio

或者手动添加到项目的 .mcp.json （或 ~/.claude.json 全球）：

{
  "mcpServers": {
    "roblox-studio-yippieblox": {
      "command": "/absolute/path/to/server/target/release/roblox-studio-yippieblox-mcp-server",
      "args": ["--stdio"],
      "env": {
        "YIPPIE_TOKEN": "mysecrettoken",
        "YIPPIE_PORT": "3334"
      }
    }
  }
}

然后重新启动Claude Code。这 studio-* 工具将可用。

克劳德桌面

打开 设置→ 开发者→ 编辑配置，或直接编辑配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

添加以下内容：

{
  "mcpServers": {
    "roblox-studio-yippieblox": {
      "command": "/absolute/path/to/server/target/release/roblox-studio-yippieblox-mcp-server",
      "args": ["--stdio"],
      "env": {
        "YIPPIE_TOKEN": "mysecrettoken",
        "YIPPIE_PORT": "3334"
      }
    }
  }
}

保存后重新启动Claude Desktop。这 studio-* 工具将出现在工具选择器中。

配置

MCP工具

所有工具的名称间隔如下 studio-*。有关完整描述、参数模式和使用示例，请参阅 improve_tool_descriptions.md.

脚本执行

我该用哪一个？ 使用 run_script 更改位置文件（添加零件、编辑属性、检查树）。使用 test_script 测试事物在运行时的行为（游戏逻辑、玩家交互、物理）。

检查点管理（撤消/重做）

典型工作流程： checkpoint_begin → run_script （进行更改）→ checkpoint_end → checkpoint_undo （如果需要）。

播放测试控制

日志流

玩家控制（仅限游戏模式）

这些工具需要主动的播放模式播放测试(studio-playtest_play).

NPC控制（仅限播放模式）

禁用工具

这些已注册，但 不起作用的 由于Roblox API的限制。不要使用它们。

捕获文件夹

屏幕截图保存到捕获目录（默认： .roblox-captures/ 在工作目录中）。一 index.json 文件使用元数据跟踪所有捕获。

Claude Code读取捕获文件，您必须在权限中分配捕获文件夹。使用 /permissions 在Claude Code中添加捕获目录路径。代理不应请求广泛的文件系统访问权限，而应仅请求特定的捕获文件夹。

如果捕获文件夹在仓库之外（例如。 ~/Pictures/RobloxCaptures/)，在macOS上，操作系统级文件夹访问可能需要用户批准。

冒烟测试

设置后，验证一切正常：

1. Start the Rust server
2. Open Studio, install plugin, connect with token
3. From Claude Code (or any MCP client), run these tool calls:

   studio-status
   → Should show connected: true

   studio-logs_subscribe({ includeHistory: true })
   → Should return ok with log history

   studio-run_script({ code: "print('Hello from MCP!') return 42" })
   → Should return value: "42" and the print appears in Studio Output

   studio-checkpoint_begin({ name: "Test checkpoint" })
   studio-run_script({ code: "local p = Instance.new('Part', workspace) p.Name = 'MCPTestPart'" })
   studio-checkpoint_end({ checkpointId: "" })
   studio-checkpoint_undo({})
   → MCPTestPart should disappear from workspace

   studio-test_script({ code: "print('Hello from playtest!') return workspace:GetChildren()" })
   → Should return success: true, value, and captured logs

   studio-playtest_run({})
   → Studio should enter Run mode (F8)
   studio-playtest_stop({})
   → Studio should return to Edit mode

   studio-logs_unsubscribe({})

安全说明

• HTTP网桥绑定到 127.0.0.1 仅 --无法从网络访问它
• A. 持有者令牌 所有网桥端点都需要（除了 /health)
• 切勿公开暴露桥口 --它仅设计用于本地主机通信
• 服务器仅将文件写入配置的捕获目录
• 身份验证令牌不应提交到版本控制中——使用环境变量

调试CLI

A. mcpctl 包含用于调试的辅助二进制文件：

# Check server health
cargo run --bin mcpctl -- health

# Show connection status
YIPPIE_TOKEN=mysecrettoken cargo run --bin mcpctl -- status

# List captures
cargo run --bin mcpctl -- captures --dir .roblox-captures

项目结构

/CLAUDE.md                          Project instructions for AI agents
/README.md                          This file
/improve_tool_descriptions.md       Source of truth for MCP tool descriptions
/server/
  Cargo.toml                        Rust dependencies
  src/
    main.rs                         Entry point
    mcp_stdio.rs                    MCP JSON-RPC over stdin/stdout
    bridge_http.rs                  HTTP bridge for plugin
    state.rs                        Shared state
    config.rs                       Configuration
    types.rs                        All data types
    captures.rs                     Capture file management
    bin/mcpctl.rs                   Debug CLI
/plugin/
  build_plugin.sh                   Builds YippieBlox.rbxmx from source
  YippieBlox/                       Plugin source (Luau modules)
    init.server.lua                 Plugin entry point
    bridge.lua                      HTTP bridge client
    tools/                          Tool handler modules
    ui/                             Widget and command trace
    util/                           Ring buffer, helpers