@openfairygui/mcp 0.3.1 → 0.4.0

package/dist/{stdio-HOHWH0x4.mjs → stdio-9ka7bvOr.mjs}

@@ -1,8 +1,10 @@
 import { createRequire } from "node:module";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ListToolsRequestSchema, ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import { createNodeBackendRuntime } from "@openfairygui/backend/node";
-import { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_CONTRACT_VERSION } from "@openfairygui/backend";
 import { z } from "zod";
+import { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_CONTRACT_VERSION, BACKEND_DIAGNOSTICS_URI, BACKEND_DIAGNOSTIC_TEMPLATE, getBackendDiagnosticCatalog, getBackendDiagnosticGuide } from "@openfairygui/backend";
+import { OPENFAIRYGUI_DOCS_INDEX_URI, OPENFAIRYGUI_OPERATION_CATALOG_URI, OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE, getInstalledContractSnapshot, getInstalledDocumentationIndex, getOpenFairyGuiOperationCatalog, getOpenFairyGuiOperationSchema, readInstalledDocumentation } from "@openfairygui/backend/docs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -53,6 +55,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."
@@ -96,6 +103,32 @@ function registerOpenFairyGuiBackendPrompts(server) {
 	}, () => promptResult(definition.text));
 }
 //#endregion
+//#region src/contract-schema.ts
+const CONTRACT_SNAPSHOT = getInstalledContractSnapshot();
+function contractObjectSchema(schema) {
+	const result = z.fromJSONSchema({
+		...schema,
+		$defs: CONTRACT_SNAPSHOT.$defs
+	});
+	if (!(result instanceof 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) {
@@ -110,12 +143,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}",
+	BACKEND_DIAGNOSTIC_TEMPLATE,
+	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_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, getInstalledDocumentationIndex()));
+	function installedDocument(uri, id) {
+		const document = 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 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", 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, getBackendDiagnosticCatalog()));
+	server.registerResource("openfairygui_docs_cli", new 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 ResourceTemplate(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, getBackendDiagnosticGuide(firstVariable(variables.code))));
+	server.registerResource("openfairygui_operation_catalog", OPENFAIRYGUI_OPERATION_CATALOG_URI, {
+		title: "UAM Operation Catalog",
+		description: "Discover current operations and their generated JSON schemas.",
+		mimeType: JSON_MIME_TYPE
+	}, (uri) => jsonResource(uri, getOpenFairyGuiOperationCatalog()));
+	server.registerResource("openfairygui_operation_schema", new ResourceTemplate(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, 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.",
@@ -146,348 +236,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 = 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);
-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 = 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"].map((kind) => z.object({
-		...operationBase,
-		kind: z.literal(kind),
-		selector: controllerSelector,
-		controller: boundedPayload
-	})),
-	z.object({
-		...operationBase,
-		kind: z.literal("removeController"),
-		selector: controllerSelector
-	}),
-	...["addTransition", "updateTransition"].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"
-	].map((kind) => z.object({
-		...operationBase,
-		kind: z.literal(kind),
-		selector: displayNodeSelector.extend({
-			kind: identifier,
-			controllerName: identifier
-		}),
-		gear: boundedPayload
-	})),
-	...["removeLookGear", "removeGear"].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(1e4),
-		resources: z.array(boundedPayload).max(1e5)
-	})).max(1e3)
-});
-const OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA = z.object({ 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(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: z.object({}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -499,8 +254,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: z.object({ projectPath: z.string().min(1) }),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			idempotentHint: false,
@@ -512,13 +265,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: z.object({
-			project,
-			sessionId: z.string().min(1).optional(),
-			canonicalProjectPath: z.string().min(1).optional(),
-			canonicalPathKey: z.string().min(1).optional()
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			idempotentHint: false,
@@ -530,8 +276,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "getSession",
 		title: "Get Backend Session",
 		description: "Return a backend session snapshot by session id.",
-		inputSchema: z.object({ sessionId }),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -543,8 +287,17 @@ 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: 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,
@@ -556,8 +309,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: 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,
@@ -569,12 +331,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: z.object({
-			sessionId,
-			expectedRevision,
-			operations: z.array(operation).min(1).max(1e3)
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: true,
@@ -587,14 +343,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: z.object({
-			sessionId,
-			expectedRevision: expectedRevision.optional(),
-			targetPath: z.string().min(1).optional(),
-			force: z.boolean().optional(),
-			mode: z.literal("materializeCleanSession").optional()
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: true,
@@ -607,13 +355,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: z.object({
-			sessionId,
-			expectedRevision: expectedRevision.optional(),
-			mode: z.literal("fullProject").optional(),
-			reason: z.string().min(1).optional()
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: true,
@@ -626,8 +367,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: z.object({ sessionId }),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			idempotentHint: false,
@@ -639,12 +378,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: z.object({
-			sessionId,
-			after: z.string().optional(),
-			limit
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -656,11 +389,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: z.object({
-			sessionId,
-			jobId
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -672,21 +400,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: z.object({
-			sessionId,
-			status: z.enum([
-				"queued",
-				"running",
-				"completed",
-				"failed",
-				"cancelled",
-				"active",
-				"terminal"
-			]).optional(),
-			kind: z.literal("cache.refresh").optional(),
-			limit
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -698,11 +411,6 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		backendMethod: "cancelJob",
 		title: "Cancel Runtime Job",
 		description: "Request cooperative cancellation for a backend runtime job.",
-		inputSchema: z.object({
-			sessionId,
-			jobId
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			idempotentHint: false,
@@ -714,8 +422,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: z.object({ sessionId }),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
@@ -727,15 +433,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: z.object({
-			sessionId,
-			reason: z.enum([
-				"manual",
-				"session_open",
-				"after_save"
-			]).optional()
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
 			readOnlyHint: false,
 			idempotentHint: false,
@@ -744,9 +441,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);
+	const text = JSON.stringify(payload, (_key, value) => value instanceof Uint8Array ? [...value] : value, 2);
 	const wirePayload = JSON.parse(text);
 	return {
 		content: [{
@@ -780,113 +530,24 @@ 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;
-			}
-			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}`);
-		}
+		const result = await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === "getCapabilities" ? [] : [decoded]);
+		const response = jsonResult(result, isBackendFailure(result));
+		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 = createRequire(import.meta.url);
 function getInjectedPackageVersion() {
-	const version = "0.3.1";
+	const version = "0.4.0";
 	return typeof version === "string" && true ? version : null;
 }
 function readPackageVersion() {
@@ -905,17 +566,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(ToolSchema.parse({
+			...metadata,
+			inputSchema: z.toJSONSchema(definition.inputSchema, {
+				target: "draft-07",
+				io: "input",
+				reused: "ref"
+			}),
+			outputSchema: z.toJSONSchema(definition.outputSchema, {
+				target: "draft-07",
+				io: "output",
+				reused: "ref"
+			})
+		}));
+	}
+	server.server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: structuredClone(tools) }));
 	registerOpenFairyGuiBackendResources(server, runtime);
 	registerOpenFairyGuiBackendPrompts(server);
 	return server;
@@ -931,4 +614,4 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
 	process.exitCode = 1;
 });
 //#endregion
-export { OPENFAIRYGUI_BACKEND_TOOL_NAMES as a, OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI as c, OPENFAIRYGUI_BACKEND_PROMPT_NAMES as d, OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS as i, OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES as l, createOpenFairyGuiMcpServer as n, OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA as o, callOpenFairyGuiBackendTool as r, OPENFAIRYGUI_BACKEND_TOOL_PREFIX as s, connectOpenFairyGuiMcpStdio as t, OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS as u };
+export { OPENFAIRYGUI_BACKEND_TOOL_NAMES as a, OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES as c, getOpenFairyGuiOperationCatalog as d, getOpenFairyGuiOperationSchema as f, OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS as i, OPENFAIRYGUI_OPERATION_CATALOG_URI as l, OPENFAIRYGUI_BACKEND_PROMPT_NAMES as m, createOpenFairyGuiMcpServer as n, OPENFAIRYGUI_BACKEND_TOOL_PREFIX as o, OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS as p, callOpenFairyGuiBackendTool as r, OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI as s, connectOpenFairyGuiMcpStdio as t, OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE as u };