@openfairygui/mcp 0.2.0-alpha.0

package/README.md

@@ -0,0 +1,83 @@
+# @openfairygui/mcp
+
+MCP server adapter for OpenFairyGUI backend runtime services.
+
+## Purpose
+
+`@openfairygui/mcp` is a thin Model Context Protocol adapter over `@openfairygui/backend`.
+
+It maps the backend P2 runtime surface into MCP tools:
+
+- `getCapabilities`
+- `openSession`
+- `getSession`
+- `applyTransaction`
+- `saveSession`
+- `closeSession`
+- `getEvents`
+- `getJob`
+- `listJobs`
+- `cancelJob`
+- `getCacheSnapshot`
+- `refreshCache`
+
+Each tool exposes a shared output schema for `structuredContent.backendResult`, preserving the backend envelope shape:
+
+- `ok`
+- `data?`
+- `error?`
+- `meta?`
+
+P1 also registers MCP-native ergonomics around the same backend surface:
+
+- read-only resources for identity snapshots:
+  - `openfairygui://backend/capabilities`
+  - `openfairygui://backend/session/{sessionId}`
+  - `openfairygui://backend/cache/{sessionId}`
+  - `openfairygui://backend/job/{sessionId}/{jobId}`
+- prompts for capability inspection, session open/inspect, revision-checked transactions, save, and runtime polling
+
+Resources return `application/json` text containing the unchanged backend result envelope. Parameterized polling remains tool-based: `getEvents` and `listJobs` are not exposed as resource URI query grammars.
+
+It does **not** redefine transaction selectors, transaction operations, path policy, session semantics, job semantics, cache semantics, or backend error envelopes. Those remain owned by `@openfairygui/backend`, `@openfairygui/functions`, and `@openfairygui/core`.
+
+It also does **not** activate artifact publish/restore jobs, subscriptions, persistent jobs, or cache-as-source-of-truth behavior. MCP roots may be useful client context, but this package does not enforce roots or duplicate backend path canonicalization; backend path policy remains authoritative.
+
+## Usage
+
+```ts
+import { createOpenFairyGuiMcpServer } from '@openfairygui/mcp';
+
+const server = createOpenFairyGuiMcpServer();
+```
+
+For stdio clients, use the package binary:
+
+```bash
+ofgui-mcp
+```
+
+Example local MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "openfairygui": {
+      "command": "ofgui-mcp"
+    }
+  }
+}
+```
+
+When running from a workspace checkout before publishing, point the command at the package binary after building:
+
+```json
+{
+  "mcpServers": {
+    "openfairygui": {
+      "command": "node",
+      "args": ["./packages/mcp/bin/ofgui-mcp.cjs"]
+    }
+  }
+}
+```

package/bin/ofgui-mcp.cjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const entry = path.resolve(__dirname, '../dist/stdio.mjs');
+
+import(pathToFileURL(entry).href)
+	.then((module) => module.connectOpenFairyGuiMcpStdio())
+	.catch((error) => {
+		console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+		process.exitCode = 1;
+	});

package/dist/index.cjs

@@ -0,0 +1,13 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_stdio = require("./stdio-BDHxauin.cjs");
+exports.OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = require_stdio.OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI;
+exports.OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS = require_stdio.OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS;
+exports.OPENFAIRYGUI_BACKEND_PROMPT_NAMES = require_stdio.OPENFAIRYGUI_BACKEND_PROMPT_NAMES;
+exports.OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES = require_stdio.OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES;
+exports.OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = require_stdio.OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS;
+exports.OPENFAIRYGUI_BACKEND_TOOL_NAMES = require_stdio.OPENFAIRYGUI_BACKEND_TOOL_NAMES;
+exports.OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA = require_stdio.OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA;
+exports.OPENFAIRYGUI_BACKEND_TOOL_PREFIX = require_stdio.OPENFAIRYGUI_BACKEND_TOOL_PREFIX;
+exports.callOpenFairyGuiBackendTool = require_stdio.callOpenFairyGuiBackendTool;
+exports.connectOpenFairyGuiMcpStdio = require_stdio.connectOpenFairyGuiMcpStdio;
+exports.createOpenFairyGuiMcpServer = require_stdio.createOpenFairyGuiMcpServer;

package/dist/index.d.cts

@@ -0,0 +1,357 @@
+import { connectOpenFairyGuiMcpStdio } from "./stdio.cjs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BackendRuntime } from "@openfairygui/backend";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+
+//#region src/server.d.ts
+interface CreateOpenFairyGuiMcpServerOptions {
+  runtime?: BackendRuntime;
+  name?: string;
+  version?: string;
+}
+declare function createOpenFairyGuiMcpServer(options?: CreateOpenFairyGuiMcpServerOptions): McpServer;
+//#endregion
+//#region src/tool-definitions.d.ts
+declare const OPENFAIRYGUI_BACKEND_TOOL_PREFIX = "openfairygui_backend_";
+declare const OPENFAIRYGUI_BACKEND_TOOL_NAMES: readonly ["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"];
+type OpenFairyGuiBackendToolName = typeof OPENFAIRYGUI_BACKEND_TOOL_NAMES[number];
+type BackendMethodName = 'getCapabilities' | 'openSession' | 'getSession' | 'applyTransaction' | 'saveSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache';
+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;
+  };
+}
+declare const OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA: z.ZodObject<{
+  backendResult: z.ZodObject<{
+    ok: z.ZodBoolean;
+    data: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodUnknown>;
+    meta: z.ZodOptional<z.ZodUnknown>;
+  }, z.core.$loose>;
+}, z.core.$strip>;
+declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
+  readonly name: "openfairygui_backend_get_capabilities";
+  readonly backendMethod: "getCapabilities";
+  readonly title: "Get Backend Capabilities";
+  readonly description: "Return the OpenFairyGUI backend capability, version, and service-plane snapshot.";
+  readonly inputSchema: z.ZodObject<{}, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_open_session";
+  readonly backendMethod: "openSession";
+  readonly title: "Open Backend Session";
+  readonly description: "Open a FairyGUI project through BackendRuntime and acquire its backend-local session lock.";
+  readonly inputSchema: z.ZodObject<{
+    projectPath: z.ZodString;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: false;
+    readonly idempotentHint: false;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_get_session";
+  readonly backendMethod: "getSession";
+  readonly title: "Get Backend Session";
+  readonly description: "Return a backend session snapshot by session id.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_apply_transaction";
+  readonly backendMethod: "applyTransaction";
+  readonly title: "Apply UAM Transaction";
+  readonly description: "Apply a backend revision-checked UAM operation batch without redefining selector or operation grammar.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    operations: z.ZodArray<z.ZodUnknown>;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly idempotentHint: false;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_save_session";
+  readonly backendMethod: "saveSession";
+  readonly title: "Save Backend Session";
+  readonly description: "Write the current backend session back through the backend coordinated non-atomic save path.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    expectedRevision: z.ZodOptional<z.ZodNumber>;
+    targetPath: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly idempotentHint: false;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_close_session";
+  readonly backendMethod: "closeSession";
+  readonly title: "Close Backend Session";
+  readonly description: "Close a backend session and release its backend-local advisory lock.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: false;
+    readonly idempotentHint: false;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_get_events";
+  readonly backendMethod: "getEvents";
+  readonly title: "Get Runtime Events";
+  readonly description: "Poll backend runtime events for a session using the backend P2 event cursor contract.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_get_job";
+  readonly backendMethod: "getJob";
+  readonly title: "Get Runtime Job";
+  readonly description: "Return a backend runtime job snapshot by session and backend-local job id.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_list_jobs";
+  readonly backendMethod: "listJobs";
+  readonly title: "List Runtime Jobs";
+  readonly description: "List backend runtime jobs for a session with backend P2 status/kind filters.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+      queued: "queued";
+      running: "running";
+      completed: "completed";
+      failed: "failed";
+      cancelled: "cancelled";
+      active: "active";
+      terminal: "terminal";
+    }>>;
+    kind: z.ZodOptional<z.ZodLiteral<"cache.refresh">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_cancel_job";
+  readonly backendMethod: "cancelJob";
+  readonly title: "Cancel Runtime Job";
+  readonly description: "Request cooperative cancellation for a backend runtime job.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: false;
+    readonly idempotentHint: false;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_get_cache_snapshot";
+  readonly backendMethod: "getCacheSnapshot";
+  readonly title: "Get Cache Snapshot";
+  readonly description: "Return the backend P2 derived read-only cache snapshot for a session.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_refresh_cache";
+  readonly backendMethod: "refreshCache";
+  readonly title: "Refresh Cache";
+  readonly description: "Create a backend P2 cache.refresh job for the session cache snapshot.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    reason: z.ZodOptional<z.ZodEnum<{
+      manual: "manual";
+      session_open: "session_open";
+      after_save: "after_save";
+    }>>;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: false;
+    readonly idempotentHint: false;
+    readonly openWorldHint: false;
+  };
+}];
+//#endregion
+//#region src/tool-handler.d.ts
+declare function callOpenFairyGuiBackendTool(runtime: BackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>): Promise<CallToolResult>;
+//#endregion
+//#region src/prompt-definitions.d.ts
+declare const OPENFAIRYGUI_BACKEND_PROMPT_NAMES: readonly ["openfairygui_inspect_capabilities", "openfairygui_open_and_inspect_session", "openfairygui_plan_revision_checked_transaction", "openfairygui_save_session", "openfairygui_poll_runtime_state"];
+type OpenFairyGuiBackendPromptName = typeof OPENFAIRYGUI_BACKEND_PROMPT_NAMES[number];
+declare const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS: readonly [{
+  readonly name: "openfairygui_inspect_capabilities";
+  readonly title: "Inspect OpenFairyGUI Backend Capabilities";
+  readonly description: "Guide a client through the capability and version discovery tool.";
+  readonly text: string;
+}, {
+  readonly name: "openfairygui_open_and_inspect_session";
+  readonly title: "Open and Inspect an OpenFairyGUI Session";
+  readonly description: "Guide a client through opening and reading a backend session.";
+  readonly text: string;
+}, {
+  readonly name: "openfairygui_plan_revision_checked_transaction";
+  readonly title: "Plan a Revision-Checked OpenFairyGUI Transaction";
+  readonly description: "Guide a client through backend-owned revision checks without inventing operation grammar.";
+  readonly text: string;
+}, {
+  readonly name: "openfairygui_save_session";
+  readonly title: "Save an OpenFairyGUI Backend Session";
+  readonly description: "Guide a client through coordinated backend save semantics.";
+  readonly text: string;
+}, {
+  readonly name: "openfairygui_poll_runtime_state";
+  readonly title: "Poll OpenFairyGUI Runtime State";
+  readonly description: "Guide a client through event, job, and cache polling tools.";
+  readonly text: string;
+}];
+//#endregion
+//#region src/resource-definitions.d.ts
+declare const OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = "openfairygui://backend/capabilities";
+declare const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES: readonly ["openfairygui://backend/session/{sessionId}", "openfairygui://backend/cache/{sessionId}", "openfairygui://backend/job/{sessionId}/{jobId}"];
+//#endregion
+export { type BackendMethodName, type CreateOpenFairyGuiMcpServerOptions, OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI, OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS, OPENFAIRYGUI_BACKEND_PROMPT_NAMES, OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES, OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS, OPENFAIRYGUI_BACKEND_TOOL_NAMES, OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA, OPENFAIRYGUI_BACKEND_TOOL_PREFIX, type OpenFairyGuiBackendPromptName, type OpenFairyGuiBackendToolDefinition, type OpenFairyGuiBackendToolName, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer };