@openfairygui/mcp 0.3.0 → 0.4.0

package/dist/stdio.cjs

@@ -1,3 +1,3 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_stdio = require("./stdio-9ewjcCag.cjs");
+const require_stdio = require("./stdio-B0OU-oZC.cjs");
 exports.connectOpenFairyGuiMcpStdio = require_stdio.connectOpenFairyGuiMcpStdio;

package/dist/stdio.mjs

@@ -1,2 +1,2 @@
-import { t as connectOpenFairyGuiMcpStdio } from "./stdio-48jCJzS3.mjs";
+import { t as connectOpenFairyGuiMcpStdio } from "./stdio-9ka7bvOr.mjs";
 export { connectOpenFairyGuiMcpStdio };

package/package.json

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

package/src/contract-schema.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { getInstalledContractSnapshot, type ContractSchema } from '@openfairygui/backend/docs';
+export { getOpenFairyGuiOperationCatalog, getOpenFairyGuiOperationSchema, OPENFAIRYGUI_OPERATION_CATALOG_URI, OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE } from '@openfairygui/backend/docs';
+
+export const CONTRACT_SNAPSHOT = getInstalledContractSnapshot();
+
+export function contractObjectSchema(schema: ContractSchema): z.ZodObject {
+	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. */
+export function decodeToolBytes(input: Record<string, unknown>, paths: string[][]): Record<string, unknown> {
+	if (!paths.length) return input;
+	const result = structuredClone(input);
+	function visit(value: unknown, parts: string[]): unknown {
+		if (!parts.length) return value === null ? value : Uint8Array.from(value as number[]);
+		if (!value || typeof value !== 'object') return value;
+		const [key, ...rest] = parts;
+		const record = value as Record<string, unknown>;
+		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;
+}

package/src/index.ts

@@ -21,9 +21,14 @@ export {
 export {
 	OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS,
 	OPENFAIRYGUI_BACKEND_TOOL_NAMES,
-	OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 	OPENFAIRYGUI_BACKEND_TOOL_PREFIX,
 	type BackendMethodName,
 	type OpenFairyGuiBackendToolDefinition,
 	type OpenFairyGuiBackendToolName,
 } from './tool-definitions.js';
+export {
+	getOpenFairyGuiOperationCatalog,
+	getOpenFairyGuiOperationSchema,
+	OPENFAIRYGUI_OPERATION_CATALOG_URI,
+	OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE,
+} from './contract-schema.js';

package/src/prompt-definitions.ts

@@ -56,6 +56,11 @@ export 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.',

package/src/resource-definitions.ts

@@ -1,6 +1,14 @@
 import { ResourceTemplate, type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import { BACKEND_DIAGNOSTICS_URI, BACKEND_DIAGNOSTIC_TEMPLATE, getBackendDiagnosticCatalog, getBackendDiagnosticGuide } from '@openfairygui/backend';
+import { getInstalledDocumentationIndex, readInstalledDocumentation, OPENFAIRYGUI_DOCS_INDEX_URI } from '@openfairygui/backend/docs';
 import type { OpenFairyGuiBackendRuntime } from './tool-handler.js';
+import {
+	getOpenFairyGuiOperationCatalog,
+	getOpenFairyGuiOperationSchema,
+	OPENFAIRYGUI_OPERATION_CATALOG_URI,
+	OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE,
+} from './contract-schema.js';
 
 const JSON_MIME_TYPE = 'application/json';
 
@@ -23,6 +31,10 @@ function jsonResource(uri: URL, backendResult: unknown): ReadResourceResult {
 export const OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = 'openfairygui://backend/capabilities';
 
 export 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}',
@@ -30,6 +42,53 @@ export const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES = [
 ] as const;
 
 export function registerOpenFairyGuiBackendResources(server: McpServer, runtime: OpenFairyGuiBackendRuntime): void {
+	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: URL, id: string): ReadResourceResult {
+		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: undefined }),
+		{ 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: undefined }),
+		{ 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: undefined }),
+		{ 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: undefined }),
+		{ 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,

package/src/server.ts

@@ -1,8 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ListToolsRequestSchema, ToolSchema, type Tool } from '@modelcontextprotocol/sdk/types.js';
 import { createNodeBackendRuntime } from '@openfairygui/backend/node';
 import { createRequire } from 'node:module';
+import { z } from 'zod';
 import { registerOpenFairyGuiBackendPrompts } from './prompt-definitions.js';
 import { registerOpenFairyGuiBackendResources } from './resource-definitions.js';
+import { CONTRACT_SNAPSHOT } from './contract-schema.js';
 import { callOpenFairyGuiBackendTool, type OpenFairyGuiBackendRuntime } from './tool-handler.js';
 import {
 	OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS,
@@ -35,34 +38,50 @@ const PACKAGE_VERSION = readPackageVersion();
 
 export interface CreateOpenFairyGuiMcpServerOptions {
 	runtime?: OpenFairyGuiBackendRuntime;
+	/** Filesystem roots exposed by the default Node backend runtime. Defaults to process.cwd(). */
+	allowedProjectRoots?: readonly string[];
 	name?: string;
 	version?: string;
 }
 
 export function createOpenFairyGuiMcpServer(options: CreateOpenFairyGuiMcpServerOptions = {}): McpServer {
-	const runtime = options.runtime ?? createNodeBackendRuntime();
+	const runtime = options.runtime ?? createNodeBackendRuntime({
+		allowedProjectRoots: options.allowedProjectRoots ?? [process.cwd()],
+	});
 	const server = new McpServer({
 		name: options.name ?? 'openfairygui-mcp',
 		version: options.version ?? PACKAGE_VERSION,
 	});
 
+	const tools: Tool[] = [];
 	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,
 			{
-				title: definition.title,
-				description: definition.description,
+				...metadata,
 				inputSchema: definition.inputSchema,
 				outputSchema: definition.outputSchema,
-				annotations: definition.annotations,
-				_meta: {
-					'openfairygui/backendMethod': definition.backendMethod,
-					'openfairygui/adapter': 'thin-backend-p2',
-				},
 			},
 			async (args: Record<string, unknown>) => callOpenFairyGuiBackendTool(runtime, definition.name as OpenFairyGuiBackendToolName, 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' }),
+		}));
 	}
+	// The installed Backend catalog is fixed. Reuse local definitions in discovery only;
+	// registered Zod schemas and the handler's structural/budget validation remain unchanged.
+	server.server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: structuredClone(tools) }));
 
 	registerOpenFairyGuiBackendResources(server, runtime);
 	registerOpenFairyGuiBackendPrompts(server);

package/src/stdio.ts

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

package/src/tool-definitions.ts

@@ -1,252 +1,58 @@
-import { z } from 'zod';
+import type { z } from 'zod';
+import type { BackendMethodName } from '@openfairygui/backend';
+import { contractObjectSchema, CONTRACT_SNAPSHOT } from './contract-schema.js';
+import { OPENFAIRYGUI_BACKEND_TOOL_METADATA, type BackendToolMetadata } from './tool-metadata.js';
 
 export const OPENFAIRYGUI_BACKEND_TOOL_PREFIX = 'openfairygui_backend_';
+export type { BackendMethodName };
+export type OpenFairyGuiBackendToolName = typeof OPENFAIRYGUI_BACKEND_TOOL_METADATA[number]['name'];
+export const OPENFAIRYGUI_BACKEND_TOOL_NAMES = OPENFAIRYGUI_BACKEND_TOOL_METADATA.map((entry) => entry.name);
 
-export 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',
-] as const;
-
-export type OpenFairyGuiBackendToolName = typeof OPENFAIRYGUI_BACKEND_TOOL_NAMES[number];
-
-export type BackendMethodName =
-	| 'getCapabilities'
-	| 'openSession'
-	| 'openProjectSession'
-	| 'getSession'
-	| 'getProjectOutline'
-	| 'validateSession'
-	| 'applyTransaction'
-	| 'saveSession'
-	| 'materializeSession'
-	| 'closeSession'
-	| 'getEvents'
-	| 'getJob'
-	| 'listJobs'
-	| 'cancelJob'
-	| 'getCacheSnapshot'
-	| 'refreshCache';
-
-export interface OpenFairyGuiBackendToolDefinition {
+export interface OpenFairyGuiBackendToolDefinition extends BackendToolMetadata {
 	name: OpenFairyGuiBackendToolName;
-	backendMethod: BackendMethodName;
-	title: string;
-	description: string;
 	inputSchema: z.ZodObject;
 	outputSchema: z.ZodObject;
-	annotations: {
-		readOnlyHint?: boolean;
-		destructiveHint?: boolean;
-		idempotentHint?: boolean;
-		openWorldHint?: boolean;
-	};
 }
 
-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();
-
-export const OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA = z.object({
-	backendResult: z.object({
-		ok: z.boolean(),
-		data: z.unknown().optional(),
-		error: z.unknown().optional(),
-		meta: z.unknown().optional(),
-	}).passthrough(),
-});
+export function isOpenFairyGuiMcpPayloadWithinBudget(root: unknown): boolean {
+	const pending: Array<{ value: unknown; depth: number }> = [{ value: root, depth: 0 }];
+	let nodes = 0;
+	while (pending.length > 0) {
+		const { value, depth } = pending.pop()!;
+		nodes += 1;
+		if (nodes > 100_000 || depth > 32) return false;
+		if (value === null || typeof value === 'boolean') continue;
+		if (typeof value === 'number') {
+			if (!Number.isFinite(value)) return false;
+			continue;
+		}
+		if (typeof value === 'string') {
+			if (value.length > 1_000_000) return false;
+			continue;
+		}
+		if (value instanceof Uint8Array) {
+			if (value.byteLength > 8 * 1024 * 1024) return false;
+			continue;
+		}
+		if (Array.isArray(value)) {
+			if (value.length > 10_000) return false;
+			for (const child of value) pending.push({ value: child, depth: depth + 1 });
+			continue;
+		}
+		if (typeof value !== 'object') return false;
+		const entries = Object.entries(value);
+		if (entries.length > 10_000 || entries.some(([key]) => key.length > 256)) return false;
+		for (const [, child] of entries) pending.push({ value: child, depth: depth + 1 });
+	}
+	return true;
+}
 
-export const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
-	{
-		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, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_open_session',
-		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, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_open_project_session',
-		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, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_get_session',
-		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, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_get_project_outline',
-		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_validate_session',
-		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_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,
-		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
-	},
-	{
-		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,
-		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_materialize_session',
-		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, idempotentHint: false, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_close_session',
-		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, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_get_events',
-		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, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_get_job',
-		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, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_list_jobs',
-		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, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_cancel_job',
-		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, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_get_cache_snapshot',
-		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, openWorldHint: false },
-	},
-	{
-		name: 'openfairygui_backend_refresh_cache',
-		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, openWorldHint: false },
-	},
-] as const satisfies readonly OpenFairyGuiBackendToolDefinition[];
+export const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly OpenFairyGuiBackendToolDefinition[] =
+	OPENFAIRYGUI_BACKEND_TOOL_METADATA.map((metadata) => {
+		const contract = CONTRACT_SNAPSHOT.tools[metadata.backendMethod];
+		return {
+			...metadata,
+			inputSchema: contractObjectSchema(contract.input),
+			outputSchema: contractObjectSchema(contract.output),
+		};
+	});