@openfairygui/mcp 0.2.0-alpha.0

package/src/prompt-definitions.ts

@@ -0,0 +1,106 @@
+import type { GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+
+export const OPENFAIRYGUI_BACKEND_PROMPT_NAMES = [
+	'openfairygui_inspect_capabilities',
+	'openfairygui_open_and_inspect_session',
+	'openfairygui_plan_revision_checked_transaction',
+	'openfairygui_save_session',
+	'openfairygui_poll_runtime_state',
+] as const;
+
+export type OpenFairyGuiBackendPromptName = typeof OPENFAIRYGUI_BACKEND_PROMPT_NAMES[number];
+
+interface OpenFairyGuiBackendPromptDefinition {
+	name: OpenFairyGuiBackendPromptName;
+	title: string;
+	description: string;
+	text: string;
+}
+
+export const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS = [
+	{
+		name: 'openfairygui_inspect_capabilities',
+		title: 'Inspect OpenFairyGUI Backend Capabilities',
+		description: 'Guide a client through the capability and version discovery tool.',
+		text: [
+			'Use openfairygui_backend_get_capabilities first.',
+			'Read contractVersion, capabilitySchemaVersion, capability planes, methods, and runtime non-goals from the backend envelope.',
+			'Do not infer artifact publish/restore, subscriptions, persistent jobs, or cache source-of-truth support when the backend marks them unsupported.',
+		].join('\n'),
+	},
+	{
+		name: 'openfairygui_open_and_inspect_session',
+		title: 'Open and Inspect an OpenFairyGUI Session',
+		description: 'Guide a client through opening and reading a backend session.',
+		text: [
+			'Use openfairygui_backend_open_session with a projectPath, then use openfairygui_backend_get_session with the returned sessionId.',
+			'Backend path policy remains authoritative for project paths and save targets; MCP roots are only client context in this package.',
+			'Close the session with openfairygui_backend_close_session when finished.',
+		].join('\n'),
+	},
+	{
+		name: 'openfairygui_plan_revision_checked_transaction',
+		title: 'Plan a Revision-Checked OpenFairyGUI Transaction',
+		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.',
+			'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.',
+		].join('\n'),
+	},
+	{
+		name: 'openfairygui_save_session',
+		title: 'Save an OpenFairyGUI Backend Session',
+		description: 'Guide a client through coordinated backend save semantics.',
+		text: [
+			'Use openfairygui_backend_save_session with sessionId and expectedRevision when available.',
+			'Backend path policy remains authoritative for targetPath; MCP does not canonicalize or authorize paths.',
+			'Handle stale revision and partial save failure envelopes from the backend without rewriting their error semantics.',
+		].join('\n'),
+	},
+	{
+		name: 'openfairygui_poll_runtime_state',
+		title: 'Poll OpenFairyGUI Runtime State',
+		description: 'Guide a client through event, job, and cache polling tools.',
+		text: [
+			'Use openfairygui_backend_get_events for polling events with the backend cursor contract.',
+			'Use openfairygui_backend_list_jobs and openfairygui_backend_get_job for in-memory job snapshots.',
+			'Use openfairygui_backend_get_cache_snapshot and openfairygui_backend_refresh_cache for derived read-only cache state.',
+			'Subscriptions, persistent jobs, artifact jobs, and cache-as-source-of-truth behavior are not supported by backend P2.',
+		].join('\n'),
+	},
+] as const satisfies readonly OpenFairyGuiBackendPromptDefinition[];
+
+function promptResult(text: string): GetPromptResult {
+	return {
+		messages: [
+			{
+				role: 'user',
+				content: {
+					type: 'text',
+					text,
+				},
+			},
+		],
+	};
+}
+
+export function registerOpenFairyGuiBackendPrompts(server: {
+	registerPrompt: (
+		name: string,
+		config: { title?: string; description?: string },
+		callback: () => GetPromptResult,
+	) => unknown;
+}): void {
+	for (const definition of OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS) {
+		server.registerPrompt(
+			definition.name,
+			{
+				title: definition.title,
+				description: definition.description,
+			},
+			() => promptResult(definition.text),
+		);
+	}
+}

package/src/resource-definitions.ts

@@ -0,0 +1,82 @@
+import { ResourceTemplate, type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import type { BackendRuntime } from '@openfairygui/backend';
+
+const JSON_MIME_TYPE = 'application/json';
+
+function firstVariable(value: string | string[] | undefined): string {
+	return Array.isArray(value) ? value[0] ?? '' : value ?? '';
+}
+
+function jsonResource(uri: URL, backendResult: unknown): ReadResourceResult {
+	return {
+		contents: [
+			{
+				uri: uri.toString(),
+				mimeType: JSON_MIME_TYPE,
+				text: JSON.stringify(backendResult, null, 2),
+			},
+		],
+	};
+}
+
+export const OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = 'openfairygui://backend/capabilities';
+
+export const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES = [
+	'openfairygui://backend/session/{sessionId}',
+	'openfairygui://backend/cache/{sessionId}',
+	'openfairygui://backend/job/{sessionId}/{jobId}',
+] as const;
+
+export function registerOpenFairyGuiBackendResources(server: McpServer, runtime: BackendRuntime): void {
+	server.registerResource(
+		'openfairygui_backend_capabilities',
+		OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI,
+		{
+			title: 'OpenFairyGUI Backend Capabilities',
+			description: 'Read the backend capability and version envelope as JSON.',
+			mimeType: JSON_MIME_TYPE,
+		},
+		(uri: URL) => jsonResource(uri, runtime.getCapabilities()),
+	);
+
+	server.registerResource(
+		'openfairygui_backend_session',
+		new ResourceTemplate('openfairygui://backend/session/{sessionId}', { list: undefined }),
+		{
+			title: 'OpenFairyGUI Backend Session Snapshot',
+			description: 'Read a backend session envelope by backend-local session id.',
+			mimeType: JSON_MIME_TYPE,
+		},
+		(uri: URL, variables) => jsonResource(uri, runtime.getSession({
+			sessionId: firstVariable(variables.sessionId),
+		})),
+	);
+
+	server.registerResource(
+		'openfairygui_backend_cache',
+		new ResourceTemplate('openfairygui://backend/cache/{sessionId}', { list: undefined }),
+		{
+			title: 'OpenFairyGUI Backend Cache Snapshot',
+			description: 'Read a derived backend cache envelope by backend-local session id.',
+			mimeType: JSON_MIME_TYPE,
+		},
+		(uri: URL, variables) => jsonResource(uri, runtime.getCacheSnapshot({
+			sessionId: firstVariable(variables.sessionId),
+		})),
+	);
+
+	server.registerResource(
+		'openfairygui_backend_job',
+		new ResourceTemplate('openfairygui://backend/job/{sessionId}/{jobId}', { list: undefined }),
+		{
+			title: 'OpenFairyGUI Backend Job Snapshot',
+			description: 'Read a backend runtime job envelope by session id and job id.',
+			mimeType: JSON_MIME_TYPE,
+		},
+		(uri: URL, variables) => jsonResource(uri, runtime.getJob({
+			sessionId: firstVariable(variables.sessionId),
+			jobId: firstVariable(variables.jobId),
+		})),
+	);
+}

package/src/server.ts

@@ -0,0 +1,48 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { BackendRuntime } from '@openfairygui/backend';
+import { registerOpenFairyGuiBackendPrompts } from './prompt-definitions.js';
+import { registerOpenFairyGuiBackendResources } from './resource-definitions.js';
+import { callOpenFairyGuiBackendTool } from './tool-handler.js';
+import {
+	OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS,
+	type OpenFairyGuiBackendToolName,
+} from './tool-definitions.js';
+
+const PACKAGE_VERSION = process.env.npm_package_version ?? '0.2.0-alpha.0';
+
+export interface CreateOpenFairyGuiMcpServerOptions {
+	runtime?: BackendRuntime;
+	name?: string;
+	version?: string;
+}
+
+export function createOpenFairyGuiMcpServer(options: CreateOpenFairyGuiMcpServerOptions = {}): McpServer {
+	const runtime = options.runtime ?? new BackendRuntime();
+	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 as OpenFairyGuiBackendToolName, args as Record<string, unknown>),
+		);
+	}
+
+	registerOpenFairyGuiBackendResources(server, runtime);
+	registerOpenFairyGuiBackendPrompts(server);
+
+	return server;
+}

package/src/stdio.ts

@@ -0,0 +1,15 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { pathToFileURL } from 'node:url';
+import { createOpenFairyGuiMcpServer } from './server.js';
+
+export async function connectOpenFairyGuiMcpStdio(): Promise<void> {
+	const server = createOpenFairyGuiMcpServer();
+	await server.connect(new StdioServerTransport());
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	connectOpenFairyGuiMcpStdio().catch((error: unknown) => {
+		console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+		process.exitCode = 1;
+	});
+}

package/src/tool-definitions.ts

@@ -0,0 +1,196 @@
+import { z } from 'zod';
+
+export const OPENFAIRYGUI_BACKEND_TOOL_PREFIX = 'openfairygui_backend_';
+
+export const OPENFAIRYGUI_BACKEND_TOOL_NAMES = [
+	'openfairygui_backend_get_capabilities',
+	'openfairygui_backend_open_session',
+	'openfairygui_backend_get_session',
+	'openfairygui_backend_apply_transaction',
+	'openfairygui_backend_save_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'
+	| 'getSession'
+	| 'applyTransaction'
+	| 'saveSession'
+	| 'closeSession'
+	| 'getEvents'
+	| 'getJob'
+	| 'listJobs'
+	| 'cancelJob'
+	| 'getCacheSnapshot'
+	| 'refreshCache';
+
+export interface OpenFairyGuiBackendToolDefinition {
+	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 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_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_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(),
+		}),
+		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 advisory 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[];

package/src/tool-handler.ts

@@ -0,0 +1,110 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { BackendRuntime } from '@openfairygui/backend';
+import type { OpenFairyGuiBackendToolName } from './tool-definitions.js';
+
+function jsonResult(payload: unknown, isError = false): CallToolResult {
+	return {
+		content: [
+			{
+				type: 'text',
+				text: JSON.stringify(payload, null, 2),
+			},
+		],
+		structuredContent: {
+			backendResult: payload,
+		},
+		isError,
+	};
+}
+
+function isBackendFailure(value: unknown): boolean {
+	return typeof value === 'object'
+		&& value !== null
+		&& 'ok' in value
+		&& (value as { ok?: unknown }).ok === false;
+}
+
+export async function callOpenFairyGuiBackendTool(
+	runtime: BackendRuntime,
+	name: OpenFairyGuiBackendToolName,
+	input: Record<string, unknown>,
+): Promise<CallToolResult> {
+	let result: unknown;
+	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_get_session':
+			result = runtime.getSession({
+				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 as Parameters<BackendRuntime['applyTransaction']>[0]['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),
+			});
+			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}`);
+		}
+	}
+	return jsonResult(result, isBackendFailure(result));
+}