@princeofscale/bloxforge 2.20.2 → 3.0.0-rc.1

package/dist/index.js

@@ -1222,6 +1222,7 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig, registry) {
   let mcpServerStartTime = 0;
   const proxyInstances = /* @__PURE__ */ new Set();
   const warnedVersionMismatches = /* @__PURE__ */ new Set();
+  const warnedProtocolMismatches = /* @__PURE__ */ new Set();
   const setMCPServerActive = (active) => {
     mcpServerActive = active;
     if (active) {
@@ -1346,6 +1347,10 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig, registry) {
       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}`);
     }
+    if (registered?.protocolMismatch && !warnedProtocolMismatches.has(pluginSessionId)) {
+      warnedProtocolMismatches.add(pluginSessionId);
+      console.error(`[protocol-mismatch] Studio plugin protocol v${registered.pluginProtocolVersion} does not match MCP server protocol v${registered.serverProtocolVersion} for ${registered.instanceId}/${registered.role}. Run --auto-install-plugin to update the plugin.`);
+    }
     res.json({
       success: true,
       assignedRole: result.assignedRole,
@@ -1353,13 +1358,16 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig, registry) {
       serverVersion: serverConfig?.version,
       serverProtocolVersion: MCP_PROTOCOL_VERSION,
       versionMismatch: registered?.versionMismatch ?? false,
-      protocolMismatch: registered?.protocolMismatch ?? false
+      protocolMismatch: registered?.protocolMismatch ?? false,
+      capabilities: ["core", "scene", "mutation", "scripts", "runtime", "assets", "ui", "environment", "terrain", "build", "media", "sync", "safety"]
     });
   });
   app.post("/disconnect", (req, res) => {
     const { pluginSessionId } = req.body;
     if (pluginSessionId) {
       bridge.unregisterInstance(pluginSessionId, "plugin_request");
+      warnedVersionMismatches.delete(pluginSessionId);
+      warnedProtocolMismatches.delete(pluginSessionId);
     }
     res.json({ success: true });
   });
@@ -3828,7 +3836,7 @@ var init_scripting = __esm({
             },
             usePattern: {
               type: "boolean",
-              description: "Use Lua pattern matching instead of literal (default: false)"
+              description: "Use Lua pattern matching instead of literal (default: false). Lua patterns do not support regex alternation; | is literal, so run separate searches for alternatives."
             },
             contextLines: {
               type: "number",
@@ -8697,8 +8705,8 @@ function crc32(buf) {
     crc = CRC_TABLE[(crc ^ buf[i]) & 255] ^ crc >>> 8;
   return (crc ^ 4294967295) >>> 0;
 }
-function writeChunk(type, data) {
-  const typeBytes = Buffer.from(type, "ascii");
+function writeChunk(type2, data) {
+  const typeBytes = Buffer.from(type2, "ascii");
   const length = Buffer.alloc(4);
   length.writeUInt32BE(data.length);
   const crcInput = Buffer.concat([typeBytes, data]);
@@ -10627,10 +10635,12 @@ var init_asset_tools = __esm({
       static findLibraryPath() {
         if (_AssetTools._cachedLibraryPath)
           return _AssetTools._cachedLibraryPath;
-        const overridePath = process.env.ROBLOXSTUDIO_MCP_BUILD_LIBRARY || process.env.BUILD_LIBRARY_PATH;
+        const overridePath = process.env.BLOXFORGE_BUILD_LIBRARY || process.env.ROBLOXSTUDIO_MCP_BUILD_LIBRARY || process.env.BUILD_LIBRARY_PATH;
         const cwd = path.resolve(process.cwd());
         const projectRoot = _AssetTools.findProjectRoot(cwd);
-        const homeLibraryPath = path.join(os.homedir(), ".robloxstudio-mcp", "build-library");
+        const newHomeLibraryPath = path.join(os.homedir(), ".bloxforge", "build-library");
+        const legacyHomeLibraryPath = path.join(os.homedir(), ".robloxstudio-mcp", "build-library");
+        const homeLibraryPath = fs.existsSync(newHomeLibraryPath) ? newHomeLibraryPath : fs.existsSync(legacyHomeLibraryPath) ? legacyHomeLibraryPath : newHomeLibraryPath;
         const projectLibraryPath = projectRoot ? path.join(projectRoot, "build-library") : null;
         const cwdLibraryPath = path.join(cwd, "build-library");
         let result;
@@ -15139,16 +15149,30 @@ import * as fs4 from "fs";
 import * as os2 from "os";
 import * as path4 from "path";
 function defaultManagedInstanceRegistryDir() {
+  if (process.env.BLOXFORGE_MANAGED_INSTANCE_REGISTRY_DIR) {
+    return process.env.BLOXFORGE_MANAGED_INSTANCE_REGISTRY_DIR;
+  }
   if (process.env.ROBLOXSTUDIO_MCP_MANAGED_INSTANCE_REGISTRY_DIR) {
     return process.env.ROBLOXSTUDIO_MCP_MANAGED_INSTANCE_REGISTRY_DIR;
   }
+  const suffix = path4.join("managed-instances", "v1");
+  let newDir;
+  let legacyDir;
   if (process.platform === "win32" && process.env.LOCALAPPDATA) {
-    return path4.join(process.env.LOCALAPPDATA, "robloxstudio-mcp", "managed-instances", "v1");
-  }
-  if (process.platform === "darwin") {
-    return path4.join(os2.homedir(), "Library", "Application Support", "robloxstudio-mcp", "managed-instances", "v1");
+    newDir = path4.join(process.env.LOCALAPPDATA, "bloxforge", suffix);
+    legacyDir = path4.join(process.env.LOCALAPPDATA, "robloxstudio-mcp", suffix);
+  } else if (process.platform === "darwin") {
+    newDir = path4.join(os2.homedir(), "Library", "Application Support", "bloxforge", suffix);
+    legacyDir = path4.join(os2.homedir(), "Library", "Application Support", "robloxstudio-mcp", suffix);
+  } else {
+    newDir = path4.join(os2.homedir(), ".local", "state", "bloxforge", suffix);
+    legacyDir = path4.join(os2.homedir(), ".local", "state", "robloxstudio-mcp", suffix);
   }
-  return path4.join(os2.homedir(), ".local", "state", "robloxstudio-mcp", "managed-instances", "v1");
+  if (fs4.existsSync(newDir))
+    return newDir;
+  if (fs4.existsSync(legacyDir))
+    return legacyDir;
+  return newDir;
 }
 function sleepSync(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
@@ -15424,7 +15448,7 @@ var init_managed_instance_registry = __esm({
 
 // ../core/dist/studio-instance-manager.js
 import { execFileSync, spawn } from "child_process";
-import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync4, realpathSync, rmSync as rmSync2, statSync as statSync3 } from "fs";
+import { copyFileSync, existsSync as existsSync3, mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync4, realpathSync, rmSync as rmSync2, statSync as statSync3 } from "fs";
 import { randomUUID as randomUUID2 } from "crypto";
 import * as os3 from "os";
 import * as path5 from "path";
@@ -15446,7 +15470,7 @@ function isWsl() {
 }
 function powershell(script) {
   return run("powershell.exe", ["-NoProfile", "-Command", script], {
-    cwd: isWsl() && existsSync2("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd()
+    cwd: isWsl() && existsSync3("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd()
   });
 }
 function windowsLocalAppData() {
@@ -15456,7 +15480,7 @@ function windowsLocalAppData() {
     return void 0;
   try {
     return run("cmd.exe", ["/c", "echo %LOCALAPPDATA%"], {
-      cwd: existsSync2("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd()
+      cwd: existsSync3("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd()
     });
   } catch {
     return void 0;
@@ -15468,7 +15492,7 @@ function toWslPath(windowsPath) {
   return run("wslpath", ["-u", windowsPath]);
 }
 function toStudioLaunchArg(arg) {
-  if (!isWsl() || !path5.isAbsolute(arg) || !existsSync2(arg))
+  if (!isWsl() || !path5.isAbsolute(arg) || !existsSync3(arg))
     return arg;
   return run("wslpath", ["-w", arg]);
 }
@@ -15494,7 +15518,7 @@ function resolveBaseplateTemplatePath() {
     path5.join(process.cwd(), "assets", BASEPLATE_TEMPLATE_NAME)
   ];
   for (const candidate of candidates) {
-    if (existsSync2(candidate))
+    if (existsSync3(candidate))
       return candidate;
   }
   throw new Error(`Baseplate template not found. Expected ${BASEPLATE_TEMPLATE_NAME} in one of: ${candidates.join(", ")}`);
@@ -15571,10 +15595,10 @@ function resolveStudioExe() {
   }
   const localAppData = windowsLocalAppData();
   const root = localAppData ? path5.join(toWslPath(localAppData), "Roblox", "Versions") : path5.join(os3.homedir(), "AppData", "Local", "Roblox", "Versions");
-  if (!existsSync2(root)) {
+  if (!existsSync3(root)) {
     throw new Error(`Roblox Studio Versions folder not found: ${root}. Set ROBLOX_STUDIO_EXE.`);
   }
-  const candidates = readdirSync4(root).filter((name) => name.startsWith("version-")).map((name) => path5.join(root, name, "RobloxStudioBeta.exe")).filter((candidate) => existsSync2(candidate)).sort((a, b) => statSync3(b).mtimeMs - statSync3(a).mtimeMs);
+  const candidates = readdirSync4(root).filter((name) => name.startsWith("version-")).map((name) => path5.join(root, name, "RobloxStudioBeta.exe")).filter((candidate) => existsSync3(candidate)).sort((a, b) => statSync3(b).mtimeMs - statSync3(a).mtimeMs);
   if (candidates.length === 0) {
     throw new Error(`RobloxStudioBeta.exe not found under ${root}. Set ROBLOX_STUDIO_EXE.`);
   }
@@ -15720,7 +15744,7 @@ var init_studio_instance_manager = __esm({
         const exe = this.processAdapter.resolveStudioExe?.() ?? resolveStudioExe();
         const args = buildStudioLaunchArgs(preparedOptions).map(toStudioLaunchArg);
         const spawnOptions = {
-          cwd: isWsl() && existsSync2("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd(),
+          cwd: isWsl() && existsSync3("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd(),
           detached: true,
           stdio: "ignore"
         };
@@ -16865,10 +16889,12 @@ var init_tools = __esm({
       static findLibraryPath() {
         if (_RobloxStudioTools._cachedLibraryPath)
           return _RobloxStudioTools._cachedLibraryPath;
-        const overridePath = process.env.ROBLOXSTUDIO_MCP_BUILD_LIBRARY || process.env.BUILD_LIBRARY_PATH;
+        const overridePath = process.env.BLOXFORGE_BUILD_LIBRARY || process.env.ROBLOXSTUDIO_MCP_BUILD_LIBRARY || process.env.BUILD_LIBRARY_PATH;
         const cwd = path6.resolve(process.cwd());
         const projectRoot = _RobloxStudioTools.findProjectRoot(cwd);
-        const homeLibraryPath = path6.join(os4.homedir(), ".robloxstudio-mcp", "build-library");
+        const newHomeLibraryPath = path6.join(os4.homedir(), ".bloxforge", "build-library");
+        const legacyHomeLibraryPath = path6.join(os4.homedir(), ".robloxstudio-mcp", "build-library");
+        const homeLibraryPath = fs5.existsSync(newHomeLibraryPath) ? newHomeLibraryPath : fs5.existsSync(legacyHomeLibraryPath) ? legacyHomeLibraryPath : newHomeLibraryPath;
         const projectLibraryPath = projectRoot ? path6.join(projectRoot, "build-library") : null;
         const cwdLibraryPath = path6.join(cwd, "build-library");
         let result;
@@ -18979,7 +19005,7 @@ var init_server = __esm({
 });
 
 // ../core/dist/install-plugin-helpers.js
-import { existsSync as existsSync4, readFileSync as readFileSync6, unlinkSync as unlinkSync2 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync6, unlinkSync as unlinkSync2 } from "fs";
 import { execSync } from "child_process";
 import { join as join6 } from "path";
 import { homedir as homedir5 } from "os";
@@ -19026,7 +19052,7 @@ function getPluginsFolder() {
 }
 function handleVariantConflict({ pluginsFolder, otherAssetName, replace, log = console.log, warn = console.warn }) {
   const otherDest = join6(pluginsFolder, otherAssetName);
-  if (!existsSync4(otherDest))
+  if (!existsSync5(otherDest))
     return;
   if (replace) {
     try {
@@ -19052,18 +19078,41 @@ var init_install_plugin_helpers = __esm({
 // ../core/dist/doctor.js
 import * as fs6 from "fs";
 import * as path7 from "path";
+import * as os5 from "os";
 function checkNodeVersion(version) {
   const major = parseInt(version.replace(/^v/, "").split(".")[0] ?? "0", 10);
   if (Number.isNaN(major) || major < 18) {
-    return { name: "Node version", status: "fail", detail: `${version} \u2014 Node 18+ is required.` };
+    return {
+      name: "Node version",
+      status: "fail",
+      detail: `${version} \u2014 Node 18+ is required.`,
+      actionable: {
+        fix: "Upgrade Node.js to version 18 or newer.",
+        verify: 'Run "node -v" to verify your version, then run "npx @princeofscale/bloxforge verify".'
+      }
+    };
   }
   return { name: "Node version", status: "ok", detail: version };
 }
 function formatDoctorReport(checks) {
-  const lines = checks.map((c) => `  ${SYMBOL[c.status]} ${c.name}: ${c.detail}`);
+  const lines = [];
+  for (const c of checks) {
+    lines.push(`  ${SYMBOL[c.status]} ${c.name}: ${c.detail}`);
+    if (c.status !== "ok" && c.actionable) {
+      lines.push(`      Fix: ${c.actionable.fix}`);
+      if (c.actionable.verify) {
+        lines.push(`      Verify: ${c.actionable.verify}`);
+      }
+    }
+  }
   const worst = checks.some((c) => c.status === "fail") ? "fail" : checks.some((c) => c.status === "warn") ? "warn" : "ok";
   const summary = worst === "ok" ? "All checks passed." : worst === "warn" ? "Some checks need attention (warnings)." : "Problems found \u2014 see failures above.";
-  return ["bloxforge doctor", ...lines, "", summary].join("\n");
+  return ["bloxforge doctor / verify", ...lines, "", summary].join("\n");
+}
+function fetchHealth(fetchImpl, port) {
+  return fetchImpl(`http://localhost:${port}/health`, {
+    signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS)
+  });
 }
 async function collectDoctorChecks(options = {}) {
   const checks = [];
@@ -19077,41 +19126,93 @@ async function collectDoctorChecks(options = {}) {
     const folder = getPluginsFolder();
     const variants = ["MCPPlugin.rbxmx", "MCPInspectorPlugin.rbxmx"];
     const found = variants.filter((v) => fs6.existsSync(path7.join(folder, v)));
-    checks.push(found.length > 0 ? { name: "Studio plugin installed", status: "ok", detail: `${found.join(", ")} in ${folder}` } : { name: "Studio plugin installed", status: "warn", detail: `none found in ${folder}. Run with --install-plugin.` });
+    checks.push(found.length > 0 ? { name: "Studio plugin installed", status: "ok", detail: `${found.join(", ")} in ${folder}` } : {
+      name: "Studio plugin installed",
+      status: "warn",
+      detail: `none found in ${folder}. Run with --install-plugin.`,
+      actionable: {
+        fix: 'Run "npx @princeofscale/bloxforge --install-plugin" to install the plugin to your local Roblox directory.',
+        verify: 'Run "npx @princeofscale/bloxforge verify" again to confirm installation.'
+      }
+    });
   } catch (error) {
-    checks.push({ name: "Studio plugin installed", status: "warn", detail: `could not resolve plugins folder: ${error instanceof Error ? error.message : String(error)}` });
+    checks.push({
+      name: "Studio plugin installed",
+      status: "warn",
+      detail: `could not resolve plugins folder: ${error instanceof Error ? error.message : String(error)}`,
+      actionable: {
+        fix: "Ensure your Roblox Studio installation is valid and accessible.",
+        verify: "Check if Roblox Studio opens correctly, then try again."
+      }
+    });
   }
   const port = options.port ?? (process.env.ROBLOX_STUDIO_PORT ? parseInt(process.env.ROBLOX_STUDIO_PORT) : 58741);
   const doFetch = options.fetchImpl ?? fetch;
   try {
-    const res = await doFetch(`http://localhost:${port}/health`);
+    const res = await fetchHealth(doFetch, port);
     if (res.ok) {
       const health = await res.json();
       checks.push({ name: "Local bridge running", status: "ok", detail: `responding on port ${port}` });
-      checks.push(health.pluginConnected ? { name: "Studio reachable", status: "ok", detail: `${health.instanceCount ?? 0} place(s) connected` } : { name: "Studio reachable", status: "warn", detail: "bridge up but no Studio plugin connected. Open Studio and enable Allow HTTP Requests." });
+      checks.push(health.pluginConnected ? { name: "Studio reachable", status: "ok", detail: `${health.instanceCount ?? 0} place(s) connected` } : {
+        name: "Studio reachable",
+        status: "warn",
+        detail: "bridge up but no Studio plugin connected.",
+        actionable: {
+          fix: 'Open Roblox Studio, open your place, and ensure "Allow HTTP Requests" is enabled in Game Settings -> Security. Play or Run the game.',
+          verify: 'Ensure the BloxForge plugin shows "Connected" in Studio, then run verify again.'
+        }
+      });
       checks.push({
         name: "Lazy tool loading",
         status: health.lazyTools === false ? "warn" : "ok",
         detail: health.lazyTools === false ? "disabled via ROBLOX_MCP_LAZY_TOOLS opt-out; all schemas are advertised upfront" : `default path active (${health.activeToolCount ?? 0} active tools; loaded ${health.loadedToolsets?.join(", ") || "core"})`
       });
       const first = health.instances?.[0];
-      if (first) {
+      const versionInstance = health.instances?.find((instance) => instance.versionMismatch) ?? first;
+      const protocolInstance = health.instances?.find((instance) => instance.protocolMismatch) ?? first;
+      if (versionInstance) {
         checks.push({
           name: "Studio plugin version",
-          status: health.versionMismatch || first.versionMismatch ? "warn" : "ok",
-          detail: `plugin v${first.pluginVersion ?? "unknown"} (${first.pluginVariant ?? "unknown"}), server v${health.serverVersion ?? health.version ?? options.version ?? "unknown"}`
+          status: health.versionMismatch || versionInstance.versionMismatch ? "warn" : "ok",
+          detail: `plugin v${versionInstance.pluginVersion ?? "unknown"} (${versionInstance.pluginVariant ?? "unknown"}), server v${health.serverVersion ?? health.version ?? options.version ?? "unknown"}`,
+          actionable: health.versionMismatch || versionInstance.versionMismatch ? {
+            fix: 'Run "npx @princeofscale/bloxforge --install-plugin" to synchronize the plugin version with your local server.',
+            verify: 'Restart Roblox Studio, then run "npx @princeofscale/bloxforge verify" and confirm this check passes.'
+          } : void 0
         });
+      }
+      if (protocolInstance) {
         checks.push({
           name: "Protocol version",
-          status: health.protocolMismatch || first.protocolMismatch ? "warn" : "ok",
-          detail: `plugin protocol ${first.pluginProtocolVersion ?? "unknown"}, server protocol ${first.serverProtocolVersion ?? health.protocolVersion ?? "unknown"}`
+          status: health.protocolMismatch || protocolInstance.protocolMismatch ? "warn" : "ok",
+          detail: `plugin protocol ${protocolInstance.pluginProtocolVersion ?? "unknown"}, server protocol ${protocolInstance.serverProtocolVersion ?? health.protocolVersion ?? "unknown"}`,
+          actionable: health.protocolMismatch || protocolInstance.protocolMismatch ? {
+            fix: "Your server and plugin are using incompatible communication protocols. Please update both to the latest versions.",
+            verify: 'Restart Roblox Studio, then run "npx @princeofscale/bloxforge verify" and confirm both protocol versions match.'
+          } : void 0
         });
       }
     } else {
-      checks.push({ name: "Local bridge running", status: "fail", detail: `port ${port} responded ${res.status}` });
+      checks.push({
+        name: "Local bridge running",
+        status: "fail",
+        detail: `port ${port} responded ${res.status}`,
+        actionable: {
+          fix: `Another application might be using port ${port}. Try running the server on a different port using --port <number>.`,
+          verify: 'Run "npx @princeofscale/bloxforge verify --port <number>" on the new port and confirm this check passes.'
+        }
+      });
     }
   } catch {
-    checks.push({ name: "Local bridge running", status: "warn", detail: `nothing responding on port ${port}. The bridge only runs while the MCP server is started by your client.` });
+    checks.push({
+      name: "Local bridge running",
+      status: "warn",
+      detail: `nothing responding on port ${port}. The bridge only runs while the MCP server is started.`,
+      actionable: {
+        fix: 'Start the BloxForge server in another terminal (e.g., via "npx @princeofscale/bloxforge") before running diagnostics.',
+        verify: 'Keep the server running, then in a new terminal run "npx @princeofscale/bloxforge verify".'
+      }
+    });
   }
   return checks;
 }
@@ -19120,12 +19221,85 @@ async function runDoctor(options = {}) {
   console.log(formatDoctorReport(checks));
   return checks.some((c) => c.status === "fail") ? 1 : 0;
 }
-var SYMBOL;
+async function generateDiagnosticReport(options = {}) {
+  const checks = await collectDoctorChecks(options);
+  const home = os5.homedir();
+  const sanitize = (text) => {
+    const escapedHome = home.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return text.replace(new RegExp(escapedHome, "g"), "<home>");
+  };
+  const lines = [];
+  lines.push("==================================================");
+  lines.push("            BLOXFORGE DIAGNOSTIC REPORT           ");
+  lines.push("==================================================");
+  lines.push("");
+  lines.push(`Generated: ${(/* @__PURE__ */ new Date()).toISOString()}`);
+  lines.push(`OS: ${process.platform} (${os5.type()} ${os5.release()} ${os5.arch()})`);
+  lines.push(`Node Version: ${process.version}`);
+  lines.push(`BloxForge Version: ${options.version ?? "unknown"}`);
+  lines.push(`Protocol Version: ${MCP_PROTOCOL_VERSION}`);
+  lines.push(`Selected Profile: ${process.env.BLOXFORGE_TOOL_PROFILE || "core"}`);
+  lines.push("");
+  lines.push("--- Doctor Results ---");
+  for (const c of checks) {
+    const statusSymbol = c.status === "ok" ? "[ OK ]" : c.status === "warn" ? "[WARN]" : "[FAIL]";
+    lines.push(`${statusSymbol} ${c.name}: ${sanitize(c.detail)}`);
+  }
+  lines.push("");
+  const port = options.port ?? (process.env.ROBLOX_STUDIO_PORT ? parseInt(process.env.ROBLOX_STUDIO_PORT) : 58741);
+  const doFetch = options.fetchImpl ?? fetch;
+  try {
+    const res = await fetchHealth(doFetch, port);
+    if (res.ok) {
+      const health = await res.json();
+      lines.push("--- Running Server Status ---");
+      lines.push(`Server Uptime: ${Math.round((health.uptime ?? 0) / 1e3)}s`);
+      lines.push(`Lazy Tools Enabled: ${health.lazyTools ?? "unknown"}`);
+      lines.push(`Active Tool Count: ${health.activeToolCount ?? "unknown"}`);
+      lines.push(`Loaded Toolsets: ${health.loadedToolsets?.join(", ") ?? "none"}`);
+      lines.push(`Connected Instances: ${health.instanceCount ?? 0}`);
+      if (health.instances && health.instances.length > 0) {
+        for (const inst of health.instances) {
+          lines.push(`  - Instance: ${inst.role} (variant: ${inst.pluginVariant ?? "unknown"}, version: ${inst.pluginVersion ?? "unknown"}, protocol: ${inst.pluginProtocolVersion ?? "unknown"})`);
+        }
+      }
+      lines.push("");
+      if (health.recentDisconnects && health.recentDisconnects.length > 0) {
+        lines.push("--- Recent Disconnects ---");
+        for (const disc of health.recentDisconnects) {
+          lines.push(`  - [${new Date(disc.disconnectedAt).toISOString()}] role: ${disc.role}, reason: ${disc.reason}`);
+        }
+        lines.push("");
+      }
+      if (health.session) {
+        lines.push("--- Session Summary ---");
+        lines.push(`Total Calls: ${health.session.totalCalls ?? 0}`);
+        lines.push(`Failed Calls: ${health.session.failures ?? 0}`);
+        if (health.session.byTool) {
+          for (const stats of health.session.byTool) {
+            lines.push(`  - ${stats.toolName}: ${stats.calls} calls, ${stats.failures} failures, avg ${Math.round(stats.averageDurationMs ?? 0)}ms`);
+          }
+        }
+        lines.push("");
+      }
+    }
+  } catch {
+    lines.push("--- Running Server Status ---");
+    lines.push("MCP server is not currently running on this port.");
+    lines.push("");
+  }
+  lines.push("==================================================");
+  lines.push("End of Report");
+  return lines.join("\n");
+}
+var SYMBOL, HEALTH_TIMEOUT_MS;
 var init_doctor = __esm({
   "../core/dist/doctor.js"() {
     "use strict";
     init_install_plugin_helpers();
+    init_bridge_service();
     SYMBOL = { ok: "\u2713", warn: "!", fail: "\u2717" };
+    HEALTH_TIMEOUT_MS = 3e3;
   }
 });
 
@@ -19134,6 +19308,7 @@ var init_dist = __esm({
   "../core/dist/index.js"() {
     "use strict";
     init_server();
+    init_server();
     init_http_server();
     init_bridge_service();
     init_tools();
@@ -19153,7 +19328,7 @@ __export(install_plugin_exports, {
   installBundledPlugin: () => installBundledPlugin,
   installPlugin: () => installPlugin
 });
-import { copyFileSync as copyFileSync2, createWriteStream, existsSync as existsSync6, mkdirSync as mkdirSync7, readFileSync as readFileSync7, unlinkSync as unlinkSync3 } from "fs";
+import { copyFileSync as copyFileSync2, createWriteStream, existsSync as existsSync7, mkdirSync as mkdirSync7, readFileSync as readFileSync7, unlinkSync as unlinkSync3 } from "fs";
 import { dirname as dirname6, join as join8 } from "path";
 import { fileURLToPath } from "url";
 import { get } from "https";
@@ -19224,7 +19399,7 @@ function prepareInstall({
   warn
 }) {
   const pluginsFolder = getPluginsFolder();
-  if (!existsSync6(pluginsFolder)) {
+  if (!existsSync7(pluginsFolder)) {
     mkdirSync7(pluginsFolder, { recursive: true });
   }
   handleVariantConflict({
@@ -19242,7 +19417,7 @@ function bundledAssetPath() {
     join8(currentDir, "..", "studio-plugin", ASSET_NAME),
     join8(currentDir, "..", "..", "..", "studio-plugin", ASSET_NAME)
   ];
-  return candidates.find((candidate) => existsSync6(candidate)) ?? null;
+  return candidates.find((candidate) => existsSync7(candidate)) ?? null;
 }
 function packageVersion() {
   const currentDir = dirname6(fileURLToPath(import.meta.url));
@@ -19266,7 +19441,7 @@ function assertBundledPluginVersion(source) {
   }
 }
 function filesMatch(a, b) {
-  if (!existsSync6(b)) return false;
+  if (!existsSync7(b)) return false;
   const aBytes = readFileSync7(a);
   const bBytes = readFileSync7(b);
   return aBytes.length === bBytes.length && aBytes.equals(bBytes);
@@ -19305,13 +19480,13 @@ async function installPlugin(options = {}) {
     return;
   }
   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);
+  const release2 = dev ? await findDevRelease() : await fetchJson(`https://api.github.com/repos/${REPO}/releases/latest`);
+  const asset = release2.assets?.find((a) => a.name === ASSET_NAME);
   if (!asset) {
-    throw new Error(`${ASSET_NAME} not found in release ${release.tag_name}`);
+    throw new Error(`${ASSET_NAME} not found in release ${release2.tag_name}`);
   }
   const dest = join8(pluginsFolder, ASSET_NAME);
-  log(`Downloading ${ASSET_NAME} from ${release.tag_name}...`);
+  log(`Downloading ${ASSET_NAME} from ${release2.tag_name}...`);
   await download(asset.browser_download_url, dest);
   log(`Installed to ${dest}`);
 }
@@ -19338,17 +19513,55 @@ var argFlagValue = (flag) => {
 var portArg = argFlagValue("--port");
 if (portArg) process.env.ROBLOX_STUDIO_PORT = portArg;
 if (process.argv.includes("--debug")) process.env.ROBLOX_STUDIO_DEBUG = "1";
-if (process.argv.includes("--doctor")) {
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`BloxForge MCP Server
+
+Usage:
+  npx @princeofscale/bloxforge [options]
+  npx @princeofscale/bloxforge <command>
+
+Options:
+  --port <port>                 Port to run the HTTP bridge on (default: 58741)
+  --debug                       Enable debug logging (stack traces, verbose output)
+  --open-cloud-key <key>        Roblox Open Cloud API Key (for some advanced tools)
+  --pollinations-key <key>      Pollinations API Key (for image-generation tools)
+  --creator-id <id>             Roblox Creator User ID
+  --creator-group-id <id>       Roblox Creator Group ID
+  --profile <profile>           Load specific tool profile (e.g., core)
+  --help, -h                    Show this help message
+
+Commands:
+  verify, --doctor              Run diagnostics to verify installation and connection
+  report                        Generate a detailed diagnostic report for bug reports
+  --install-plugin              Manually install the Studio plugin to your local Roblox directory
+  --auto-install-plugin         Silently install the plugin (used by AI clients automatically)
+  `);
+  process.exit(0);
+}
+if (process.argv.includes("--doctor") || process.argv.includes("verify")) {
   const require2 = createRequire(import.meta.url);
   const { version } = require2("../package.json");
   process.exitCode = await runDoctor({
     version,
     port: portArg ? parseInt(portArg) : void 0
   });
+} else if (process.argv.includes("--report") || process.argv.includes("report")) {
+  const require2 = createRequire(import.meta.url);
+  const { version } = require2("../package.json");
+  const reportText = await generateDiagnosticReport({
+    version,
+    port: portArg ? parseInt(portArg) : void 0
+  });
+  console.log(reportText);
+  process.exit(0);
 } else if (process.argv.includes("--install-plugin")) {
   const { installPlugin: installPlugin2 } = await Promise.resolve().then(() => (init_install_plugin(), install_plugin_exports));
   await installPlugin2().catch((err) => {
-    console.error(err instanceof Error ? err.message : String(err));
+    console.error(`[install-plugin] What happened: Failed to install plugin.`);
+    console.error(`[install-plugin] Why: ${err instanceof Error ? err.message : String(err)}`);
+    console.error(`[install-plugin] Fix: Ensure your Roblox Studio plugins folder is accessible and you have write permissions.`);
+    console.error(`[install-plugin] Verify: Run 'npx @princeofscale/bloxforge verify' to check if the plugin is installed.`);
+    if (process.env.ROBLOX_STUDIO_DEBUG) console.error(err);
     process.exitCode = 1;
   });
 } else {
@@ -19359,7 +19572,7 @@ if (process.argv.includes("--doctor")) {
       warn: (message) => console.error(message)
     }).catch((err) => {
       console.error(
-        `[install-plugin] Auto-install skipped: ${err instanceof Error ? err.message : String(err)}`
+        `[install-plugin] Auto-install skipped. Why: ${err instanceof Error ? err.message : String(err)}`
       );
     });
   }
@@ -19385,7 +19598,12 @@ if (process.argv.includes("--doctor")) {
     tools: getAllTools()
   });
   server.run().catch((error) => {
-    console.error("Server failed to start:", error);
+    console.error(`
+[Fatal Error] What happened: BloxForge Server failed to start.`);
+    console.error(`[Fatal Error] Why: ${error instanceof Error ? error.message : String(error)}`);
+    console.error(`[Fatal Error] Fix: Check if another instance is already running on port ${process.env.ROBLOX_STUDIO_PORT || 58741}.`);
+    console.error(`[Fatal Error] Verify: Run 'npx @princeofscale/bloxforge verify' to diagnose the issue.`);
+    if (process.env.ROBLOX_STUDIO_DEBUG) console.error(error);
     process.exit(1);
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@princeofscale/bloxforge",
-  "version": "2.20.2",
+  "version": "3.0.0-rc.1",
   "description": "Open-source AI agent toolkit for building, inspecting, testing, and automating Roblox games in Studio.",
   "main": "dist/index.js",
   "type": "module",
@@ -36,7 +36,10 @@
     "open-source",
     "developer-tools"
   ],
-  "author": "",
+  "author": {
+    "name": "princeofscale",
+    "url": "https://github.com/princeofscale"
+  },
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/studio-plugin/MCPInspectorPlugin.rbxmx

@@ -708,8 +708,10 @@ local function computeInstanceId()
 end
 local assignedRole
 local duplicateInstanceRole = false
-local hasVersionMismatch = false
+local versionMismatchConnections = {}
 local lastVersionMismatchWarningKey
+local protocolMismatchConnections = {}
+local lastProtocolMismatchWarningKey
 local lastReadyInstanceId
 local readyFailureLogKeys = {}
 -- Cache the published place name from MarketplaceService:GetProductInfo so
@@ -1118,16 +1120,49 @@ local function pollForRequests(connIndex)
 		end
 		local serverVersion = _condition
 		if data.versionMismatch == true then
-			hasVersionMismatch = true
+			versionMismatchConnections[conn] = true
 			local warningKey = `{State.CURRENT_VERSION}:{serverVersion}`
 			if lastVersionMismatchWarningKey ~= warningKey then
 				lastVersionMismatchWarningKey = warningKey
 				warn(`[BloxForge] Version mismatch: Studio plugin v{State.CURRENT_VERSION} / MCP v{serverVersion}. Run npx -y @princeofscale/bloxforge@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")
+		else
+			versionMismatchConnections[conn] = nil
+			-- ▼ ReadonlySet.size ▼
+			local _size = 0
+			for _ in versionMismatchConnections do
+				_size += 1
+			end
+			-- ▲ ReadonlySet.size ▲
+			if _size == 0 then
+				UI.hideBanner("version-mismatch")
+			end
+		end
+		local _condition_1 = data.serverProtocolVersion
+		if _condition_1 == nil then
+			_condition_1 = 0
+		end
+		local serverProtocol = _condition_1
+		if data.protocolMismatch == true then
+			protocolMismatchConnections[conn] = true
+			local warningKey = `{State.PROTOCOL_VERSION}:{serverProtocol}`
+			if lastProtocolMismatchWarningKey ~= warningKey then
+				lastProtocolMismatchWarningKey = warningKey
+				warn(`[BloxForge] Protocol mismatch: Studio plugin protocol v{State.PROTOCOL_VERSION} / MCP protocol v{serverProtocol}. Run npx -y @princeofscale/bloxforge@latest --auto-install-plugin and restart Studio.`)
+			end
+			UI.showBanner("protocol-mismatch", `Protocol mismatch: Plugin protocol v{State.PROTOCOL_VERSION} / MCP protocol v{serverProtocol}`)
+		else
+			protocolMismatchConnections[conn] = nil
+			-- ▼ ReadonlySet.size ▼
+			local _size = 0
+			for _ in protocolMismatchConnections do
+				_size += 1
+			end
+			-- ▲ ReadonlySet.size ▲
+			if _size == 0 then
+				UI.hideBanner("protocol-mismatch")
+			end
 		end
 		-- Server tells us when its in-memory instances map doesn't have us
 		-- (e.g. after an MCP process restart, or after it reaped us during a
@@ -1146,12 +1181,12 @@ local function pollForRequests(connIndex)
 			local el = ui
 			el.step1Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
 			el.step1Label.Text = "HTTP server (OK)"
-			local _condition_1 = mcpConnected
-			if _condition_1 then
+			local _condition_2 = mcpConnected
+			if _condition_2 then
 				local _value = (string.find(el.statusLabel.Text, "Connected"))
-				_condition_1 = not (_value ~= 0 and _value == _value and _value)
+				_condition_2 = not (_value ~= 0 and _value == _value and _value)
 			end
-			if _condition_1 then
+			if _condition_2 then
 				el.statusLabel.Text = "Connected"
 				el.statusLabel.TextColor3 = Color3.fromRGB(34, 197, 94)
 				el.statusIndicator.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
@@ -1182,11 +1217,11 @@ local function pollForRequests(connIndex)
 					conn.mcpWaitStartTime = tick()
 				end
 				local _exp = tick()
-				local _condition_2 = conn.mcpWaitStartTime
-				if _condition_2 == nil then
-					_condition_2 = tick()
+				local _condition_3 = conn.mcpWaitStartTime
+				if _condition_3 == nil then
+					_condition_3 = tick()
 				end
-				local elapsed = _exp - _condition_2
+				local elapsed = _exp - _condition_3
 				el.troubleshootLabel.Visible = elapsed > 8
 				UI.startPulseAnimation()
 			end
@@ -1356,6 +1391,26 @@ function deactivatePlugin(connIndex)
 	end
 	conn.isActive = false
 	conn.lastMcpOk = false
+	versionMismatchConnections[conn] = nil
+	protocolMismatchConnections[conn] = nil
+	-- ▼ ReadonlySet.size ▼
+	local _size = 0
+	for _ in versionMismatchConnections do
+		_size += 1
+	end
+	-- ▲ ReadonlySet.size ▲
+	if _size == 0 then
+		UI.hideBanner("version-mismatch")
+	end
+	-- ▼ ReadonlySet.size ▼
+	local _size_1 = 0
+	for _ in protocolMismatchConnections do
+		_size_1 += 1
+	end
+	-- ▲ ReadonlySet.size ▲
+	if _size_1 == 0 then
+		UI.hideBanner("protocol-mismatch")
+	end
 	if idx == State.getActiveTabIndex() then
 		UI.updateUIState()
 	end
@@ -1418,7 +1473,13 @@ local function checkForUpdates()
 			if _condition ~= "" and _condition then
 				local latestVersion = data.version
 				if Utils.compareVersions(State.CURRENT_VERSION, latestVersion) < 0 then
-					if not hasVersionMismatch then
+					-- ▼ ReadonlySet.size ▼
+					local _size = 0
+					for _ in versionMismatchConnections do
+						_size += 1
+					end
+					-- ▲ ReadonlySet.size ▲
+					if _size == 0 then
 						UI.showBanner("update", `v{latestVersion} available - github.com/princeofscale/bloxforge`)
 					end
 				end
@@ -1556,9 +1617,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.20.2" is replaced with the package version at package time
+	-- "3.0.0-rc.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.20.2`
+	return `{tostring(h)}-3.0.0-rc.1`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -10353,7 +10414,6 @@ local function computeWrapperLineOffset()
 	local before = string.sub(probe, 1, start - 1)
 	return countLines(before) - 1
 end
-local WRAPPER_LINE_OFFSET = computeWrapperLineOffset()
 -- Count source lines so the wrapper can filter traceback frames that fall
 -- outside the user code range (the wrapper's own preamble/postamble lines).
 function countLines(s)
@@ -10388,7 +10448,7 @@ end
 -- instead of hand-maintained, so reordering preamble lines can never desync
 -- __mcp_LINE_OFFSET / remapPayloadLines from the real line count.
 function renderWrapper(lineOffset, userLines, code, payloadPattern)
-	return `return ((function()\
+	return `return (function()\
 \tlocal __mcp_traceback\
 \tlocal __mcp_remap\
 \tlocal __mcp_LINE_OFFSET = {lineOffset}\
@@ -10505,7 +10565,7 @@ function renderWrapper(lineOffset, userLines, code, payloadPattern)
 \t__mcp_remap = function(s)\
 \t\t-- Two chunk-name formats can reference our payload:\
 \t\t--   * "Workspace.__MCPExecLuauPayload:N" — ModuleScript:require fallback path\
-\t\t--   * "[string \\"return ((function()...\\"]:N" — loadstring() (default in plugin)\
+\t\t--   * "[string \\"return (function()...\\"]:N" — loadstring() (default in plugin)\
 \t\t-- Subtract LINE_OFFSET to get the user-relative number, then clamp.\
 \t\t-- Clamping matters for unclosed constructs ("local x = (") where the\
 \t\t-- parser keeps reading into wrapper postamble and reports a payload\
@@ -10568,6 +10628,9 @@ function renderWrapper(lineOffset, userLines, code, payloadPattern)
 \treturn \{ ok = ok, value = errOrValue, output = __mcp_output \}\
 end)()`
 end
+-- roblox-ts emits function declarations as ordered local assignments, so this
+-- must run after every helper used by computeWrapperLineOffset is initialized.
+local WRAPPER_LINE_OFFSET = computeWrapperLineOffset()
 local function buildWrapper(code, payloadInstanceName)
 	if payloadInstanceName == nil then
 		payloadInstanceName = PAYLOAD_INSTANCE_NAME
@@ -11236,7 +11299,7 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.20.2"
+local CURRENT_VERSION = "3.0.0-rc.1"
 local PLUGIN_VARIANT = "inspector"
 local PROTOCOL_VERSION = 1
 local MAX_CONNECTIONS = 5

package/studio-plugin/MCPPlugin.rbxmx

@@ -708,8 +708,10 @@ local function computeInstanceId()
 end
 local assignedRole
 local duplicateInstanceRole = false
-local hasVersionMismatch = false
+local versionMismatchConnections = {}
 local lastVersionMismatchWarningKey
+local protocolMismatchConnections = {}
+local lastProtocolMismatchWarningKey
 local lastReadyInstanceId
 local readyFailureLogKeys = {}
 -- Cache the published place name from MarketplaceService:GetProductInfo so
@@ -1118,16 +1120,49 @@ local function pollForRequests(connIndex)
 		end
 		local serverVersion = _condition
 		if data.versionMismatch == true then
-			hasVersionMismatch = true
+			versionMismatchConnections[conn] = true
 			local warningKey = `{State.CURRENT_VERSION}:{serverVersion}`
 			if lastVersionMismatchWarningKey ~= warningKey then
 				lastVersionMismatchWarningKey = warningKey
 				warn(`[BloxForge] Version mismatch: Studio plugin v{State.CURRENT_VERSION} / MCP v{serverVersion}. Run npx -y @princeofscale/bloxforge@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")
+		else
+			versionMismatchConnections[conn] = nil
+			-- ▼ ReadonlySet.size ▼
+			local _size = 0
+			for _ in versionMismatchConnections do
+				_size += 1
+			end
+			-- ▲ ReadonlySet.size ▲
+			if _size == 0 then
+				UI.hideBanner("version-mismatch")
+			end
+		end
+		local _condition_1 = data.serverProtocolVersion
+		if _condition_1 == nil then
+			_condition_1 = 0
+		end
+		local serverProtocol = _condition_1
+		if data.protocolMismatch == true then
+			protocolMismatchConnections[conn] = true
+			local warningKey = `{State.PROTOCOL_VERSION}:{serverProtocol}`
+			if lastProtocolMismatchWarningKey ~= warningKey then
+				lastProtocolMismatchWarningKey = warningKey
+				warn(`[BloxForge] Protocol mismatch: Studio plugin protocol v{State.PROTOCOL_VERSION} / MCP protocol v{serverProtocol}. Run npx -y @princeofscale/bloxforge@latest --auto-install-plugin and restart Studio.`)
+			end
+			UI.showBanner("protocol-mismatch", `Protocol mismatch: Plugin protocol v{State.PROTOCOL_VERSION} / MCP protocol v{serverProtocol}`)
+		else
+			protocolMismatchConnections[conn] = nil
+			-- ▼ ReadonlySet.size ▼
+			local _size = 0
+			for _ in protocolMismatchConnections do
+				_size += 1
+			end
+			-- ▲ ReadonlySet.size ▲
+			if _size == 0 then
+				UI.hideBanner("protocol-mismatch")
+			end
 		end
 		-- Server tells us when its in-memory instances map doesn't have us
 		-- (e.g. after an MCP process restart, or after it reaped us during a
@@ -1146,12 +1181,12 @@ local function pollForRequests(connIndex)
 			local el = ui
 			el.step1Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
 			el.step1Label.Text = "HTTP server (OK)"
-			local _condition_1 = mcpConnected
-			if _condition_1 then
+			local _condition_2 = mcpConnected
+			if _condition_2 then
 				local _value = (string.find(el.statusLabel.Text, "Connected"))
-				_condition_1 = not (_value ~= 0 and _value == _value and _value)
+				_condition_2 = not (_value ~= 0 and _value == _value and _value)
 			end
-			if _condition_1 then
+			if _condition_2 then
 				el.statusLabel.Text = "Connected"
 				el.statusLabel.TextColor3 = Color3.fromRGB(34, 197, 94)
 				el.statusIndicator.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
@@ -1182,11 +1217,11 @@ local function pollForRequests(connIndex)
 					conn.mcpWaitStartTime = tick()
 				end
 				local _exp = tick()
-				local _condition_2 = conn.mcpWaitStartTime
-				if _condition_2 == nil then
-					_condition_2 = tick()
+				local _condition_3 = conn.mcpWaitStartTime
+				if _condition_3 == nil then
+					_condition_3 = tick()
 				end
-				local elapsed = _exp - _condition_2
+				local elapsed = _exp - _condition_3
 				el.troubleshootLabel.Visible = elapsed > 8
 				UI.startPulseAnimation()
 			end
@@ -1356,6 +1391,26 @@ function deactivatePlugin(connIndex)
 	end
 	conn.isActive = false
 	conn.lastMcpOk = false
+	versionMismatchConnections[conn] = nil
+	protocolMismatchConnections[conn] = nil
+	-- ▼ ReadonlySet.size ▼
+	local _size = 0
+	for _ in versionMismatchConnections do
+		_size += 1
+	end
+	-- ▲ ReadonlySet.size ▲
+	if _size == 0 then
+		UI.hideBanner("version-mismatch")
+	end
+	-- ▼ ReadonlySet.size ▼
+	local _size_1 = 0
+	for _ in protocolMismatchConnections do
+		_size_1 += 1
+	end
+	-- ▲ ReadonlySet.size ▲
+	if _size_1 == 0 then
+		UI.hideBanner("protocol-mismatch")
+	end
 	if idx == State.getActiveTabIndex() then
 		UI.updateUIState()
 	end
@@ -1418,7 +1473,13 @@ local function checkForUpdates()
 			if _condition ~= "" and _condition then
 				local latestVersion = data.version
 				if Utils.compareVersions(State.CURRENT_VERSION, latestVersion) < 0 then
-					if not hasVersionMismatch then
+					-- ▼ ReadonlySet.size ▼
+					local _size = 0
+					for _ in versionMismatchConnections do
+						_size += 1
+					end
+					-- ▲ ReadonlySet.size ▲
+					if _size == 0 then
 						UI.showBanner("update", `v{latestVersion} available - github.com/princeofscale/bloxforge`)
 					end
 				end
@@ -1556,9 +1617,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.20.2" is replaced with the package version at package time
+	-- "3.0.0-rc.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.20.2`
+	return `{tostring(h)}-3.0.0-rc.1`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -10353,7 +10414,6 @@ local function computeWrapperLineOffset()
 	local before = string.sub(probe, 1, start - 1)
 	return countLines(before) - 1
 end
-local WRAPPER_LINE_OFFSET = computeWrapperLineOffset()
 -- Count source lines so the wrapper can filter traceback frames that fall
 -- outside the user code range (the wrapper's own preamble/postamble lines).
 function countLines(s)
@@ -10388,7 +10448,7 @@ end
 -- instead of hand-maintained, so reordering preamble lines can never desync
 -- __mcp_LINE_OFFSET / remapPayloadLines from the real line count.
 function renderWrapper(lineOffset, userLines, code, payloadPattern)
-	return `return ((function()\
+	return `return (function()\
 \tlocal __mcp_traceback\
 \tlocal __mcp_remap\
 \tlocal __mcp_LINE_OFFSET = {lineOffset}\
@@ -10505,7 +10565,7 @@ function renderWrapper(lineOffset, userLines, code, payloadPattern)
 \t__mcp_remap = function(s)\
 \t\t-- Two chunk-name formats can reference our payload:\
 \t\t--   * "Workspace.__MCPExecLuauPayload:N" — ModuleScript:require fallback path\
-\t\t--   * "[string \\"return ((function()...\\"]:N" — loadstring() (default in plugin)\
+\t\t--   * "[string \\"return (function()...\\"]:N" — loadstring() (default in plugin)\
 \t\t-- Subtract LINE_OFFSET to get the user-relative number, then clamp.\
 \t\t-- Clamping matters for unclosed constructs ("local x = (") where the\
 \t\t-- parser keeps reading into wrapper postamble and reports a payload\
@@ -10568,6 +10628,9 @@ function renderWrapper(lineOffset, userLines, code, payloadPattern)
 \treturn \{ ok = ok, value = errOrValue, output = __mcp_output \}\
 end)()`
 end
+-- roblox-ts emits function declarations as ordered local assignments, so this
+-- must run after every helper used by computeWrapperLineOffset is initialized.
+local WRAPPER_LINE_OFFSET = computeWrapperLineOffset()
 local function buildWrapper(code, payloadInstanceName)
 	if payloadInstanceName == nil then
 		payloadInstanceName = PAYLOAD_INSTANCE_NAME
@@ -11236,7 +11299,7 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.20.2"
+local CURRENT_VERSION = "3.0.0-rc.1"
 local PLUGIN_VARIANT = "main"
 local PROTOCOL_VERSION = 1
 local MAX_CONNECTIONS = 5

package/studio-plugin/package-lock.json

@@ -67,9 +67,9 @@
       }
     },
     "node_modules/ajv": {
-      "version": "8.17.1",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz",
-      "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -234,9 +234,9 @@
       "license": "MIT"
     },
     "node_modules/fast-uri": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
-      "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.3.tgz",
+      "integrity": "sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg==",
       "dev": true,
       "funding": [
         {
@@ -466,9 +466,9 @@
       "license": "MIT"
     },
     "node_modules/picomatch": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz",
-      "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==",
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
       "dev": true,
       "license": "MIT",
       "engines": {

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

@@ -54,8 +54,10 @@ function computeInstanceId(): string {
 
 let assignedRole: string | undefined;
 let duplicateInstanceRole = false;
-let hasVersionMismatch = false;
+const versionMismatchConnections = new Set<Connection>();
 let lastVersionMismatchWarningKey: string | undefined;
+const protocolMismatchConnections = new Set<Connection>();
+let lastProtocolMismatchWarningKey: string | undefined;
 let lastReadyInstanceId: string | undefined;
 const readyFailureLogKeys = new Set<string>();
 
@@ -408,16 +410,30 @@ function pollForRequests(connIndex: number) {
 		conn.lastMcpOk = mcpConnected;
 		const serverVersion = data.serverVersion ?? "unknown";
 		if (data.versionMismatch === true) {
-			hasVersionMismatch = true;
+			versionMismatchConnections.add(conn);
 			const warningKey = `${State.CURRENT_VERSION}:${serverVersion}`;
 			if (lastVersionMismatchWarningKey !== warningKey) {
 				lastVersionMismatchWarningKey = warningKey;
 				warn(`[BloxForge] Version mismatch: Studio plugin v${State.CURRENT_VERSION} / MCP v${serverVersion}. Run npx -y @princeofscale/bloxforge@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");
+		} else {
+			versionMismatchConnections.delete(conn);
+			if (versionMismatchConnections.size() === 0) UI.hideBanner("version-mismatch");
+		}
+
+		const serverProtocol = data.serverProtocolVersion ?? 0;
+		if (data.protocolMismatch === true) {
+			protocolMismatchConnections.add(conn);
+			const warningKey = `${State.PROTOCOL_VERSION}:${serverProtocol}`;
+			if (lastProtocolMismatchWarningKey !== warningKey) {
+				lastProtocolMismatchWarningKey = warningKey;
+				warn(`[BloxForge] Protocol mismatch: Studio plugin protocol v${State.PROTOCOL_VERSION} / MCP protocol v${serverProtocol}. Run npx -y @princeofscale/bloxforge@latest --auto-install-plugin and restart Studio.`);
+			}
+			UI.showBanner("protocol-mismatch", `Protocol mismatch: Plugin protocol v${State.PROTOCOL_VERSION} / MCP protocol v${serverProtocol}`);
+		} else {
+			protocolMismatchConnections.delete(conn);
+			if (protocolMismatchConnections.size() === 0) UI.hideBanner("protocol-mismatch");
 		}
 
 		// Server tells us when its in-memory instances map doesn't have us
@@ -629,6 +645,10 @@ function deactivatePlugin(connIndex?: number) {
 
 	conn.isActive = false;
 	conn.lastMcpOk = false;
+	versionMismatchConnections.delete(conn);
+	protocolMismatchConnections.delete(conn);
+	if (versionMismatchConnections.size() === 0) UI.hideBanner("version-mismatch");
+	if (protocolMismatchConnections.size() === 0) UI.hideBanner("protocol-mismatch");
 
 	if (idx === State.getActiveTabIndex()) UI.updateUIState();
 	UI.updateTabDot(idx);
@@ -679,7 +699,7 @@ function checkForUpdates() {
 			if (ok && data?.version) {
 				const latestVersion = data.version;
 				if (Utils.compareVersions(State.CURRENT_VERSION, latestVersion) < 0) {
-					if (!hasVersionMismatch) {
+					if (versionMismatchConnections.size() === 0) {
 						UI.showBanner("update", `v${latestVersion} available - github.com/princeofscale/bloxforge`);
 					}
 				}

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

@@ -68,7 +68,6 @@ function computeWrapperLineOffset(): number {
 	const before = string.sub(probe, 1, (start as number) - 1);
 	return countLines(before) - 1;
 }
-const WRAPPER_LINE_OFFSET = computeWrapperLineOffset();
 
 // Count source lines so the wrapper can filter traceback frames that fall
 // outside the user code range (the wrapper's own preamble/postamble lines).
@@ -97,7 +96,7 @@ function renderWrapper(
 	code: string,
 	payloadPattern: string,
 ): string {
-	return `return ((function()
+	return `return (function()
 \tlocal __mcp_traceback
 \tlocal __mcp_remap
 \tlocal __mcp_LINE_OFFSET = ${lineOffset}
@@ -214,7 +213,7 @@ ${code}
 \t__mcp_remap = function(s)
 \t\t-- Two chunk-name formats can reference our payload:
 \t\t--   * "Workspace.__MCPExecLuauPayload:N" — ModuleScript:require fallback path
-\t\t--   * "[string \\"return ((function()...\\"]:N" — loadstring() (default in plugin)
+\t\t--   * "[string \\"return (function()...\\"]:N" — loadstring() (default in plugin)
 \t\t-- Subtract LINE_OFFSET to get the user-relative number, then clamp.
 \t\t-- Clamping matters for unclosed constructs ("local x = (") where the
 \t\t-- parser keeps reading into wrapper postamble and reports a payload
@@ -278,6 +277,10 @@ ${code}
 end)()`;
 }
 
+// roblox-ts emits function declarations as ordered local assignments, so this
+// must run after every helper used by computeWrapperLineOffset is initialized.
+const WRAPPER_LINE_OFFSET = computeWrapperLineOffset();
+
 function buildWrapper(code: string, payloadInstanceName = PAYLOAD_INSTANCE_NAME): string {
 	// The line offset is DERIVED from the rendered template (see
 	// computeWrapperLineOffset) instead of hand-maintained, so reordering the