v0.16.1: one-command setup and a paste-to-AI install prompt

Setup is now one command, or a prompt you paste into your AI agent. Tufan-Blox-Bridge is a free Roblox Studio MCP server and plugin that works as an add-on to Roblox's built-in Studio MCP.

Easiest install

Paste this into Claude Code, Cursor or another AI agent, opened in your Roblox project folder:

Set up Tufan-Blox-Bridge, a Roblox Studio MCP server and plugin, for this project.

1. Run `npx -y tufan-blox-bridge@latest setup` in this folder. It installs the server and the Studio plugin, and registers with Claude Code or Cursor.
2. If it says nothing was registered, add the config it prints to your MCP settings, keeping any servers already there.
3. Don't ask me for API keys. They're optional.
4. Tell me what it did and the next steps it printed.

Or run it yourself:

npx -y tufan-blox-bridge@latest setup

What changed

• New setup command: installs the server and plugin, then registers with Claude Code and/or Cursor for your folder, keeping your existing config.
• The plugin now ships inside the npm package, so it always matches the server and installing it no longer depends on GitHub's API, whose rate limit could make it fail with a 403.
• --help and --version work. --help used to start the server and hang.
• Fixed a Node crash on exit on Windows in CLI commands.
• Removed two wrong instructions: "Allow HTTP Requests" and default.project.json aren't needed.

The Studio plugin itself is unchanged from v0.16.0. Tested on Windows with Claude Code; macOS, Linux and Cursor itself haven't been tried yet.

v0.16.0: Roblox Studio MCP add-on, works with the built-in server

Tufan-Blox-Bridge is a free Roblox Studio MCP server and plugin that works as an add-on to Roblox's built-in Studio MCP. This release makes the two work together and fixes everything a full live stress test turned up.

Works with the built-in Studio MCP

• Tufan now tells your AI at connect which server owns which job: the built-in server for screenshots, play tests and live debugging, Tufan for editing, safety, versioning and audits.
• Tufan detects a running Play session and flags any result that used the edit copy instead of the live game. is_running reports Play too.
• Removed capture_screenshot. It copied screen pixels, so a window covering Studio ended up in the shot. Use the built-in server's screen_capture.

Fixed

• Lost replies under load. Past Roblox's limit of about 500 HTTP requests a minute, the plugin dropped replies and calls hung for 90 seconds. Calls now wait for the budget to refill, up to about a minute, and none are lost. Use batch, create_tree or mass_edit for big jobs.
• Stale reads. Removed the 4-second read cache, which could hide changes made in Studio, by the built-in server or by another session.
• get_asset_details and search_assets broke when Roblox removed an endpoint. They now return names and creators again. Roblox no longer reports whether a model contains scripts, so the tools point you to scan_backdoors.
• False alarms in scan_perf and project_health. They counted installed plugins and Studio's own UI as game content, and meshes using SurfaceAppearance as untextured.
• run_luau: timeoutBudget now works, prints are no longer lost, and invalid UTF-8 no longer loses the whole result.
• Instance names containing dots now resolve, and edits past the end of a script return an error instead of silently appending.

Tested

184 live checks against Roblox Studio on Windows passed, covering 69 of the 85 tools, bad input, 5 MB payloads, 2,000-part builds, 800 calls under load, Play session cycles and session failover. Blender and keyless validation suites also pass. Paid, publishing and git-writing tools weren't part of the live run, and get_server_logs / get_server_history haven't been verified against a live game yet.

Upgrade

Update the server, restart your AI client, and install the new plugin. The plugin changed in this release, so you need both.

npm i -g tufan-blox-bridge@latest
tufan-blox-bridge install-plugin

v0.15.0 — production server logs, project context, one-line install

What's new

• get_server_logs + get_server_history — production observability via the new Open Cloud server-management APIs (BETA): per-server errors/warnings with stack traces, and 30 days of terminated/crashed/OOM servers. Needs TUFAN_OPENCLOUD_KEY with universe:read.
• project_context — persistent per-place AI-context notes; the AI reads them at session start instead of re-exploring.
• One-line install — install.ps1/install.sh + tufan-blox-bridge install-plugin (auto-installs this .rbxm into Studio's Plugins folder).
• Datastore quota awareness — surfaces rate-limit headers; warns that Open Cloud calls share the live game's DataStore budget (post-2026-07-29 unified limits).
• @modelcontextprotocol/sdk 1.30.0 — 2026-07-28 spec audited (docs/MCP-SPEC-2026-07-28.md); v2 split-package migration deferred.

Tool surface: 83 → 86. Plugin .rbxm unchanged since v0.14.0 (server-only release) — attached for the installer.

Quick install: npm i -g tufan-blox-bridge && tufan-blox-bridge install-plugin

v0.14.0 — playtest surface removed (official Roblox MCP owns play sessions)

Breaking: the playtest tools are gone

playtest (start/stop/pause), playtest_probe and playtest_input have been removed. Tool surface 86 → 83.

Why. A Studio plugin can only drive RunService:Run() — server scripts and physics, no player character. Roblox's own Studio MCP starts real Play Solo with a character and gives you execute_luau inside the live session plus user_keyboard_input / user_mouse_input / character_navigation. Tufan was shipping a strictly weaker duplicate that cost tool-menu space and steered the model toward the worse option. Cut rather than maintained.

Migration

Removed	Use instead (official Roblox Studio MCP)
playtest (start/stop/pause)	start_stop_play
playtest_probe	execute_luau
playtest_input	user_keyboard_input / user_mouse_input / character_navigation

What stays in Tufan

• is_running — kept, re-homed from the Playtest group to Meta. Read-only edit-vs-run guard for the write tools.
• Everything that observes a run: get_output_log, get_recent_errors (server-side live feed, no Studio round-trip — answers instantly even while Studio is busy in a session), capture_screenshot.
• run_luau is unchanged and still edit-mode only; it never reached a play session and its description now says so.

Also in this release

• Fixed dangling playtest_probe cross-references in the run_luau and cloud_luau tool descriptions.
• Doc tool counts unified at the real 83 (README said 87, LAUNCH 86, server/README 76, MARKET_COMPARISON 81 — all had drifted). Write-tool count 39 → 36.

Upgrading

1. npm is live again — latest now resolves to 0.14.0 (it had been pinned at a dead 0.6.0 since May). npx -y tufan-blox-bridge@latest, then restart your MCP client.
2. Reinstall the plugin. TufanBloxBridge.rbxm is attached and has changed — first plugin-side change since 0.9.0. Drop it in your Roblox Plugins folder, or run scripts/build-plugin.ps1 -Install.

Verified: tsc clean; a live tools/list against the built server returns 83 tools, zero playtest_*, is_running present.

v0.13.0 — monthly refresh: encodeDeep fix + 6 server tools

Monthly refresh — ecosystem scan + repo audit. Tool surface 81 → 87. Server v0.13.0 / plugin v0.9.0.

Fixes (plugin v0.9.0):

• encodeDeep array-corruption root fix — repairs scene_state + place_on (were broken) and run_luau/pick/objects_in_region/playtest_probe (array corruption). Verified live in Studio.
• make_responsive zero-size-parent collapse guard, get_tree className filter on collapsed runs, scan_perf loop-body accuracy, git_branch/git_remote usable in read-only.
• 7 dead-code/doc removals (handlers/aliases/drift dead since v0.7.0).

New server tools: format_scripts · lint_scripts · typecheck · export_sourcemap (Luau verify trio + sourcemap) and datastore · cloud_luau (Open Cloud "verify against production"). All server-side, no plugin change.

Plus a narrow-safe set_property tagged-value unwrap. Full detail: docs/REFRESH-NOTES.md.

Install: drag TufanBloxBridge.rbxm into Studio. npm publish stays paused (npx resolves the prior version until published).

v0.10.0 — spatial awareness (scene_state, pick, place_on, objects_in_region)

Spatial awareness — the AI can now relate what it sees to world coordinates. Until now a screenshot was a flat PNG the AI couldn't ground; these four tools turn the viewport into measurable space. Server-only — the v0.8.0 plugin .rbxm stays current; just restart your MCP client.

New tools (72 → 76)

• scene_state (read) — camera intrinsics + every visible object's world and on-screen pixel coordinates (via WorldToScreenPoint). Grounds a screenshot: "KitsuneLogoDisplay is at screen (605, 244) = world (0, 25, 0)." Models count as one bounding-box unit; closest-first.
• pick (read) — raycast a screen point (x,y / nx,ny / center) → hit instance + Model ancestor + world position + surface normal + distance. Powers "what is that?" and tracing (sample points along a screen path).
• place_on (write) — raycast to a surface (a screen point, a target instance's top via onTarget, or straight down via ground), then sit the object flush — offset by its bounding box so it never clips or floats. Optional alignToNormal (rotate to a slope) and snap (grid). dryRun returns the computed CFrame without moving. Moves a Part (CFrame) or a Model (PivotTo, bbox-center flush), one undo entry.
• objects_in_region (read) — list parts whose bounds overlap a box (center+size), sphere (center+radius), or around an instance (its bounding box, padded).

Notes

• Read-only safe: the three read tools dispatch fixed, audited read-only code and stay visible under TUFAN_READONLY=1; only place_on is write-gated. scene_state + pick are in the lean TUFAN_TOOLSET=core surface.
• Zero plugin changes — each tool is a canned Luau dispatch through the existing bridge.
• Verified live: scene_state/pick/objects_in_region cross-checked against a real scene; place_on apply confirmed flush (object bottom landed exactly on the target surface).

Units: studs (world/size/distance), degrees (orientation), pixels top-left (screen).

---

Install: drop the attached TufanBloxBridge.rbxm into your Roblox Plugins folder, and claude mcp add tufan -- npx -y tufan-blox-bridge@latest.

npm publish is still pending — npx currently resolves to 0.6.0. To run 0.10.0 today, clone the repo, npm run build in server/, and point your MCP config at server/dist/index.js.

v0.9.0 — import_file: local files into Studio via Open Cloud

The import-local-files gap is closed. New import_file tool: take a file on your disk, get it into your open Studio place — uploaded under your own account, so the LoadAsset ownership wall never applies.

Server-only release — the v0.8.0 plugin .rbxm stays current (attached here for convenience). Just restart your MCP client to pick up the new server.

📥 import_file

import_file({ filePath: "C:/assets/palm_tree.rbxm" })
→ Uploaded "palm_tree" → assetId 1234567890 (rbxassetid://1234567890)
→ inserted at Workspace.PalmTree

You give it	It becomes
.rbxm / .rbxmx / .fbx / .gltf / .glb	Model — uploaded + inserted into the place
.mp3 / .ogg / .wav / .flac	Audio → a Sound instance wired to the new id
.png / .jpg / .bmp / .tga	Image → a Decal instance (id property verified by read-back)
KeyframeSequence .rbxm + assetType: "Animation"	Animation asset → an Animation instance — a real publish path for animation files
.obj	clean rejection — convert to .fbx/.glb first

• Resumable: audio sits in Roblox's moderation queue — if processing outlives waitSeconds, you get an operationId; re-calling with it resumes without re-uploading or burning quota.
• Owner resolution: TUFAN_GROUP_ID / TUFAN_CREATOR_ID env, else auto-detected from the logged-in Studio user.
• Guard rails: 20 MB cap, audio quota surfaced (10/month, 100/month ID-verified), actionable 401/403/429 errors, API key scrubbed from any echoed response, honest insert reporting (no unverified "success").

Setup (one-time)

1. Create an API key → add the assets API (Read + Write) → add yourself under Access Permissions → leave IP restriction off
2. Set TUFAN_OPENCLOUD_KEY=<key> in the tufan MCP server env
3. Done — import_file handles the rest, including telling you exactly what's missing if the key is wrong

Verified live

Both paths tested end-to-end against the production Open Cloud API: .rbxmx model upload → insert in 3.9s (through proxy/multi-session mode, user id auto-detected), .png → Decal with read-back-verified Texture in 2.3s.

---

Install: drop the attached TufanBloxBridge.rbxm into your Roblox Plugins folder, and claude mcp add tufan -- npx -y tufan-blox-bridge@latest.

npm publish is still pending — npx currently resolves to 0.6.0. To use 0.9.0 today, clone the repo, npm run build in server/, and point your MCP config at server/dist/index.js.

v0.8.0 — serialization keystone, leaner surface, snapshots & audits

Everything since v0.6.0 — three versions' worth: the v0.6.1 power pack, the v0.7.x lean-surface pass, and the v0.8.0 serialization keystone. Server and plugin must both be updated (restart your MCP client so npx pulls 0.8.0, and replace the .rbxm in your Plugins folder with the one attached here).

⚠️ Breaking — tool renames (v0.7.0 + v0.8.0)

Merged (old names gone):

• get_script_source + set_script_source → script_source(path, source?) — read if no source, write if provided
• get_tags / add_tag / remove_tag → tag(path, action, tag?) — action = get / add / remove
• start_playtest / stop_playtest / pause_playtest → playtest(action) — is_running unchanged

Removed in v0.7.0, each with an exact survivor (79 → 71 tools, zero capability lost):
get_children→get_tree · get_script_tree→search_objects · mass_set_property→mass_edit · mass_create/mass_duplicate→batch/create_tree · insert_script_lines/delete_script_lines→edit_script_lines · get_playtest_output→get_output_log

🔑 v0.8.0 — serialization keystone + census tools

• Full property round-trip for NumberSequence, ColorSequence, NumberRange, Rect, Font, PhysicalProperties — particle curves, UI gradients, fonts, and springs are finally editable via get_properties / set_property / mass_edit (they silently broke before).
• project_health — one-look place census in a single traversal (instances, scripts, parts, Luau KB, per-service breakdown).
• find_duplicates — exact-clone script detection (extract-a-module candidates).
• mass_set_attribute — the attribute twin of mass_edit, with per-item error reporting.
• Read-only mode upgraded — TUFAN_READONLY=1 hides all 36 write tools; mixed tools (script_source, tag) stay visible with writes blocked, so inspector mode can still read scripts and tags.

🛡 v0.7.1 — hardening (audit pass)

• Read-only mode no longer leaks copy_script_across / playtest_probe / pull_place as callable.
• Pre-pull protective snapshot now aborts the pull if it fails, instead of silently overwriting a dirty mirror.
• run_luau / playtest_probe watchdog — infinite-yield payloads return a clear error (default 30s, timeoutBudget overridable).
• Mass/batch ops report per-item failures instead of hiding them.

📱 v0.7.0 — lean surface + responsive engine

• TUFAN_TOOLSET=core — expose only the ~22 everyday tools; power suites stay one env var away. Composes with read-only mode.
• make_responsive — convert a UI subtree Offset→Scale across all six breaking properties with a validated formula; skips draggables; dryRun previews.
• scan_responsive — audit tree and scripts for resolution breakage and sub-44px tap targets.

⚡ v0.6.1 — power pack

• batch — dozens of mixed ops in one round-trip + one undo entry.
• describe — an instance's full context (props, attributes, tags, children, scripts, bounds) in one call.
• patch_script — multi-hunk anchored find/replace on one script, fully atomic.
• Snapshots — snapshot / restore / list_snapshots / delete_snapshot: checkpoint any subtree before risky changes.
• playtest_probe + playtest_input — structured Luau eval inside a running sim + character input driving; with playtest this closes the build→test→inspect loop for Run mode.
• get_recent_errors — live error/warning feed with a since-cursor, no Studio round-trip.
• scan_perf — ranked frame-killer fix list.
• run_luau returns structured JSON for table results; get_tree is token-lean; read caching with write-invalidation.
• Fix: edits made during a playtest now land in the edit DataModel and survive the run.

---

Install: drop the attached TufanBloxBridge.rbxm into your Roblox Plugins folder, and claude mcp add tufan -- npx -y tufan-blox-bridge@latest. Full docs in the README.

npm publish of 0.8.0 is pending — npx currently resolves to 0.6.0 until then. Watch this repo for the npm release.

v0.6.0 — concurrent multi-session (shared bridge), no collisions

Multiple Claude sessions can now drive the same Studio at once — no more 'only one works, the others say No place connected'.

How: one server still owns the plugin (port 58741). Any other session's server runs as a proxy — it forwards its tool calls to the owner (/proxy/dispatch) and reads the place list from it (/proxy/places). The owner runs every command through its single plugin queue, so all sessions' commands are serialized there → no collisions. If the owner's session closes, a proxy automatically promotes to owner and the plugin reconnects.

Owner/single-session behavior is unchanged (zero risk to existing flow). Server-only — plugin .rbxm unchanged, no reinstall.

Tested: proxy forwards dispatch + reads/resolves the owner's place cache (8/8). Live 3-session concurrency: verify on your side.

Upgrade — important: reconnect every session (/mcp) so they all run 0.6.0. The owner especially needs 0.6.0 (it serves the /proxy/* endpoints); a proxy pointed at an old owner can't forward. npx cache is cleared on this machine.

v0.5.1 — real playtest control (Run mode) for automation

Playtest control is now real (it's needed to close the automation loop).

RunService:Run/Stop/Pause are PluginSecurity — callable from a plugin — so:

• start_playtest → RunService:Run() (Run mode: server scripts + physics, no player character). Runs in the same DataModel, so run_luau and get_playtest_output keep working during the run — build → test → inspect → fix, automated.
• stop_playtest → RunService:Stop(), pause_playtest → RunService:Pause(), is_running now reports run-mode.

Honest limit: full Play Solo (F5 — with player character + client) has no plugin API; start that manually. Run mode covers server-logic / module / physics automation.

Upgrade: /mcp reconnect + reinstall the .rbxm + restart Studio.