@luaward/mcp 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -5,10 +5,10 @@ import { resolve as resolve3 } from "node:path";
5
5
  import { pathToFileURL } from "node:url";
6
6
 
7
7
  // src/index.ts
8
- import { existsSync as existsSync3, readFileSync as readFileSync2 } from "node:fs";
9
- import { homedir as homedir3 } from "node:os";
10
- import { join as join3, resolve as resolve2 } from "node:path";
11
- import { createInterface as createInterface2 } from "node:readline";
8
+ import { existsSync as existsSync4, readFileSync as readFileSync2 } from "node:fs";
9
+ import { homedir as homedir4 } from "node:os";
10
+ import { join as join4, resolve as resolve2 } from "node:path";
11
+ import { createInterface as createInterface3 } from "node:readline";
12
12
 
13
13
  // src/potassium.ts
14
14
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -204,6 +204,7 @@ var PotassiumClient = class {
204
204
  fetchFn;
205
205
  sessionId = null;
206
206
  initialized = false;
207
+ lastInitNetworkError = null;
207
208
  rpcSeq = 1e3;
208
209
  constructor(options = {}) {
209
210
  this.url = (options.url || process.env.POTASSIUM_MCP_URL || DEFAULT_POTASSIUM_URL).trim();
@@ -226,6 +227,7 @@ var PotassiumClient = class {
226
227
  }
227
228
  async ensureInitialized() {
228
229
  if (this.initialized) return true;
230
+ this.lastInitNetworkError = null;
229
231
  try {
230
232
  const res = await this.fetchFn(this.url, {
231
233
  method: "POST",
@@ -237,7 +239,7 @@ var PotassiumClient = class {
237
239
  params: {
238
240
  protocolVersion: "2025-03-26",
239
241
  capabilities: {},
240
- clientInfo: { name: "@luaward/mcp", version: "0.2.1" }
242
+ clientInfo: { name: "@luaward/mcp", version: "0.2.3" }
241
243
  }
242
244
  })
243
245
  });
@@ -258,12 +260,20 @@ var PotassiumClient = class {
258
260
  } catch {
259
261
  }
260
262
  return true;
261
- } catch {
263
+ } catch (err) {
264
+ this.lastInitNetworkError = err instanceof Error ? err.message : String(err);
262
265
  return false;
263
266
  }
264
267
  }
265
268
  async callTool(name, args = {}) {
266
- await this.ensureInitialized();
269
+ const initOk = await this.ensureInitialized();
270
+ if (!initOk && this.lastInitNetworkError) {
271
+ return {
272
+ ok: false,
273
+ text: `Potassium local MCP (${this.url}) is not reachable: ${this.lastInitNetworkError}`,
274
+ isError: true
275
+ };
276
+ }
267
277
  try {
268
278
  const res = await this.fetchFn(this.url, {
269
279
  method: "POST",
@@ -497,12 +507,544 @@ var PotassiumClient = class {
497
507
  }
498
508
  };
499
509
 
500
- // src/windows.ts
501
- import { execFile, spawn } from "node:child_process";
502
- import { existsSync as existsSync2, readdirSync, statSync } from "node:fs";
510
+ // src/studio.ts
511
+ import { spawn } from "node:child_process";
512
+ import { existsSync as existsSync2 } from "node:fs";
503
513
  import { homedir as homedir2 } from "node:os";
504
514
  import { join as join2 } from "node:path";
505
515
  import { createInterface } from "node:readline";
516
+ import { inflateSync } from "node:zlib";
517
+ function discoverRobloxStudioMcpBatch(env = process.env) {
518
+ if (env.ROBLOX_STUDIO_MCP_PATH?.trim()) {
519
+ return env.ROBLOX_STUDIO_MCP_PATH.trim();
520
+ }
521
+ const home = homedir2();
522
+ const localAppData = env.LOCALAPPDATA || join2(home, "AppData", "Local");
523
+ const candidates = [
524
+ join2(localAppData, "Roblox", "mcp.bat"),
525
+ join2(localAppData, "RobloxStudio", "mcp.bat")
526
+ ];
527
+ for (const c of candidates) {
528
+ if (existsSync2(c)) return c;
529
+ }
530
+ return candidates[0];
531
+ }
532
+ function parseStudioToolResponse(rpcRes) {
533
+ if (!rpcRes) {
534
+ return { ok: false, text: "Empty response from Roblox Studio MCP", isError: true };
535
+ }
536
+ if (rpcRes.error && typeof rpcRes.error === "object") {
537
+ const err = rpcRes.error;
538
+ return {
539
+ ok: false,
540
+ text: err.message || `Roblox Studio MCP error (${String(err.code ?? "unknown")})`,
541
+ isError: true
542
+ };
543
+ }
544
+ const result = rpcRes.result;
545
+ if (!result || typeof result !== "object") {
546
+ return { ok: true, text: JSON.stringify(rpcRes.result ?? {}), structured: rpcRes.result };
547
+ }
548
+ const texts = [];
549
+ if (Array.isArray(result.content)) {
550
+ for (const item of result.content) {
551
+ if (item && typeof item.text === "string") {
552
+ texts.push(item.text);
553
+ }
554
+ }
555
+ }
556
+ const joined = texts.join("\n").trim();
557
+ let structured = result.structuredContent;
558
+ if (structured === void 0 && (joined.startsWith("{") || joined.startsWith("["))) {
559
+ try {
560
+ structured = JSON.parse(joined);
561
+ } catch {
562
+ }
563
+ }
564
+ return {
565
+ ok: !result.isError,
566
+ text: joined || (structured !== void 0 ? JSON.stringify(structured) : "ok"),
567
+ structured,
568
+ isError: Boolean(result.isError)
569
+ };
570
+ }
571
+ var RobloxStudioMcpClient = class {
572
+ batchPath;
573
+ timeoutMs;
574
+ customTransport;
575
+ child = null;
576
+ initPromise = null;
577
+ pending = /* @__PURE__ */ new Map();
578
+ rpcSeq = 9e3;
579
+ cachedToolNames = null;
580
+ exitHookInstalled = false;
581
+ constructor(options = {}) {
582
+ this.batchPath = options.batchPath || discoverRobloxStudioMcpBatch(options.env);
583
+ this.timeoutMs = options.timeoutMs ?? 25e3;
584
+ this.customTransport = options.transport;
585
+ }
586
+ dispose() {
587
+ const c = this.child;
588
+ this.child = null;
589
+ this.initPromise = null;
590
+ for (const [id, p] of this.pending) {
591
+ clearTimeout(p.timer);
592
+ p.reject(new Error("Roblox Studio MCP client disposed"));
593
+ this.pending.delete(id);
594
+ }
595
+ if (c && !c.killed) {
596
+ try {
597
+ c.stdin.end();
598
+ c.kill();
599
+ } catch {
600
+ }
601
+ }
602
+ }
603
+ async ensureStdioProcess() {
604
+ if (this.customTransport) return;
605
+ if (this.child && !this.child.killed && this.initPromise) {
606
+ return this.initPromise;
607
+ }
608
+ if (!existsSync2(this.batchPath)) {
609
+ throw new Error(
610
+ `Roblox Studio MCP launcher not found at "${this.batchPath}". Ensure Roblox Studio is installed with MCP enabled (expected %LOCALAPPDATA%\\Roblox\\mcp.bat) or set ROBLOX_STUDIO_MCP_PATH.`
611
+ );
612
+ }
613
+ const isBat = /\.(?:bat|cmd)$/i.test(this.batchPath);
614
+ const child = isBat ? spawn("cmd.exe", ["/d", "/s", "/c", `"${this.batchPath}"`], {
615
+ stdio: ["pipe", "pipe", "pipe"],
616
+ windowsHide: true
617
+ }) : spawn(this.batchPath, [], {
618
+ stdio: ["pipe", "pipe", "pipe"],
619
+ windowsHide: true
620
+ });
621
+ child.unref();
622
+ this.child = child;
623
+ if (!this.exitHookInstalled) {
624
+ this.exitHookInstalled = true;
625
+ process.once("exit", () => this.dispose());
626
+ }
627
+ const rl = createInterface({ input: child.stdout, crlfDelay: Number.POSITIVE_INFINITY });
628
+ rl.on("line", (line) => {
629
+ const trimmed = line.trim();
630
+ if (!trimmed.startsWith("{")) return;
631
+ try {
632
+ const parsed = JSON.parse(trimmed);
633
+ if (parsed.id !== void 0 && parsed.id !== null) {
634
+ const key = String(parsed.id);
635
+ const waiter = this.pending.get(key);
636
+ if (waiter) {
637
+ this.pending.delete(key);
638
+ clearTimeout(waiter.timer);
639
+ waiter.resolve(parsed);
640
+ }
641
+ }
642
+ } catch {
643
+ }
644
+ });
645
+ child.once("exit", (code) => {
646
+ if (this.child === child) {
647
+ this.child = null;
648
+ this.initPromise = null;
649
+ }
650
+ const err = new Error(`Roblox Studio MCP process exited (code ${code ?? "null"})`);
651
+ for (const [id, waiter] of this.pending) {
652
+ clearTimeout(waiter.timer);
653
+ waiter.reject(err);
654
+ this.pending.delete(id);
655
+ }
656
+ });
657
+ this.initPromise = (async () => {
658
+ await this.sendRawRpc("initialize", {
659
+ protocolVersion: "2025-03-26",
660
+ capabilities: {},
661
+ clientInfo: { name: "@luaward/mcp", version: "0.2.3" }
662
+ });
663
+ if (this.child && !this.child.killed) {
664
+ this.child.stdin.write(
665
+ `${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} })}
666
+ `
667
+ );
668
+ }
669
+ })();
670
+ return this.initPromise;
671
+ }
672
+ async sendRawRpc(method, params) {
673
+ if (this.customTransport) {
674
+ return this.customTransport(method, params);
675
+ }
676
+ const child = this.child;
677
+ if (!child || child.killed) {
678
+ throw new Error("Roblox Studio MCP process is not running");
679
+ }
680
+ const id = ++this.rpcSeq;
681
+ const key = String(id);
682
+ return new Promise((resolveRpc, rejectRpc) => {
683
+ const timer = setTimeout(() => {
684
+ this.pending.delete(key);
685
+ rejectRpc(new Error(`Roblox Studio MCP request "${method}" timed out after ${this.timeoutMs}ms`));
686
+ }, this.timeoutMs);
687
+ this.pending.set(key, { resolve: resolveRpc, reject: rejectRpc, timer });
688
+ child.stdin.write(
689
+ `${JSON.stringify({ jsonrpc: "2.0", id, method, ...params ? { params } : {} })}
690
+ `
691
+ );
692
+ });
693
+ }
694
+ async sendRpc(method, params) {
695
+ await this.ensureStdioProcess();
696
+ return this.sendRawRpc(method, params);
697
+ }
698
+ async listTools() {
699
+ if (this.cachedToolNames) return this.cachedToolNames;
700
+ try {
701
+ const res = await this.sendRpc("tools/list", {});
702
+ const tools = res?.result?.tools;
703
+ if (Array.isArray(tools)) {
704
+ this.cachedToolNames = tools.map((t) => typeof t?.name === "string" ? t.name : "").filter(Boolean);
705
+ return this.cachedToolNames;
706
+ }
707
+ } catch {
708
+ }
709
+ return [];
710
+ }
711
+ async listStudios() {
712
+ const tools = await this.listTools();
713
+ const listToolName = tools.find((t) => t === "list_studios" || t === "get_studios" || t === "list_clients") ?? "list_studios";
714
+ try {
715
+ const rpcRes = await this.sendRpc("tools/call", { name: listToolName, arguments: {} });
716
+ const parsed = parseStudioToolResponse(rpcRes);
717
+ if (!parsed.ok) {
718
+ return { ok: false, studios: [], rawText: parsed.text };
719
+ }
720
+ const studios = [];
721
+ const s = parsed.structured;
722
+ const arr = Array.isArray(s) ? s : s && typeof s === "object" ? Array.isArray(s.studios) ? s.studios : Array.isArray(s.clients) ? s.clients : Array.isArray(s.instances) ? s.instances : null : null;
723
+ if (arr) {
724
+ for (const item of arr) {
725
+ if (item && typeof item === "object") {
726
+ const obj = item;
727
+ const sid = String(
728
+ obj.studio_id ?? obj.studioId ?? obj.id ?? obj.session_id ?? obj.pid ?? ""
729
+ ).trim();
730
+ if (sid) {
731
+ studios.push({
732
+ studio_id: sid,
733
+ place_id: obj.place_id ?? obj.placeId,
734
+ place_name: typeof (obj.place_name ?? obj.placeName ?? obj.name) === "string" ? String(obj.place_name ?? obj.placeName ?? obj.name) : void 0,
735
+ user: typeof obj.user === "string" ? obj.user : void 0,
736
+ raw: obj
737
+ });
738
+ }
739
+ } else if (typeof item === "string" || typeof item === "number") {
740
+ studios.push({ studio_id: String(item) });
741
+ }
742
+ }
743
+ return { ok: true, studios, rawText: parsed.text };
744
+ }
745
+ const matches = [
746
+ ...parsed.text.matchAll(/\b(?:studio_id|studioId|studio|id)[:=\s"']*([A-Za-z0-9_-]{2,64})\b/gi)
747
+ ];
748
+ for (const m of matches) {
749
+ if (m[1]) studios.push({ studio_id: m[1] });
750
+ }
751
+ return { ok: true, studios, rawText: parsed.text };
752
+ } catch (err) {
753
+ return {
754
+ ok: false,
755
+ studios: [],
756
+ rawText: err instanceof Error ? err.message : String(err)
757
+ };
758
+ }
759
+ }
760
+ /**
761
+ * Automatically resolves `studio_id` when the caller omits it and exactly one Roblox Studio instance is connected.
762
+ */
763
+ async resolveStudioId(explicitStudioId) {
764
+ if (explicitStudioId && explicitStudioId.trim()) {
765
+ return {
766
+ ok: true,
767
+ studioId: explicitStudioId.trim(),
768
+ studios: [{ studio_id: explicitStudioId.trim() }],
769
+ autoSelected: false
770
+ };
771
+ }
772
+ const listed = await this.listStudios();
773
+ if (!listed.ok) {
774
+ return {
775
+ ok: false,
776
+ studios: [],
777
+ autoSelected: false,
778
+ err: `Could not query Roblox Studio MCP (${this.batchPath}): ${listed.rawText}`
779
+ };
780
+ }
781
+ if (listed.studios.length === 1 && listed.studios[0]) {
782
+ return {
783
+ ok: true,
784
+ studioId: listed.studios[0].studio_id,
785
+ studios: listed.studios,
786
+ autoSelected: true
787
+ };
788
+ }
789
+ if (listed.studios.length === 0) {
790
+ return {
791
+ ok: false,
792
+ studios: [],
793
+ autoSelected: false,
794
+ err: "No connected Roblox Studio instance found via %LOCALAPPDATA%\\Roblox\\mcp.bat. Open a place in Roblox Studio with MCP enabled first."
795
+ };
796
+ }
797
+ const listStr = listed.studios.map((s) => `${s.studio_id}${s.place_name ? ` ("${s.place_name}")` : ""}`).join(", ");
798
+ return {
799
+ ok: false,
800
+ studios: listed.studios,
801
+ autoSelected: false,
802
+ err: `Multiple Roblox Studio instances are open (${listStr}); pass studio_id explicitly.`
803
+ };
804
+ }
805
+ async callTool(name, args = {}) {
806
+ const finalArgs = { ...args };
807
+ let studioId = typeof finalArgs.studio_id === "string" ? finalArgs.studio_id.trim() : void 0;
808
+ let autoSelected = false;
809
+ if (!studioId && name !== "list_studios" && name !== "get_studios") {
810
+ const resolved = await this.resolveStudioId();
811
+ if (!resolved.ok) {
812
+ return { ok: false, text: resolved.err ?? "Failed to resolve studio_id", isError: true };
813
+ }
814
+ studioId = resolved.studioId;
815
+ autoSelected = resolved.autoSelected;
816
+ if (studioId) {
817
+ finalArgs.studio_id = studioId;
818
+ }
819
+ }
820
+ try {
821
+ const rpcRes = await this.sendRpc("tools/call", { name, arguments: finalArgs });
822
+ const parsed = parseStudioToolResponse(rpcRes);
823
+ return {
824
+ ...parsed,
825
+ studioId,
826
+ autoSelected
827
+ };
828
+ } catch (err) {
829
+ return {
830
+ ok: false,
831
+ text: err instanceof Error ? err.message : String(err),
832
+ studioId,
833
+ autoSelected,
834
+ isError: true
835
+ };
836
+ }
837
+ }
838
+ async runStudioLuau(code, explicitStudioId) {
839
+ const resolved = await this.resolveStudioId(explicitStudioId);
840
+ if (!resolved.ok) {
841
+ return {
842
+ ok: false,
843
+ text: resolved.err ?? "Could not resolve Roblox Studio instance",
844
+ isError: true
845
+ };
846
+ }
847
+ const tools = await this.listTools();
848
+ const execTool = tools.find((t) => t === "run_code" || t === "execute_luau" || t === "run_script" || t === "eval") ?? "run_code";
849
+ const res = await this.callTool(execTool, {
850
+ command: code,
851
+ code,
852
+ source: code,
853
+ ...resolved.studioId ? { studio_id: resolved.studioId } : {}
854
+ });
855
+ return {
856
+ ...res,
857
+ studioId: resolved.studioId,
858
+ autoSelected: resolved.autoSelected
859
+ };
860
+ }
861
+ };
862
+ function paethPredictor(a, b, c) {
863
+ const p = a + b - c;
864
+ const pa = Math.abs(p - a);
865
+ const pb = Math.abs(p - b);
866
+ const pc = Math.abs(p - c);
867
+ if (pa <= pb && pa <= pc) return a;
868
+ if (pb <= pc) return b;
869
+ return c;
870
+ }
871
+ function decodePngRgba(base64Data) {
872
+ try {
873
+ const buf = Buffer.from(base64Data, "base64");
874
+ if (buf.length < 33) return null;
875
+ if (buf[0] !== 137 || buf[1] !== 80 || buf[2] !== 78 || buf[3] !== 71) return null;
876
+ let offset = 8;
877
+ let width = 0;
878
+ let height = 0;
879
+ let bitDepth = 0;
880
+ let colorType = 0;
881
+ const idatChunks = [];
882
+ while (offset + 8 <= buf.length) {
883
+ const len = buf.readUInt32BE(offset);
884
+ const type = buf.toString("ascii", offset + 4, offset + 8);
885
+ const dataStart = offset + 8;
886
+ const dataEnd = dataStart + len;
887
+ if (dataEnd + 4 > buf.length) break;
888
+ if (type === "IHDR" && len >= 13) {
889
+ width = buf.readUInt32BE(dataStart);
890
+ height = buf.readUInt32BE(dataStart + 4);
891
+ bitDepth = buf[dataStart + 8] ?? 0;
892
+ colorType = buf[dataStart + 9] ?? 0;
893
+ } else if (type === "IDAT") {
894
+ idatChunks.push(buf.subarray(dataStart, dataEnd));
895
+ } else if (type === "IEND") {
896
+ break;
897
+ }
898
+ offset = dataEnd + 4;
899
+ }
900
+ if (width <= 0 || height <= 0 || bitDepth !== 8 || idatChunks.length === 0) return null;
901
+ const channels = colorType === 6 ? 4 : colorType === 2 ? 3 : colorType === 0 ? 1 : 0;
902
+ if (channels === 0) return null;
903
+ const compressed = Buffer.concat(idatChunks);
904
+ const raw = inflateSync(compressed);
905
+ const stride = width * channels;
906
+ if (raw.length < height * (stride + 1)) return null;
907
+ const unfiltered = new Uint8Array(height * stride);
908
+ for (let y = 0; y < height; y++) {
909
+ const filterType = raw[y * (stride + 1)] ?? 0;
910
+ const rowIn = y * (stride + 1) + 1;
911
+ const rowOut = y * stride;
912
+ const prevRowOut = (y - 1) * stride;
913
+ for (let x = 0; x < stride; x++) {
914
+ const rawByte = raw[rowIn + x] ?? 0;
915
+ const a = x >= channels ? unfiltered[rowOut + x - channels] ?? 0 : 0;
916
+ const b = y > 0 ? unfiltered[prevRowOut + x] ?? 0 : 0;
917
+ const c = y > 0 && x >= channels ? unfiltered[prevRowOut + x - channels] ?? 0 : 0;
918
+ let val = rawByte;
919
+ if (filterType === 1) val = rawByte + a & 255;
920
+ else if (filterType === 2) val = rawByte + b & 255;
921
+ else if (filterType === 3) val = rawByte + (a + b >> 1) & 255;
922
+ else if (filterType === 4) val = rawByte + paethPredictor(a, b, c) & 255;
923
+ unfiltered[rowOut + x] = val;
924
+ }
925
+ }
926
+ const rgba = new Uint8Array(width * height * 4);
927
+ for (let i = 0; i < width * height; i++) {
928
+ if (channels === 4) {
929
+ rgba[i * 4] = unfiltered[i * 4] ?? 0;
930
+ rgba[i * 4 + 1] = unfiltered[i * 4 + 1] ?? 0;
931
+ rgba[i * 4 + 2] = unfiltered[i * 4 + 2] ?? 0;
932
+ rgba[i * 4 + 3] = unfiltered[i * 4 + 3] ?? 255;
933
+ } else if (channels === 3) {
934
+ rgba[i * 4] = unfiltered[i * 3] ?? 0;
935
+ rgba[i * 4 + 1] = unfiltered[i * 3 + 1] ?? 0;
936
+ rgba[i * 4 + 2] = unfiltered[i * 3 + 2] ?? 0;
937
+ rgba[i * 4 + 3] = 255;
938
+ } else {
939
+ const g = unfiltered[i] ?? 0;
940
+ rgba[i * 4] = g;
941
+ rgba[i * 4 + 1] = g;
942
+ rgba[i * 4 + 2] = g;
943
+ rgba[i * 4 + 3] = 255;
944
+ }
945
+ }
946
+ return { width, height, rgba };
947
+ } catch {
948
+ return null;
949
+ }
950
+ }
951
+ function comparePngBase64(b64A, b64B, metaA, metaB) {
952
+ if (b64A === b64B) {
953
+ return {
954
+ widthA: metaA?.width,
955
+ heightA: metaA?.height,
956
+ widthB: metaB?.width,
957
+ heightB: metaB?.height,
958
+ sameDimensions: true,
959
+ similarityPct: 100,
960
+ diffPct: 0,
961
+ changedCells: [],
962
+ gridSummary: "Images are 100% byte-identical (0.0% diff across all 4x4 grid regions)."
963
+ };
964
+ }
965
+ const imgA = decodePngRgba(b64A);
966
+ const imgB = decodePngRgba(b64B);
967
+ if (!imgA || !imgB) {
968
+ const lenA = Buffer.byteLength(b64A, "base64");
969
+ const lenB = Buffer.byteLength(b64B, "base64");
970
+ const ratio = Math.max(lenA, lenB) > 0 ? Math.min(lenA, lenB) / Math.max(lenA, lenB) : 1;
971
+ const sim = Math.round(ratio * 1e3) / 10;
972
+ return {
973
+ widthA: metaA?.width,
974
+ heightA: metaA?.height,
975
+ widthB: metaB?.width,
976
+ heightB: metaB?.height,
977
+ sameDimensions: metaA?.width === metaB?.width && metaA?.height === metaB?.height,
978
+ similarityPct: sim,
979
+ diffPct: Math.round((100 - sim) * 10) / 10,
980
+ changedCells: [],
981
+ gridSummary: `Binary size comparison: A=${lenA} bytes, B=${lenB} bytes (~${sim}% size similarity).`
982
+ };
983
+ }
984
+ const gridRows = 4;
985
+ const gridCols = 4;
986
+ const samplesPerCell = 16;
987
+ const totalCols = gridCols * samplesPerCell;
988
+ const totalRows = gridRows * samplesPerCell;
989
+ let totalDiff = 0;
990
+ let totalSamples = 0;
991
+ const changedCells = [];
992
+ const cellLines = [];
993
+ const rowLabels = ["Top", "UpperMid", "LowerMid", "Bottom"];
994
+ const colLabels = ["Left", "CenterLeft", "CenterRight", "Right"];
995
+ for (let gr = 0; gr < gridRows; gr++) {
996
+ for (let gc = 0; gc < gridCols; gc++) {
997
+ let cellDiff = 0;
998
+ let cellCount = 0;
999
+ for (let sr = 0; sr < samplesPerCell; sr++) {
1000
+ for (let sc = 0; sc < samplesPerCell; sc++) {
1001
+ const u = (gc * samplesPerCell + sc + 0.5) / totalCols;
1002
+ const v = (gr * samplesPerCell + sr + 0.5) / totalRows;
1003
+ const ax = Math.min(imgA.width - 1, Math.floor(u * imgA.width));
1004
+ const ay = Math.min(imgA.height - 1, Math.floor(v * imgA.height));
1005
+ const bx = Math.min(imgB.width - 1, Math.floor(u * imgB.width));
1006
+ const by = Math.min(imgB.height - 1, Math.floor(v * imgB.height));
1007
+ const aIdx = (ay * imgA.width + ax) * 4;
1008
+ const bIdx = (by * imgB.width + bx) * 4;
1009
+ const dr = Math.abs((imgA.rgba[aIdx] ?? 0) - (imgB.rgba[bIdx] ?? 0));
1010
+ const dg = Math.abs((imgA.rgba[aIdx + 1] ?? 0) - (imgB.rgba[bIdx + 1] ?? 0));
1011
+ const db = Math.abs((imgA.rgba[aIdx + 2] ?? 0) - (imgB.rgba[bIdx + 2] ?? 0));
1012
+ const d = (dr + dg + db) / (255 * 3);
1013
+ cellDiff += d;
1014
+ cellCount++;
1015
+ totalDiff += d;
1016
+ totalSamples++;
1017
+ }
1018
+ }
1019
+ const cellPct = Math.round(cellDiff / Math.max(1, cellCount) * 1e3) / 10;
1020
+ const label = `${rowLabels[gr]}-${colLabels[gc]}`;
1021
+ if (cellPct >= 5) {
1022
+ changedCells.push(`${label} (${cellPct}% diff)`);
1023
+ }
1024
+ cellLines.push(`${label}:${cellPct}%`);
1025
+ }
1026
+ }
1027
+ const diffPct = Math.round(totalDiff / Math.max(1, totalSamples) * 1e3) / 10;
1028
+ const similarityPct = Math.max(0, Math.round((100 - diffPct) * 10) / 10);
1029
+ return {
1030
+ widthA: imgA.width,
1031
+ heightA: imgA.height,
1032
+ widthB: imgB.width,
1033
+ heightB: imgB.height,
1034
+ sameDimensions: imgA.width === imgB.width && imgA.height === imgB.height,
1035
+ similarityPct,
1036
+ diffPct,
1037
+ changedCells,
1038
+ gridSummary: `4x4 region diff: ${cellLines.join(", ")}`
1039
+ };
1040
+ }
1041
+
1042
+ // src/windows.ts
1043
+ import { execFile, spawn as spawn2 } from "node:child_process";
1044
+ import { existsSync as existsSync3, readdirSync, statSync } from "node:fs";
1045
+ import { homedir as homedir3 } from "node:os";
1046
+ import { join as join3 } from "node:path";
1047
+ import { createInterface as createInterface2 } from "node:readline";
506
1048
  import { promisify } from "node:util";
507
1049
  var execFileAsync = promisify(execFile);
508
1050
  function encodePowerShellCommand(script) {
@@ -526,25 +1068,25 @@ function buildRobloxDeepLink(params) {
526
1068
  return `roblox://experiences/start?${queryParts.join("&")}`;
527
1069
  }
528
1070
  function findRobloxPlayerBinary(env = process.env) {
529
- if (env.ROBLOX_PLAYER_PATH && existsSync2(env.ROBLOX_PLAYER_PATH)) {
1071
+ if (env.ROBLOX_PLAYER_PATH && existsSync3(env.ROBLOX_PLAYER_PATH)) {
530
1072
  return env.ROBLOX_PLAYER_PATH;
531
1073
  }
532
- const home = homedir2();
533
- const localAppData = env.LOCALAPPDATA || join2(home, "AppData", "Local");
1074
+ const home = homedir3();
1075
+ const localAppData = env.LOCALAPPDATA || join3(home, "AppData", "Local");
534
1076
  const roots = [
535
- join2(localAppData, "Roblox", "Versions"),
536
- join2(localAppData, "Bloxstrap", "Versions"),
537
- join2(localAppData, "Fishstrap", "Versions"),
1077
+ join3(localAppData, "Roblox", "Versions"),
1078
+ join3(localAppData, "Bloxstrap", "Versions"),
1079
+ join3(localAppData, "Fishstrap", "Versions"),
538
1080
  "C:\\Program Files (x86)\\Roblox\\Versions"
539
1081
  ];
540
1082
  let newestExe = null;
541
1083
  let newestMtime = -1;
542
1084
  for (const root of roots) {
543
- if (!existsSync2(root)) continue;
1085
+ if (!existsSync3(root)) continue;
544
1086
  try {
545
1087
  for (const entry of readdirSync(root)) {
546
- const exe = join2(root, entry, "RobloxPlayerBeta.exe");
547
- if (existsSync2(exe)) {
1088
+ const exe = join3(root, entry, "RobloxPlayerBeta.exe");
1089
+ if (existsSync3(exe)) {
548
1090
  const st = statSync(exe);
549
1091
  if (st.mtimeMs > newestMtime) {
550
1092
  newestMtime = st.mtimeMs;
@@ -558,21 +1100,21 @@ function findRobloxPlayerBinary(env = process.env) {
558
1100
  return newestExe;
559
1101
  }
560
1102
  function findPotassiumBinary(customPath, env = process.env) {
561
- if (customPath && existsSync2(customPath)) return customPath;
562
- if (env.POTASSIUM_PATH && existsSync2(env.POTASSIUM_PATH)) return env.POTASSIUM_PATH;
563
- const home = homedir2();
564
- const localAppData = env.LOCALAPPDATA || join2(home, "AppData", "Local");
565
- const appData = env.APPDATA || join2(home, "AppData", "Roaming");
1103
+ if (customPath && existsSync3(customPath)) return customPath;
1104
+ if (env.POTASSIUM_PATH && existsSync3(env.POTASSIUM_PATH)) return env.POTASSIUM_PATH;
1105
+ const home = homedir3();
1106
+ const localAppData = env.LOCALAPPDATA || join3(home, "AppData", "Local");
1107
+ const appData = env.APPDATA || join3(home, "AppData", "Roaming");
566
1108
  const candidates = [
567
- join2(localAppData, "Potassium", "Potassium.exe"),
568
- join2(appData, "Potassium", "Potassium.exe"),
569
- join2(home, "Desktop", "Potassium.exe"),
570
- join2(home, "Desktop", "Potassium", "Potassium.exe"),
571
- join2(home, "Downloads", "Potassium", "Potassium.exe"),
1109
+ join3(localAppData, "Potassium", "Potassium.exe"),
1110
+ join3(appData, "Potassium", "Potassium.exe"),
1111
+ join3(home, "Desktop", "Potassium.exe"),
1112
+ join3(home, "Desktop", "Potassium", "Potassium.exe"),
1113
+ join3(home, "Downloads", "Potassium", "Potassium.exe"),
572
1114
  "C:\\Potassium\\Potassium.exe"
573
1115
  ];
574
1116
  for (const c of candidates) {
575
- if (existsSync2(c)) return c;
1117
+ if (existsSync3(c)) return c;
576
1118
  }
577
1119
  return null;
578
1120
  }
@@ -716,8 +1258,35 @@ namespace Luaward {
716
1258
  [DllImport("user32.dll")] public static extern uint SendInput(uint nInputs, INPUT[] pInputs, int cbSize);
717
1259
  [DllImport("user32.dll")] public static extern uint MapVirtualKey(uint uCode, uint uMapType);
718
1260
  [DllImport("user32.dll")] public static extern bool PrintWindow(IntPtr hwnd, IntPtr hdcBlt, uint nFlags);
1261
+ [DllImport("user32.dll")] public static extern IntPtr WindowFromPoint(POINT Point);
1262
+ [DllImport("user32.dll")] public static extern IntPtr GetAncestor(IntPtr hwnd, uint gaFlags);
1263
+ [DllImport("user32.dll")] public static extern bool IsChild(IntPtr hWndParent, IntPtr hWnd);
719
1264
 
1265
+ public const uint GA_ROOT = 2;
720
1266
  public const uint PW_RENDERFULLCONTENT = 0x00000002;
1267
+
1268
+ public static bool IsWindowTopAtPoint(IntPtr targetHwnd, int x, int y) {
1269
+ if (targetHwnd == IntPtr.Zero) return false;
1270
+ POINT pt = new POINT { X = x, Y = y };
1271
+ IntPtr hit = WindowFromPoint(pt);
1272
+ if (hit == IntPtr.Zero) return false;
1273
+ if (hit == targetHwnd || IsChild(targetHwnd, hit)) return true;
1274
+ IntPtr root = GetAncestor(hit, GA_ROOT);
1275
+ return root == targetHwnd;
1276
+ }
1277
+
1278
+ public static bool IsWindowUnoccluded(IntPtr targetHwnd, int left, int top, int width, int height) {
1279
+ if (targetHwnd == IntPtr.Zero || width <= 0 || height <= 0) return false;
1280
+ int cx = left + (width / 2);
1281
+ int cy = top + (height / 2);
1282
+ int insetX = Math.Max(4, Math.Min(40, width / 6));
1283
+ int insetY = Math.Max(4, Math.Min(40, height / 6));
1284
+ return IsWindowTopAtPoint(targetHwnd, cx, cy)
1285
+ && IsWindowTopAtPoint(targetHwnd, left + insetX, top + insetY)
1286
+ && IsWindowTopAtPoint(targetHwnd, left + width - insetX, top + insetY)
1287
+ && IsWindowTopAtPoint(targetHwnd, left + insetX, top + height - insetY)
1288
+ && IsWindowTopAtPoint(targetHwnd, left + width - insetX, top + height - insetY);
1289
+ }
721
1290
  public const uint INPUT_MOUSE = 0;
722
1291
  public const uint INPUT_KEYBOARD = 1;
723
1292
  public const uint MOUSEEVENTF_MOVE = 0x0001;
@@ -871,7 +1440,7 @@ var PowerShellWindowsDriver = class {
871
1440
  return this.workerReady;
872
1441
  }
873
1442
  const encodedBootstrap = encodePowerShellCommand(PS_WORKER_BOOTSTRAP);
874
- const child = spawn(
1443
+ const child = spawn2(
875
1444
  "powershell.exe",
876
1445
  ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encodedBootstrap],
877
1446
  { stdio: ["pipe", "pipe", "pipe"], windowsHide: true }
@@ -886,7 +1455,7 @@ var PowerShellWindowsDriver = class {
886
1455
  child.stderr.on("data", (chunk) => {
887
1456
  stderrBuf = (stderrBuf + String(chunk)).slice(-2e3);
888
1457
  });
889
- const rl = createInterface({ input: child.stdout, crlfDelay: Number.POSITIVE_INFINITY });
1458
+ const rl = createInterface2({ input: child.stdout, crlfDelay: Number.POSITIVE_INFINITY });
890
1459
  this.workerReady = new Promise((resolveReady, rejectReady) => {
891
1460
  let isReady = false;
892
1461
  const readyTimer = setTimeout(() => {
@@ -1151,6 +1720,11 @@ $h = [IntPtr]::new([Convert]::ToInt64("${win.hwnd}", 16))
1151
1720
  if (!pw) return { ok: false, text: "Potassium window not found for relative_to=potassium_window" };
1152
1721
  baseX = pw.rect.left;
1153
1722
  baseY = pw.rect.top;
1723
+ } else if (params.relativeTo === "studio_window") {
1724
+ const sw = (await this.listWindows("studio"))[0];
1725
+ if (!sw) return { ok: false, text: "Roblox Studio window not found for relative_to=studio_window" };
1726
+ baseX = sw.clientRect.width > 0 ? sw.clientRect.screenLeft : sw.rect.left;
1727
+ baseY = sw.clientRect.height > 0 ? sw.clientRect.screenTop : sw.rect.top;
1154
1728
  }
1155
1729
  const screenX = Math.round((params.x ?? 0) + baseX);
1156
1730
  const screenY = Math.round((params.y ?? 0) + baseY);
@@ -1351,7 +1925,7 @@ $sent += [int][Luaward.Win32Desktop]::SendKeyVk(${vk}, $true)
1351
1925
  async launchRoblox(params) {
1352
1926
  const deepLink = buildRobloxDeepLink(params);
1353
1927
  const bin = params.binaryPath || (params.directBinary ? findRobloxPlayerBinary() : null);
1354
- if (bin && existsSync2(bin)) {
1928
+ if (bin && existsSync3(bin)) {
1355
1929
  const b64Bin = Buffer.from(bin, "utf8").toString("base64");
1356
1930
  const b64Link2 = Buffer.from(deepLink, "utf8").toString("base64");
1357
1931
  const res = await this.runPsJson(`
@@ -1571,23 +2145,47 @@ function Capture-ViaPrintWindow {
1571
2145
  }
1572
2146
  }
1573
2147
 
1574
- $result = $null
1575
- if ($method -eq "printwindow" -and $hasHwnd) {
1576
- $result = Capture-ViaPrintWindow
1577
- } else {
2148
+ function Capture-ViaCopyFromScreen {
1578
2149
  $bmp = New-Object System.Drawing.Bitmap $w, $h
1579
2150
  $g = [System.Drawing.Graphics]::FromImage($bmp)
1580
2151
  try {
1581
2152
  $g.CopyFromScreen($left, $top, 0, 0, (New-Object System.Drawing.Size($w, $h)))
1582
2153
  $ms = New-Object System.IO.MemoryStream
1583
2154
  $bmp.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png)
1584
- $result = @{
2155
+ return @{
1585
2156
  ok = $true
1586
2157
  width = $w
1587
2158
  height = $h
1588
2159
  captureMethod = "copy"
1589
2160
  data = [Convert]::ToBase64String($ms.ToArray())
1590
2161
  }
2162
+ } finally {
2163
+ $g.Dispose()
2164
+ $bmp.Dispose()
2165
+ }
2166
+ }
2167
+
2168
+ $result = $null
2169
+ $hwndPtr = [IntPtr]::new([Convert]::ToInt64("${opts.hwnd || "0x0"}", 16))
2170
+ $isTop = $hasHwnd -and [Luaward.Win32Desktop]::IsWindowUnoccluded($hwndPtr, $left, $top, $w, $h)
2171
+ if ($hasHwnd -and ($method -eq "printwindow" -or ($method -eq "auto" -and (-not $isTop)))) {
2172
+ try {
2173
+ $result = Capture-ViaPrintWindow
2174
+ } catch {
2175
+ $pwErr = $_.Exception.Message
2176
+ if ($method -eq "auto") {
2177
+ try {
2178
+ $result = Capture-ViaCopyFromScreen
2179
+ } catch {
2180
+ $result = @{ ok = $false; err = "PrintWindow failed ($pwErr); CopyFromScreen fallback failed ($($_.Exception.Message))" }
2181
+ }
2182
+ } else {
2183
+ $result = @{ ok = $false; err = "PrintWindow failed: $pwErr" }
2184
+ }
2185
+ }
2186
+ } else {
2187
+ try {
2188
+ $result = Capture-ViaCopyFromScreen
1591
2189
  } catch {
1592
2190
  $copyErr = $_.Exception.Message
1593
2191
  if ($method -eq "auto" -and $hasHwnd) {
@@ -1599,19 +2197,32 @@ if ($method -eq "printwindow" -and $hasHwnd) {
1599
2197
  } else {
1600
2198
  $result = @{ ok = $false; err = "CopyFromScreen failed: $copyErr" }
1601
2199
  }
1602
- } finally {
1603
- $g.Dispose()
1604
- $bmp.Dispose()
1605
2200
  }
1606
2201
  }
1607
2202
  $result | ConvertTo-Json -Compress
1608
2203
  `;
1609
2204
  }
2205
+ function isRobloxStudioWindow(w) {
2206
+ const proc = w.processName.toLowerCase();
2207
+ const title = w.title.toLowerCase();
2208
+ const cls = w.className.toLowerCase();
2209
+ return proc.includes("robloxstudiobeta") || proc === "robloxstudio" || title.includes("roblox studio") || cls.includes("qt5") && proc.includes("studio");
2210
+ }
2211
+ function isRobloxPlayerWindow(w) {
2212
+ if (isRobloxStudioWindow(w)) return false;
2213
+ const proc = w.processName.toLowerCase();
2214
+ const title = w.title.toLowerCase();
2215
+ const cls = w.className.toLowerCase();
2216
+ return proc.includes("robloxplayerbeta") || proc === "robloxplayer" || proc.includes("roblox") && !proc.includes("studio") || title === "roblox" || cls.includes("windowsclient");
2217
+ }
1610
2218
  function matchesWindowTarget(w, filter) {
1611
2219
  const f = filter.trim().toLowerCase();
1612
2220
  if (!f || f === "all") return true;
1613
- if (f === "roblox") {
1614
- return w.processName.toLowerCase().includes("roblox") || w.title.toLowerCase() === "roblox" || w.className.toLowerCase().includes("windowsclient");
2221
+ if (f === "roblox" || f === "roblox_player" || f === "player") {
2222
+ return isRobloxPlayerWindow(w);
2223
+ }
2224
+ if (f === "studio" || f === "roblox_studio" || f === "robloxstudiobeta") {
2225
+ return isRobloxStudioWindow(w);
1615
2226
  }
1616
2227
  if (f === "potassium") {
1617
2228
  return w.processName.toLowerCase().includes("potassium") || w.title.toLowerCase().includes("potassium");
@@ -1621,13 +2232,15 @@ function matchesWindowTarget(w, filter) {
1621
2232
  }
1622
2233
 
1623
2234
  // src/index.ts
1624
- var MCP_BRIDGE_VERSION = "0.2.2";
2235
+ var MCP_BRIDGE_VERSION = "0.2.3";
1625
2236
  var DEFAULT_MCP_URL = "https://luaward.com/mcp";
2237
+ var TOKEN_CREATE_URL = "https://dash.luaward.com/dashboard/ai";
1626
2238
  var TOKEN_SHAPE = /^lwm_[0-9a-f]{48}$/;
2239
+ var POTASSIUM_ENABLE_HINT = "To enable Potassium Local MCP (port 8225): open Potassium -> Settings (gear icon) -> MCP Server -> enable 'MCP Server' on port 8225 and attach Potassium to RobloxPlayerBeta.exe (or run editor_tabs action='install_autoexec' once to auto-connect on future attaches).";
1627
2240
  function resolveStoredToken(configDir) {
1628
- const base = configDir || process.env.LUAWARD_CONFIG_DIR || join3(homedir3(), ".config", "luaward");
1629
- const credPath = join3(base, "credentials.json");
1630
- if (!existsSync3(credPath)) return {};
2241
+ const base = configDir || process.env.LUAWARD_CONFIG_DIR || join4(homedir4(), ".config", "luaward");
2242
+ const credPath = join4(base, "credentials.json");
2243
+ if (!existsSync4(credPath)) return {};
1631
2244
  try {
1632
2245
  const raw = JSON.parse(readFileSync2(credPath, "utf8"));
1633
2246
  const token = typeof raw.token === "string" && TOKEN_SHAPE.test(raw.token.trim()) ? raw.token.trim() : void 0;
@@ -1874,7 +2487,7 @@ var LOCAL_HYBRID_TOOLS = [
1874
2487
  },
1875
2488
  target: {
1876
2489
  type: "string",
1877
- description: 'Target window: "roblox" (default), "potassium", window title substring, PID, or HWND'
2490
+ description: 'Target window: "roblox" (RobloxPlayerBeta only, default), "studio" (RobloxStudioBeta), "potassium", window title substring, PID, or HWND'
1878
2491
  },
1879
2492
  x: { type: "integer", description: "Window top-left X coordinate for resize (default 80)" },
1880
2493
  y: { type: "integer", description: "Window top-left Y coordinate for resize (default 80)" },
@@ -1905,7 +2518,7 @@ var LOCAL_HYBRID_TOOLS = [
1905
2518
  properties: {
1906
2519
  target: {
1907
2520
  type: "string",
1908
- description: '"roblox" (default), "potassium", "screen", or window title substring'
2521
+ description: '"roblox" (RobloxPlayerBeta only, default), "studio" (RobloxStudioBeta), "potassium", "screen", or window title substring'
1909
2522
  },
1910
2523
  focus_first: {
1911
2524
  type: "boolean",
@@ -1940,7 +2553,7 @@ var LOCAL_HYBRID_TOOLS = [
1940
2553
  properties: {
1941
2554
  target: {
1942
2555
  type: "string",
1943
- description: '"potassium" (default), "roblox", or window title substring'
2556
+ description: '"potassium" (default), "roblox" (RobloxPlayerBeta), "studio" (RobloxStudioBeta), or window title substring'
1944
2557
  },
1945
2558
  max_depth: {
1946
2559
  type: "integer",
@@ -2011,8 +2624,16 @@ var LOCAL_HYBRID_TOOLS = [
2011
2624
  },
2012
2625
  relative_to: {
2013
2626
  type: "string",
2014
- enum: ["screen", "roblox_client", "potassium_window"],
2627
+ enum: ["screen", "roblox_client", "potassium_window", "studio_window"],
2015
2628
  description: "Coordinate origin (default 'screen')"
2629
+ },
2630
+ verify: {
2631
+ type: "boolean",
2632
+ description: "When true, verify after clicking/moving by querying UserInputService:GetMouseLocation() and returning a gui_snapshot diff (default false)"
2633
+ },
2634
+ session: {
2635
+ type: "string",
2636
+ description: "Optional Luaward game session selector when verify=true"
2016
2637
  }
2017
2638
  },
2018
2639
  required: ["action"],
@@ -2056,7 +2677,7 @@ var LOCAL_HYBRID_TOOLS = [
2056
2677
  },
2057
2678
  target: {
2058
2679
  type: "string",
2059
- description: 'Optional window to focus before sending keys ("roblox" or "potassium")'
2680
+ description: 'Optional window to focus before sending keys ("roblox", "studio", or "potassium")'
2060
2681
  }
2061
2682
  },
2062
2683
  required: ["action"],
@@ -2098,6 +2719,10 @@ var LOCAL_HYBRID_TOOLS = [
2098
2719
  type: "integer",
2099
2720
  description: "Optional vertical pixel offset from element center (default 0)"
2100
2721
  },
2722
+ verify: {
2723
+ type: "boolean",
2724
+ description: "When true, verify after clicking by querying UserInputService:GetMouseLocation() and returning a before/after gui_snapshot diff (default false)"
2725
+ },
2101
2726
  session: {
2102
2727
  type: "string",
2103
2728
  description: "Optional Luaward game session selector"
@@ -2113,35 +2738,401 @@ var LOCAL_HYBRID_TOOLS = [
2113
2738
  idempotentHint: false,
2114
2739
  openWorldHint: false
2115
2740
  }
2116
- }
2117
- ];
2118
- var HybridMcpBridge = class {
2119
- token;
2120
- url;
2121
- potassium;
2122
- windows;
2123
- autoInject;
2124
- autoInjectPollMs;
2125
- autoInjectMaxPolls;
2126
- fetchFn;
2127
- cachedPairCommand;
2128
- lastLaunchParams;
2129
- rpcSeq = 5e3;
2130
- constructor(options = {}) {
2131
- const resolved = resolveBridgeConfig([], process.env, options.configDir);
2132
- this.token = options.token !== void 0 ? options.token || null : resolved.token;
2133
- this.url = options.url ?? resolved.url;
2134
- this.fetchFn = options.fetchImpl ?? fetch;
2135
- this.cachedPairCommand = options.pairCommand ?? resolved.pairCommand;
2136
- this.autoInject = options.autoInject ?? resolved.autoInject;
2741
+ },
2742
+ {
2743
+ name: "studio_mirror_remotes",
2744
+ title: "Mirror live game remotes hierarchy into Roblox Studio",
2745
+ description: "Scan RemoteEvent, RemoteFunction, UnreliableRemoteEvent, BindableEvent, and BindableFunction hierarchy from the live connected game and reconstruct the exact folder and remote tree inside Roblox Studio via %LOCALAPPDATA%\\Roblox\\mcp.bat (auto-selecting studio_id when one Studio is open).",
2746
+ inputSchema: {
2747
+ type: "object",
2748
+ properties: {
2749
+ root: {
2750
+ type: "string",
2751
+ description: "Root service/path to mirror (default 'ReplicatedStorage')"
2752
+ },
2753
+ filter: {
2754
+ type: "string",
2755
+ description: "Optional case-insensitive path substring filter"
2756
+ },
2757
+ kind: {
2758
+ type: "string",
2759
+ enum: ["network", "bindable", "all"],
2760
+ description: "Remote kind filter (default 'all')"
2761
+ },
2762
+ max: {
2763
+ type: "integer",
2764
+ minimum: 1,
2765
+ maximum: 500,
2766
+ description: "Maximum remotes to mirror (default 200)"
2767
+ },
2768
+ studio_id: {
2769
+ type: "string",
2770
+ description: "Optional Roblox Studio instance ID (auto-filled when 1 Studio is open)"
2771
+ },
2772
+ session: {
2773
+ type: "string",
2774
+ description: "Optional live game session selector"
2775
+ }
2776
+ },
2777
+ additionalProperties: false
2778
+ },
2779
+ annotations: {
2780
+ title: "Mirror live game remotes into Roblox Studio",
2781
+ readOnlyHint: false,
2782
+ destructiveHint: false,
2783
+ idempotentHint: true,
2784
+ openWorldHint: false
2785
+ }
2786
+ },
2787
+ {
2788
+ name: "studio_mirror_gui",
2789
+ title: "Mirror live game GUI hierarchy into Roblox Studio StarterGui",
2790
+ description: "Capture a ScreenGui/GuiObject tree from the live connected game (including ClassName, Name, Position, Size, AnchorPoint, Visible, ZIndex, colors, Text, Image, UICorner, UIStroke, and layouts) and reconstruct it inside Roblox Studio's StarterGui via %LOCALAPPDATA%\\Roblox\\mcp.bat.",
2791
+ inputSchema: {
2792
+ type: "object",
2793
+ properties: {
2794
+ target: {
2795
+ type: "string",
2796
+ description: "Live GUI root path or #n handle to mirror (default 'Players.LocalPlayer.PlayerGui')"
2797
+ },
2798
+ studio_root: {
2799
+ type: "string",
2800
+ description: "Destination container in Roblox Studio (default 'StarterGui')"
2801
+ },
2802
+ depth: {
2803
+ type: "integer",
2804
+ minimum: 1,
2805
+ maximum: 12,
2806
+ description: "Maximum hierarchy depth (default 6)"
2807
+ },
2808
+ max_instances: {
2809
+ type: "integer",
2810
+ minimum: 1,
2811
+ maximum: 600,
2812
+ description: "Maximum GUI instances to mirror (default 250)"
2813
+ },
2814
+ only_visible: {
2815
+ type: "boolean",
2816
+ description: "Only mirror visible GUI elements (default false)"
2817
+ },
2818
+ studio_id: {
2819
+ type: "string",
2820
+ description: "Optional Roblox Studio instance ID (auto-filled when 1 Studio is open)"
2821
+ },
2822
+ session: {
2823
+ type: "string",
2824
+ description: "Optional live game session selector"
2825
+ }
2826
+ },
2827
+ additionalProperties: false
2828
+ },
2829
+ annotations: {
2830
+ title: "Mirror live game GUI into Roblox Studio",
2831
+ readOnlyHint: false,
2832
+ destructiveHint: false,
2833
+ idempotentHint: true,
2834
+ openWorldHint: false
2835
+ }
2836
+ },
2837
+ {
2838
+ name: "studio_diff",
2839
+ title: "Diff scripts, remotes, or GUI between Roblox Studio and live game",
2840
+ description: "Compare scripts, remotes, or GUI hierarchy between Roblox Studio (%LOCALAPPDATA%\\Roblox\\mcp.bat) and the live connected Roblox game, reporting items only in live, only in Studio, modified items, and line diffs.",
2841
+ inputSchema: {
2842
+ type: "object",
2843
+ properties: {
2844
+ scope: {
2845
+ type: "string",
2846
+ enum: ["scripts", "remotes", "gui", "all"],
2847
+ description: "What to compare (default 'scripts')"
2848
+ },
2849
+ target: {
2850
+ type: "string",
2851
+ description: "Optional root or specific script path to compare (default 'ReplicatedStorage')"
2852
+ },
2853
+ studio_id: {
2854
+ type: "string",
2855
+ description: "Optional Roblox Studio instance ID (auto-filled when 1 Studio is open)"
2856
+ },
2857
+ session: {
2858
+ type: "string",
2859
+ description: "Optional live game session selector"
2860
+ }
2861
+ },
2862
+ additionalProperties: false
2863
+ },
2864
+ annotations: {
2865
+ title: "Diff Roblox Studio vs live game",
2866
+ readOnlyHint: true,
2867
+ destructiveHint: false,
2868
+ idempotentHint: true,
2869
+ openWorldHint: false
2870
+ }
2871
+ },
2872
+ {
2873
+ name: "studio_to_live",
2874
+ title: "Run a Roblox Studio script directly in the live game",
2875
+ description: "Read a Script/LocalScript/ModuleScript source from Roblox Studio (by studio_path or current Selection via %LOCALAPPDATA%\\Roblox\\mcp.bat) and execute it immediately in the live connected Roblox game via run_and_collect.",
2876
+ inputSchema: {
2877
+ type: "object",
2878
+ properties: {
2879
+ studio_path: {
2880
+ type: "string",
2881
+ description: "Script path in Roblox Studio (e.g. 'StarterPlayer.StarterPlayerScripts.Main') or 'Selection' for currently selected script (default 'Selection')"
2882
+ },
2883
+ clean_env: {
2884
+ type: "boolean",
2885
+ description: "Run in clean native Luau SAFEENV environment (default true)"
2886
+ },
2887
+ track_resources: {
2888
+ type: "boolean",
2889
+ description: "Track resources in snapshot mode for cleanup_run (default true)"
2890
+ },
2891
+ auto_cleanup: {
2892
+ type: "boolean",
2893
+ description: "Automatically clean up resources after collecting logs (default false)"
2894
+ },
2895
+ settle_ms: {
2896
+ type: "integer",
2897
+ minimum: 0,
2898
+ maximum: 15e3,
2899
+ description: "Settle window in ms after return (default 300)"
2900
+ },
2901
+ studio_id: {
2902
+ type: "string",
2903
+ description: "Optional Roblox Studio instance ID (auto-filled when 1 Studio is open)"
2904
+ },
2905
+ session: {
2906
+ type: "string",
2907
+ description: "Optional live game session selector"
2908
+ }
2909
+ },
2910
+ additionalProperties: false
2911
+ },
2912
+ annotations: {
2913
+ title: "Run Roblox Studio script in live game",
2914
+ readOnlyHint: false,
2915
+ destructiveHint: true,
2916
+ idempotentHint: false,
2917
+ openWorldHint: false
2918
+ }
2919
+ },
2920
+ {
2921
+ name: "studio_publish",
2922
+ title: "Publish a Roblox Studio script to Luaward Cloud",
2923
+ description: "Read a script's Luau source directly from Roblox Studio (%LOCALAPPDATA%\\Roblox\\mcp.bat) and deploy/protect it on Luaward Cloud via deploy_script.",
2924
+ inputSchema: {
2925
+ type: "object",
2926
+ properties: {
2927
+ script: {
2928
+ type: "string",
2929
+ description: "Target Luaward Cloud script name or ID"
2930
+ },
2931
+ studio_path: {
2932
+ type: "string",
2933
+ description: "Script path in Roblox Studio or 'Selection' for the currently selected script (default 'Selection')"
2934
+ },
2935
+ publish: {
2936
+ type: "boolean",
2937
+ description: "Promote build to live automatically (default true; false for staged draft)"
2938
+ },
2939
+ preset: {
2940
+ type: "string",
2941
+ enum: ["fast", "balanced", "max"],
2942
+ description: "Optional protection preset"
2943
+ },
2944
+ studio_id: {
2945
+ type: "string",
2946
+ description: "Optional Roblox Studio instance ID (auto-filled when 1 Studio is open)"
2947
+ }
2948
+ },
2949
+ required: ["script"],
2950
+ additionalProperties: false
2951
+ },
2952
+ annotations: {
2953
+ title: "Publish Roblox Studio script to Luaward Cloud",
2954
+ readOnlyHint: false,
2955
+ destructiveHint: false,
2956
+ idempotentHint: false,
2957
+ openWorldHint: false
2958
+ }
2959
+ },
2960
+ {
2961
+ name: "live_scripts_to_studio",
2962
+ title: "Decompile live game scripts and import them into Roblox Studio",
2963
+ description: "Decompile LocalScripts and ModuleScripts from the live connected game and create corresponding script instances with .Source populated inside Roblox Studio via %LOCALAPPDATA%\\Roblox\\mcp.bat.",
2964
+ inputSchema: {
2965
+ type: "object",
2966
+ properties: {
2967
+ targets: {
2968
+ type: "array",
2969
+ items: { type: "string" },
2970
+ description: "Explicit list of live script paths to import into Studio"
2971
+ },
2972
+ filter: {
2973
+ type: "string",
2974
+ description: "Case-insensitive path substring filter when targets is omitted (e.g. 'ReplicatedStorage')"
2975
+ },
2976
+ studio_root: {
2977
+ type: "string",
2978
+ description: "Optional destination container in Studio (e.g. 'ServerStorage.LiveImports'; omit to mirror into matching services)"
2979
+ },
2980
+ max: {
2981
+ type: "integer",
2982
+ minimum: 1,
2983
+ maximum: 100,
2984
+ description: "Maximum scripts to import in one call (default 15)"
2985
+ },
2986
+ disabled: {
2987
+ type: "boolean",
2988
+ description: "Set .Disabled = true on imported LocalScripts in Studio (default true)"
2989
+ },
2990
+ studio_id: {
2991
+ type: "string",
2992
+ description: "Optional Roblox Studio instance ID (auto-filled when 1 Studio is open)"
2993
+ },
2994
+ session: {
2995
+ type: "string",
2996
+ description: "Optional live game session selector"
2997
+ }
2998
+ },
2999
+ additionalProperties: false
3000
+ },
3001
+ annotations: {
3002
+ title: "Import live decompiled scripts into Roblox Studio",
3003
+ readOnlyHint: false,
3004
+ destructiveHint: false,
3005
+ idempotentHint: true,
3006
+ openWorldHint: false
3007
+ }
3008
+ },
3009
+ {
3010
+ name: "compare_screens",
3011
+ title: "Capture and compare screenshots between two windows (e.g. Roblox vs Studio)",
3012
+ description: "Capture screenshots of two desktop targets (default target_a='roblox' RobloxPlayerBeta vs target_b='studio' RobloxStudioBeta), compute pixel and 4x4 grid region similarity/difference metrics, and return both PNG images side by side.",
3013
+ inputSchema: {
3014
+ type: "object",
3015
+ properties: {
3016
+ target_a: {
3017
+ type: "string",
3018
+ description: "First window target (default 'roblox' - strictly RobloxPlayerBeta)"
3019
+ },
3020
+ target_b: {
3021
+ type: "string",
3022
+ description: "Second window target (default 'studio' - RobloxStudioBeta)"
3023
+ },
3024
+ client_only: {
3025
+ type: "boolean",
3026
+ description: "Capture inner client viewport only (default true)"
3027
+ },
3028
+ method: {
3029
+ type: "string",
3030
+ enum: ["auto", "copy", "printwindow"],
3031
+ description: "Capture method ('auto' uses WindowFromPoint occlusion detection + PrintWindow for background windows, default 'auto')"
3032
+ },
3033
+ focus_first: {
3034
+ type: "boolean",
3035
+ description: "Focus each window before capturing (default false)"
3036
+ }
3037
+ },
3038
+ additionalProperties: false
3039
+ },
3040
+ annotations: {
3041
+ title: "Compare screenshots between two windows",
3042
+ readOnlyHint: true,
3043
+ destructiveHint: false,
3044
+ idempotentHint: true,
3045
+ openWorldHint: false
3046
+ }
3047
+ }
3048
+ ];
3049
+ var HybridMcpBridge = class {
3050
+ token;
3051
+ url;
3052
+ potassium;
3053
+ windows;
3054
+ studio;
3055
+ autoInject;
3056
+ autoInjectPollMs;
3057
+ autoInjectMaxPolls;
3058
+ autoInjectCooldownMs;
3059
+ fetchFn;
3060
+ stderr;
3061
+ cachedPairCommand;
3062
+ lastLaunchParams;
3063
+ lastAutoInjectFailureAt = 0;
3064
+ lastAutoInjectFailureReason = "";
3065
+ scopeWarningEmitted = false;
3066
+ lastScopeWarning = null;
3067
+ rpcSeq = 5e3;
3068
+ constructor(options = {}) {
3069
+ const resolved = resolveBridgeConfig([], process.env, options.configDir);
3070
+ this.token = options.token !== void 0 ? options.token || null : resolved.token;
3071
+ this.url = options.url ?? resolved.url;
3072
+ this.fetchFn = options.fetchImpl ?? fetch;
3073
+ this.stderr = options.stderr ?? process.stderr;
3074
+ this.cachedPairCommand = options.pairCommand ?? resolved.pairCommand;
3075
+ this.autoInject = options.autoInject ?? resolved.autoInject;
2137
3076
  this.autoInjectPollMs = options.autoInjectPollMs ?? 400;
2138
3077
  this.autoInjectMaxPolls = options.autoInjectMaxPolls ?? 15;
3078
+ this.autoInjectCooldownMs = options.autoInjectCooldownMs ?? 3e4;
2139
3079
  this.potassium = options.potassiumClient ?? new PotassiumClient({
2140
3080
  url: options.potassiumUrl ?? resolved.potassiumUrl,
2141
3081
  token: options.potassiumToken !== void 0 ? options.potassiumToken : resolved.potassiumToken,
2142
3082
  fetchImpl: this.fetchFn
2143
3083
  });
2144
3084
  this.windows = options.windowsDriver ?? new PowerShellWindowsDriver();
3085
+ this.studio = options.studioClient ?? new RobloxStudioMcpClient(options.studioOptions);
3086
+ }
3087
+ evaluateTokenScopesFromTools(tools) {
3088
+ const names = new Set(tools.map((t) => String(t.name ?? "")));
3089
+ if (names.size === 0) {
3090
+ return { missingScopes: [], hiddenTools: [], warning: null };
3091
+ }
3092
+ const missingScopes = [];
3093
+ const hiddenTools = [];
3094
+ if (!names.has("spy_start") && !names.has("spy_stop")) {
3095
+ missingScopes.push("spy");
3096
+ hiddenTools.push("spy_start", "spy_stop");
3097
+ }
3098
+ if (!names.has("search_scripts") && !names.has("scripts_read") && !names.has("scripts_list")) {
3099
+ missingScopes.push("scripts");
3100
+ hiddenTools.push("search_scripts", "scripts_read", "scripts_list", "scripts_sync");
3101
+ }
3102
+ if (missingScopes.length === 0) {
3103
+ this.lastScopeWarning = null;
3104
+ return { missingScopes: [], hiddenTools: [], warning: null };
3105
+ }
3106
+ const warning = `[Luaward MCP Warning] Your MCP token is missing scope(s): ${missingScopes.join(", ")}. Tools (${hiddenTools.join(", ")}) will not appear in tools/list. Create a new token with full scopes (read, scripts, spy, control) at ${TOKEN_CREATE_URL}`;
3107
+ this.lastScopeWarning = warning;
3108
+ if (!this.scopeWarningEmitted) {
3109
+ this.scopeWarningEmitted = true;
3110
+ try {
3111
+ this.stderr.write(`${warning}
3112
+ `);
3113
+ } catch {
3114
+ }
3115
+ }
3116
+ return { missingScopes, hiddenTools, warning };
3117
+ }
3118
+ async checkTokenScopes() {
3119
+ if (!this.token) {
3120
+ return { missingScopes: [], hiddenTools: [], warning: null };
3121
+ }
3122
+ try {
3123
+ const res = await this.callCloudRpc({
3124
+ jsonrpc: "2.0",
3125
+ id: ++this.rpcSeq,
3126
+ method: "tools/list",
3127
+ params: {}
3128
+ });
3129
+ const tools = res.body?.result?.tools;
3130
+ if (Array.isArray(tools)) {
3131
+ return this.evaluateTokenScopesFromTools(tools);
3132
+ }
3133
+ } catch {
3134
+ }
3135
+ return { missingScopes: [], hiddenTools: [], warning: this.lastScopeWarning };
2145
3136
  }
2146
3137
  cloudHeaders(protoVer) {
2147
3138
  const headers = {
@@ -2224,54 +3215,83 @@ var HybridMcpBridge = class {
2224
3215
  }
2225
3216
  async tryZeroTouchAutoInject(opts) {
2226
3217
  const waitMs = Math.max(0, opts?.waitForClientMs ?? 0);
3218
+ if (!opts?.force && waitMs === 0 && this.lastAutoInjectFailureAt > 0 && this.autoInjectCooldownMs > 0) {
3219
+ const elapsed = Date.now() - this.lastAutoInjectFailureAt;
3220
+ if (elapsed < this.autoInjectCooldownMs) {
3221
+ const remSec = Math.max(1, Math.ceil((this.autoInjectCooldownMs - elapsed) / 1e3));
3222
+ return {
3223
+ injected: false,
3224
+ text: `Potassium auto-inject skipped (cooldown ${remSec}s remaining after: ${this.lastAutoInjectFailureReason}). ${POTASSIUM_ENABLE_HINT}`
3225
+ };
3226
+ }
3227
+ }
2227
3228
  const clientPollMs = Math.max(0, opts?.pollClientMs ?? Math.min(1e3, this.autoInjectPollMs || 500));
2228
3229
  const deadline = Date.now() + waitMs;
2229
3230
  let clientsRes = await this.potassium.listClients();
2230
- while ((!clientsRes.ok || clientsRes.clients.length === 0) && Date.now() < deadline) {
3231
+ while (clientsRes.ok && clientsRes.clients.length === 0 && Date.now() < deadline) {
2231
3232
  if (clientPollMs > 0) await sleep(clientPollMs);
2232
3233
  clientsRes = await this.potassium.listClients();
2233
3234
  }
2234
3235
  if (!clientsRes.ok) {
3236
+ this.lastAutoInjectFailureAt = Date.now();
3237
+ this.lastAutoInjectFailureReason = `Potassium local MCP error: ${clientsRes.rawText}`;
2235
3238
  return {
2236
3239
  injected: false,
2237
- text: `Potassium local MCP error: ${clientsRes.rawText}`
3240
+ text: `${this.lastAutoInjectFailureReason}. ${POTASSIUM_ENABLE_HINT}`
2238
3241
  };
2239
3242
  }
2240
3243
  if (clientsRes.clients.length === 0) {
3244
+ this.lastAutoInjectFailureAt = Date.now();
3245
+ this.lastAutoInjectFailureReason = waitMs > 0 ? `no attached Roblox client appeared in Potassium local MCP within ${Math.round(waitMs / 1e3)}s` : "no attached Roblox client found in Potassium local MCP";
2241
3246
  return {
2242
3247
  injected: false,
2243
- text: waitMs > 0 ? `no attached Roblox client appeared in Potassium local MCP within ${Math.round(waitMs / 1e3)}s` : "no attached Roblox client found in Potassium local MCP"
3248
+ text: this.lastAutoInjectFailureReason
2244
3249
  };
2245
3250
  }
2246
3251
  const pairCmd = await this.fetchWorkspacePairCommand();
2247
3252
  if (!pairCmd) {
2248
- return { injected: false, text: "could not fetch workspace pair command (luaward://pair)" };
3253
+ this.lastAutoInjectFailureAt = Date.now();
3254
+ this.lastAutoInjectFailureReason = "could not fetch workspace pair command (luaward://pair)";
3255
+ return { injected: false, text: this.lastAutoInjectFailureReason };
2249
3256
  }
2250
3257
  const pids = clientsRes.clients.map((c) => c.pid ?? c.id).filter((p) => p !== void 0 && p !== "");
2251
3258
  const execRes = await this.potassium.executeScript(pairCmd, pids.length > 0 ? pids : void 0);
2252
3259
  if (!execRes.ok) {
2253
- return { injected: false, text: `Potassium execute_script failed: ${execRes.text}` };
3260
+ this.lastAutoInjectFailureAt = Date.now();
3261
+ this.lastAutoInjectFailureReason = `Potassium execute_script failed: ${execRes.text}`;
3262
+ return { injected: false, text: this.lastAutoInjectFailureReason };
2254
3263
  }
2255
3264
  for (let i = 0; i < this.autoInjectMaxPolls; i++) {
2256
3265
  if (this.autoInjectPollMs > 0) await sleep(this.autoInjectPollMs);
2257
3266
  const check = await this.callCloudTool("list_sessions", {});
2258
3267
  if (check.ok && check.text && !check.text.includes("no game is connected")) {
3268
+ this.lastAutoInjectFailureAt = 0;
3269
+ this.lastAutoInjectFailureReason = "";
2259
3270
  return {
2260
3271
  injected: true,
2261
3272
  text: `Auto-injected Luaward agent via Potassium local MCP (${clientsRes.clients.length} client(s))`
2262
3273
  };
2263
3274
  }
2264
3275
  }
3276
+ this.lastAutoInjectFailureAt = Date.now();
3277
+ this.lastAutoInjectFailureReason = "injected pair command via Potassium, but session did not register within timeout";
2265
3278
  return {
2266
3279
  injected: false,
2267
- text: "injected pair command via Potassium, but session did not register within timeout"
3280
+ text: this.lastAutoInjectFailureReason
2268
3281
  };
2269
3282
  }
3283
+ formatPotassiumError(rawText) {
3284
+ if (/not reachable|offline|econnrefused|fetch failed|http [45]\d\d/i.test(rawText)) {
3285
+ return `${rawText}
3286
+ Hint: ${POTASSIUM_ENABLE_HINT}`;
3287
+ }
3288
+ return rawText;
3289
+ }
2270
3290
  resolveLocalFileArg(args, targetField) {
2271
3291
  const rawPath = args.file_path;
2272
3292
  if (typeof rawPath !== "string" || !rawPath.trim()) return;
2273
3293
  const fullPath = resolve2(rawPath.trim());
2274
- if (!existsSync3(fullPath)) {
3294
+ if (!existsSync4(fullPath)) {
2275
3295
  throw new Error(`Local file_path not found: ${fullPath}`);
2276
3296
  }
2277
3297
  const content = readFileSync2(fullPath, "utf8");
@@ -2284,7 +3304,9 @@ var HybridMcpBridge = class {
2284
3304
  switch (action) {
2285
3305
  case "list": {
2286
3306
  const res = await this.potassium.listTabs();
2287
- if (!res.ok) return { content: [{ type: "text", text: res.rawText }], isError: true };
3307
+ if (!res.ok) {
3308
+ return { content: [{ type: "text", text: this.formatPotassiumError(res.rawText) }], isError: true };
3309
+ }
2288
3310
  if (res.tabs.length === 0) {
2289
3311
  return { content: [{ type: "text", text: res.rawText || "no tabs in Potassium" }] };
2290
3312
  }
@@ -2298,7 +3320,9 @@ ${lines.join("\n")}` }]
2298
3320
  }
2299
3321
  case "read": {
2300
3322
  const res = await this.potassium.readTab(tabId);
2301
- if (!res.ok) return { content: [{ type: "text", text: res.content }], isError: true };
3323
+ if (!res.ok) {
3324
+ return { content: [{ type: "text", text: this.formatPotassiumError(res.content) }], isError: true };
3325
+ }
2302
3326
  const header = `-- Potassium tab ${res.tabId ?? "active"}${res.name ? ` ("${res.name}")` : ""}`;
2303
3327
  return { content: [{ type: "text", text: `${header}
2304
3328
  ${res.content}` }] };
@@ -2308,7 +3332,7 @@ ${res.content}` }] };
2308
3332
  let content = typeof args.content === "string" ? args.content : "";
2309
3333
  if (typeof args.file_path === "string" && args.file_path.trim()) {
2310
3334
  const fp = resolve2(args.file_path.trim());
2311
- if (!existsSync3(fp)) {
3335
+ if (!existsSync4(fp)) {
2312
3336
  return { content: [{ type: "text", text: `Local file_path not found: ${fp}` }], isError: true };
2313
3337
  }
2314
3338
  content = readFileSync2(fp, "utf8");
@@ -2319,7 +3343,10 @@ ${res.content}` }] };
2319
3343
  tabId: action === "write" ? tabId : void 0,
2320
3344
  reuseScratch: args.reuse_scratch !== false
2321
3345
  });
2322
- return { content: [{ type: "text", text: res.text }], isError: !res.ok };
3346
+ return {
3347
+ content: [{ type: "text", text: res.ok ? res.text : this.formatPotassiumError(res.text) }],
3348
+ isError: !res.ok
3349
+ };
2323
3350
  }
2324
3351
  case "activate": {
2325
3352
  if (!tabId) {
@@ -2330,7 +3357,12 @@ ${res.content}` }] };
2330
3357
  }
2331
3358
  const res = await this.potassium.callTool("tabs", { action: "activate", tab_id: tabId, id: tabId });
2332
3359
  return {
2333
- content: [{ type: "text", text: res.ok ? `activated tab ${tabId}` : res.text }],
3360
+ content: [
3361
+ {
3362
+ type: "text",
3363
+ text: res.ok ? `activated tab ${tabId}` : this.formatPotassiumError(res.text)
3364
+ }
3365
+ ],
2334
3366
  isError: !res.ok
2335
3367
  };
2336
3368
  }
@@ -2351,13 +3383,17 @@ ${res.content}` }] };
2351
3383
  };
2352
3384
  }
2353
3385
  return {
2354
- content: [{ type: "text", text: res.ok ? `closed tab ${tabId}` : res.text }],
3386
+ content: [
3387
+ { type: "text", text: res.ok ? `closed tab ${tabId}` : this.formatPotassiumError(res.text) }
3388
+ ],
2355
3389
  isError: !res.ok
2356
3390
  };
2357
3391
  }
2358
3392
  case "run_tab": {
2359
3393
  const read = await this.potassium.readTab(tabId);
2360
- if (!read.ok) return { content: [{ type: "text", text: read.content }], isError: true };
3394
+ if (!read.ok) {
3395
+ return { content: [{ type: "text", text: this.formatPotassiumError(read.content) }], isError: true };
3396
+ }
2361
3397
  if (!read.content.trim()) {
2362
3398
  return { content: [{ type: "text", text: "Target Potassium tab is empty" }], isError: true };
2363
3399
  }
@@ -2486,15 +3522,19 @@ ${luauBody}`,
2486
3522
  }),
2487
3523
  this.potassium.listClients()
2488
3524
  ]);
2489
- const rbxWins = wins.filter(
2490
- (w) => w.processName.toLowerCase().includes("roblox") || w.title === "Roblox"
2491
- );
3525
+ const rbxWins = wins.filter((w) => isRobloxPlayerWindow(w));
3526
+ const studioWins = wins.filter((w) => isRobloxStudioWindow(w));
2492
3527
  const potWins = wins.filter((w) => w.processName.toLowerCase().includes("potassium"));
2493
3528
  const lines = [
2494
3529
  ...winErr ? [`Desktop window query warning: ${winErr}`] : [],
2495
3530
  `Roblox windows: ${rbxWins.length}${rbxWins.length ? ` (${rbxWins.map((w) => `PID ${w.pid}, ${w.responding ? "responding" : "NOT RESPONDING"}, client ${w.clientRect.width}x${w.clientRect.height}`).join("; ")})` : ""}`,
3531
+ ...studioWins.length > 0 ? [
3532
+ `Roblox Studio windows: ${studioWins.length} (${studioWins.map((w) => `PID ${w.pid} "${w.title}", client ${w.clientRect.width}x${w.clientRect.height}`).join("; ")})`
3533
+ ] : [],
2496
3534
  `Potassium windows: ${potWins.length}${potWins.length ? ` (PID ${potWins.map((w) => w.pid).join(", ")})` : ""}`,
2497
- `Potassium MCP (${this.potassium.url}): ${kClients.ok ? `online (${kClients.clients.length} attached client(s))` : `offline (${kClients.rawText})`}`
3535
+ `Potassium MCP (${this.potassium.url}): ${kClients.ok ? `online (${kClients.clients.length} attached client(s))` : `offline (${kClients.rawText})
3536
+ Hint: ${POTASSIUM_ENABLE_HINT}`}`,
3537
+ ...this.lastScopeWarning ? [this.lastScopeWarning] : []
2498
3538
  ];
2499
3539
  return { content: [{ type: "text", text: lines.join("\n") }] };
2500
3540
  }
@@ -2744,22 +3784,856 @@ ${lines.join("\n")}` }]
2744
3784
  const screenX = Math.round(cr.screenLeft + clientX * scaleX);
2745
3785
  const screenY = Math.round(cr.screenTop + clientY * scaleY);
2746
3786
  const mouseAction = args.double_click === true ? "double_click" : args.button === "right" ? "right_click" : "click";
3787
+ const session = typeof args.session === "string" ? args.session : void 0;
3788
+ const shouldVerify = args.verify === true;
3789
+ const beforeSnap = shouldVerify ? await this.captureGuiSnapshotForVerify(session) : null;
2747
3790
  const clickRes = await this.windows.mouse({
2748
3791
  action: mouseAction,
2749
3792
  mode: "ui",
2750
3793
  x: screenX,
2751
3794
  y: screenY
2752
3795
  });
3796
+ let verifySuffix = "";
3797
+ if (shouldVerify) {
3798
+ const verifyText = await this.verifyMouseActionInGame(beforeSnap, session);
3799
+ verifySuffix = `
3800
+ ${verifyText}`;
3801
+ }
2753
3802
  return {
2754
3803
  content: [
2755
3804
  {
2756
3805
  type: "text",
2757
- text: `os_click ${mouseAction} on ${resolvedPath} (${target}): in-game client=(${Math.round(clientX)}, ${Math.round(clientY)}) -> Windows screen=(${screenX}, ${screenY})`
3806
+ text: `os_click ${mouseAction} on ${resolvedPath} (${target}): in-game client=(${Math.round(clientX)}, ${Math.round(clientY)}) -> Windows screen=(${screenX}, ${screenY})${verifySuffix}`
2758
3807
  }
2759
3808
  ],
2760
3809
  isError: !clickRes.ok
2761
3810
  };
2762
3811
  }
3812
+ async captureGuiSnapshotForVerify(session) {
3813
+ try {
3814
+ const res = await this.callCloudTool("gui_snapshot", {
3815
+ ...session ? { session } : {}
3816
+ });
3817
+ return res.ok ? res.text : null;
3818
+ } catch {
3819
+ return null;
3820
+ }
3821
+ }
3822
+ computeSnapshotLineDiff(beforeText, afterText) {
3823
+ if (afterText.includes("--- diff")) {
3824
+ const idx = afterText.indexOf("--- diff");
3825
+ return afterText.slice(idx).trim();
3826
+ }
3827
+ if (!beforeText) {
3828
+ return "captured post-click gui_snapshot (no baseline snapshot)";
3829
+ }
3830
+ const beforeLines = beforeText.split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("GUI snapshot"));
3831
+ const afterLines = afterText.split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("GUI snapshot"));
3832
+ const beforeSet = new Set(beforeLines);
3833
+ const afterSet = new Set(afterLines);
3834
+ const added = afterLines.filter((l) => !beforeSet.has(l));
3835
+ const removed = beforeLines.filter((l) => !afterSet.has(l));
3836
+ if (added.length === 0 && removed.length === 0) {
3837
+ return "no GUI state change detected";
3838
+ }
3839
+ const out = [];
3840
+ for (const r of removed.slice(0, 12)) out.push(`- ${r}`);
3841
+ for (const a of added.slice(0, 12)) out.push(`+ ${a}`);
3842
+ if (removed.length > 12 || added.length > 12) {
3843
+ out.push(`... (+${Math.max(0, added.length - 12)} added, -${Math.max(0, removed.length - 12)} removed)`);
3844
+ }
3845
+ return out.join("\n");
3846
+ }
3847
+ async verifyMouseActionInGame(beforeSnap, session) {
3848
+ const lines = ["Verification:"];
3849
+ try {
3850
+ const mouseCode = [
3851
+ "local uis = game:GetService('UserInputService')",
3852
+ "local m = uis:GetMouseLocation()",
3853
+ "local inset = game:GetService('GuiService'):GetGuiInset()",
3854
+ "return { mouseX = math.floor(m.X + 0.5), mouseY = math.floor(m.Y + 0.5), guiX = math.floor(m.X + 0.5), guiY = math.floor(m.Y - (inset and inset.Y or 0) + 0.5) }"
3855
+ ].join("; ");
3856
+ const mouseRes = await this.callCloudTool("exec", {
3857
+ code: mouseCode,
3858
+ readonly: true,
3859
+ ...session ? { session } : {}
3860
+ });
3861
+ if (mouseRes.ok) {
3862
+ const mx = /\bmouseX\s*=\s*(-?\d+(?:\.\d+)?)/.exec(mouseRes.text);
3863
+ const my = /\bmouseY\s*=\s*(-?\d+(?:\.\d+)?)/.exec(mouseRes.text);
3864
+ const gx = /\bguiX\s*=\s*(-?\d+(?:\.\d+)?)/.exec(mouseRes.text);
3865
+ const gy = /\bguiY\s*=\s*(-?\d+(?:\.\d+)?)/.exec(mouseRes.text);
3866
+ if (mx && my) {
3867
+ const guiPart = gx && gy ? ` \xB7 gui=(${gx[1]}, ${gy[1]})` : "";
3868
+ lines.push(`- GetMouseLocation: inset=(${mx[1]}, ${my[1]})${guiPart}`);
3869
+ } else {
3870
+ lines.push(`- GetMouseLocation: ${mouseRes.text.trim()}`);
3871
+ }
3872
+ } else {
3873
+ lines.push(`- GetMouseLocation unavailable: ${mouseRes.text}`);
3874
+ }
3875
+ } catch (err) {
3876
+ lines.push(`- GetMouseLocation error: ${err instanceof Error ? err.message : String(err)}`);
3877
+ }
3878
+ try {
3879
+ const snapRes = await this.callCloudTool("gui_snapshot", {
3880
+ diff_from: "latest",
3881
+ ...session ? { session } : {}
3882
+ });
3883
+ if (snapRes.ok) {
3884
+ const diffSummary = this.computeSnapshotLineDiff(beforeSnap, snapRes.text);
3885
+ lines.push(`- gui_snapshot diff:
3886
+ ${diffSummary}`);
3887
+ } else {
3888
+ lines.push(`- gui_snapshot diff unavailable: ${snapRes.text}`);
3889
+ }
3890
+ } catch (err) {
3891
+ lines.push(`- gui_snapshot diff error: ${err instanceof Error ? err.message : String(err)}`);
3892
+ }
3893
+ return lines.join("\n");
3894
+ }
3895
+ extractJsonPayloadFromExec(rawText) {
3896
+ const trimmed = rawText.trim();
3897
+ if (!trimmed) return null;
3898
+ const candidates = [trimmed];
3899
+ if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
3900
+ try {
3901
+ const unquoted = JSON.parse(trimmed);
3902
+ if (typeof unquoted === "string") candidates.unshift(unquoted);
3903
+ } catch {
3904
+ }
3905
+ }
3906
+ const firstBracket = trimmed.search(/[\[{]/);
3907
+ const lastBracket = Math.max(trimmed.lastIndexOf("]"), trimmed.lastIndexOf("}"));
3908
+ if (firstBracket >= 0 && lastBracket > firstBracket) {
3909
+ candidates.push(trimmed.slice(firstBracket, lastBracket + 1));
3910
+ }
3911
+ for (const c of candidates) {
3912
+ try {
3913
+ return JSON.parse(c);
3914
+ } catch {
3915
+ }
3916
+ }
3917
+ return null;
3918
+ }
3919
+ async handleStudioMirrorRemotes(args) {
3920
+ const roots = Array.isArray(args.roots) && args.roots.length > 0 ? args.roots.map(String) : ["ReplicatedStorage", "Workspace"];
3921
+ const maxDepth = typeof args.max_depth === "number" ? Math.max(1, Math.min(12, args.max_depth)) : 6;
3922
+ const clearExisting = args.clear_existing === true;
3923
+ const session = typeof args.session === "string" ? args.session : void 0;
3924
+ const requestedStudioId = typeof args.studio_id === "string" ? args.studio_id : void 0;
3925
+ const liveScanCode = [
3926
+ "local HttpService = game:GetService('HttpService')",
3927
+ `local roots = ${JSON.stringify(roots)}`,
3928
+ `local maxDepth = ${maxDepth}`,
3929
+ "local remoteClasses = { RemoteEvent = true, RemoteFunction = true, UnreliableRemoteEvent = true, BindableEvent = true, BindableFunction = true }",
3930
+ "local items = {}",
3931
+ "local function scan(inst, rootName, segs, depth)",
3932
+ " if depth > maxDepth then return end",
3933
+ " for _, child in ipairs(inst:GetChildren()) do",
3934
+ " local nextSegs = {}",
3935
+ " for i = 1, #segs do nextSegs[i] = segs[i] end",
3936
+ " nextSegs[#nextSegs + 1] = child.Name",
3937
+ " if remoteClasses[child.ClassName] then",
3938
+ " items[#items + 1] = { root = rootName, className = child.ClassName, segments = nextSegs, path = rootName .. '.' .. table.concat(nextSegs, '.') }",
3939
+ " end",
3940
+ " if #child:GetChildren() > 0 then",
3941
+ " scan(child, rootName, nextSegs, depth + 1)",
3942
+ " end",
3943
+ " end",
3944
+ "end",
3945
+ "for _, rName in ipairs(roots) do",
3946
+ " local ok, svc = pcall(function() return game:GetService(rName) end)",
3947
+ " if ok and svc then scan(svc, rName, {}, 1) end",
3948
+ "end",
3949
+ "return HttpService:JSONEncode(items)"
3950
+ ].join("\n");
3951
+ const liveRes = await this.callCloudTool("exec", {
3952
+ code: liveScanCode,
3953
+ readonly: true,
3954
+ ...session ? { session } : {}
3955
+ });
3956
+ if (!liveRes.ok) {
3957
+ return {
3958
+ content: [{ type: "text", text: `studio_mirror_remotes failed to read live remotes: ${liveRes.text}` }],
3959
+ isError: true
3960
+ };
3961
+ }
3962
+ const items = this.extractJsonPayloadFromExec(liveRes.text) ?? [];
3963
+ const studioCode = [
3964
+ "local HttpService = game:GetService('HttpService')",
3965
+ `local items = HttpService:JSONDecode(${JSON.stringify(JSON.stringify(items))})`,
3966
+ `local clearExisting = ${clearExisting ? "true" : "false"}`,
3967
+ "local created, existing = 0, 0",
3968
+ "for _, item in ipairs(items) do",
3969
+ " local ok, rootInst = pcall(function() return game:GetService(item.root) end)",
3970
+ " if ok and rootInst then",
3971
+ " local cur = rootInst",
3972
+ " for i = 1, #item.segments - 1 do",
3973
+ " local seg = item.segments[i]",
3974
+ " local nextInst = cur:FindFirstChild(seg)",
3975
+ " if not nextInst then",
3976
+ " nextInst = Instance.new('Folder')",
3977
+ " nextInst.Name = seg",
3978
+ " nextInst.Parent = cur",
3979
+ " end",
3980
+ " cur = nextInst",
3981
+ " end",
3982
+ " local leafName = item.segments[#item.segments]",
3983
+ " if leafName then",
3984
+ " local found = cur:FindFirstChild(leafName)",
3985
+ " if found and clearExisting and found.ClassName == item.className then",
3986
+ " found:Destroy()",
3987
+ " found = nil",
3988
+ " end",
3989
+ " if not found then",
3990
+ " local okNew, inst = pcall(Instance.new, item.className)",
3991
+ " if okNew and inst then",
3992
+ " inst.Name = leafName",
3993
+ " inst.Parent = cur",
3994
+ " created = created + 1",
3995
+ " end",
3996
+ " else",
3997
+ " existing = existing + 1",
3998
+ " end",
3999
+ " end",
4000
+ " end",
4001
+ "end",
4002
+ "return string.format('mirrored %d remotes (created=%d, existing=%d)', #items, created, existing)"
4003
+ ].join("\n");
4004
+ const studioRes = await this.studio.runStudioLuau(studioCode, requestedStudioId);
4005
+ if (!studioRes.ok) {
4006
+ return {
4007
+ content: [
4008
+ {
4009
+ type: "text",
4010
+ text: `studio_mirror_remotes collected ${items.length} live remotes but Studio execution failed: ${studioRes.text}`
4011
+ }
4012
+ ],
4013
+ isError: true
4014
+ };
4015
+ }
4016
+ const samplePaths = items.slice(0, 15).map((i) => ` - [${i.className}] ${i.path}`);
4017
+ return {
4018
+ content: [
4019
+ {
4020
+ type: "text",
4021
+ text: [
4022
+ `studio_mirror_remotes complete (studio_id=${studioRes.studioId ?? "auto"}):`,
4023
+ `- Live remotes discovered: ${items.length} across ${roots.join(", ")}`,
4024
+ `- Studio result: ${studioRes.text}`,
4025
+ ...samplePaths.length > 0 ? ["- Sample mirrored paths:", ...samplePaths] : []
4026
+ ].join("\n")
4027
+ }
4028
+ ]
4029
+ };
4030
+ }
4031
+ async handleStudioMirrorGui(args) {
4032
+ const targetPath = typeof args.target_path === "string" ? args.target_path.trim() : "";
4033
+ const containerName = typeof args.container_name === "string" && args.container_name.trim() ? args.container_name.trim() : "LuawardMirroredGui";
4034
+ const maxNodes = typeof args.max_nodes === "number" ? Math.max(10, Math.min(1e3, args.max_nodes)) : 250;
4035
+ const includeCoreGui = args.include_core_gui === true;
4036
+ const session = typeof args.session === "string" ? args.session : void 0;
4037
+ const requestedStudioId = typeof args.studio_id === "string" ? args.studio_id : void 0;
4038
+ const liveGuiCode = [
4039
+ "local HttpService = game:GetService('HttpService')",
4040
+ "local Players = game:GetService('Players')",
4041
+ `local targetPath = ${JSON.stringify(targetPath)}`,
4042
+ `local maxNodes = ${maxNodes}`,
4043
+ `local includeCore = ${includeCoreGui ? "true" : "false"}`,
4044
+ "local nodes = {}",
4045
+ "local count = 0",
4046
+ "local function serColor(c) return c and { c.R, c.G, c.B } or nil end",
4047
+ "local function serUDim2(u) return u and { u.X.Scale, u.X.Offset, u.Y.Scale, u.Y.Offset } or nil end",
4048
+ "local function serVec2(v) return v and { v.X, v.Y } or nil end",
4049
+ "local function serializeTree(inst, depth)",
4050
+ " if count >= maxNodes or depth > 10 then return nil end",
4051
+ " count = count + 1",
4052
+ " local node = { className = inst.ClassName, name = inst.Name, children = {} }",
4053
+ " pcall(function()",
4054
+ " if inst:IsA('LayerCollector') then node.enabled = inst.Enabled end",
4055
+ " if inst:IsA('GuiObject') then",
4056
+ " node.visible = inst.Visible",
4057
+ " node.pos = serUDim2(inst.Position)",
4058
+ " node.size = serUDim2(inst.Size)",
4059
+ " node.anchor = serVec2(inst.AnchorPoint)",
4060
+ " node.bg = serColor(inst.BackgroundColor3)",
4061
+ " node.bgTrans = inst.BackgroundTransparency",
4062
+ " node.zIndex = inst.ZIndex",
4063
+ " node.layoutOrder = inst.LayoutOrder",
4064
+ " end",
4065
+ " if inst:IsA('TextLabel') or inst:IsA('TextButton') or inst:IsA('TextBox') then",
4066
+ " node.text = tostring(inst.Text or ''):sub(1, 200)",
4067
+ " node.textColor = serColor(inst.TextColor3)",
4068
+ " node.textSize = inst.TextSize",
4069
+ " end",
4070
+ " if inst:IsA('UICorner') then",
4071
+ " node.corner = { inst.CornerRadius.Scale, inst.CornerRadius.Offset }",
4072
+ " end",
4073
+ " end)",
4074
+ " for _, child in ipairs(inst:GetChildren()) do",
4075
+ " if count >= maxNodes then break end",
4076
+ " local cNode = serializeTree(child, depth + 1)",
4077
+ " if cNode then node.children[#node.children + 1] = cNode end",
4078
+ " end",
4079
+ " return node",
4080
+ "end",
4081
+ "if targetPath ~= '' and lw and lw.resolve then",
4082
+ " local inst = lw.resolve(targetPath)",
4083
+ " if inst then nodes[#nodes + 1] = serializeTree(inst, 1) end",
4084
+ "else",
4085
+ " local lp = Players.LocalPlayer",
4086
+ " local pgui = lp and lp:FindFirstChildOfClass('PlayerGui')",
4087
+ " if pgui then",
4088
+ " for _, child in ipairs(pgui:GetChildren()) do",
4089
+ " if count >= maxNodes then break end",
4090
+ " local n = serializeTree(child, 1)",
4091
+ " if n then nodes[#nodes + 1] = n end",
4092
+ " end",
4093
+ " end",
4094
+ " if includeCore then",
4095
+ " local ok, cgui = pcall(function() return game:GetService('CoreGui') end)",
4096
+ " if ok and cgui then",
4097
+ " for _, child in ipairs(cgui:GetChildren()) do",
4098
+ " if count >= maxNodes then break end",
4099
+ " if child.Name ~= 'RobloxGui' then",
4100
+ " local n = serializeTree(child, 1)",
4101
+ " if n then nodes[#nodes + 1] = n end",
4102
+ " end",
4103
+ " end",
4104
+ " end",
4105
+ " end",
4106
+ "end",
4107
+ "return HttpService:JSONEncode({ count = count, trees = nodes })"
4108
+ ].join("\n");
4109
+ const liveRes = await this.callCloudTool("exec", {
4110
+ code: liveGuiCode,
4111
+ readonly: true,
4112
+ ...session ? { session } : {}
4113
+ });
4114
+ if (!liveRes.ok) {
4115
+ return {
4116
+ content: [{ type: "text", text: `studio_mirror_gui failed to read live GUI: ${liveRes.text}` }],
4117
+ isError: true
4118
+ };
4119
+ }
4120
+ const payload = this.extractJsonPayloadFromExec(liveRes.text) ?? {
4121
+ count: 0,
4122
+ trees: []
4123
+ };
4124
+ const studioBuildCode = [
4125
+ "local HttpService = game:GetService('HttpService')",
4126
+ "local StarterGui = game:GetService('StarterGui')",
4127
+ `local containerName = ${JSON.stringify(containerName)}`,
4128
+ `local payload = HttpService:JSONDecode(${JSON.stringify(JSON.stringify(payload))})`,
4129
+ "local folder = StarterGui:FindFirstChild(containerName)",
4130
+ "if folder then folder:Destroy() end",
4131
+ "folder = Instance.new('Folder')",
4132
+ "folder.Name = containerName",
4133
+ "folder.Parent = StarterGui",
4134
+ "local created = 0",
4135
+ "local function buildNode(node, parent)",
4136
+ " local ok, inst = pcall(Instance.new, node.className)",
4137
+ " if not ok or not inst then",
4138
+ " inst = Instance.new('Frame')",
4139
+ " end",
4140
+ " inst.Name = node.name or node.className",
4141
+ " pcall(function()",
4142
+ " if node.enabled ~= nil and inst:IsA('LayerCollector') then inst.Enabled = node.enabled end",
4143
+ " if inst:IsA('GuiObject') then",
4144
+ " if node.visible ~= nil then inst.Visible = node.visible end",
4145
+ " if node.pos then inst.Position = UDim2.new(node.pos[1], node.pos[2], node.pos[3], node.pos[4]) end",
4146
+ " if node.size then inst.Size = UDim2.new(node.size[1], node.size[2], node.size[3], node.size[4]) end",
4147
+ " if node.anchor then inst.AnchorPoint = Vector2.new(node.anchor[1], node.anchor[2]) end",
4148
+ " if node.bg then inst.BackgroundColor3 = Color3.new(node.bg[1], node.bg[2], node.bg[3]) end",
4149
+ " if node.bgTrans ~= nil then inst.BackgroundTransparency = node.bgTrans end",
4150
+ " if node.zIndex ~= nil then inst.ZIndex = node.zIndex end",
4151
+ " if node.layoutOrder ~= nil then inst.LayoutOrder = node.layoutOrder end",
4152
+ " end",
4153
+ " if node.text ~= nil and (inst:IsA('TextLabel') or inst:IsA('TextButton') or inst:IsA('TextBox')) then",
4154
+ " inst.Text = node.text",
4155
+ " if node.textColor then inst.TextColor3 = Color3.new(node.textColor[1], node.textColor[2], node.textColor[3]) end",
4156
+ " if node.textSize then inst.TextSize = node.textSize end",
4157
+ " end",
4158
+ " if node.corner and inst:IsA('UICorner') then",
4159
+ " inst.CornerRadius = UDim.new(node.corner[1], node.corner[2])",
4160
+ " end",
4161
+ " end)",
4162
+ " inst.Parent = parent",
4163
+ " created = created + 1",
4164
+ " if type(node.children) == 'table' then",
4165
+ " for _, child in ipairs(node.children) do buildNode(child, inst) end",
4166
+ " end",
4167
+ "end",
4168
+ "for _, tree in ipairs(payload.trees or {}) do buildNode(tree, folder) end",
4169
+ "return string.format('mirrored %d GUI nodes into StarterGui.%s', created, containerName)"
4170
+ ].join("\n");
4171
+ const studioRes = await this.studio.runStudioLuau(studioBuildCode, requestedStudioId);
4172
+ if (!studioRes.ok) {
4173
+ return {
4174
+ content: [
4175
+ {
4176
+ type: "text",
4177
+ text: `studio_mirror_gui serialized ${payload.count} live GUI nodes but Studio execution failed: ${studioRes.text}`
4178
+ }
4179
+ ],
4180
+ isError: true
4181
+ };
4182
+ }
4183
+ return {
4184
+ content: [
4185
+ {
4186
+ type: "text",
4187
+ text: [
4188
+ `studio_mirror_gui complete (studio_id=${studioRes.studioId ?? "auto"}):`,
4189
+ `- Live GUI nodes serialized: ${payload.count} (${payload.trees.length} root trees)`,
4190
+ `- Studio container: StarterGui.${containerName}`,
4191
+ `- Studio result: ${studioRes.text}`
4192
+ ].join("\n")
4193
+ }
4194
+ ]
4195
+ };
4196
+ }
4197
+ async handleStudioDiff(args) {
4198
+ const roots = Array.isArray(args.roots) && args.roots.length > 0 ? args.roots.map(String) : ["ReplicatedStorage", "StarterGui", "Workspace"];
4199
+ const scope = typeof args.scope === "string" ? args.scope : "all";
4200
+ const maxDepth = typeof args.max_depth === "number" ? Math.max(1, Math.min(10, args.max_depth)) : 5;
4201
+ const session = typeof args.session === "string" ? args.session : void 0;
4202
+ const requestedStudioId = typeof args.studio_id === "string" ? args.studio_id : void 0;
4203
+ const buildDiffScanCode = (isLive) => [
4204
+ "local HttpService = game:GetService('HttpService')",
4205
+ `local roots = ${JSON.stringify(roots)}`,
4206
+ `local scope = ${JSON.stringify(scope)}`,
4207
+ `local maxDepth = ${maxDepth}`,
4208
+ `local isLive = ${isLive ? "true" : "false"}`,
4209
+ "local entries = {}",
4210
+ "local count = 0",
4211
+ "local remoteClasses = { RemoteEvent = true, RemoteFunction = true, UnreliableRemoteEvent = true, BindableEvent = true, BindableFunction = true }",
4212
+ "local scriptClasses = { LocalScript = true, ModuleScript = true, Script = true }",
4213
+ "local function matchesScope(inst)",
4214
+ " if scope == 'remotes' then return remoteClasses[inst.ClassName] == true end",
4215
+ " if scope == 'scripts' then return scriptClasses[inst.ClassName] == true end",
4216
+ " if scope == 'gui' then return inst:IsA('GuiBase2d') or inst:IsA('LayerCollector') end",
4217
+ " return true",
4218
+ "end",
4219
+ "local function scan(inst, prefix, depth)",
4220
+ " if depth > maxDepth or count >= 1500 then return end",
4221
+ " for _, child in ipairs(inst:GetChildren()) do",
4222
+ " local p = prefix .. '.' .. child.Name",
4223
+ " if matchesScope(child) then",
4224
+ " count = count + 1",
4225
+ " entries[#entries + 1] = { path = p, className = child.ClassName }",
4226
+ " end",
4227
+ " if #child:GetChildren() > 0 then scan(child, p, depth + 1) end",
4228
+ " end",
4229
+ "end",
4230
+ "for _, rName in ipairs(roots) do",
4231
+ " local rootInst = nil",
4232
+ " if isLive and rName == 'StarterGui' then",
4233
+ " local lp = game:GetService('Players').LocalPlayer",
4234
+ " rootInst = lp and lp:FindFirstChildOfClass('PlayerGui') or game:GetService('StarterGui')",
4235
+ " else",
4236
+ " pcall(function() rootInst = game:GetService(rName) end)",
4237
+ " end",
4238
+ " if rootInst then scan(rootInst, rName, 1) end",
4239
+ "end",
4240
+ "return HttpService:JSONEncode(entries)"
4241
+ ].join("\n");
4242
+ const [liveRes, studioRes] = await Promise.all([
4243
+ this.callCloudTool("exec", {
4244
+ code: buildDiffScanCode(true),
4245
+ readonly: true,
4246
+ ...session ? { session } : {}
4247
+ }),
4248
+ this.studio.runStudioLuau(buildDiffScanCode(false), requestedStudioId)
4249
+ ]);
4250
+ if (!liveRes.ok) {
4251
+ return {
4252
+ content: [{ type: "text", text: `studio_diff failed to scan live game: ${liveRes.text}` }],
4253
+ isError: true
4254
+ };
4255
+ }
4256
+ if (!studioRes.ok) {
4257
+ return {
4258
+ content: [{ type: "text", text: `studio_diff failed to scan Roblox Studio: ${studioRes.text}` }],
4259
+ isError: true
4260
+ };
4261
+ }
4262
+ const liveEntries = this.extractJsonPayloadFromExec(liveRes.text) ?? [];
4263
+ const studioEntries = this.extractJsonPayloadFromExec(studioRes.text) ?? [];
4264
+ const liveMap = /* @__PURE__ */ new Map();
4265
+ for (const e of liveEntries) liveMap.set(e.path, e.className);
4266
+ const studioMap = /* @__PURE__ */ new Map();
4267
+ for (const e of studioEntries) studioMap.set(e.path, e.className);
4268
+ const onlyInLive = [];
4269
+ const onlyInStudio = [];
4270
+ const classMismatches = [];
4271
+ let matchedCount = 0;
4272
+ for (const [p, liveCls] of liveMap) {
4273
+ const studioCls = studioMap.get(p);
4274
+ if (!studioCls) {
4275
+ onlyInLive.push(`${p} [${liveCls}]`);
4276
+ } else if (studioCls !== liveCls) {
4277
+ classMismatches.push(`${p} (live=${liveCls}, studio=${studioCls})`);
4278
+ } else {
4279
+ matchedCount++;
4280
+ }
4281
+ }
4282
+ for (const [p, studioCls] of studioMap) {
4283
+ if (!liveMap.has(p)) {
4284
+ onlyInStudio.push(`${p} [${studioCls}]`);
4285
+ }
4286
+ }
4287
+ const lines = [
4288
+ `studio_diff report (scope=${scope}, roots=${roots.join(", ")}, studio_id=${studioRes.studioId ?? "auto"}):`,
4289
+ `- Matched instances: ${matchedCount}`,
4290
+ `- Only in Live Game: ${onlyInLive.length}`,
4291
+ ...onlyInLive.slice(0, 20).map((x) => ` + [Live] ${x}`),
4292
+ ...onlyInLive.length > 20 ? [` ... (+${onlyInLive.length - 20} more)`] : [],
4293
+ `- Only in Roblox Studio: ${onlyInStudio.length}`,
4294
+ ...onlyInStudio.slice(0, 20).map((x) => ` - [Studio] ${x}`),
4295
+ ...onlyInStudio.length > 20 ? [` ... (+${onlyInStudio.length - 20} more)`] : [],
4296
+ `- Class mismatches: ${classMismatches.length}`,
4297
+ ...classMismatches.slice(0, 10).map((x) => ` ! ${x}`)
4298
+ ];
4299
+ return {
4300
+ content: [{ type: "text", text: lines.join("\n") }]
4301
+ };
4302
+ }
4303
+ buildStudioReadScriptSourceCode(studioPath) {
4304
+ return [
4305
+ "local HttpService = game:GetService('HttpService')",
4306
+ `local pathStr = ${JSON.stringify(studioPath)}`,
4307
+ "local segs = {}",
4308
+ "for seg in string.gmatch(pathStr, '[^%.]+') do segs[#segs + 1] = seg end",
4309
+ "if #segs == 0 then error('Empty studio_path') end",
4310
+ "local startIdx = 1",
4311
+ "if segs[1] == 'game' then startIdx = 2 end",
4312
+ "local cur = game:GetService(segs[startIdx])",
4313
+ "for i = startIdx + 1, #segs do",
4314
+ " cur = cur and cur:FindFirstChild(segs[i])",
4315
+ "end",
4316
+ "if not cur then error('Studio instance not found: ' .. pathStr) end",
4317
+ "local ok, src = pcall(function() return cur.Source end)",
4318
+ "if not ok or type(src) ~= 'string' then error(pathStr .. ' (' .. cur.ClassName .. ') has no readable .Source') end",
4319
+ "return HttpService:JSONEncode({ name = cur.Name, className = cur.ClassName, path = cur:GetFullName(), source = src })"
4320
+ ].join("\n");
4321
+ }
4322
+ async handleStudioToLive(args) {
4323
+ const studioPath = typeof args.studio_path === "string" ? args.studio_path.trim() : "";
4324
+ const directCode = typeof args.code === "string" ? args.code : "";
4325
+ const requestedStudioId = typeof args.studio_id === "string" ? args.studio_id : void 0;
4326
+ const session = typeof args.session === "string" ? args.session : void 0;
4327
+ const collect = args.collect !== false;
4328
+ if (!studioPath && !directCode.trim()) {
4329
+ return {
4330
+ content: [{ type: "text", text: "studio_to_live requires either studio_path or code" }],
4331
+ isError: true
4332
+ };
4333
+ }
4334
+ let codeToRun = directCode;
4335
+ let sourceLabel = "inline Studio snippet";
4336
+ let resolvedStudioId = requestedStudioId;
4337
+ if (studioPath) {
4338
+ const studioRes = await this.studio.runStudioLuau(
4339
+ this.buildStudioReadScriptSourceCode(studioPath),
4340
+ requestedStudioId
4341
+ );
4342
+ if (!studioRes.ok) {
4343
+ return {
4344
+ content: [
4345
+ {
4346
+ type: "text",
4347
+ text: `studio_to_live failed to read ${studioPath} from Roblox Studio: ${studioRes.text}`
4348
+ }
4349
+ ],
4350
+ isError: true
4351
+ };
4352
+ }
4353
+ resolvedStudioId = studioRes.studioId;
4354
+ const parsed = this.extractJsonPayloadFromExec(studioRes.text);
4355
+ if (!parsed || typeof parsed.source !== "string") {
4356
+ return {
4357
+ content: [
4358
+ {
4359
+ type: "text",
4360
+ text: `studio_to_live could not parse script source from Studio response: ${studioRes.text}`
4361
+ }
4362
+ ],
4363
+ isError: true
4364
+ };
4365
+ }
4366
+ codeToRun = parsed.source;
4367
+ sourceLabel = `${parsed.path} [${parsed.className}] (${codeToRun.length} bytes, studio_id=${resolvedStudioId ?? "auto"})`;
4368
+ }
4369
+ const cloudTool = collect ? "run_and_collect" : "exec";
4370
+ const cloudArgs = {
4371
+ code: codeToRun,
4372
+ ...collect ? {
4373
+ wait_seconds: typeof args.wait_seconds === "number" ? args.wait_seconds : 1.5,
4374
+ clean_env: typeof args.clean_env === "boolean" ? args.clean_env : true
4375
+ } : {},
4376
+ ...session ? { session } : {}
4377
+ };
4378
+ const liveRes = await this.callCloudTool(cloudTool, cloudArgs);
4379
+ return {
4380
+ content: [
4381
+ {
4382
+ type: "text",
4383
+ text: `studio_to_live (${sourceLabel} -> ${cloudTool}):
4384
+ ${liveRes.text}`
4385
+ }
4386
+ ],
4387
+ isError: !liveRes.ok
4388
+ };
4389
+ }
4390
+ async handleStudioPublish(args) {
4391
+ const studioPath = typeof args.studio_path === "string" ? args.studio_path.trim() : "";
4392
+ if (!studioPath) {
4393
+ return {
4394
+ content: [{ type: "text", text: "studio_publish requires studio_path" }],
4395
+ isError: true
4396
+ };
4397
+ }
4398
+ const requestedStudioId = typeof args.studio_id === "string" ? args.studio_id : void 0;
4399
+ const studioRes = await this.studio.runStudioLuau(
4400
+ this.buildStudioReadScriptSourceCode(studioPath),
4401
+ requestedStudioId
4402
+ );
4403
+ if (!studioRes.ok) {
4404
+ return {
4405
+ content: [
4406
+ {
4407
+ type: "text",
4408
+ text: `studio_publish failed to read ${studioPath} from Roblox Studio: ${studioRes.text}`
4409
+ }
4410
+ ],
4411
+ isError: true
4412
+ };
4413
+ }
4414
+ const parsed = this.extractJsonPayloadFromExec(studioRes.text);
4415
+ if (!parsed || typeof parsed.source !== "string") {
4416
+ return {
4417
+ content: [
4418
+ {
4419
+ type: "text",
4420
+ text: `studio_publish could not parse script source from Studio response: ${studioRes.text}`
4421
+ }
4422
+ ],
4423
+ isError: true
4424
+ };
4425
+ }
4426
+ const scriptId = typeof args.script_id === "string" ? args.script_id.trim() : "";
4427
+ if (scriptId) {
4428
+ const deployRes = await this.callCloudTool("deploy_script", {
4429
+ script_id: scriptId,
4430
+ source: parsed.source,
4431
+ ...typeof args.note === "string" ? { note: args.note } : {}
4432
+ });
4433
+ return {
4434
+ content: [
4435
+ {
4436
+ type: "text",
4437
+ text: `studio_publish deployed ${parsed.path} (${parsed.source.length} bytes, studio_id=${studioRes.studioId ?? "auto"}) to Luaward script ${scriptId}:
4438
+ ${deployRes.text}`
4439
+ }
4440
+ ],
4441
+ isError: !deployRes.ok
4442
+ };
4443
+ }
4444
+ const scriptName = typeof args.name === "string" && args.name.trim() ? args.name.trim() : parsed.name || "StudioScript";
4445
+ const createRes = await this.callCloudTool("create_script", {
4446
+ name: scriptName,
4447
+ source: parsed.source,
4448
+ ...typeof args.description === "string" ? { description: args.description } : {}
4449
+ });
4450
+ return {
4451
+ content: [
4452
+ {
4453
+ type: "text",
4454
+ text: `studio_publish created Luaward script "${scriptName}" from ${parsed.path} (${parsed.source.length} bytes, studio_id=${studioRes.studioId ?? "auto"}):
4455
+ ${createRes.text}`
4456
+ }
4457
+ ],
4458
+ isError: !createRes.ok
4459
+ };
4460
+ }
4461
+ async handleLiveScriptsToStudio(args) {
4462
+ const filter = typeof args.filter === "string" ? args.filter.trim() : "";
4463
+ const containerName = typeof args.container_name === "string" && args.container_name.trim() ? args.container_name.trim() : "LuawardLiveScripts";
4464
+ const limit = typeof args.limit === "number" ? Math.max(1, Math.min(50, args.limit)) : 15;
4465
+ const includeDecompiled = args.include_decompiled !== false;
4466
+ const session = typeof args.session === "string" ? args.session : void 0;
4467
+ const requestedStudioId = typeof args.studio_id === "string" ? args.studio_id : void 0;
4468
+ const liveCollectCode = [
4469
+ "local HttpService = game:GetService('HttpService')",
4470
+ `local filter = string.lower(${JSON.stringify(filter)})`,
4471
+ `local limit = ${limit}`,
4472
+ `local includeDecompiled = ${includeDecompiled ? "true" : "false"}`,
4473
+ "local roots = { game:GetService('ReplicatedStorage'), game:GetService('StarterPlayer'), game:GetService('Workspace'), game:GetService('Players').LocalPlayer }",
4474
+ "local results = {}",
4475
+ "local seen = {}",
4476
+ "local decompFn = (type(decompile) == 'function' and decompile) or (type(getscriptbytecode) == 'function' and function(s) local ok, b = pcall(getscriptbytecode, s); return ok and b and ('-- bytecode (' .. tostring(#b) .. ' bytes)') or nil end) or nil",
4477
+ "for _, root in ipairs(roots) do",
4478
+ " if root then",
4479
+ " local ok, list = pcall(function() return root:GetDescendants() end)",
4480
+ " if ok and type(list) == 'table' then",
4481
+ " for _, inst in ipairs(list) do",
4482
+ " if #results >= limit then break end",
4483
+ " if not seen[inst] and (inst.ClassName == 'LocalScript' or inst.ClassName == 'ModuleScript') then",
4484
+ " seen[inst] = true",
4485
+ " local fullPath = inst:GetFullName()",
4486
+ " if filter == '' or string.find(string.lower(fullPath), filter, 1, true) then",
4487
+ " local src = '-- Live script: ' .. fullPath .. '\\n-- ClassName: ' .. inst.ClassName",
4488
+ " if includeDecompiled and decompFn then",
4489
+ " local okD, dec = pcall(decompFn, inst)",
4490
+ " if okD and type(dec) == 'string' and #dec > 0 then",
4491
+ " src = src .. '\\n\\n' .. dec:sub(1, 32000)",
4492
+ " end",
4493
+ " end",
4494
+ " results[#results + 1] = { name = inst.Name, className = inst.ClassName, path = fullPath, source = src }",
4495
+ " end",
4496
+ " end",
4497
+ " end",
4498
+ " end",
4499
+ " end",
4500
+ "end",
4501
+ "return HttpService:JSONEncode(results)"
4502
+ ].join("\n");
4503
+ const liveRes = await this.callCloudTool("exec", {
4504
+ code: liveCollectCode,
4505
+ readonly: true,
4506
+ ...session ? { session } : {}
4507
+ });
4508
+ if (!liveRes.ok) {
4509
+ return {
4510
+ content: [
4511
+ {
4512
+ type: "text",
4513
+ text: `live_scripts_to_studio failed to collect live scripts: ${liveRes.text}`
4514
+ }
4515
+ ],
4516
+ isError: true
4517
+ };
4518
+ }
4519
+ const scripts = this.extractJsonPayloadFromExec(liveRes.text) ?? [];
4520
+ const studioImportCode = [
4521
+ "local HttpService = game:GetService('HttpService')",
4522
+ "local ServerStorage = game:GetService('ServerStorage')",
4523
+ `local containerName = ${JSON.stringify(containerName)}`,
4524
+ `local items = HttpService:JSONDecode(${JSON.stringify(JSON.stringify(scripts))})`,
4525
+ "local folder = ServerStorage:FindFirstChild(containerName)",
4526
+ "if not folder then",
4527
+ " folder = Instance.new('Folder')",
4528
+ " folder.Name = containerName",
4529
+ " folder.Parent = ServerStorage",
4530
+ "end",
4531
+ "local imported = 0",
4532
+ "for _, item in ipairs(items) do",
4533
+ " local ok, inst = pcall(Instance.new, item.className)",
4534
+ " if ok and inst then",
4535
+ " inst.Name = item.name .. '_' .. tostring(imported + 1)",
4536
+ " pcall(function() inst:SetAttribute('LivePath', item.path) end)",
4537
+ " pcall(function() inst.Source = item.source end)",
4538
+ " inst.Parent = folder",
4539
+ " imported = imported + 1",
4540
+ " end",
4541
+ "end",
4542
+ "return string.format('imported %d live scripts into ServerStorage.%s', imported, containerName)"
4543
+ ].join("\n");
4544
+ const studioRes = await this.studio.runStudioLuau(studioImportCode, requestedStudioId);
4545
+ if (!studioRes.ok) {
4546
+ return {
4547
+ content: [
4548
+ {
4549
+ type: "text",
4550
+ text: `live_scripts_to_studio collected ${scripts.length} scripts from live game, but Studio import failed: ${studioRes.text}`
4551
+ }
4552
+ ],
4553
+ isError: true
4554
+ };
4555
+ }
4556
+ const listLines = scripts.slice(0, 15).map((s) => ` - [${s.className}] ${s.path} (${s.source.length} bytes)`);
4557
+ return {
4558
+ content: [
4559
+ {
4560
+ type: "text",
4561
+ text: [
4562
+ `live_scripts_to_studio complete (studio_id=${studioRes.studioId ?? "auto"}):`,
4563
+ `- Scripts collected from live game: ${scripts.length}`,
4564
+ `- Studio container: ServerStorage.${containerName}`,
4565
+ `- Studio result: ${studioRes.text}`,
4566
+ ...listLines
4567
+ ].join("\n")
4568
+ }
4569
+ ]
4570
+ };
4571
+ }
4572
+ async handleCompareScreens(args) {
4573
+ const targetA = typeof args.target_a === "string" && args.target_a.trim() ? args.target_a.trim() : "roblox";
4574
+ const targetB = typeof args.target_b === "string" && args.target_b.trim() ? args.target_b.trim() : "studio";
4575
+ const rawMethod = typeof args.method === "string" ? args.method : "auto";
4576
+ const method = rawMethod === "copy" || rawMethod === "screen" ? "copy" : rawMethod === "printwindow" || rawMethod === "print_window" ? "printwindow" : "auto";
4577
+ const includeImages = args.include_images === true;
4578
+ let base64A = typeof args.base64_a === "string" && args.base64_a.trim() ? args.base64_a.trim() : "";
4579
+ let base64B = typeof args.base64_b === "string" && args.base64_b.trim() ? args.base64_b.trim() : "";
4580
+ let labelA = base64A ? "base64_a" : targetA;
4581
+ let labelB = base64B ? "base64_b" : targetB;
4582
+ let metaA;
4583
+ let metaB;
4584
+ if (!base64A) {
4585
+ const shotA = await this.windows.captureScreenshot({ target: targetA, method, clientOnly: true });
4586
+ if (!shotA.ok || !shotA.data) {
4587
+ return {
4588
+ content: [
4589
+ {
4590
+ type: "text",
4591
+ text: `compare_screens failed to capture target_a (${targetA}): ${shotA.err ?? "unknown error"}`
4592
+ }
4593
+ ],
4594
+ isError: true
4595
+ };
4596
+ }
4597
+ base64A = shotA.data;
4598
+ metaA = { width: shotA.width, height: shotA.height };
4599
+ labelA = `${targetA} (${shotA.width}x${shotA.height}, method=${shotA.captureMethod ?? method})`;
4600
+ }
4601
+ if (!base64B) {
4602
+ const shotB = await this.windows.captureScreenshot({ target: targetB, method, clientOnly: true });
4603
+ if (!shotB.ok || !shotB.data) {
4604
+ return {
4605
+ content: [
4606
+ {
4607
+ type: "text",
4608
+ text: `compare_screens failed to capture target_b (${targetB}): ${shotB.err ?? "unknown error"}`
4609
+ }
4610
+ ],
4611
+ isError: true
4612
+ };
4613
+ }
4614
+ base64B = shotB.data;
4615
+ metaB = { width: shotB.width, height: shotB.height };
4616
+ labelB = `${targetB} (${shotB.width}x${shotB.height}, method=${shotB.captureMethod ?? method})`;
4617
+ }
4618
+ const cmp = comparePngBase64(base64A, base64B, metaA, metaB);
4619
+ const content = [
4620
+ {
4621
+ type: "text",
4622
+ text: [
4623
+ `compare_screens (${labelA} vs ${labelB}):`,
4624
+ `- Similarity: ${cmp.similarityPct}% (diff=${cmp.diffPct}%)`,
4625
+ `- Dimensions: A=${cmp.widthA ?? "?"}x${cmp.heightA ?? "?"}, B=${cmp.widthB ?? "?"}x${cmp.heightB ?? "?"} (sameDimensions=${cmp.sameDimensions})`,
4626
+ `- Changed cells (>=5% diff): ${cmp.changedCells.length > 0 ? cmp.changedCells.join(", ") : "none"}`,
4627
+ `- ${cmp.gridSummary}`
4628
+ ].join("\n")
4629
+ }
4630
+ ];
4631
+ if (includeImages) {
4632
+ content.push({ type: "image", data: base64A, mimeType: "image/png" });
4633
+ content.push({ type: "image", data: base64B, mimeType: "image/png" });
4634
+ }
4635
+ return { content };
4636
+ }
2763
4637
  async handleLocalToolCall(name, args) {
2764
4638
  try {
2765
4639
  switch (name) {
@@ -2774,6 +4648,9 @@ ${lines.join("\n")}` }]
2774
4648
  case "desktop_ui_tree":
2775
4649
  return await this.handleDesktopUiTree(args);
2776
4650
  case "desktop_mouse": {
4651
+ const shouldVerify = args.verify === true;
4652
+ const session = typeof args.session === "string" ? args.session : void 0;
4653
+ const beforeSnap = shouldVerify ? await this.captureGuiSnapshotForVerify(session) : null;
2777
4654
  const res = await this.windows.mouse({
2778
4655
  action: String(args.action ?? "click"),
2779
4656
  mode: typeof args.mode === "string" ? args.mode : void 0,
@@ -2788,7 +4665,13 @@ ${lines.join("\n")}` }]
2788
4665
  holdMs: typeof args.hold_ms === "number" ? args.hold_ms : void 0,
2789
4666
  relativeTo: typeof args.relative_to === "string" ? args.relative_to : void 0
2790
4667
  });
2791
- return { content: [{ type: "text", text: res.text }], isError: !res.ok };
4668
+ let text = res.text;
4669
+ if (shouldVerify) {
4670
+ const verifyText = await this.verifyMouseActionInGame(beforeSnap, session);
4671
+ text = `${text}
4672
+ ${verifyText}`;
4673
+ }
4674
+ return { content: [{ type: "text", text }], isError: !res.ok };
2792
4675
  }
2793
4676
  case "desktop_keyboard": {
2794
4677
  const res = await this.windows.keyboard({
@@ -2803,6 +4686,20 @@ ${lines.join("\n")}` }]
2803
4686
  }
2804
4687
  case "os_click":
2805
4688
  return await this.handleOsClick(args);
4689
+ case "studio_mirror_remotes":
4690
+ return await this.handleStudioMirrorRemotes(args);
4691
+ case "studio_mirror_gui":
4692
+ return await this.handleStudioMirrorGui(args);
4693
+ case "studio_diff":
4694
+ return await this.handleStudioDiff(args);
4695
+ case "studio_to_live":
4696
+ return await this.handleStudioToLive(args);
4697
+ case "studio_publish":
4698
+ return await this.handleStudioPublish(args);
4699
+ case "live_scripts_to_studio":
4700
+ return await this.handleLiveScriptsToStudio(args);
4701
+ case "compare_screens":
4702
+ return await this.handleCompareScreens(args);
2806
4703
  default:
2807
4704
  return null;
2808
4705
  }
@@ -2902,9 +4799,20 @@ ${lines.join("\n")}` }]
2902
4799
  });
2903
4800
  }
2904
4801
  if (!res.body) return null;
4802
+ if (msg?.method === "initialize" && res.body.result && typeof res.body.result === "object") {
4803
+ const scopeRes = await this.checkTokenScopes();
4804
+ if (scopeRes.warning) {
4805
+ const initResult = res.body.result;
4806
+ const prevInstructions = typeof initResult.instructions === "string" ? initResult.instructions.trim() : "";
4807
+ initResult.instructions = prevInstructions ? `${prevInstructions}
4808
+
4809
+ ${scopeRes.warning}` : scopeRes.warning;
4810
+ }
4811
+ }
2905
4812
  if (msg?.method === "tools/list" && res.body.result && typeof res.body.result === "object") {
2906
4813
  const resultObj = res.body.result;
2907
4814
  if (Array.isArray(resultObj.tools)) {
4815
+ this.evaluateTokenScopesFromTools(resultObj.tools);
2908
4816
  const existingNames = new Set(resultObj.tools.map((t) => String(t.name ?? "")));
2909
4817
  for (const tool of resultObj.tools) {
2910
4818
  const tName = String(tool.name ?? "");
@@ -2976,7 +4884,7 @@ function startStdioBridge(options = {}) {
2976
4884
  const stdin = options.stdin ?? process.stdin;
2977
4885
  const stdout = options.stdout ?? process.stdout;
2978
4886
  const bridge = new HybridMcpBridge(options);
2979
- const rl = createInterface2({ input: stdin, crlfDelay: Number.POSITIVE_INFINITY });
4887
+ const rl = createInterface3({ input: stdin, crlfDelay: Number.POSITIVE_INFINITY });
2980
4888
  const pending = /* @__PURE__ */ new Set();
2981
4889
  rl.on("line", (line) => {
2982
4890
  const task = (async () => {
@@ -2993,6 +4901,7 @@ function startStdioBridge(options = {}) {
2993
4901
  rl.on("close", async () => {
2994
4902
  await Promise.allSettled([...pending]);
2995
4903
  bridge.windows.dispose?.();
4904
+ bridge.studio.dispose?.();
2996
4905
  resolveDone();
2997
4906
  });
2998
4907
  });