@openfairygui/mcp 0.3.1 → 0.5.0-alpha.1

package/dist/{stdio-N6Yxacus.cjs → stdio-CB98zdOf.cjs}

@@ -21,10 +21,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
+let _modelcontextprotocol_sdk_types_js = require("@modelcontextprotocol/sdk/types.js");
 let _openfairygui_backend_node = require("@openfairygui/backend/node");
 let node_module = require("node:module");
-let _openfairygui_backend = require("@openfairygui/backend");
 let zod = require("zod");
+let _openfairygui_backend = require("@openfairygui/backend");
+let _openfairygui_backend_docs = require("@openfairygui/backend/docs");
 let _modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
 let node_path = require("node:path");
 node_path = __toESM(node_path);
@@ -76,6 +78,11 @@ const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS = [
 		description: "Guide a client through backend-owned revision checks without inventing operation grammar.",
 		text: [
 			"Use openfairygui_backend_get_session to read the current revision before mutation.",
+			"Use openfairygui_backend_get_project_outline for identities, then openfairygui_backend_query_entity for current properties at the returned revision.",
+			"For settings edits, query target {kind:\"project\"} or {kind:\"package\",selector:{packageId}}; copy entity.properties.settings, change the requested fields, and submit the complete settings to updateProjectSettings or updatePackageSettings.",
+			"Read openfairygui://contracts/operations and openfairygui://contracts/operations/{kind} for the current operation names and exact JSON parameters.",
+			"Call openfairygui_backend_preflight_transaction with the queried revision and planned operations to execute and discard an isolated preview; inspect the backend diagnostics.",
+			"A successful preview does not reserve a revision or guarantee save. Apply the same batch with expectedRevision set to the preview baseRevision; refresh properties and re-plan on stale revision.",
 			"Call openfairygui_backend_apply_transaction with sessionId, expectedRevision, and backend/UAM-owned operations.",
 			"If the backend returns a stale revision error, refresh the session snapshot and re-plan against the new revision.",
 			"Do not invent selector grammar, transaction grammar, or operation payload semantics at the MCP layer."
@@ -119,6 +126,32 @@ function registerOpenFairyGuiBackendPrompts(server) {
 	}, () => promptResult(definition.text));
 }
 //#endregion
+//#region src/contract-schema.ts
+const CONTRACT_SNAPSHOT = (0, _openfairygui_backend_docs.getInstalledContractSnapshot)();
+function contractObjectSchema(schema) {
+	const result = zod.z.fromJSONSchema({
+		...schema,
+		$defs: CONTRACT_SNAPSHOT.$defs
+	});
+	if (!(result instanceof zod.z.ZodObject)) throw new TypeError("Tool contract must be an object");
+	return result;
+}
+/** Decode only generated Uint8Array locations; arbitrary JSON metadata is not rewritten. */
+function decodeToolBytes(input, paths) {
+	if (!paths.length) return input;
+	const result = structuredClone(input);
+	function visit(value, parts) {
+		if (!parts.length) return value === null ? value : Uint8Array.from(value);
+		if (!value || typeof value !== "object") return value;
+		const [key, ...rest] = parts;
+		const record = value;
+		for (const name of key === "*" ? Object.keys(record) : [key]) if (Object.hasOwn(record, name)) record[name] = visit(record[name], rest);
+		return value;
+	}
+	for (const parts of paths) visit(result, parts);
+	return result;
+}
+//#endregion
 //#region src/resource-definitions.ts
 const JSON_MIME_TYPE = "application/json";
 function firstVariable(value) {
@@ -133,12 +166,69 @@ function jsonResource(uri, backendResult) {
 }
 const OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = "openfairygui://backend/capabilities";
 const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES = [
+	"openfairygui://docs/methods/{method}",
+	"openfairygui://docs/cli/{command}",
+	_openfairygui_backend.BACKEND_DIAGNOSTIC_TEMPLATE,
+	_openfairygui_backend_docs.OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE,
 	"openfairygui://backend/session/{sessionId}",
 	"openfairygui://backend/session/{sessionId}/outline",
 	"openfairygui://backend/cache/{sessionId}",
 	"openfairygui://backend/job/{sessionId}/{jobId}"
 ];
 function registerOpenFairyGuiBackendResources(server, runtime) {
+	server.registerResource("openfairygui_docs_index", _openfairygui_backend_docs.OPENFAIRYGUI_DOCS_INDEX_URI, {
+		title: "Installed Documentation",
+		description: "Offline documentation IDs, URIs, installed package version and contract digest shared with the CLI.",
+		mimeType: JSON_MIME_TYPE
+	}, (uri) => jsonResource(uri, (0, _openfairygui_backend_docs.getInstalledDocumentationIndex)()));
+	function installedDocument(uri, id) {
+		const document = (0, _openfairygui_backend_docs.readInstalledDocumentation)(id);
+		return { contents: [{
+			uri: uri.toString(),
+			mimeType: document.mimeType,
+			text: document.text
+		}] };
+	}
+	for (const id of [
+		"workflow",
+		"restore-limits",
+		"skill",
+		"contracts"
+	]) server.registerResource(`openfairygui_docs_${id}`, `openfairygui://docs/${id}`, {
+		title: `Installed ${id}`,
+		description: "Read the installed-version corpus without repository or network access.",
+		mimeType: id === "contracts" ? JSON_MIME_TYPE : "text/markdown"
+	}, (uri) => installedDocument(uri, id));
+	server.registerResource("openfairygui_docs_method", new _modelcontextprotocol_sdk_server_mcp_js.ResourceTemplate("openfairygui://docs/methods/{method}", { list: void 0 }), {
+		title: "Installed Method Contract",
+		description: "Read self-contained Backend/MCP wire input/output schemas and metadata.",
+		mimeType: JSON_MIME_TYPE
+	}, (uri, variables) => installedDocument(uri, `methods/${firstVariable(variables.method)}`));
+	server.registerResource("openfairygui_diagnostic_catalog", _openfairygui_backend.BACKEND_DIAGNOSTICS_URI, {
+		title: "Diagnostic Recovery Catalog",
+		description: "Complete formal diagnostic ownership and recovery guidance; never automatic repair.",
+		mimeType: JSON_MIME_TYPE
+	}, (uri) => jsonResource(uri, (0, _openfairygui_backend.getBackendDiagnosticCatalog)()));
+	server.registerResource("openfairygui_docs_cli", new _modelcontextprotocol_sdk_server_mcp_js.ResourceTemplate("openfairygui://docs/cli/{command}", { list: void 0 }), {
+		title: "Installed CLI Output Contract",
+		description: "Read a generated, self-contained CLI JSON envelope schema.",
+		mimeType: JSON_MIME_TYPE
+	}, (uri, variables) => installedDocument(uri, `cli/${decodeURIComponent(firstVariable(variables.command))}`));
+	server.registerResource("openfairygui_diagnostic_guide", new _modelcontextprotocol_sdk_server_mcp_js.ResourceTemplate(_openfairygui_backend.BACKEND_DIAGNOSTIC_TEMPLATE, { list: void 0 }), {
+		title: "Diagnostic Recovery Guide",
+		description: "Read the recovery boundary for one stable diagnostic code.",
+		mimeType: JSON_MIME_TYPE
+	}, (uri, variables) => jsonResource(uri, (0, _openfairygui_backend.getBackendDiagnosticGuide)(firstVariable(variables.code))));
+	server.registerResource("openfairygui_operation_catalog", _openfairygui_backend_docs.OPENFAIRYGUI_OPERATION_CATALOG_URI, {
+		title: "UAM Operation Catalog",
+		description: "Discover current operations and their generated JSON schemas.",
+		mimeType: JSON_MIME_TYPE
+	}, (uri) => jsonResource(uri, (0, _openfairygui_backend_docs.getOpenFairyGuiOperationCatalog)()));
+	server.registerResource("openfairygui_operation_schema", new _modelcontextprotocol_sdk_server_mcp_js.ResourceTemplate(_openfairygui_backend_docs.OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE, { list: void 0 }), {
+		title: "UAM Operation Schema",
+		description: "Read the precise Core-derived JSON wire schema for one operation. Structure is not semantic preflight.",
+		mimeType: JSON_MIME_TYPE
+	}, (uri, variables) => jsonResource(uri, (0, _openfairygui_backend_docs.getOpenFairyGuiOperationSchema)(firstVariable(variables.kind))));
 	server.registerResource("openfairygui_backend_capabilities", OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI, {
 		title: "OpenFairyGUI Backend Capabilities",
 		description: "Read the backend capability and version envelope as JSON.",
@@ -169,348 +259,13 @@ function registerOpenFairyGuiBackendResources(server, runtime) {
 	})));
 }
 //#endregion
-//#region src/tool-definitions.ts
-const OPENFAIRYGUI_BACKEND_TOOL_PREFIX = "openfairygui_backend_";
-const OPENFAIRYGUI_BACKEND_TOOL_NAMES = [
-	"openfairygui_backend_get_capabilities",
-	"openfairygui_backend_open_session",
-	"openfairygui_backend_open_project_session",
-	"openfairygui_backend_get_session",
-	"openfairygui_backend_get_project_outline",
-	"openfairygui_backend_validate_session",
-	"openfairygui_backend_apply_transaction",
-	"openfairygui_backend_save_session",
-	"openfairygui_backend_materialize_session",
-	"openfairygui_backend_close_session",
-	"openfairygui_backend_get_events",
-	"openfairygui_backend_get_job",
-	"openfairygui_backend_list_jobs",
-	"openfairygui_backend_cancel_job",
-	"openfairygui_backend_get_cache_snapshot",
-	"openfairygui_backend_refresh_cache"
-];
-const sessionId = zod.z.string().min(1);
-const jobId = zod.z.string().min(1);
-const expectedRevision = zod.z.number().int().nonnegative();
-const limit = zod.z.number().int().nonnegative().optional();
-const identifier = zod.z.string().min(1).max(256);
-function isOpenFairyGuiMcpPayloadWithinBudget(root) {
-	const pending = [{
-		value: root,
-		depth: 0
-	}];
-	let nodes = 0;
-	while (pending.length > 0) {
-		const { value, depth } = pending.pop();
-		nodes += 1;
-		if (nodes > 1e5 || 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 > 1e6) return false;
-			continue;
-		}
-		if (value instanceof Uint8Array) {
-			if (value.byteLength > 8 * 1024 * 1024) return false;
-			continue;
-		}
-		if (Array.isArray(value)) {
-			if (value.length > 1e4) 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 > 1e4 || entries.some(([key]) => key.length > 256)) return false;
-		for (const [, child] of entries) pending.push({
-			value: child,
-			depth: depth + 1
-		});
-	}
-	return true;
-}
-const boundedPayload = zod.z.json();
-const bytes = zod.z.array(zod.z.number().int().min(0).max(255)).max(8 * 1024 * 1024);
-const packageSelector = zod.z.object({ packageId: identifier });
-const resourceSelector = zod.z.object({
-	packageId: identifier,
-	resourceId: identifier
-});
-const componentSelector = zod.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: zod.z.string().max(256).optional(),
-	path: zod.z.string().min(1).max(4096)
-});
-const operationBase = { opId: identifier.optional() };
-const operation = zod.z.discriminatedUnion("kind", [
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("updateProjectSettings"),
-		settings: boundedPayload
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("updatePackageSettings"),
-		selector: packageSelector,
-		settings: boundedPayload
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("renameResource"),
-		selector: resourceSelector,
-		newName: identifier
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("moveResource"),
-		selector: resourceSelector,
-		toPath: zod.z.string().max(4096)
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("setResourceFavorite"),
-		selector: resourceSelector,
-		favorite: zod.z.boolean()
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("setResourceFolderFavorite"),
-		selector: folderSelector,
-		favorite: zod.z.boolean()
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("setResourceFolderAtlas"),
-		selector: folderSelector,
-		atlas: zod.z.string().max(32)
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("setResourceExported"),
-		selector: resourceSelector,
-		exported: zod.z.boolean()
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("addResourceFolder"),
-		selector: packageSelector,
-		path: zod.z.string().max(4096),
-		branch: zod.z.string().max(256).optional(),
-		favorite: zod.z.boolean().optional(),
-		atlas: zod.z.string().max(32).optional()
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("renameResourceFolder"),
-		selector: folderSelector,
-		newName: identifier
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("moveResourceFolder"),
-		selector: folderSelector,
-		toPath: zod.z.string().max(4096)
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("removeResourceFolder"),
-		selector: folderSelector
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("setImageResourceProps"),
-		selector: resourceSelector,
-		props: boundedPayload
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("addResource"),
-		selector: packageSelector,
-		resource: boundedPayload,
-		atIndex: zod.z.number().int().nonnegative().optional()
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("addBranch"),
-		branch: identifier
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("renameBranch"),
-		selector: zod.z.object({ branch: identifier }),
-		newName: identifier
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("removeBranch"),
-		selector: zod.z.object({ branch: identifier })
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("addPackage"),
-		package: boundedPayload,
-		atIndex: zod.z.number().int().nonnegative()
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("renamePackage"),
-		selector: packageSelector,
-		newName: identifier
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("removePackage"),
-		selector: packageSelector
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("addComponent"),
-		selector: packageSelector,
-		component: boundedPayload,
-		atIndex: zod.z.number().int().nonnegative()
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("removeComponent"),
-		selector: componentSelector
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("moveComponent"),
-		selector: componentSelector,
-		toPackageId: identifier,
-		toIndex: zod.z.number().int().nonnegative()
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("replaceResourceBytes"),
-		selector: resourceSelector,
-		sourceBytes: bytes
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("removeResource"),
-		selector: resourceSelector
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("setDisplayNodeProps"),
-		selector: displayNodeSelector,
-		props: boundedPayload
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("setComponentProps"),
-		selector: componentSelector,
-		props: boundedPayload
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("attachDisplayNode"),
-		selector: componentSelector,
-		atIndex: zod.z.number().int().nonnegative(),
-		node: boundedPayload
-	}),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("detachDisplayNode"),
-		selector: displayNodeSelector
-	}),
-	...["addController", "updateController"].map((kind) => zod.z.object({
-		...operationBase,
-		kind: zod.z.literal(kind),
-		selector: controllerSelector,
-		controller: boundedPayload
-	})),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("removeController"),
-		selector: controllerSelector
-	}),
-	...["addTransition", "updateTransition"].map((kind) => zod.z.object({
-		...operationBase,
-		kind: zod.z.literal(kind),
-		selector: transitionSelector,
-		transition: boundedPayload
-	})),
-	zod.z.object({
-		...operationBase,
-		kind: zod.z.literal("removeTransition"),
-		selector: transitionSelector
-	}),
-	...[
-		"addLookGear",
-		"updateLookGear",
-		"addGear",
-		"updateGear"
-	].map((kind) => zod.z.object({
-		...operationBase,
-		kind: zod.z.literal(kind),
-		selector: displayNodeSelector.extend({
-			kind: identifier,
-			controllerName: identifier
-		}),
-		gear: boundedPayload
-	})),
-	...["removeLookGear", "removeGear"].map((kind) => zod.z.object({
-		...operationBase,
-		kind: zod.z.literal(kind),
-		selector: displayNodeSelector.extend({
-			kind: identifier,
-			controllerName: identifier
-		})
-	}))
-]);
-const project = zod.z.object({
-	projectId: identifier,
-	projectType: zod.z.number().int(),
-	version: zod.z.string().max(256),
-	branches: zod.z.array(zod.z.string().max(256)).max(256),
-	settings: boundedPayload,
-	packages: zod.z.array(zod.z.object({
-		id: identifier,
-		name: identifier,
-		compressPNG: zod.z.boolean().nullable(),
-		jpegQuality: zod.z.number().finite().nullable(),
-		publish: boundedPayload.nullable(),
-		branchNames: zod.z.array(zod.z.string().max(256)).max(256),
-		folders: zod.z.array(boundedPayload).max(1e4),
-		resources: zod.z.array(boundedPayload).max(1e5)
-	})).max(1e3)
-});
-const OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA = zod.z.object({ backendResult: zod.z.discriminatedUnion("ok", [zod.z.object({
-	ok: zod.z.literal(true),
-	data: boundedPayload,
-	meta: boundedPayload
-}), zod.z.object({
-	ok: zod.z.literal(false),
-	error: zod.z.object({
-		code: identifier,
-		message: zod.z.string().max(1e6)
-	}).passthrough(),
-	meta: boundedPayload,
-	session: boundedPayload.optional()
-})]) });
-const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
+//#region src/tool-metadata.ts
+const OPENFAIRYGUI_BACKEND_TOOL_METADATA = [
 	{
 		name: "openfairygui_backend_get_capabilities",
 		backendMethod: "getCapabilities",
 		title: "Get Backend Capabilities",
 		description: "Return the OpenFairyGUI backend capability, version, and service-plane snapshot.",
-		inputSchema: zod.z.object({}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -522,8 +277,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "openSession",
 		title: "Open Backend Session",
 		description: "Open a FairyGUI project through BackendRuntime and acquire its backend-local session lock.",
-		inputSchema: zod.z.object({ projectPath: zod.z.string().min(1) }),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			idempotentHint: false,
@@ -535,13 +288,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "openProjectSession",
 		title: "Open Project Session",
 		description: "Open a browser-safe backend session from an already loaded UAM project without filesystem access.",
-		inputSchema: zod.z.object({
-			project,
-			sessionId: zod.z.string().min(1).optional(),
-			canonicalProjectPath: zod.z.string().min(1).optional(),
-			canonicalPathKey: zod.z.string().min(1).optional()
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			idempotentHint: false,
@@ -553,8 +299,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "getSession",
 		title: "Get Backend Session",
 		description: "Return a backend session snapshot by session id.",
-		inputSchema: zod.z.object({ sessionId }),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -566,8 +310,41 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "getProjectOutline",
 		title: "Get Project Outline",
 		description: "Return a revision-bound project/package/resource/component identity outline without source bytes or full property payloads.",
-		inputSchema: zod.z.object({ sessionId }),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	},
+	{
+		name: "openfairygui_backend_query_entity",
+		backendMethod: "queryEntity",
+		title: "Query Entity Properties",
+		description: "Read revision-bound project/package settings, resource, component-property, display-node, controller (including pages/actions), or transition (including items) snapshots. Project queries use only kind; other queries use formal selectors. Settings snapshots include the complete settings payload for updateProjectSettings/updatePackageSettings. No source bytes; fixed projection with explicit response limits.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	},
+	{
+		name: "openfairygui_backend_read_session_state",
+		backendMethod: "readSessionState",
+		title: "Read Session State",
+		description: "Read a detached copy of the currently committed public UAM model without primary asset sourceBytes, with revision, dirty state and source-read diagnostics. Optional expectedRevision rejects stale reads. Does not hydrate, write, reserve history or guarantee downstream usability. Complete tool response is limited to 16 MiB.",
+		maxResponseBytes: 16777216,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	},
+	{
+		name: "openfairygui_backend_read_resource_bytes",
+		backendMethod: "readResourceBytes",
+		title: "Read Resource Bytes",
+		description: "Read a detached copy of one asset resource primary sourceBytes already held in the session, using exact packageId/resourceId and the required model edit revision. No filesystem hydration or auxiliary-file discovery. Stale reads require restarting the model/bytes read. Complete tool response is limited to 16 MiB.",
+		maxResponseBytes: 16777216,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -579,8 +356,17 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "validateSession",
 		title: "Validate Project Session",
 		description: "Validate the current session project structure, references, paths, and available source bytes without writing files.",
-		inputSchema: zod.z.object({ sessionId }),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	},
+	{
+		name: "openfairygui_backend_preflight_transaction",
+		backendMethod: "preflightTransaction",
+		title: "Preview UAM Transaction",
+		description: "Execute a revision-checked operation batch on an isolated project snapshot and discard the result. Returns the base revision and Core diagnostics; does not write, reserve a revision, or guarantee a later apply/save.",
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -592,12 +378,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "applyTransaction",
 		title: "Apply UAM Transaction",
 		description: "Apply a bounded, revision-checked UAM operation batch using the Core transaction discriminants.",
-		inputSchema: zod.z.object({
-			sessionId,
-			expectedRevision,
-			operations: zod.z.array(operation).min(1).max(1e3)
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: true,
@@ -610,14 +390,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "saveSession",
 		title: "Save Backend Session",
 		description: "Write the current backend session through its coordinated save path; Node uses an atomic staged directory swap.",
-		inputSchema: zod.z.object({
-			sessionId,
-			expectedRevision: expectedRevision.optional(),
-			targetPath: zod.z.string().min(1).optional(),
-			force: zod.z.boolean().optional(),
-			mode: zod.z.literal("materializeCleanSession").optional()
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: true,
@@ -630,13 +402,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "materializeSession",
 		title: "Materialize Backend Session",
 		description: "Force materialize the current backend session project through the configured project storage without requiring a dirty edit revision.",
-		inputSchema: zod.z.object({
-			sessionId,
-			expectedRevision: expectedRevision.optional(),
-			mode: zod.z.literal("fullProject").optional(),
-			reason: zod.z.string().min(1).optional()
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: true,
@@ -649,8 +414,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "closeSession",
 		title: "Close Backend Session",
 		description: "Close a backend session and release its backend-local session lock.",
-		inputSchema: zod.z.object({ sessionId }),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			idempotentHint: false,
@@ -662,12 +425,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "getEvents",
 		title: "Get Runtime Events",
 		description: "Poll backend runtime events for a session using the backend P2 event cursor contract.",
-		inputSchema: zod.z.object({
-			sessionId,
-			after: zod.z.string().optional(),
-			limit
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -679,11 +436,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "getJob",
 		title: "Get Runtime Job",
 		description: "Return a backend runtime job snapshot by session and backend-local job id.",
-		inputSchema: zod.z.object({
-			sessionId,
-			jobId
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -695,21 +447,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "listJobs",
 		title: "List Runtime Jobs",
 		description: "List backend runtime jobs for a session with backend P2 status/kind filters.",
-		inputSchema: zod.z.object({
-			sessionId,
-			status: zod.z.enum([
-				"queued",
-				"running",
-				"completed",
-				"failed",
-				"cancelled",
-				"active",
-				"terminal"
-			]).optional(),
-			kind: zod.z.literal("cache.refresh").optional(),
-			limit
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -721,11 +458,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "cancelJob",
 		title: "Cancel Runtime Job",
 		description: "Request cooperative cancellation for a backend runtime job.",
-		inputSchema: zod.z.object({
-			sessionId,
-			jobId
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			idempotentHint: false,
@@ -737,8 +469,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "getCacheSnapshot",
 		title: "Get Cache Snapshot",
 		description: "Return the backend P2 derived read-only cache snapshot for a session.",
-		inputSchema: zod.z.object({ sessionId }),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -750,15 +480,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "refreshCache",
 		title: "Refresh Cache",
 		description: "Create a backend P2 cache.refresh job for the session cache snapshot.",
-		inputSchema: zod.z.object({
-			sessionId,
-			reason: zod.z.enum([
-				"manual",
-				"session_open",
-				"after_save"
-			]).optional()
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			idempotentHint: false,
@@ -767,9 +488,62 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 	}
 ];
 //#endregion
+//#region src/tool-definitions.ts
+const OPENFAIRYGUI_BACKEND_TOOL_PREFIX = "openfairygui_backend_";
+const OPENFAIRYGUI_BACKEND_TOOL_NAMES = OPENFAIRYGUI_BACKEND_TOOL_METADATA.map((entry) => entry.name);
+function isOpenFairyGuiMcpPayloadWithinBudget(root) {
+	const pending = [{
+		value: root,
+		depth: 0
+	}];
+	let nodes = 0;
+	while (pending.length > 0) {
+		const { value, depth } = pending.pop();
+		nodes += 1;
+		if (nodes > 1e5 || 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 > 1e6) return false;
+			continue;
+		}
+		if (value instanceof Uint8Array) {
+			if (value.byteLength > 8 * 1024 * 1024) return false;
+			continue;
+		}
+		if (Array.isArray(value)) {
+			if (value.length > 1e4) 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 > 1e4 || entries.some(([key]) => key.length > 256)) return false;
+		for (const [, child] of entries) pending.push({
+			value: child,
+			depth: depth + 1
+		});
+	}
+	return true;
+}
+const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = OPENFAIRYGUI_BACKEND_TOOL_METADATA.map((metadata) => {
+	const contract = CONTRACT_SNAPSHOT.tools[metadata.backendMethod];
+	return {
+		...metadata,
+		inputSchema: contractObjectSchema(contract.input),
+		outputSchema: contractObjectSchema(contract.output)
+	};
+});
+//#endregion
 //#region src/tool-handler.ts
-function jsonResult(payload, isError = false) {
-	const text = JSON.stringify(payload, null, 2);
+function jsonResult(payload, isError = false, compact = false) {
+	const text = JSON.stringify(payload, (_key, value) => value instanceof Uint8Array ? [...value] : value, compact ? void 0 : 2);
 	const wirePayload = JSON.parse(text);
 	return {
 		content: [{
@@ -803,113 +577,32 @@ function unhandledBackendFailure(startedAt) {
 }
 async function callOpenFairyGuiBackendTool(runtime, name, input) {
 	if (!isOpenFairyGuiMcpPayloadWithinBudget(input)) throw new RangeError("MCP input exceeds the depth, node, key, string, or byte budget.");
+	const definition = OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS.find((entry) => entry.name === name);
+	if (!definition) throw new RangeError(`Unknown OpenFairyGUI backend MCP tool: ${name}`);
+	const decoded = decodeToolBytes(definition.inputSchema.parse(input), CONTRACT_SNAPSHOT.tools[definition.backendMethod].bytePaths);
 	const startedAt = Date.now();
-	let result;
 	try {
-		switch (name) {
-			case "openfairygui_backend_get_capabilities":
-				result = runtime.getCapabilities();
-				break;
-			case "openfairygui_backend_open_session":
-				result = await runtime.openSession({ projectPath: String(input.projectPath) });
-				break;
-			case "openfairygui_backend_open_project_session":
-				result = runtime.openProjectSession({
-					project: input.project,
-					sessionId: input.sessionId === void 0 ? void 0 : String(input.sessionId),
-					canonicalProjectPath: input.canonicalProjectPath === void 0 ? void 0 : String(input.canonicalProjectPath),
-					canonicalPathKey: input.canonicalPathKey === void 0 ? void 0 : String(input.canonicalPathKey)
-				});
-				break;
-			case "openfairygui_backend_get_session":
-				result = runtime.getSession({ sessionId: String(input.sessionId) });
-				break;
-			case "openfairygui_backend_get_project_outline":
-				result = runtime.getProjectOutline({ sessionId: String(input.sessionId) });
-				break;
-			case "openfairygui_backend_validate_session":
-				result = runtime.validateSession({ sessionId: String(input.sessionId) });
-				break;
-			case "openfairygui_backend_apply_transaction": {
-				const operations = input.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
-				});
-				break;
+		const result = await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === "getCapabilities" ? [] : [decoded]);
+		let response = jsonResult(result, isBackendFailure(result), definition.maxResponseBytes !== void 0);
+		if (definition.maxResponseBytes !== void 0 && new TextEncoder().encode(JSON.stringify(response)).byteLength > definition.maxResponseBytes) response = jsonResult({
+			...unhandledBackendFailure(startedAt),
+			error: {
+				code: "mcp_response_budget_exceeded",
+				message: "The complete MCP tool response exceeds its byte limit.",
+				maxBytes: definition.maxResponseBytes
 			}
-			case "openfairygui_backend_save_session":
-				result = await runtime.saveSession({
-					sessionId: String(input.sessionId),
-					expectedRevision: input.expectedRevision === void 0 ? void 0 : Number(input.expectedRevision),
-					targetPath: input.targetPath === void 0 ? void 0 : String(input.targetPath),
-					force: input.force === void 0 ? void 0 : Boolean(input.force),
-					mode: input.mode
-				});
-				break;
-			case "openfairygui_backend_materialize_session":
-				result = await runtime.materializeSession({
-					sessionId: String(input.sessionId),
-					expectedRevision: input.expectedRevision === void 0 ? void 0 : Number(input.expectedRevision),
-					mode: input.mode,
-					reason: input.reason === void 0 ? void 0 : String(input.reason)
-				});
-				break;
-			case "openfairygui_backend_close_session":
-				result = await runtime.closeSession({ sessionId: String(input.sessionId) });
-				break;
-			case "openfairygui_backend_get_events":
-				result = runtime.getEvents({
-					sessionId: String(input.sessionId),
-					after: input.after === void 0 ? void 0 : String(input.after),
-					limit: input.limit === void 0 ? void 0 : Number(input.limit)
-				});
-				break;
-			case "openfairygui_backend_get_job":
-				result = runtime.getJob({
-					sessionId: String(input.sessionId),
-					jobId: String(input.jobId)
-				});
-				break;
-			case "openfairygui_backend_list_jobs":
-				result = runtime.listJobs({
-					sessionId: String(input.sessionId),
-					status: input.status,
-					kind: input.kind,
-					limit: input.limit === void 0 ? void 0 : Number(input.limit)
-				});
-				break;
-			case "openfairygui_backend_cancel_job":
-				result = runtime.cancelJob({
-					sessionId: String(input.sessionId),
-					jobId: String(input.jobId)
-				});
-				break;
-			case "openfairygui_backend_get_cache_snapshot":
-				result = runtime.getCacheSnapshot({ sessionId: String(input.sessionId) });
-				break;
-			case "openfairygui_backend_refresh_cache":
-				result = runtime.refreshCache({
-					sessionId: String(input.sessionId),
-					reason: input.reason
-				});
-				break;
-			default: throw new Error(`Unknown OpenFairyGUI backend MCP tool: ${name}`);
-		}
+		}, true);
+		definition.outputSchema.parse(response.structuredContent);
+		return response;
 	} catch {
 		return jsonResult(unhandledBackendFailure(startedAt), true);
 	}
-	return jsonResult(result, isBackendFailure(result));
 }
 //#endregion
 //#region src/server.ts
 const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
 function getInjectedPackageVersion() {
-	const version = "0.3.1";
+	const version = "0.5.0-alpha.1";
 	return typeof version === "string" && true ? version : null;
 }
 function readPackageVersion() {
@@ -928,17 +621,39 @@ function createOpenFairyGuiMcpServer(options = {}) {
 		name: options.name ?? "openfairygui-mcp",
 		version: options.version ?? PACKAGE_VERSION
 	});
-	for (const definition of OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS) server.registerTool(definition.name, {
-		title: definition.title,
-		description: definition.description,
-		inputSchema: definition.inputSchema,
-		outputSchema: definition.outputSchema,
-		annotations: definition.annotations,
-		_meta: {
-			"openfairygui/backendMethod": definition.backendMethod,
-			"openfairygui/adapter": "thin-backend-p2"
-		}
-	}, async (args) => callOpenFairyGuiBackendTool(runtime, definition.name, args));
+	const tools = [];
+	for (const definition of OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS) {
+		const metadata = {
+			name: definition.name,
+			title: definition.title,
+			description: definition.description,
+			annotations: definition.annotations,
+			_meta: {
+				"openfairygui/backendMethod": definition.backendMethod,
+				"openfairygui/adapter": "thin-backend-p2",
+				"openfairygui/contractDigest": CONTRACT_SNAPSHOT.digest
+			}
+		};
+		server.registerTool(definition.name, {
+			...metadata,
+			inputSchema: definition.inputSchema,
+			outputSchema: definition.outputSchema
+		}, async (args) => callOpenFairyGuiBackendTool(runtime, definition.name, args));
+		tools.push(_modelcontextprotocol_sdk_types_js.ToolSchema.parse({
+			...metadata,
+			inputSchema: zod.z.toJSONSchema(definition.inputSchema, {
+				target: "draft-07",
+				io: "input",
+				reused: "ref"
+			}),
+			outputSchema: zod.z.toJSONSchema(definition.outputSchema, {
+				target: "draft-07",
+				io: "output",
+				reused: "ref"
+			})
+		}));
+	}
+	server.server.setRequestHandler(_modelcontextprotocol_sdk_types_js.ListToolsRequestSchema, () => ({ tools: structuredClone(tools) }));
 	registerOpenFairyGuiBackendResources(server, runtime);
 	registerOpenFairyGuiBackendPrompts(server);
 	return server;
@@ -990,16 +705,16 @@ Object.defineProperty(exports, "OPENFAIRYGUI_BACKEND_TOOL_NAMES", {
 		return OPENFAIRYGUI_BACKEND_TOOL_NAMES;
 	}
 });
-Object.defineProperty(exports, "OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA", {
+Object.defineProperty(exports, "OPENFAIRYGUI_BACKEND_TOOL_PREFIX", {
 	enumerable: true,
 	get: function() {
-		return OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA;
+		return OPENFAIRYGUI_BACKEND_TOOL_PREFIX;
 	}
 });
-Object.defineProperty(exports, "OPENFAIRYGUI_BACKEND_TOOL_PREFIX", {
+Object.defineProperty(exports, "__toESM", {
 	enumerable: true,
 	get: function() {
-		return OPENFAIRYGUI_BACKEND_TOOL_PREFIX;
+		return __toESM;
 	}
 });
 Object.defineProperty(exports, "callOpenFairyGuiBackendTool", {