@chrrxs/robloxstudio-mcp-inspector 2.8.0

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

@@ -0,0 +1,318 @@
+const ScriptEditorService = game.GetService("ScriptEditorService");
+
+function safeCall<T>(func: (...args: never[]) => T, ...args: never[]): T | undefined {
+	const [success, result] = pcall(func, ...args);
+	if (success) {
+		return result;
+	} else {
+		warn(`MCP Plugin Error: ${result}`);
+		return undefined;
+	}
+}
+
+function getInstancePath(instance: Instance): string {
+	if (!instance || instance === game) {
+		return "game";
+	}
+
+	const pathParts: string[] = [];
+	let current: Instance | undefined = instance;
+
+	while (current && current !== game) {
+		pathParts.unshift(current.Name);
+		current = current.Parent as Instance | undefined;
+	}
+
+	return `game.${pathParts.join(".")}`;
+}
+
+function getInstanceByPath(path: string): Instance | undefined {
+	if (path === "game" || path === "") {
+		return game;
+	}
+
+	const cleaned = path.gsub("^game%.", "")[0];
+	const parts: string[] = [];
+	for (const [part] of cleaned.gmatch("[^%.]+")) {
+		parts.push(part as string);
+	}
+
+	let current: Instance | undefined = game;
+	for (const part of parts) {
+		if (!current) return undefined;
+		current = current.FindFirstChild(part);
+	}
+
+	return current;
+}
+
+function splitLines(source: string): LuaTuple<[string[], boolean]> {
+	const normalized = ((source ?? "") as string).gsub("\r\n", "\n")[0].gsub("\r", "\n")[0];
+	const endsWithNewline = normalized.sub(-1) === "\n";
+
+	const lines: string[] = [];
+	let start = 1;
+
+	while (true) {
+		const [newlinePos] = string.find(normalized, "\n", start, true);
+		if (newlinePos !== undefined) {
+			lines.push(string.sub(normalized, start, newlinePos - 1));
+			start = newlinePos + 1;
+		} else {
+			const remainder = string.sub(normalized, start);
+			if (remainder !== "" || !endsWithNewline) {
+				lines.push(remainder);
+			}
+			break;
+		}
+	}
+
+	if (lines.size() === 0) {
+		lines.push("");
+	}
+
+	return [lines, endsWithNewline] as unknown as LuaTuple<[string[], boolean]>;
+}
+
+function joinLines(lines: string[], hadTrailingNewline: boolean): string {
+	let source = lines.join("\n");
+	if (hadTrailingNewline && source.sub(-1) !== "\n") {
+		source += "\n";
+	}
+	return source;
+}
+
+function readScriptSource(instance: LuaSourceContainer): string {
+	const [ok, result] = pcall(() => {
+		const doc = ScriptEditorService.FindScriptDocument(instance);
+		if (doc) {
+			return doc.GetText();
+		}
+		return undefined;
+	});
+	if (ok && result) {
+		return result;
+	}
+	return (instance as unknown as { Source: string }).Source;
+}
+
+function convertPropertyValue(instance: Instance, propertyName: string, propertyValue: unknown): unknown {
+	if (propertyValue === undefined) return undefined;
+
+	const inst = instance as unknown as Record<string, unknown>;
+
+	if (typeIs(propertyValue, "table")) {
+		const arr = propertyValue as unknown[];
+		const tbl = propertyValue as Record<string, unknown>;
+
+		if (typeIs(arr, "table") && (arr as defined[]).size() > 0) {
+			const len = (arr as defined[]).size();
+
+			if (len === 3) {
+				const prop = propertyName.lower();
+				if (
+					prop === "position" || prop === "size" || prop === "orientation" ||
+					prop === "velocity" || prop === "angularvelocity"
+				) {
+					return new Vector3(
+						(arr[0] as number) ?? 0,
+						(arr[1] as number) ?? 0,
+						(arr[2] as number) ?? 0,
+					);
+				} else if (prop === "color" || prop === "color3") {
+					return new Color3(
+						(arr[0] as number) ?? 0,
+						(arr[1] as number) ?? 0,
+						(arr[2] as number) ?? 0,
+					);
+				} else {
+					const [success, currentVal] = pcall(() => inst[propertyName]);
+					if (success) {
+						if (typeOf(currentVal) === "Vector3") {
+							return new Vector3(
+								(arr[0] as number) ?? 0,
+								(arr[1] as number) ?? 0,
+								(arr[2] as number) ?? 0,
+							);
+						} else if (typeOf(currentVal) === "Color3") {
+							return new Color3(
+								(arr[0] as number) ?? 0,
+								(arr[1] as number) ?? 0,
+								(arr[2] as number) ?? 0,
+							);
+						}
+					}
+				}
+			} else if (len === 2) {
+				const [success, currentVal] = pcall(() => inst[propertyName]);
+				if (success && typeOf(currentVal) === "Vector2") {
+					return new Vector2((arr[0] as number) ?? 0, (arr[1] as number) ?? 0);
+				}
+			} else if (len === 4) {
+				const [success, currentVal] = pcall(() => inst[propertyName]);
+				if (success && typeOf(currentVal) === "UDim2") {
+					return new UDim2(
+						(arr[0] as number) ?? 0,
+						(arr[1] as number) ?? 0,
+						(arr[2] as number) ?? 0,
+						(arr[3] as number) ?? 0,
+					);
+				}
+			}
+		}
+
+		if (tbl.X !== undefined || tbl.Y !== undefined || tbl.Z !== undefined) {
+
+			if (typeIs(tbl.X, "table") && typeIs(tbl.Y, "table")) {
+				const xTbl = tbl.X as unknown as Record<string, number>;
+				const yTbl = tbl.Y as unknown as Record<string, number>;
+				return new UDim2(
+					xTbl.Scale ?? 0, xTbl.Offset ?? 0,
+					yTbl.Scale ?? 0, yTbl.Offset ?? 0,
+				);
+			}
+			return new Vector3(
+				(tbl.X as number) ?? 0,
+				(tbl.Y as number) ?? 0,
+				(tbl.Z as number) ?? 0,
+			);
+		}
+
+		if (tbl.R !== undefined || tbl.G !== undefined || tbl.B !== undefined) {
+			return new Color3(
+				(tbl.R as number) ?? 0,
+				(tbl.G as number) ?? 0,
+				(tbl.B as number) ?? 0,
+			);
+		}
+	}
+
+	if (typeIs(propertyValue, "string")) {
+		const [success, currentVal] = pcall(() => inst[propertyName]);
+		if (success && typeOf(currentVal) === "EnumItem") {
+			const enumItem = currentVal as EnumItem;
+			const enumTypeName = tostring(enumItem.EnumType);
+			const [enumSuccess, enumVal] = pcall(() => {
+				return (Enum as unknown as Record<string, Record<string, EnumItem>>)[enumTypeName][propertyValue];
+			});
+			if (enumSuccess && enumVal) return enumVal;
+		}
+		if (propertyName === "BrickColor") {
+			return new BrickColor(propertyValue as unknown as number);
+		}
+		if (propertyValue === "true") return true;
+		if (propertyValue === "false") return false;
+	}
+
+	return propertyValue;
+}
+
+function evaluateFormula(
+	formula: string,
+	variables: Record<string, unknown> | undefined,
+	instance: Instance | undefined,
+	index: number,
+): LuaTuple<[number, string | undefined]> {
+	let value = formula;
+
+	value = value.gsub("index", tostring(index))[0];
+
+	if (instance && instance.IsA("BasePart")) {
+		const pos = instance.Position;
+		const sz = instance.Size;
+		value = value.gsub("Position%.X", tostring(pos.X))[0];
+		value = value.gsub("Position%.Y", tostring(pos.Y))[0];
+		value = value.gsub("Position%.Z", tostring(pos.Z))[0];
+		value = value.gsub("Size%.X", tostring(sz.X))[0];
+		value = value.gsub("Size%.Y", tostring(sz.Y))[0];
+		value = value.gsub("Size%.Z", tostring(sz.Z))[0];
+		value = value.gsub("magnitude", tostring(pos.Magnitude))[0];
+	}
+
+	if (variables) {
+		for (const [k, v] of pairs(variables)) {
+			value = value.gsub(k as string, tostring(v))[0];
+		}
+	}
+
+	value = value.gsub("sin%(([%d%.%-]+)%)", (x: string) => tostring(math.sin(tonumber(x) ?? 0)))[0];
+	value = value.gsub("cos%(([%d%.%-]+)%)", (x: string) => tostring(math.cos(tonumber(x) ?? 0)))[0];
+	value = value.gsub("sqrt%(([%d%.%-]+)%)", (x: string) => tostring(math.sqrt(tonumber(x) ?? 0)))[0];
+	value = value.gsub("abs%(([%d%.%-]+)%)", (x: string) => tostring(math.abs(tonumber(x) ?? 0)))[0];
+	value = value.gsub("floor%(([%d%.%-]+)%)", (x: string) => tostring(math.floor(tonumber(x) ?? 0)))[0];
+	value = value.gsub("ceil%(([%d%.%-]+)%)", (x: string) => tostring(math.ceil(tonumber(x) ?? 0)))[0];
+
+	const directResult = tonumber(value);
+	if (directResult !== undefined) {
+		return [directResult, undefined] as unknown as LuaTuple<[number, string | undefined]>;
+	}
+
+	const [success, evalResult] = pcall(() => {
+		const num = tonumber(value);
+		if (num !== undefined) return num;
+
+		{
+			const [a, b] = value.match("^([%d%.%-]+)%s*%*%s*([%d%.%-]+)$") as LuaTuple<[string?, string?]>;
+			if (a && b) return (tonumber(a) ?? 0) * (tonumber(b) ?? 0);
+		}
+
+		{
+			const [a, b] = value.match("^([%d%.%-]+)%s*%+%s*([%d%.%-]+)$") as LuaTuple<[string?, string?]>;
+			if (a && b) return (tonumber(a) ?? 0) + (tonumber(b) ?? 0);
+		}
+
+		{
+			const [a, b] = value.match("^([%d%.%-]+)%s*%-%s*([%d%.%-]+)$") as LuaTuple<[string?, string?]>;
+			if (a && b) return (tonumber(a) ?? 0) - (tonumber(b) ?? 0);
+		}
+
+		{
+			const [a, b] = value.match("^([%d%.%-]+)%s*/%s*([%d%.%-]+)$") as LuaTuple<[string?, string?]>;
+			if (a && b) {
+				const divisor = tonumber(b) ?? 1;
+				if (divisor !== 0) return (tonumber(a) ?? 0) / divisor;
+			}
+		}
+
+		error(`Unsupported formula pattern: ${value}`);
+	});
+
+	if (success && typeIs(evalResult, "number")) {
+		return [evalResult, undefined] as unknown as LuaTuple<[number, string | undefined]>;
+	} else {
+		return [index, "Complex formulas not supported - using index value"] as unknown as LuaTuple<[number, string | undefined]>;
+	}
+}
+
+function compareVersions(v1: string, v2: string): number {
+	function parseVersion(v: string): number[] {
+		const parts: number[] = [];
+		for (const [num] of string.gmatch(v, "%d+")) {
+			parts.push(tonumber(num) ?? 0);
+		}
+		return parts;
+	}
+
+	const p1 = parseVersion(v1);
+	const p2 = parseVersion(v2);
+	const maxLen = math.max(p1.size(), p2.size());
+	for (let i = 0; i < maxLen; i++) {
+		const n1 = p1[i] ?? 0;
+		const n2 = p2[i] ?? 0;
+		if (n1 < n2) return -1;
+		if (n1 > n2) return 1;
+	}
+	return 0;
+}
+
+export = {
+	safeCall,
+	getInstancePath,
+	getInstanceByPath,
+	splitLines,
+	joinLines,
+	readScriptSource,
+	convertPropertyValue,
+	evaluateFormula,
+	compareVersions,
+};

package/studio-plugin/src/modules/handlers/AssetHandlers.ts

@@ -0,0 +1,241 @@
+import Utils from "../Utils";
+import Recording from "../Recording";
+
+const AssetService = game.GetService("AssetService");
+const ChangeHistoryService = game.GetService("ChangeHistoryService");
+const Selection = game.GetService("Selection");
+
+const { getInstancePath, getInstanceByPath } = Utils;
+const { beginRecording, finishRecording } = Recording;
+
+function insertAsset(requestData: Record<string, unknown>) {
+	const assetId = requestData.assetId as number;
+	const parentPath = (requestData.parentPath as string) ?? "game.Workspace";
+	const position = requestData.position as { x: number; y: number; z: number } | undefined;
+
+	if (!assetId) {
+		return { error: "assetId is required" };
+	}
+
+	const parentInstance = getInstanceByPath(parentPath);
+	if (!parentInstance) {
+		return { error: `Parent instance not found: ${parentPath}` };
+	}
+
+	const recordingId = beginRecording(`Insert asset ${assetId}`);
+
+	let wrapperModel: Instance | undefined;
+	const [insertSuccess, insertResult] = pcall(() => {
+		const loadedWrapper = (AssetService as unknown as { LoadAssetAsync(id: number): Instance }).LoadAssetAsync(assetId);
+		wrapperModel = loadedWrapper;
+
+		const insertedInstances: Instance[] = [];
+		const children = loadedWrapper.GetChildren();
+
+		for (const child of children) {
+			child.Parent = parentInstance;
+			insertedInstances.push(child);
+		}
+
+		if (position) {
+			const pos = new Vector3(position.x ?? 0, position.y ?? 0, position.z ?? 0);
+			for (const inst of insertedInstances) {
+				if (inst.IsA("BasePart")) {
+					inst.Position = pos;
+				} else if (inst.IsA("Model")) {
+					if (inst.PrimaryPart) {
+						inst.PivotTo(new CFrame(pos));
+					} else {
+						const firstPart = inst.FindFirstChildWhichIsA("BasePart", true);
+						if (firstPart) {
+							inst.PivotTo(new CFrame(pos));
+						}
+					}
+				}
+			}
+		}
+
+		pcall(() => {
+			Selection.Set(insertedInstances);
+		});
+
+		const resultInstances = insertedInstances.map((inst) => ({
+			name: inst.Name,
+			className: inst.ClassName,
+			path: getInstancePath(inst),
+		}));
+
+		return {
+			success: true,
+			assetId,
+			parentPath,
+			insertedCount: insertedInstances.size(),
+			instances: resultInstances,
+		};
+	});
+
+	if (wrapperModel) {
+		pcall(() => {
+			wrapperModel!.Destroy();
+		});
+	}
+
+	finishRecording(recordingId, insertSuccess);
+
+	if (!insertSuccess) {
+		return { error: `Failed to insert asset ${assetId}: ${tostring(insertResult)}` };
+	}
+
+	return insertResult;
+}
+
+function previewAsset(requestData: Record<string, unknown>) {
+	const assetId = requestData.assetId as number;
+	const includeProperties = (requestData.includeProperties as boolean) ?? true;
+	const maxDepth = (requestData.maxDepth as number) ?? 10;
+
+	if (!assetId) {
+		return { error: "assetId is required" };
+	}
+
+	const [loadSuccess, wrapperModel] = pcall(() => {
+		return (AssetService as unknown as { LoadAssetAsync(id: number): Instance }).LoadAssetAsync(assetId);
+	});
+
+	if (!loadSuccess || !wrapperModel) {
+		return { error: `Failed to load asset ${assetId}: ${tostring(wrapperModel)}` };
+	}
+
+	// Stats tracking
+	let totalInstances = 0;
+	const classCounts: Record<string, number> = {};
+	let hasScripts = false;
+	let hasAnimations = false;
+	let hasSounds = false;
+	let hasParticles = false;
+
+	function buildHierarchy(instance: Instance, depth: number): Record<string, unknown> {
+		totalInstances++;
+
+		const className = instance.ClassName;
+		classCounts[className] = (classCounts[className] ?? 0) + 1;
+
+		if (instance.IsA("LuaSourceContainer")) hasScripts = true;
+		if (className === "Animation" || className === "AnimationController" || className === "Animator") hasAnimations = true;
+		if (instance.IsA("Sound")) hasSounds = true;
+		if (className === "ParticleEmitter" || className === "Fire" || className === "Smoke" || className === "Sparkles") hasParticles = true;
+
+		const node: Record<string, unknown> = {
+			name: instance.Name,
+			className,
+		};
+
+		if (includeProperties) {
+			const props: Record<string, unknown> = {};
+
+			if (instance.IsA("BasePart")) {
+				props.size = { x: instance.Size.X, y: instance.Size.Y, z: instance.Size.Z };
+				props.position = { x: instance.Position.X, y: instance.Position.Y, z: instance.Position.Z };
+				props.material = tostring(instance.Material);
+				props.color = `${instance.Color.R}, ${instance.Color.G}, ${instance.Color.B}`;
+				props.transparency = instance.Transparency;
+				props.anchored = instance.Anchored;
+			}
+
+			if (instance.IsA("MeshPart")) {
+				const meshPart = instance as MeshPart;
+				props.meshId = meshPart.MeshId;
+				props.textureId = meshPart.TextureID;
+			}
+
+			if (instance.IsA("Model")) {
+				const model = instance as Model;
+				if (model.PrimaryPart) {
+					props.primaryPart = model.PrimaryPart.Name;
+				}
+			}
+
+			if (instance.IsA("LuaSourceContainer")) {
+				const [ok, src] = pcall(() => (instance as unknown as { Source: string }).Source);
+				if (ok && src) {
+					const preview = string.sub(src, 1, 200);
+					props.sourcePreview = preview;
+					props.sourceLength = src.size();
+				}
+			}
+
+			if (className === "Decal" || className === "Texture") {
+				const [ok, texId] = pcall(() => (instance as unknown as { Texture: string }).Texture);
+				if (ok) props.texture = texId;
+			}
+
+			if (instance.IsA("Sound")) {
+				props.soundId = (instance as Sound).SoundId;
+			}
+
+			// Only include props if there are any
+			let hasProps = false;
+			for (const _ of pairs(props)) {
+				hasProps = true;
+				break;
+			}
+			if (hasProps) {
+				node.properties = props;
+			}
+		}
+
+		if (depth < maxDepth) {
+			const childNodes: Record<string, unknown>[] = [];
+			for (const child of instance.GetChildren()) {
+				childNodes.push(buildHierarchy(child, depth + 1));
+			}
+			if (childNodes.size() > 0) {
+				node.children = childNodes;
+			}
+		} else {
+			const childCount = instance.GetChildren().size();
+			if (childCount > 0) {
+				node.childCount = childCount;
+				node.truncated = true;
+			}
+		}
+
+		return node;
+	}
+
+	const [previewSuccess, previewResult] = pcall(() => {
+		const hierarchyRoots: Record<string, unknown>[] = [];
+		for (const child of (wrapperModel as Instance).GetChildren()) {
+			hierarchyRoots.push(buildHierarchy(child, 0));
+		}
+
+		return {
+			success: true,
+			assetId,
+			hierarchy: hierarchyRoots,
+			summary: {
+				totalInstances,
+				classCounts,
+				hasScripts,
+				hasAnimations,
+				hasSounds,
+				hasParticles,
+			},
+		};
+	});
+
+	pcall(() => {
+		(wrapperModel as Instance).Destroy();
+	});
+
+	if (!previewSuccess) {
+		return { error: `Failed to preview asset ${assetId}: ${tostring(previewResult)}` };
+	}
+
+	return previewResult;
+}
+
+export = {
+	insertAsset,
+	previewAsset,
+};