@openfairygui/mcp 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "FairyGUI Headless Authoring SDK - MCP server adapter for the backend runtime.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -13,6 +13,9 @@
   "bugs": {
     "url": "https://github.com/OpenFairyGUI/OpenFairyGUI/issues"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.cjs",
@@ -58,13 +61,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6",
-    "@openfairygui/backend": "0.3.0"
+    "@openfairygui/backend": "0.3.1"
   },
   "devDependencies": {
     "ava": "^7.0.0",
     "tsx": "^4.0.0",
-    "@openfairygui/test-utils": "0.2.0-alpha.10",
-    "@openfairygui/core": "0.3.0"
+    "@openfairygui/core": "0.3.1",
+    "@openfairygui/test-utils": "0.3.0"
   },
   "ava": {
     "extensions": {

package/src/server.ts

@@ -35,12 +35,16 @@ const PACKAGE_VERSION = readPackageVersion();
 
 export interface CreateOpenFairyGuiMcpServerOptions {
 	runtime?: OpenFairyGuiBackendRuntime;
+	/** Filesystem roots exposed by the default Node backend runtime. Defaults to process.cwd(). */
+	allowedProjectRoots?: readonly string[];
 	name?: string;
 	version?: string;
 }
 
 export function createOpenFairyGuiMcpServer(options: CreateOpenFairyGuiMcpServerOptions = {}): McpServer {
-	const runtime = options.runtime ?? createNodeBackendRuntime();
+	const runtime = options.runtime ?? createNodeBackendRuntime({
+		allowedProjectRoots: options.allowedProjectRoots ?? [process.cwd()],
+	});
 	const server = new McpServer({
 		name: options.name ?? 'openfairygui-mcp',
 		version: options.version ?? PACKAGE_VERSION,

package/src/stdio.ts

@@ -1,9 +1,14 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createOpenFairyGuiMcpServer } from './server.js';
 
 export async function connectOpenFairyGuiMcpStdio(): Promise<void> {
-	const server = createOpenFairyGuiMcpServer();
+	const configuredRoots = process.env.OPENFAIRYGUI_ALLOWED_PROJECT_ROOTS
+		?.split(path.delimiter)
+		.map((value) => value.trim())
+		.filter(Boolean);
+	const server = createOpenFairyGuiMcpServer({ allowedProjectRoots: configuredRoots });
 	await server.connect(new StdioServerTransport());
 }
 

package/src/tool-definitions.ts

@@ -60,14 +60,109 @@ const sessionId = z.string().min(1);
 const jobId = z.string().min(1);
 const expectedRevision = z.number().int().nonnegative();
 const limit = z.number().int().nonnegative().optional();
+const identifier = z.string().min(1).max(256);
+export function isOpenFairyGuiMcpPayloadWithinBudget(root: unknown): boolean {
+	const pending: Array<{ value: unknown; depth: number }> = [{ value: root, depth: 0 }];
+	let nodes = 0;
+	while (pending.length > 0) {
+		const { value, depth } = pending.pop()!;
+		nodes += 1;
+		if (nodes > 100_000 || depth > 32) return false;
+		if (value === null || typeof value === 'boolean') continue;
+		if (typeof value === 'number') {
+			if (!Number.isFinite(value)) return false;
+			continue;
+		}
+		if (typeof value === 'string') {
+			if (value.length > 1_000_000) return false;
+			continue;
+		}
+		if (value instanceof Uint8Array) {
+			if (value.byteLength > 8 * 1024 * 1024) return false;
+			continue;
+		}
+		if (Array.isArray(value)) {
+			if (value.length > 10_000) return false;
+			for (const child of value) pending.push({ value: child, depth: depth + 1 });
+			continue;
+		}
+		if (typeof value !== 'object') return false;
+		const entries = Object.entries(value);
+		if (entries.length > 10_000 || entries.some(([key]) => key.length > 256)) return false;
+		for (const [, child] of entries) pending.push({ value: child, depth: depth + 1 });
+	}
+	return true;
+}
+const boundedPayload = z.json();
+const bytes = z.array(z.number().int().min(0).max(255)).max(8 * 1024 * 1024);
+const packageSelector = z.object({ packageId: identifier });
+const resourceSelector = z.object({ packageId: identifier, resourceId: identifier });
+const componentSelector = z.object({ packageId: identifier, componentResourceId: identifier });
+const displayNodeSelector = componentSelector.extend({ displayNodeId: identifier });
+const controllerSelector = componentSelector.extend({ controllerName: identifier });
+const transitionSelector = componentSelector.extend({ transitionName: identifier });
+const folderSelector = packageSelector.extend({ branch: z.string().max(256).optional(), path: z.string().min(1).max(4096) });
+const operationBase = { opId: identifier.optional() };
+const operation = z.discriminatedUnion('kind', [
+	z.object({ ...operationBase, kind: z.literal('updateProjectSettings'), settings: boundedPayload }),
+	z.object({ ...operationBase, kind: z.literal('updatePackageSettings'), selector: packageSelector, settings: boundedPayload }),
+	z.object({ ...operationBase, kind: z.literal('renameResource'), selector: resourceSelector, newName: identifier }),
+	z.object({ ...operationBase, kind: z.literal('moveResource'), selector: resourceSelector, toPath: z.string().max(4096) }),
+	z.object({ ...operationBase, kind: z.literal('setResourceFavorite'), selector: resourceSelector, favorite: z.boolean() }),
+	z.object({ ...operationBase, kind: z.literal('setResourceFolderFavorite'), selector: folderSelector, favorite: z.boolean() }),
+	z.object({ ...operationBase, kind: z.literal('setResourceFolderAtlas'), selector: folderSelector, atlas: z.string().max(32) }),
+	z.object({ ...operationBase, kind: z.literal('setResourceExported'), selector: resourceSelector, exported: z.boolean() }),
+	z.object({ ...operationBase, kind: z.literal('addResourceFolder'), selector: packageSelector, path: z.string().max(4096), branch: z.string().max(256).optional(), favorite: z.boolean().optional(), atlas: z.string().max(32).optional() }),
+	z.object({ ...operationBase, kind: z.literal('renameResourceFolder'), selector: folderSelector, newName: identifier }),
+	z.object({ ...operationBase, kind: z.literal('moveResourceFolder'), selector: folderSelector, toPath: z.string().max(4096) }),
+	z.object({ ...operationBase, kind: z.literal('removeResourceFolder'), selector: folderSelector }),
+	z.object({ ...operationBase, kind: z.literal('setImageResourceProps'), selector: resourceSelector, props: boundedPayload }),
+	z.object({ ...operationBase, kind: z.literal('addResource'), selector: packageSelector, resource: boundedPayload, atIndex: z.number().int().nonnegative().optional() }),
+	z.object({ ...operationBase, kind: z.literal('addBranch'), branch: identifier }),
+	z.object({ ...operationBase, kind: z.literal('renameBranch'), selector: z.object({ branch: identifier }), newName: identifier }),
+	z.object({ ...operationBase, kind: z.literal('removeBranch'), selector: z.object({ branch: identifier }) }),
+	z.object({ ...operationBase, kind: z.literal('addPackage'), package: boundedPayload, atIndex: z.number().int().nonnegative() }),
+	z.object({ ...operationBase, kind: z.literal('renamePackage'), selector: packageSelector, newName: identifier }),
+	z.object({ ...operationBase, kind: z.literal('removePackage'), selector: packageSelector }),
+	z.object({ ...operationBase, kind: z.literal('addComponent'), selector: packageSelector, component: boundedPayload, atIndex: z.number().int().nonnegative() }),
+	z.object({ ...operationBase, kind: z.literal('removeComponent'), selector: componentSelector }),
+	z.object({ ...operationBase, kind: z.literal('moveComponent'), selector: componentSelector, toPackageId: identifier, toIndex: z.number().int().nonnegative() }),
+	z.object({ ...operationBase, kind: z.literal('replaceResourceBytes'), selector: resourceSelector, sourceBytes: bytes }),
+	z.object({ ...operationBase, kind: z.literal('removeResource'), selector: resourceSelector }),
+	z.object({ ...operationBase, kind: z.literal('setDisplayNodeProps'), selector: displayNodeSelector, props: boundedPayload }),
+	z.object({ ...operationBase, kind: z.literal('setComponentProps'), selector: componentSelector, props: boundedPayload }),
+	z.object({ ...operationBase, kind: z.literal('attachDisplayNode'), selector: componentSelector, atIndex: z.number().int().nonnegative(), node: boundedPayload }),
+	z.object({ ...operationBase, kind: z.literal('detachDisplayNode'), selector: displayNodeSelector }),
+	...(['addController', 'updateController'] as const).map((kind) => z.object({ ...operationBase, kind: z.literal(kind), selector: controllerSelector, controller: boundedPayload })),
+	z.object({ ...operationBase, kind: z.literal('removeController'), selector: controllerSelector }),
+	...(['addTransition', 'updateTransition'] as const).map((kind) => z.object({ ...operationBase, kind: z.literal(kind), selector: transitionSelector, transition: boundedPayload })),
+	z.object({ ...operationBase, kind: z.literal('removeTransition'), selector: transitionSelector }),
+	...(['addLookGear', 'updateLookGear', 'addGear', 'updateGear'] as const).map((kind) => z.object({ ...operationBase, kind: z.literal(kind), selector: displayNodeSelector.extend({ kind: identifier, controllerName: identifier }), gear: boundedPayload })),
+	...(['removeLookGear', 'removeGear'] as const).map((kind) => z.object({ ...operationBase, kind: z.literal(kind), selector: displayNodeSelector.extend({ kind: identifier, controllerName: identifier }) })),
+]);
+const project = z.object({
+	projectId: identifier,
+	projectType: z.number().int(),
+	version: z.string().max(256),
+	branches: z.array(z.string().max(256)).max(256),
+	settings: boundedPayload,
+	packages: z.array(z.object({
+		id: identifier,
+		name: identifier,
+		compressPNG: z.boolean().nullable(),
+		jpegQuality: z.number().finite().nullable(),
+		publish: boundedPayload.nullable(),
+		branchNames: z.array(z.string().max(256)).max(256),
+		folders: z.array(boundedPayload).max(10_000),
+		resources: z.array(boundedPayload).max(100_000),
+	})).max(1_000),
+});
 
 export const OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA = z.object({
-	backendResult: z.object({
-		ok: z.boolean(),
-		data: z.unknown().optional(),
-		error: z.unknown().optional(),
-		meta: z.unknown().optional(),
-	}).passthrough(),
+	backendResult: z.discriminatedUnion('ok', [
+		z.object({ ok: z.literal(true), data: boundedPayload, meta: boundedPayload }),
+		z.object({ ok: z.literal(false), error: z.object({ code: identifier, message: z.string().max(1_000_000) }).passthrough(), meta: boundedPayload, session: boundedPayload.optional() }),
+	]),
 });
 
 export const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
@@ -97,7 +192,7 @@ export const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		title: 'Open Project Session',
 		description: 'Open a browser-safe backend session from an already loaded UAM project without filesystem access.',
 		inputSchema: z.object({
-			project: z.unknown(),
+			project,
 			sessionId: z.string().min(1).optional(),
 			canonicalProjectPath: z.string().min(1).optional(),
 			canonicalPathKey: z.string().min(1).optional(),
@@ -136,11 +231,11 @@ export const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		name: 'openfairygui_backend_apply_transaction',
 		backendMethod: 'applyTransaction',
 		title: 'Apply UAM Transaction',
-		description: 'Apply a backend revision-checked UAM operation batch without redefining selector or operation grammar.',
+		description: 'Apply a bounded, revision-checked UAM operation batch using the Core transaction discriminants.',
 		inputSchema: z.object({
 			sessionId,
 			expectedRevision,
-			operations: z.array(z.unknown()),
+			operations: z.array(operation).min(1).max(1_000),
 		}),
 		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
@@ -149,7 +244,7 @@ export const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		name: 'openfairygui_backend_save_session',
 		backendMethod: 'saveSession',
 		title: 'Save Backend Session',
-		description: 'Write the current backend session back through the backend coordinated non-atomic save path.',
+		description: 'Write the current backend session through its coordinated save path; Node uses an atomic staged directory swap.',
 		inputSchema: z.object({
 			sessionId,
 			expectedRevision: expectedRevision.optional(),

package/src/tool-handler.ts

@@ -1,6 +1,13 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import type { BackendRuntime } from '@openfairygui/backend';
-import type { OpenFairyGuiBackendToolName } from './tool-definitions.js';
+import {
+	BACKEND_CAPABILITY_SCHEMA_VERSION,
+	BACKEND_CONTRACT_VERSION,
+	type BackendRuntime,
+} from '@openfairygui/backend';
+import {
+	isOpenFairyGuiMcpPayloadWithinBudget,
+	type OpenFairyGuiBackendToolName,
+} from './tool-definitions.js';
 
 export type OpenFairyGuiBackendRuntime = Pick<
 	BackendRuntime,
@@ -23,15 +30,17 @@ export type OpenFairyGuiBackendRuntime = Pick<
 >;
 
 function jsonResult(payload: unknown, isError = false): CallToolResult {
+	const text = JSON.stringify(payload, null, 2);
+	const wirePayload = JSON.parse(text) as unknown;
 	return {
 		content: [
 			{
 				type: 'text',
-				text: JSON.stringify(payload, null, 2),
+				text,
 			},
 		],
 		structuredContent: {
-			backendResult: payload,
+			backendResult: wirePayload,
 		},
 		isError,
 	};
@@ -44,13 +53,37 @@ function isBackendFailure(value: unknown): boolean {
 		&& (value as { ok?: unknown }).ok === false;
 }
 
+function unhandledBackendFailure(startedAt: number): unknown {
+	return {
+		ok: false,
+		meta: {
+			requestId: crypto.randomUUID(),
+			durationMs: Math.max(0, Date.now() - startedAt),
+			warnings: [],
+			diagnostics: [],
+			stage: 'runtime',
+			contractVersion: BACKEND_CONTRACT_VERSION,
+			capabilitySchemaVersion: BACKEND_CAPABILITY_SCHEMA_VERSION,
+		},
+		error: {
+			code: 'backend_unhandled_error',
+			message: 'Backend tool execution failed.',
+		},
+	};
+}
+
 export async function callOpenFairyGuiBackendTool(
 	runtime: OpenFairyGuiBackendRuntime,
 	name: OpenFairyGuiBackendToolName,
 	input: Record<string, unknown>,
 ): Promise<CallToolResult> {
+	if (!isOpenFairyGuiMcpPayloadWithinBudget(input)) {
+		throw new RangeError('MCP input exceeds the depth, node, key, string, or byte budget.');
+	}
+	const startedAt = Date.now();
 	let result: unknown;
-	switch (name) {
+	try {
+		switch (name) {
 		case 'openfairygui_backend_get_capabilities':
 			result = runtime.getCapabilities();
 			break;
@@ -82,13 +115,19 @@ export async function callOpenFairyGuiBackendTool(
 				sessionId: String(input.sessionId),
 			});
 			break;
-		case 'openfairygui_backend_apply_transaction':
+		case 'openfairygui_backend_apply_transaction': {
+			const operations = (input.operations as Parameters<BackendRuntime['applyTransaction']>[0]['operations']).map(
+				(operation) => operation.kind === 'replaceResourceBytes'
+					? { ...operation, sourceBytes: new Uint8Array(operation.sourceBytes) }
+					: operation,
+			);
 			result = await runtime.applyTransaction({
 				sessionId: String(input.sessionId),
 				expectedRevision: Number(input.expectedRevision),
-				operations: input.operations as Parameters<BackendRuntime['applyTransaction']>[0]['operations'],
+				operations,
 			});
 			break;
+		}
 		case 'openfairygui_backend_save_session':
 			result = await runtime.saveSession({
 				sessionId: String(input.sessionId),
@@ -149,10 +188,13 @@ export async function callOpenFairyGuiBackendTool(
 				reason: input.reason as Parameters<BackendRuntime['refreshCache']>[0]['reason'],
 			});
 			break;
-		default: {
-			const exhaustive: never = name;
-			throw new Error(`Unknown OpenFairyGUI backend MCP tool: ${exhaustive}`);
+			default: {
+				const exhaustive: never = name;
+				throw new Error(`Unknown OpenFairyGUI backend MCP tool: ${exhaustive}`);
+			}
 		}
+	} catch {
+		return jsonResult(unhandledBackendFailure(startedAt), true);
 	}
 	return jsonResult(result, isBackendFailure(result));
 }