@chrrxs/robloxstudio-mcp 2.15.0 → 2.15.1

package/dist/index.js

@@ -19,6 +19,10 @@ function toPublic(inst) {
     placeName: inst.placeName,
     dataModelName: inst.dataModelName,
     isRunning: inst.isRunning,
+    pluginVersion: inst.pluginVersion,
+    pluginVariant: inst.pluginVariant,
+    serverVersion: inst.serverVersion,
+    versionMismatch: inst.versionMismatch,
     lastActivity: inst.lastActivity,
     connectedAt: inst.connectedAt
   };
@@ -45,6 +49,10 @@ var init_bridge_service = __esm({
         const { pluginSessionId, instanceId, role } = input;
         const prior = this.instances.get(pluginSessionId);
         let assignedRole = role;
+        const pluginVersion = input.pluginVersion ?? "";
+        const pluginVariant = input.pluginVariant ?? "unknown";
+        const serverVersion = input.serverVersion ?? "";
+        const versionMismatch = pluginVersion !== "" && serverVersion !== "" && pluginVersion !== serverVersion;
         if (role === "client") {
           if (prior && prior.instanceId === instanceId && prior.role.match(/^client-\d+$/)) {
             assignedRole = prior.role;
@@ -82,6 +90,10 @@ var init_bridge_service = __esm({
           placeName: input.placeName ?? "",
           dataModelName: input.dataModelName ?? "",
           isRunning: input.isRunning ?? false,
+          pluginVersion,
+          pluginVariant,
+          serverVersion,
+          versionMismatch,
           lastActivity: Date.now(),
           connectedAt: prior?.connectedAt ?? Date.now()
         });
@@ -326,6 +338,7 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
   let lastMCPActivity = 0;
   let mcpServerStartTime = 0;
   const proxyInstances = /* @__PURE__ */ new Set();
+  const warnedVersionMismatches = /* @__PURE__ */ new Set();
   const setMCPServerActive = (active) => {
     mcpServerActive = active;
     if (active) {
@@ -354,13 +367,16 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
   app.use(express.urlencoded({ limit: "50mb", extended: true }));
   app.get("/health", (req, res) => {
     const instances = bridge.getInstances();
+    const publicInstances = instances.map(toPublic);
     res.json({
       status: "ok",
       service: "robloxstudio-mcp",
       version: serverConfig?.version,
+      serverVersion: serverConfig?.version,
       pluginConnected: instances.length > 0,
       instanceCount: instances.length,
-      instances: instances.map(toPublic),
+      instances: publicInstances,
+      versionMismatch: publicInstances.some((inst) => inst.versionMismatch),
       mcpServerActive: isMCPServerActive(),
       uptime: mcpServerActive ? Date.now() - mcpServerStartTime : 0,
       pendingRequests: bridge.getPendingRequestCount(),
@@ -369,7 +385,7 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
     });
   });
   app.post("/ready", (req, res) => {
-    const { pluginSessionId, instanceId, role, placeId, placeName, dataModelName, isRunning } = req.body;
+    const { pluginSessionId, instanceId, role, placeId, placeName, dataModelName, isRunning, pluginVersion, pluginVariant } = req.body;
     if (!pluginSessionId || !instanceId || !role) {
       res.status(400).json({
         success: false,
@@ -384,7 +400,10 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
       placeId: typeof placeId === "number" ? placeId : 0,
       placeName: typeof placeName === "string" ? placeName : "",
       dataModelName: typeof dataModelName === "string" ? dataModelName : "",
-      isRunning: !!isRunning
+      isRunning: !!isRunning,
+      pluginVersion: typeof pluginVersion === "string" ? pluginVersion : "",
+      pluginVariant: typeof pluginVariant === "string" ? pluginVariant : "unknown",
+      serverVersion: serverConfig?.version ?? ""
     });
     if (!result.ok) {
       res.status(409).json({
@@ -395,10 +414,17 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
       });
       return;
     }
+    const registered = bridge.getInstanceBySessionId(pluginSessionId);
+    if (registered?.versionMismatch && !warnedVersionMismatches.has(pluginSessionId)) {
+      warnedVersionMismatches.add(pluginSessionId);
+      console.error(`[version-mismatch] Studio plugin v${registered.pluginVersion} (${registered.pluginVariant}) does not match MCP server v${registered.serverVersion} for ${registered.instanceId}/${registered.role}`);
+    }
     res.json({
       success: true,
       assignedRole: result.assignedRole,
-      instanceId: result.instanceId
+      instanceId: result.instanceId,
+      serverVersion: serverConfig?.version,
+      versionMismatch: registered?.versionMismatch ?? false
     });
   });
   app.post("/disconnect", (req, res) => {
@@ -410,17 +436,25 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
   });
   app.get("/status", (req, res) => {
     const instances = bridge.getInstances();
+    const publicInstances = instances.map(toPublic);
     res.json({
       pluginConnected: instances.length > 0,
       instanceCount: instances.length,
-      instances: instances.map(toPublic),
+      instances: publicInstances,
+      serverVersion: serverConfig?.version,
+      versionMismatch: publicInstances.some((inst) => inst.versionMismatch),
       mcpServerActive: isMCPServerActive(),
       lastMCPActivity,
       uptime: mcpServerActive ? Date.now() - mcpServerStartTime : 0
     });
   });
   app.get("/instances", (req, res) => {
-    res.json({ instances: bridge.getInstances() });
+    const instances = bridge.getInstances();
+    res.json({
+      instances,
+      serverVersion: serverConfig?.version,
+      versionMismatch: instances.some((inst) => inst.versionMismatch)
+    });
   });
   app.get("/poll", (req, res) => {
     const pluginSessionId = req.query.pluginSessionId;
@@ -430,11 +464,17 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
     let callerInstanceId;
     let callerRole;
     let knownInstance = false;
+    let callerPluginVersion;
+    let callerPluginVariant;
+    let versionMismatch = false;
     if (pluginSessionId) {
       const inst = bridge.getInstanceBySessionId(pluginSessionId);
       if (inst) {
         callerInstanceId = inst.instanceId;
         callerRole = inst.role;
+        callerPluginVersion = inst.pluginVersion;
+        callerPluginVariant = inst.pluginVariant;
+        versionMismatch = inst.versionMismatch;
         knownInstance = true;
       }
     }
@@ -444,6 +484,10 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
         pluginConnected: true,
         mcpConnected: false,
         knownInstance,
+        serverVersion: serverConfig?.version,
+        pluginVersion: callerPluginVersion,
+        pluginVariant: callerPluginVariant,
+        versionMismatch,
         request: null
       });
       return;
@@ -456,6 +500,10 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
         mcpConnected: true,
         pluginConnected: true,
         knownInstance,
+        serverVersion: serverConfig?.version,
+        pluginVersion: callerPluginVersion,
+        pluginVariant: callerPluginVariant,
+        versionMismatch,
         proxyInstanceCount: proxyInstances.size
       });
     } else {
@@ -464,6 +512,10 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
         mcpConnected: true,
         pluginConnected: true,
         knownInstance,
+        serverVersion: serverConfig?.version,
+        pluginVersion: callerPluginVersion,
+        pluginVariant: callerPluginVariant,
+        versionMismatch,
         proxyInstanceCount: proxyInstances.size
       });
     }
@@ -7283,20 +7335,20 @@ function getPluginsFolder() {
   }
   return join2(homedir2(), "Documents", "Roblox", "Plugins");
 }
-function handleVariantConflict({ pluginsFolder, otherAssetName, replace }) {
+function handleVariantConflict({ pluginsFolder, otherAssetName, replace, log = console.log, warn = console.warn }) {
   const otherDest = join2(pluginsFolder, otherAssetName);
   if (!existsSync2(otherDest))
     return;
   if (replace) {
     try {
       unlinkSync(otherDest);
-      console.log(`Removed conflicting ${otherAssetName}.`);
+      log(`Removed conflicting ${otherAssetName}.`);
     } catch (err) {
-      console.warn(`[install-plugin] Could not remove ${otherDest}: ${err}. Continuing.`);
+      warn(`[install-plugin] Could not remove ${otherDest}: ${err}. Continuing.`);
     }
     return;
   }
-  console.warn(`
+  warn(`
 [install-plugin] WARNING: ${otherAssetName} is already present in ${pluginsFolder}.
 Only one MCP plugin variant should be present. If both variants are in the Studio Plugins folder, Studio loads both and runtime routing can become unpredictable.
 Re-run with --replace-variant to remove ${otherAssetName}, or delete it manually.
@@ -7327,10 +7379,12 @@ var init_dist = __esm({
 // src/install-plugin.ts
 var install_plugin_exports = {};
 __export(install_plugin_exports, {
+  installBundledPlugin: () => installBundledPlugin,
   installPlugin: () => installPlugin
 });
-import { createWriteStream, existsSync as existsSync3, mkdirSync as mkdirSync2, unlinkSync as unlinkSync2 } from "fs";
-import { join as join3 } from "path";
+import { copyFileSync, createWriteStream, existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, unlinkSync as unlinkSync2 } from "fs";
+import { dirname as dirname2, join as join3 } from "path";
+import { fileURLToPath } from "url";
 import { get } from "https";
 function httpsGet(url) {
   return new Promise((resolve2, reject) => {
@@ -7393,9 +7447,11 @@ async function findDevRelease() {
   }
   return prerelease;
 }
-async function installPlugin() {
-  const dev = process.argv.includes("--dev");
-  const replaceVariant = process.argv.includes("--replace-variant");
+function prepareInstall({
+  replaceVariant,
+  log,
+  warn
+}) {
   const pluginsFolder = getPluginsFolder();
   if (!existsSync3(pluginsFolder)) {
     mkdirSync2(pluginsFolder, { recursive: true });
@@ -7403,18 +7459,56 @@ async function installPlugin() {
   handleVariantConflict({
     pluginsFolder,
     otherAssetName: OTHER_VARIANT,
-    replace: replaceVariant
+    replace: replaceVariant,
+    log,
+    warn
   });
-  console.log(dev ? "Fetching latest dev prerelease..." : "Fetching latest release...");
+  return pluginsFolder;
+}
+function bundledAssetPath() {
+  const currentDir = dirname2(fileURLToPath(import.meta.url));
+  const candidates = [
+    join3(currentDir, "..", "studio-plugin", ASSET_NAME),
+    join3(currentDir, "..", "..", "..", "studio-plugin", ASSET_NAME)
+  ];
+  return candidates.find((candidate) => existsSync3(candidate)) ?? null;
+}
+function filesMatch(a, b) {
+  if (!existsSync3(b)) return false;
+  const aBytes = readFileSync3(a);
+  const bBytes = readFileSync3(b);
+  return aBytes.length === bBytes.length && aBytes.equals(bBytes);
+}
+async function installBundledPlugin(options = {}) {
+  const log = options.log ?? console.log;
+  const warn = options.warn ?? console.warn;
+  const replaceVariant = options.replaceVariant ?? process.argv.includes("--replace-variant");
+  const source = bundledAssetPath();
+  if (!source) {
+    throw new Error(`Bundled ${ASSET_NAME} not found in package`);
+  }
+  const pluginsFolder = prepareInstall({ replaceVariant, log, warn });
+  const dest = join3(pluginsFolder, ASSET_NAME);
+  if (filesMatch(source, dest)) return;
+  copyFileSync(source, dest);
+  log(`Installed ${ASSET_NAME} to ${dest}`);
+}
+async function installPlugin(options = {}) {
+  const dev = options.dev ?? process.argv.includes("--dev");
+  const replaceVariant = options.replaceVariant ?? process.argv.includes("--replace-variant");
+  const log = options.log ?? console.log;
+  const warn = options.warn ?? console.warn;
+  const pluginsFolder = prepareInstall({ replaceVariant, log, warn });
+  log(dev ? "Fetching latest dev prerelease..." : "Fetching latest release...");
   const release = dev ? await findDevRelease() : await fetchJson(`https://api.github.com/repos/${REPO}/releases/latest`);
   const asset = release.assets?.find((a) => a.name === ASSET_NAME);
   if (!asset) {
     throw new Error(`${ASSET_NAME} not found in release ${release.tag_name}`);
   }
   const dest = join3(pluginsFolder, ASSET_NAME);
-  console.log(`Downloading ${ASSET_NAME} from ${release.tag_name}...`);
+  log(`Downloading ${ASSET_NAME} from ${release.tag_name}...`);
   await download(asset.browser_download_url, dest);
-  console.log(`Installed to ${dest}`);
+  log(`Installed to ${dest}`);
 }
 var REPO, ASSET_NAME, OTHER_VARIANT, TIMEOUT_MS, MAX_REDIRECTS;
 var init_install_plugin = __esm({
@@ -7439,6 +7533,18 @@ if (process.argv.includes("--install-plugin")) {
     process.exitCode = 1;
   });
 } else {
+  if (process.argv.includes("--auto-install-plugin")) {
+    const { installBundledPlugin: installBundledPlugin2 } = await Promise.resolve().then(() => (init_install_plugin(), install_plugin_exports));
+    await installBundledPlugin2({
+      replaceVariant: process.argv.includes("--replace-variant"),
+      log: (message) => console.error(`[install-plugin] ${message}`),
+      warn: (message) => console.error(message)
+    }).catch((err) => {
+      console.error(
+        `[install-plugin] Auto-install skipped: ${err instanceof Error ? err.message : String(err)}`
+      );
+    });
+  }
   const flagValue = (flag) => {
     const idx = process.argv.indexOf(flag);
     return idx !== -1 && idx + 1 < process.argv.length ? process.argv[idx + 1] : void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrrxs/robloxstudio-mcp",
-  "version": "2.15.0",
+  "version": "2.15.1",
   "description": "MCP server for testing, debugging, and controlling Roblox Studio from AI coding tools",
   "main": "dist/index.js",
   "type": "module",
@@ -28,7 +28,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/chrrxs/robloxstudio-mcp.git"
+    "url": "git+https://github.com/chrrxs/robloxstudio-mcp.git"
   },
   "homepage": "https://github.com/chrrxs/robloxstudio-mcp#readme",
   "bugs": {

package/studio-plugin/INSTALLATION.md

@@ -15,6 +15,7 @@ Complete your AI assistant integration with this easy-to-install Studio plugin.
 ### Method 2: Direct Download
 1. **Download the plugin:**
    - **GitHub Release**: [Download MCPPlugin.rbxmx](https://github.com/chrrxs/robloxstudio-mcp/releases/latest/download/MCPPlugin.rbxmx)
+   - **CLI installer**: `npx -y @chrrxs/robloxstudio-mcp@latest --install-plugin`
    - This is the official Roblox plugin format
 
 2. **Install to plugins folder:**
@@ -54,7 +55,12 @@ Choose your AI assistant:
 
 **For Claude Code:**
 ```bash
-claude mcp add robloxstudio-mcp
+claude mcp add robloxstudio -- npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin
+```
+
+**For Codex CLI:**
+```bash
+codex mcp add robloxstudio -- npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin
 ```
 
 **For Claude Desktop/Others:**
@@ -63,12 +69,16 @@ claude mcp add robloxstudio-mcp
   "mcpServers": {
     "robloxstudio-mcp": {
       "command": "npx",
-      "args": ["-y", "@chrrxs/robloxstudio-mcp"]
+      "args": ["-y", "@chrrxs/robloxstudio-mcp@latest", "--auto-install-plugin"]
     }
   }
 }
 ```
 
+`@latest` floats the server package to the newest npm release. `--auto-install-plugin` copies the matching `.rbxmx` bundled with that package into Studio's Plugins folder when the server starts.
+
+If Studio shows a yellow plugin/server version mismatch banner, the connection remains usable. Restart the MCP server with `--auto-install-plugin`, then fully close and reopen Studio so it loads the matching plugin file.
+
 <details>
 <summary>Note for native Windows users</summary>
 If you encounter issues, you may need to run it through `cmd`. Update your configuration like this:
@@ -78,7 +88,7 @@ If you encounter issues, you may need to run it through `cmd`. Update your confi
   "mcpServers": {
     "robloxstudio-mcp": {
       "command": "cmd",
-      "args": ["/c", "npx", "-y", "@chrrxs/robloxstudio-mcp@latest"]
+      "args": ["/c", "npx", "-y", "@chrrxs/robloxstudio-mcp@latest", "--auto-install-plugin"]
     }
   }
 }

package/studio-plugin/MCPInspectorPlugin.rbxmx

@@ -106,6 +106,7 @@ local SceneAnalysisHandlers = TS.import(script, script.Parent, "handlers", "Scen
 local CaptureHandlers = TS.import(script, script.Parent, "handlers", "CaptureHandlers")
 local InputHandlers = TS.import(script, script.Parent, "handlers", "InputHandlers")
 local LuauExec = TS.import(script, script.Parent, "LuauExec")
+local State = TS.import(script, script.Parent, "State")
 local StudioTestService = game:GetService("StudioTestService")
 -- Mirror of Communication.computeInstanceId() — duplicated here because the
 -- client broker runs in the play-server DM where it can't easily import from
@@ -201,6 +202,8 @@ local function reRegisterProxy(proxyId, role)
 			placeName = resolvePlaceName(),
 			dataModelName = game.Name,
 			isRunning = RunService:IsRunning(),
+			pluginVersion = State.CURRENT_VERSION,
+			pluginVariant = State.PLUGIN_VARIANT,
 		})
 	end)
 end
@@ -456,6 +459,8 @@ local function registerProxy(player, rf)
 		placeName = resolvePlaceName(),
 		dataModelName = game.Name,
 		isRunning = RunService:IsRunning(),
+		pluginVersion = State.CURRENT_VERSION,
+		pluginVariant = State.PLUGIN_VARIANT,
 	})
 	if not ok or not res or not res.Success then
 		warn(`[robloxstudio-mcp] proxy register failed for {player.Name}`)
@@ -584,6 +589,8 @@ end
 local instanceId = computeInstanceId()
 local assignedRole
 local duplicateInstanceRole = false
+local hasVersionMismatch = false
+local lastVersionMismatchWarningKey
 -- Cache the published place name from MarketplaceService:GetProductInfo so
 -- /ready can carry a friendly identifier (e.g. "Natural Disasters") distinct
 -- from game.Name (the DataModel name, often "Place1" in edit). We only fetch
@@ -783,6 +790,8 @@ function sendReady(conn)
 					placeName = resolvePlaceName(),
 					dataModelName = game.Name,
 					isRunning = RunService:IsRunning(),
+					pluginVersion = State.CURRENT_VERSION,
+					pluginVariant = State.PLUGIN_VARIANT,
 					pluginReady = true,
 					timestamp = tick(),
 				}),
@@ -848,6 +857,23 @@ local function pollForRequests(connIndex)
 		local mcpConnected = data.mcpConnected == true
 		conn.lastHttpOk = true
 		conn.lastMcpOk = mcpConnected
+		local _condition = data.serverVersion
+		if _condition == nil then
+			_condition = "unknown"
+		end
+		local serverVersion = _condition
+		if data.versionMismatch == true then
+			hasVersionMismatch = true
+			local warningKey = `{State.CURRENT_VERSION}:{serverVersion}`
+			if lastVersionMismatchWarningKey ~= warningKey then
+				lastVersionMismatchWarningKey = warningKey
+				warn(`[MCPPlugin] Version mismatch: Studio plugin v{State.CURRENT_VERSION} / MCP v{serverVersion}. Run npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin and restart Studio.`)
+			end
+			UI.showBanner("version-mismatch", `Plugin v{State.CURRENT_VERSION} / MCP v{serverVersion} mismatch`)
+		elseif hasVersionMismatch then
+			hasVersionMismatch = false
+			UI.hideBanner("version-mismatch")
+		end
 		-- Server tells us when its in-memory instances map doesn't have us
 		-- (e.g. after an MCP process restart). Re-issue /ready immediately so
 		-- target=server/client-N start routing again. The throttle inside
@@ -860,12 +886,12 @@ local function pollForRequests(connIndex)
 			local el = ui
 			el.step1Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
 			el.step1Label.Text = "HTTP server (OK)"
-			local _condition = mcpConnected
-			if _condition then
+			local _condition_1 = mcpConnected
+			if _condition_1 then
 				local _value = (string.find(el.statusLabel.Text, "Connected"))
-				_condition = not (_value ~= 0 and _value == _value and _value)
+				_condition_1 = not (_value ~= 0 and _value == _value and _value)
 			end
-			if _condition then
+			if _condition_1 then
 				el.statusLabel.Text = "Connected"
 				el.statusLabel.TextColor3 = Color3.fromRGB(34, 197, 94)
 				el.statusIndicator.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
@@ -896,11 +922,11 @@ local function pollForRequests(connIndex)
 					conn.mcpWaitStartTime = tick()
 				end
 				local _exp = tick()
-				local _condition_1 = conn.mcpWaitStartTime
-				if _condition_1 == nil then
-					_condition_1 = tick()
+				local _condition_2 = conn.mcpWaitStartTime
+				if _condition_2 == nil then
+					_condition_2 = tick()
 				end
-				local elapsed = _exp - _condition_1
+				local elapsed = _exp - _condition_2
 				el.troubleshootLabel.Visible = elapsed > 8
 				UI.startPulseAnimation()
 			end
@@ -1109,11 +1135,9 @@ local function checkForUpdates()
 			if _condition ~= "" and _condition then
 				local latestVersion = data.version
 				if Utils.compareVersions(State.CURRENT_VERSION, latestVersion) < 0 then
-					local ui = UI.getElements()
-					ui.updateBannerText.Text = `v{latestVersion} available - github.com/chrrxs/robloxstudio-mcp`
-					ui.updateBanner.Visible = true
-					ui.contentFrame.Position = UDim2.new(0, 8, 0, 92)
-					ui.contentFrame.Size = UDim2.new(1, -16, 1, -100)
+					if not hasVersionMismatch then
+						UI.showBanner("update", `v{latestVersion} available - github.com/chrrxs/robloxstudio-mcp`)
+					end
 				end
 			end
 		end
@@ -1263,9 +1287,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.15.0" is replaced with the package version at package time
+	-- "2.15.1" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-2.15.0`
+	return `{tostring(h)}-2.15.1`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -7441,7 +7465,8 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.15.0"
+local CURRENT_VERSION = "2.15.1"
+local PLUGIN_VARIANT = "inspector"
 local MAX_CONNECTIONS = 5
 local BASE_PORT = 58741
 local activeTabIndex = 0
@@ -7519,6 +7544,7 @@ local function getConnections()
 end
 return {
 	CURRENT_VERSION = CURRENT_VERSION,
+	PLUGIN_VARIANT = PLUGIN_VARIANT,
 	MAX_CONNECTIONS = MAX_CONNECTIONS,
 	BASE_PORT = BASE_PORT,
 	connections = connections,
@@ -7691,6 +7717,7 @@ local buttonHover = false
 local toolbarButton
 local toolbarIcons
 local lastToolbarIcon
+local activeBannerKind
 local updateToolbarIcon
 local function setToolbarButton(btn, icons)
 	toolbarButton = btn
@@ -7721,6 +7748,23 @@ local TWEEN_QUICK = TweenInfo.new(0.15, Enum.EasingStyle.Quad, Enum.EasingDirect
 local function tweenProp(instance, props)
 	TweenService:Create(instance, TWEEN_QUICK, props):Play()
 end
+local function showBanner(kind, text)
+	activeBannerKind = kind
+	elements.updateBannerText.Text = text
+	elements.updateBanner.Visible = true
+	elements.contentFrame.Position = UDim2.new(0, 8, 0, 92)
+	elements.contentFrame.Size = UDim2.new(1, -16, 1, -100)
+end
+local function hideBanner(kind)
+	if kind ~= nil and activeBannerKind ~= kind then
+		return nil
+	end
+	activeBannerKind = nil
+	elements.updateBanner.Visible = false
+	elements.updateBannerText.Text = ""
+	elements.contentFrame.Position = UDim2.new(0, 8, 0, 66)
+	elements.contentFrame.Size = UDim2.new(1, -16, 1, -74)
+end
 local C = {
 	bg = Color3.fromRGB(14, 14, 14),
 	card = Color3.fromRGB(22, 22, 22),
@@ -8422,6 +8466,8 @@ return {
 	startPulseAnimation = startPulseAnimation,
 	setToolbarButton = setToolbarButton,
 	updateToolbarIcon = updateToolbarIcon,
+	showBanner = showBanner,
+	hideBanner = hideBanner,
 	getElements = function()
 		return elements
 	end,

package/studio-plugin/MCPPlugin.rbxmx

@@ -106,6 +106,7 @@ local SceneAnalysisHandlers = TS.import(script, script.Parent, "handlers", "Scen
 local CaptureHandlers = TS.import(script, script.Parent, "handlers", "CaptureHandlers")
 local InputHandlers = TS.import(script, script.Parent, "handlers", "InputHandlers")
 local LuauExec = TS.import(script, script.Parent, "LuauExec")
+local State = TS.import(script, script.Parent, "State")
 local StudioTestService = game:GetService("StudioTestService")
 -- Mirror of Communication.computeInstanceId() — duplicated here because the
 -- client broker runs in the play-server DM where it can't easily import from
@@ -201,6 +202,8 @@ local function reRegisterProxy(proxyId, role)
 			placeName = resolvePlaceName(),
 			dataModelName = game.Name,
 			isRunning = RunService:IsRunning(),
+			pluginVersion = State.CURRENT_VERSION,
+			pluginVariant = State.PLUGIN_VARIANT,
 		})
 	end)
 end
@@ -456,6 +459,8 @@ local function registerProxy(player, rf)
 		placeName = resolvePlaceName(),
 		dataModelName = game.Name,
 		isRunning = RunService:IsRunning(),
+		pluginVersion = State.CURRENT_VERSION,
+		pluginVariant = State.PLUGIN_VARIANT,
 	})
 	if not ok or not res or not res.Success then
 		warn(`[robloxstudio-mcp] proxy register failed for {player.Name}`)
@@ -584,6 +589,8 @@ end
 local instanceId = computeInstanceId()
 local assignedRole
 local duplicateInstanceRole = false
+local hasVersionMismatch = false
+local lastVersionMismatchWarningKey
 -- Cache the published place name from MarketplaceService:GetProductInfo so
 -- /ready can carry a friendly identifier (e.g. "Natural Disasters") distinct
 -- from game.Name (the DataModel name, often "Place1" in edit). We only fetch
@@ -783,6 +790,8 @@ function sendReady(conn)
 					placeName = resolvePlaceName(),
 					dataModelName = game.Name,
 					isRunning = RunService:IsRunning(),
+					pluginVersion = State.CURRENT_VERSION,
+					pluginVariant = State.PLUGIN_VARIANT,
 					pluginReady = true,
 					timestamp = tick(),
 				}),
@@ -848,6 +857,23 @@ local function pollForRequests(connIndex)
 		local mcpConnected = data.mcpConnected == true
 		conn.lastHttpOk = true
 		conn.lastMcpOk = mcpConnected
+		local _condition = data.serverVersion
+		if _condition == nil then
+			_condition = "unknown"
+		end
+		local serverVersion = _condition
+		if data.versionMismatch == true then
+			hasVersionMismatch = true
+			local warningKey = `{State.CURRENT_VERSION}:{serverVersion}`
+			if lastVersionMismatchWarningKey ~= warningKey then
+				lastVersionMismatchWarningKey = warningKey
+				warn(`[MCPPlugin] Version mismatch: Studio plugin v{State.CURRENT_VERSION} / MCP v{serverVersion}. Run npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin and restart Studio.`)
+			end
+			UI.showBanner("version-mismatch", `Plugin v{State.CURRENT_VERSION} / MCP v{serverVersion} mismatch`)
+		elseif hasVersionMismatch then
+			hasVersionMismatch = false
+			UI.hideBanner("version-mismatch")
+		end
 		-- Server tells us when its in-memory instances map doesn't have us
 		-- (e.g. after an MCP process restart). Re-issue /ready immediately so
 		-- target=server/client-N start routing again. The throttle inside
@@ -860,12 +886,12 @@ local function pollForRequests(connIndex)
 			local el = ui
 			el.step1Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
 			el.step1Label.Text = "HTTP server (OK)"
-			local _condition = mcpConnected
-			if _condition then
+			local _condition_1 = mcpConnected
+			if _condition_1 then
 				local _value = (string.find(el.statusLabel.Text, "Connected"))
-				_condition = not (_value ~= 0 and _value == _value and _value)
+				_condition_1 = not (_value ~= 0 and _value == _value and _value)
 			end
-			if _condition then
+			if _condition_1 then
 				el.statusLabel.Text = "Connected"
 				el.statusLabel.TextColor3 = Color3.fromRGB(34, 197, 94)
 				el.statusIndicator.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
@@ -896,11 +922,11 @@ local function pollForRequests(connIndex)
 					conn.mcpWaitStartTime = tick()
 				end
 				local _exp = tick()
-				local _condition_1 = conn.mcpWaitStartTime
-				if _condition_1 == nil then
-					_condition_1 = tick()
+				local _condition_2 = conn.mcpWaitStartTime
+				if _condition_2 == nil then
+					_condition_2 = tick()
 				end
-				local elapsed = _exp - _condition_1
+				local elapsed = _exp - _condition_2
 				el.troubleshootLabel.Visible = elapsed > 8
 				UI.startPulseAnimation()
 			end
@@ -1109,11 +1135,9 @@ local function checkForUpdates()
 			if _condition ~= "" and _condition then
 				local latestVersion = data.version
 				if Utils.compareVersions(State.CURRENT_VERSION, latestVersion) < 0 then
-					local ui = UI.getElements()
-					ui.updateBannerText.Text = `v{latestVersion} available - github.com/chrrxs/robloxstudio-mcp`
-					ui.updateBanner.Visible = true
-					ui.contentFrame.Position = UDim2.new(0, 8, 0, 92)
-					ui.contentFrame.Size = UDim2.new(1, -16, 1, -100)
+					if not hasVersionMismatch then
+						UI.showBanner("update", `v{latestVersion} available - github.com/chrrxs/robloxstudio-mcp`)
+					end
 				end
 			end
 		end
@@ -1263,9 +1287,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.15.0" is replaced with the package version at package time
+	-- "2.15.1" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-2.15.0`
+	return `{tostring(h)}-2.15.1`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -7441,7 +7465,8 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.15.0"
+local CURRENT_VERSION = "2.15.1"
+local PLUGIN_VARIANT = "main"
 local MAX_CONNECTIONS = 5
 local BASE_PORT = 58741
 local activeTabIndex = 0
@@ -7519,6 +7544,7 @@ local function getConnections()
 end
 return {
 	CURRENT_VERSION = CURRENT_VERSION,
+	PLUGIN_VARIANT = PLUGIN_VARIANT,
 	MAX_CONNECTIONS = MAX_CONNECTIONS,
 	BASE_PORT = BASE_PORT,
 	connections = connections,
@@ -7691,6 +7717,7 @@ local buttonHover = false
 local toolbarButton
 local toolbarIcons
 local lastToolbarIcon
+local activeBannerKind
 local updateToolbarIcon
 local function setToolbarButton(btn, icons)
 	toolbarButton = btn
@@ -7721,6 +7748,23 @@ local TWEEN_QUICK = TweenInfo.new(0.15, Enum.EasingStyle.Quad, Enum.EasingDirect
 local function tweenProp(instance, props)
 	TweenService:Create(instance, TWEEN_QUICK, props):Play()
 end
+local function showBanner(kind, text)
+	activeBannerKind = kind
+	elements.updateBannerText.Text = text
+	elements.updateBanner.Visible = true
+	elements.contentFrame.Position = UDim2.new(0, 8, 0, 92)
+	elements.contentFrame.Size = UDim2.new(1, -16, 1, -100)
+end
+local function hideBanner(kind)
+	if kind ~= nil and activeBannerKind ~= kind then
+		return nil
+	end
+	activeBannerKind = nil
+	elements.updateBanner.Visible = false
+	elements.updateBannerText.Text = ""
+	elements.contentFrame.Position = UDim2.new(0, 8, 0, 66)
+	elements.contentFrame.Size = UDim2.new(1, -16, 1, -74)
+end
 local C = {
 	bg = Color3.fromRGB(14, 14, 14),
 	card = Color3.fromRGB(22, 22, 22),
@@ -8422,6 +8466,8 @@ return {
 	startPulseAnimation = startPulseAnimation,
 	setToolbarButton = setToolbarButton,
 	updateToolbarIcon = updateToolbarIcon,
+	showBanner = showBanner,
+	hideBanner = hideBanner,
 	getElements = function()
 		return elements
 	end,

package/studio-plugin/src/modules/ClientBroker.ts

@@ -5,6 +5,7 @@ import SceneAnalysisHandlers from "./handlers/SceneAnalysisHandlers";
 import CaptureHandlers from "./handlers/CaptureHandlers";
 import InputHandlers from "./handlers/InputHandlers";
 import LuauExec from "./LuauExec";
+import State from "./State";
 
 interface StudioTestServiceMultiplayer extends StudioTestService {
 	CanLeaveTest(): boolean;
@@ -134,6 +135,8 @@ function reRegisterProxy(proxyId: string, role: string): void {
 			placeName: resolvePlaceName(),
 			dataModelName: game.Name,
 			isRunning: RunService.IsRunning(),
+			pluginVersion: State.CURRENT_VERSION,
+			pluginVariant: State.PLUGIN_VARIANT,
 		}),
 	);
 }
@@ -329,6 +332,8 @@ function registerProxy(player: Player, rf: RemoteFunction) {
 		placeName: resolvePlaceName(),
 		dataModelName: game.Name,
 		isRunning: RunService.IsRunning(),
+		pluginVersion: State.CURRENT_VERSION,
+		pluginVariant: State.PLUGIN_VARIANT,
 	});
 	if (!ok || !res || !res.Success) {
 		warn(`[robloxstudio-mcp] proxy register failed for ${player.Name}`);

package/studio-plugin/src/modules/Communication.ts

@@ -47,6 +47,8 @@ function computeInstanceId(): string {
 const instanceId = computeInstanceId();
 let assignedRole: string | undefined;
 let duplicateInstanceRole = false;
+let hasVersionMismatch = false;
+let lastVersionMismatchWarningKey: string | undefined;
 
 // Cache the published place name from MarketplaceService:GetProductInfo so
 // /ready can carry a friendly identifier (e.g. "Natural Disasters") distinct
@@ -238,6 +240,8 @@ function sendReady(conn: Connection): void {
 					placeName: resolvePlaceName(),
 					dataModelName: game.Name,
 					isRunning: RunService.IsRunning(),
+					pluginVersion: State.CURRENT_VERSION,
+					pluginVariant: State.PLUGIN_VARIANT,
 					pluginReady: true,
 					timestamp: tick(),
 				}),
@@ -301,6 +305,19 @@ function pollForRequests(connIndex: number) {
 		const mcpConnected = data.mcpConnected === true;
 		conn.lastHttpOk = true;
 		conn.lastMcpOk = mcpConnected;
+		const serverVersion = data.serverVersion ?? "unknown";
+		if (data.versionMismatch === true) {
+			hasVersionMismatch = true;
+			const warningKey = `${State.CURRENT_VERSION}:${serverVersion}`;
+			if (lastVersionMismatchWarningKey !== warningKey) {
+				lastVersionMismatchWarningKey = warningKey;
+				warn(`[MCPPlugin] Version mismatch: Studio plugin v${State.CURRENT_VERSION} / MCP v${serverVersion}. Run npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin and restart Studio.`);
+			}
+			UI.showBanner("version-mismatch", `Plugin v${State.CURRENT_VERSION} / MCP v${serverVersion} mismatch`);
+		} else if (hasVersionMismatch) {
+			hasVersionMismatch = false;
+			UI.hideBanner("version-mismatch");
+		}
 
 		// Server tells us when its in-memory instances map doesn't have us
 		// (e.g. after an MCP process restart). Re-issue /ready immediately so
@@ -539,11 +556,9 @@ function checkForUpdates() {
 			if (ok && data?.version) {
 				const latestVersion = data.version;
 				if (Utils.compareVersions(State.CURRENT_VERSION, latestVersion) < 0) {
-					const ui = UI.getElements();
-					ui.updateBannerText.Text = `v${latestVersion} available - github.com/chrrxs/robloxstudio-mcp`;
-					ui.updateBanner.Visible = true;
-					ui.contentFrame.Position = new UDim2(0, 8, 0, 92);
-					ui.contentFrame.Size = new UDim2(1, -16, 1, -100);
+					if (!hasVersionMismatch) {
+						UI.showBanner("update", `v${latestVersion} available - github.com/chrrxs/robloxstudio-mcp`);
+					}
 				}
 			}
 		}

package/studio-plugin/src/modules/State.ts

@@ -1,6 +1,7 @@
 import { Connection } from "../types";
 
 const CURRENT_VERSION = "__VERSION__";
+const PLUGIN_VARIANT = "__PLUGIN_VARIANT__";
 const MAX_CONNECTIONS = 5;
 const BASE_PORT = 58741;
 let activeTabIndex = 0;
@@ -81,6 +82,7 @@ function getConnections(): Connection[] {
 
 export = {
 	CURRENT_VERSION,
+	PLUGIN_VARIANT,
 	MAX_CONNECTIONS,
 	BASE_PORT,
 	connections,

package/studio-plugin/src/modules/UI.ts

@@ -38,6 +38,7 @@ interface ToolbarIcons {
 let toolbarButton: PluginToolbarButton | undefined;
 let toolbarIcons: ToolbarIcons | undefined;
 let lastToolbarIcon: string | undefined;
+let activeBannerKind: string | undefined;
 
 function setToolbarButton(btn: PluginToolbarButton, icons: ToolbarIcons) {
 	toolbarButton = btn;
@@ -77,6 +78,23 @@ function tweenProp(instance: Instance, props: Record<string, unknown>) {
 	TweenService.Create(instance, TWEEN_QUICK, props as unknown as { [key: string]: unknown }).Play();
 }
 
+function showBanner(kind: string, text: string) {
+	activeBannerKind = kind;
+	elements.updateBannerText.Text = text;
+	elements.updateBanner.Visible = true;
+	elements.contentFrame.Position = new UDim2(0, 8, 0, 92);
+	elements.contentFrame.Size = new UDim2(1, -16, 1, -100);
+}
+
+function hideBanner(kind?: string) {
+	if (kind !== undefined && activeBannerKind !== kind) return;
+	activeBannerKind = undefined;
+	elements.updateBanner.Visible = false;
+	elements.updateBannerText.Text = "";
+	elements.contentFrame.Position = new UDim2(0, 8, 0, 66);
+	elements.contentFrame.Size = new UDim2(1, -16, 1, -74);
+}
+
 const C = {
 	bg: Color3.fromRGB(14, 14, 14),
 	card: Color3.fromRGB(22, 22, 22),
@@ -759,5 +777,7 @@ export = {
 	startPulseAnimation,
 	setToolbarButton,
 	updateToolbarIcon,
+	showBanner,
+	hideBanner,
 	getElements: () => elements,
 };

package/studio-plugin/src/types/index.d.ts

@@ -30,6 +30,10 @@ export interface RequestPayload {
 
 export interface PollResponse {
 	mcpConnected: boolean;
+	serverVersion?: string;
+	pluginVersion?: string;
+	pluginVariant?: string;
+	versionMismatch?: boolean;
 	request?: RequestPayload;
 	requestId?: string;
 	// Server signals knownInstance=false when its in-memory instances map
@@ -42,6 +46,8 @@ export interface ReadyResponse {
 	success: boolean;
 	assignedRole?: string;
 	instanceId?: string;
+	serverVersion?: string;
+	versionMismatch?: boolean;
 	error?: string;
 	message?: string;
 }