@openfairygui/mcp 0.3.0 → 0.4.0

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

@@ -1,8 +1,12 @@
 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 { 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";
 //#region src/prompt-definitions.ts
 const OPENFAIRYGUI_BACKEND_PROMPT_NAMES = [
@@ -51,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."
@@ -94,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) {
@@ -108,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.",
@@ -144,152 +236,13 @@ function registerOpenFairyGuiBackendResources(server, runtime) {
 	})));
 }
 //#endregion
-//#region src/tool-handler.ts
-function jsonResult(payload, isError = false) {
-	return {
-		content: [{
-			type: "text",
-			text: JSON.stringify(payload, null, 2)
-		}],
-		structuredContent: { backendResult: payload },
-		isError
-	};
-}
-function isBackendFailure(value) {
-	return typeof value === "object" && value !== null && "ok" in value && value.ok === false;
-}
-async function callOpenFairyGuiBackendTool(runtime, name, input) {
-	let result;
-	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":
-			result = await runtime.applyTransaction({
-				sessionId: String(input.sessionId),
-				expectedRevision: Number(input.expectedRevision),
-				operations: input.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}`);
-	}
-	return jsonResult(result, isBackendFailure(result));
-}
-//#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 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() });
-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,
@@ -301,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,
@@ -314,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: z.unknown(),
-			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,
@@ -332,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,
@@ -345,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,
@@ -358,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,
@@ -370,13 +330,7 @@ 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.",
-		inputSchema: z.object({
-			sessionId,
-			expectedRevision,
-			operations: z.array(z.unknown())
-		}),
-		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
+		description: "Apply a bounded, revision-checked UAM operation batch using the Core transaction discriminants.",
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: true,
@@ -388,15 +342,7 @@ 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.",
-		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,
+		description: "Write the current backend session through its coordinated save path; Node uses an atomic staged directory swap.",
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: true,
@@ -409,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,
@@ -428,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,
@@ -441,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,
@@ -458,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,
@@ -474,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,
@@ -500,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,
@@ -516,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,
@@ -529,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,
@@ -546,10 +441,113 @@ 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, (_key, value) => value instanceof Uint8Array ? [...value] : value, 2);
+	const wirePayload = JSON.parse(text);
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		structuredContent: { backendResult: wirePayload },
+		isError
+	};
+}
+function isBackendFailure(value) {
+	return typeof value === "object" && value !== null && "ok" in value && value.ok === false;
+}
+function unhandledBackendFailure(startedAt) {
+	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."
+		}
+	};
+}
+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();
+	try {
+		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);
+	}
+}
+//#endregion
 //#region src/server.ts
 const require = createRequire(import.meta.url);
 function getInjectedPackageVersion() {
-	const version = "0.3.0";
+	const version = "0.4.0";
 	return typeof version === "string" && true ? version : null;
 }
 function readPackageVersion() {
@@ -563,22 +561,44 @@ function readPackageVersion() {
 }
 const PACKAGE_VERSION = readPackageVersion();
 function createOpenFairyGuiMcpServer(options = {}) {
-	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
 	});
-	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;
@@ -586,11 +606,12 @@ function createOpenFairyGuiMcpServer(options = {}) {
 //#endregion
 //#region src/stdio.ts
 async function connectOpenFairyGuiMcpStdio() {
-	await createOpenFairyGuiMcpServer().connect(new StdioServerTransport());
+	const configuredRoots = process.env.OPENFAIRYGUI_ALLOWED_PROJECT_ROOTS?.split(path.delimiter).map((value) => value.trim()).filter(Boolean);
+	await createOpenFairyGuiMcpServer({ allowedProjectRoots: configuredRoots }).connect(new StdioServerTransport());
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) connectOpenFairyGuiMcpStdio().catch((error) => {
 	console.error(error instanceof Error ? error.stack ?? error.message : String(error));
 	process.exitCode = 1;
 });
 //#endregion
-export { OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA as a, OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI as c, OPENFAIRYGUI_BACKEND_PROMPT_NAMES as d, OPENFAIRYGUI_BACKEND_TOOL_NAMES as i, OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES as l, createOpenFairyGuiMcpServer as n, OPENFAIRYGUI_BACKEND_TOOL_PREFIX as o, OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS as r, callOpenFairyGuiBackendTool 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 };