@openfairygui/mcp 0.3.1 → 0.5.0-alpha.1

package/src/tool-handler.ts

@@ -3,34 +3,21 @@ import {
 	BACKEND_CAPABILITY_SCHEMA_VERSION,
 	BACKEND_CONTRACT_VERSION,
 	type BackendRuntime,
+	type BackendMethodName,
 } from '@openfairygui/backend';
 import {
 	isOpenFairyGuiMcpPayloadWithinBudget,
+	OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS,
 	type OpenFairyGuiBackendToolName,
 } from './tool-definitions.js';
 
-export type OpenFairyGuiBackendRuntime = Pick<
-	BackendRuntime,
-	| 'getCapabilities'
-	| 'openSession'
-	| 'openProjectSession'
-	| 'getSession'
-	| 'getProjectOutline'
-	| 'validateSession'
-	| 'applyTransaction'
-	| 'saveSession'
-	| 'materializeSession'
-	| 'closeSession'
-	| 'getEvents'
-	| 'getJob'
-	| 'listJobs'
-	| 'cancelJob'
-	| 'getCacheSnapshot'
-	| 'refreshCache'
->;
+import { decodeToolBytes, CONTRACT_SNAPSHOT } from './contract-schema.js';
+import type { McpUnhandledFailure, McpResponseBudgetFailure } from './tool-metadata.js';
 
-function jsonResult(payload: unknown, isError = false): CallToolResult {
-	const text = JSON.stringify(payload, null, 2);
+export type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, BackendMethodName>;
+
+function jsonResult(payload: unknown, isError = false, compact = false): CallToolResult {
+	const text = JSON.stringify(payload, (_key, value) => value instanceof Uint8Array ? [...value] : value, compact ? undefined : 2);
 	const wirePayload = JSON.parse(text) as unknown;
 	return {
 		content: [
@@ -53,7 +40,7 @@ function isBackendFailure(value: unknown): boolean {
 		&& (value as { ok?: unknown }).ok === false;
 }
 
-function unhandledBackendFailure(startedAt: number): unknown {
+function unhandledBackendFailure(startedAt: number): McpUnhandledFailure {
 	return {
 		ok: false,
 		meta: {
@@ -80,121 +67,23 @@ export async function callOpenFairyGuiBackendTool(
 	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 parsed = definition.inputSchema.parse(input) as Record<string, unknown>;
+	const decoded = decodeToolBytes(parsed, CONTRACT_SNAPSHOT.tools[definition.backendMethod].bytePaths);
 	const startedAt = Date.now();
-	let result: unknown;
 	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 as Parameters<BackendRuntime['openProjectSession']>[0]['project'],
-				sessionId: input.sessionId === undefined ? undefined : String(input.sessionId),
-				canonicalProjectPath: input.canonicalProjectPath === undefined ? undefined : String(input.canonicalProjectPath),
-				canonicalPathKey: input.canonicalPathKey === undefined ? undefined : 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 as Parameters<BackendRuntime['applyTransaction']>[0]['operations']).map(
-				(operation) => operation.kind === 'replaceResourceBytes'
-					? { ...operation, sourceBytes: new Uint8Array(operation.sourceBytes) }
-					: operation,
-			);
-			result = await runtime.applyTransaction({
-				sessionId: String(input.sessionId),
-				expectedRevision: Number(input.expectedRevision),
-				operations,
-			});
-			break;
-		}
-		case 'openfairygui_backend_save_session':
-			result = await runtime.saveSession({
-				sessionId: String(input.sessionId),
-				expectedRevision: input.expectedRevision === undefined ? undefined : Number(input.expectedRevision),
-				targetPath: input.targetPath === undefined ? undefined : String(input.targetPath),
-				force: input.force === undefined ? undefined : Boolean(input.force),
-				mode: input.mode as Parameters<BackendRuntime['saveSession']>[0]['mode'],
-			});
-			break;
-		case 'openfairygui_backend_materialize_session':
-			result = await runtime.materializeSession({
-				sessionId: String(input.sessionId),
-				expectedRevision: input.expectedRevision === undefined ? undefined : Number(input.expectedRevision),
-				mode: input.mode as Parameters<BackendRuntime['materializeSession']>[0]['mode'],
-				reason: input.reason === undefined ? undefined : 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 === undefined ? undefined : String(input.after),
-				limit: input.limit === undefined ? undefined : 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 as Parameters<BackendRuntime['listJobs']>[0]['status'],
-				kind: input.kind as Parameters<BackendRuntime['listJobs']>[0]['kind'],
-				limit: input.limit === undefined ? undefined : 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 as Parameters<BackendRuntime['refreshCache']>[0]['reason'],
-			});
-			break;
-			default: {
-				const exhaustive: never = name;
-				throw new Error(`Unknown OpenFairyGUI backend MCP tool: ${exhaustive}`);
-			}
+		const result = await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === 'getCapabilities' ? [] : [decoded]);
+		let response = jsonResult(result, isBackendFailure(result), definition.maxResponseBytes !== undefined);
+		if (definition.maxResponseBytes !== undefined && new TextEncoder().encode(JSON.stringify(response)).byteLength > definition.maxResponseBytes) {
+			response = jsonResult({
+				...unhandledBackendFailure(startedAt),
+				error: { code: 'mcp_response_budget_exceeded', message: 'The complete MCP tool response exceeds its byte limit.', maxBytes: definition.maxResponseBytes },
+			} satisfies McpResponseBudgetFailure, true);
 		}
+		definition.outputSchema.parse(response.structuredContent);
+		return response;
 	} catch {
 		return jsonResult(unhandledBackendFailure(startedAt), true);
 	}
-	return jsonResult(result, isBackendFailure(result));
 }

package/src/tool-metadata.ts

@@ -0,0 +1,181 @@
+import type { BackendMethodName, BackendResponseMeta } from '@openfairygui/backend';
+
+export interface BackendToolMetadata {
+	name: `openfairygui_backend_${string}`;
+	backendMethod: BackendMethodName;
+	title: string;
+	description: string;
+	/** Bound the complete CallToolResult JSON; bounded reads use compact text JSON. */
+	maxResponseBytes?: number;
+	annotations: {
+		readOnlyHint?: boolean;
+		destructiveHint?: boolean;
+		idempotentHint?: boolean;
+		openWorldHint?: boolean;
+	};
+}
+
+/** MCP transport failure, not a Backend domain error. */
+export interface McpUnhandledFailure {
+	ok: false;
+	meta: BackendResponseMeta;
+	error: { code: 'backend_unhandled_error'; message: string };
+}
+
+export interface McpResponseBudgetFailure {
+	ok: false;
+	meta: BackendResponseMeta;
+	error: { code: 'mcp_response_budget_exceeded'; message: string; maxBytes: number };
+}
+
+/** Host objects cannot cross JSON; materialize keeps its existing MCP target boundary. */
+export const MCP_OMITTED_INPUT_FIELDS = {
+	openProjectSession: ['storage'],
+	saveSession: ['fileSystem'],
+	materializeSession: ['storage', 'fileSystem', 'targetPath'],
+} as const;
+
+export 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.',
+		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.',
+		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.',
+		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.',
+		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.',
+		annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+	},
+	{
+		name: 'openfairygui_backend_query_entity',
+		backendMethod: 'queryEntity',
+		title: 'Query Entity Properties',
+		description: 'Read revision-bound project/package settings, resource, component-property, display-node, controller (including pages/actions), or transition (including items) snapshots. Project queries use only kind; other queries use formal selectors. Settings snapshots include the complete settings payload for updateProjectSettings/updatePackageSettings. No source bytes; fixed projection with explicit response limits.',
+		annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+	},
+	{
+		name: 'openfairygui_backend_read_session_state',
+		backendMethod: 'readSessionState',
+		title: 'Read Session State',
+		description: 'Read a detached copy of the currently committed public UAM model without primary asset sourceBytes, with revision, dirty state and source-read diagnostics. Optional expectedRevision rejects stale reads. Does not hydrate, write, reserve history or guarantee downstream usability. Complete tool response is limited to 16 MiB.',
+		maxResponseBytes: 16777216,
+		annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+	},
+	{
+		name: 'openfairygui_backend_read_resource_bytes',
+		backendMethod: 'readResourceBytes',
+		title: 'Read Resource Bytes',
+		description: 'Read a detached copy of one asset resource primary sourceBytes already held in the session, using exact packageId/resourceId and the required model edit revision. No filesystem hydration or auxiliary-file discovery. Stale reads require restarting the model/bytes read. Complete tool response is limited to 16 MiB.',
+		maxResponseBytes: 16777216,
+		annotations: { readOnlyHint: true, idempotentHint: true, 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.',
+		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, openWorldHint: false },
+	},
+	{
+		name: 'openfairygui_backend_apply_transaction',
+		backendMethod: 'applyTransaction',
+		title: 'Apply UAM Transaction',
+		description: 'Apply a bounded, revision-checked UAM operation batch using the Core transaction discriminants.',
+		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 through its coordinated save path; Node uses an atomic staged directory swap.',
+		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.',
+		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.',
+		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.',
+		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.',
+		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.',
+		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.',
+		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.',
+		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.',
+		annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: false },
+	},
+] as const satisfies readonly BackendToolMetadata[];