@openfairygui/mcp 0.2.0-alpha.1 → 0.2.0-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenFairyGUI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.cts

@@ -1,17 +1,9 @@
 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 { BackendRuntime } from "@openfairygui/backend";
 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_open_project_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"];
@@ -342,7 +334,16 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
 }];
 //#endregion
 //#region src/tool-handler.d.ts
-declare function callOpenFairyGuiBackendTool(runtime: BackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>): Promise<CallToolResult>;
+type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, 'getCapabilities' | 'openSession' | 'openProjectSession' | 'getSession' | 'applyTransaction' | 'saveSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache'>;
+declare function callOpenFairyGuiBackendTool(runtime: OpenFairyGuiBackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>): Promise<CallToolResult>;
+//#endregion
+//#region src/server.d.ts
+interface CreateOpenFairyGuiMcpServerOptions {
+  runtime?: OpenFairyGuiBackendRuntime;
+  name?: string;
+  version?: string;
+}
+declare function createOpenFairyGuiMcpServer(options?: CreateOpenFairyGuiMcpServerOptions): McpServer;
 //#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"];
@@ -378,4 +379,4 @@ declare const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS: readonly [{
 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 };
+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 OpenFairyGuiBackendRuntime, type OpenFairyGuiBackendToolDefinition, type OpenFairyGuiBackendToolName, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer };

package/dist/index.d.mts

@@ -1,17 +1,9 @@
 import { connectOpenFairyGuiMcpStdio } from "./stdio.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { BackendRuntime } from "@openfairygui/backend";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { BackendRuntime } from "@openfairygui/backend";
 
-//#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_open_project_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"];
@@ -342,7 +334,16 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
 }];
 //#endregion
 //#region src/tool-handler.d.ts
-declare function callOpenFairyGuiBackendTool(runtime: BackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>): Promise<CallToolResult>;
+type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, 'getCapabilities' | 'openSession' | 'openProjectSession' | 'getSession' | 'applyTransaction' | 'saveSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache'>;
+declare function callOpenFairyGuiBackendTool(runtime: OpenFairyGuiBackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>): Promise<CallToolResult>;
+//#endregion
+//#region src/server.d.ts
+interface CreateOpenFairyGuiMcpServerOptions {
+  runtime?: OpenFairyGuiBackendRuntime;
+  name?: string;
+  version?: string;
+}
+declare function createOpenFairyGuiMcpServer(options?: CreateOpenFairyGuiMcpServerOptions): McpServer;
 //#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"];
@@ -378,4 +379,4 @@ declare const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS: readonly [{
 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 };
+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 OpenFairyGuiBackendRuntime, type OpenFairyGuiBackendToolDefinition, type OpenFairyGuiBackendToolName, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer };

package/package.json

@@ -1,85 +1,85 @@
 {
-	"name": "@openfairygui/mcp",
-	"version": "0.2.0-alpha.1",
-	"description": "FairyGUI Headless Authoring SDK - MCP server adapter for the backend runtime.",
-	"author": "OpenFairyGUI Contributors",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/OpenFairyGUI/OpenFairyGUI.git",
-		"directory": "packages/mcp"
-	},
-	"homepage": "https://github.com/OpenFairyGUI/OpenFairyGUI#readme",
-	"bugs": {
-		"url": "https://github.com/OpenFairyGUI/OpenFairyGUI/issues"
-	},
-	"type": "module",
-	"sideEffects": false,
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.mjs",
-	"types": "./dist/index.d.mts",
-	"exports": {
-		".": {
-			"require": {
-				"types": "./dist/index.d.cts",
-				"default": "./dist/index.cjs"
-			},
-			"default": {
-				"types": "./dist/index.d.mts",
-				"default": "./dist/index.mjs"
-			}
-		},
-		"./stdio": {
-			"require": {
-				"types": "./dist/stdio.d.cts",
-				"default": "./dist/stdio.cjs"
-			},
-			"default": {
-				"types": "./dist/stdio.d.mts",
-				"default": "./dist/stdio.mjs"
-			}
-		}
-	},
-	"bin": {
-		"ofgui-mcp": "bin/ofgui-mcp.cjs"
-	},
-	"scripts": {
-		"build": "tsdown src/index.ts src/stdio.ts --format esm,cjs --platform node --external node:fs --external node:path --external node:fs/promises --env.PACKAGE_VERSION=$npm_package_version",
-		"build:watch": "tsdown src/index.ts src/stdio.ts --watch --format esm,cjs --platform node --env.PACKAGE_VERSION=$npm_package_version",
-		"test": "ava test/**/*.test.ts --no-worker-threads"
-	},
-	"files": [
-		"dist/",
-		"bin/",
-		"src/"
-	],
-	"keywords": [
-		"fairygui",
-		"mcp",
-		"model-context-protocol",
-		"backend",
-		"authoring"
-	],
-	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.29.0",
-		"@openfairygui/backend": "workspace:*",
-		"zod": "^4.3.6"
-	},
-	"devDependencies": {
-		"@openfairygui/core": "workspace:*",
-		"ava": "^7.0.0",
-		"tsx": "^4.0.0"
-	},
-	"ava": {
-		"extensions": {
-			"ts": "module"
-		},
-		"nodeArguments": [
-			"--import",
-			"tsx/esm"
-		],
-		"files": [
-			"test/**/*.test.ts"
-		]
-	}
-}
+  "name": "@openfairygui/mcp",
+  "version": "0.2.0-alpha.3",
+  "description": "FairyGUI Headless Authoring SDK - MCP server adapter for the backend runtime.",
+  "author": "OpenFairyGUI Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenFairyGUI/OpenFairyGUI.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/OpenFairyGUI/OpenFairyGUI#readme",
+  "bugs": {
+    "url": "https://github.com/OpenFairyGUI/OpenFairyGUI/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "default": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "./stdio": {
+      "require": {
+        "types": "./dist/stdio.d.cts",
+        "default": "./dist/stdio.cjs"
+      },
+      "default": {
+        "types": "./dist/stdio.d.mts",
+        "default": "./dist/stdio.mjs"
+      }
+    }
+  },
+  "bin": {
+    "ofgui-mcp": "bin/ofgui-mcp.cjs"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "fairygui",
+    "mcp",
+    "model-context-protocol",
+    "backend",
+    "authoring"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6",
+    "@openfairygui/backend": "0.2.0-alpha.3"
+  },
+  "devDependencies": {
+    "ava": "^7.0.0",
+    "tsx": "^4.0.0",
+    "@openfairygui/core": "0.2.0-alpha.3"
+  },
+  "ava": {
+    "extensions": {
+      "ts": "module"
+    },
+    "nodeArguments": [
+      "--import",
+      "tsx/esm"
+    ],
+    "files": [
+      "test/**/*.test.ts"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/stdio.ts --format esm,cjs --platform node --external node:fs --external node:path --external node:fs/promises --env.PACKAGE_VERSION=$npm_package_version",
+    "build:watch": "tsdown src/index.ts src/stdio.ts --watch --format esm,cjs --platform node --env.PACKAGE_VERSION=$npm_package_version",
+    "test": "ava test/**/*.test.ts --no-worker-threads"
+  }
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export {
 } from './stdio.js';
 export {
 	callOpenFairyGuiBackendTool,
+	type OpenFairyGuiBackendRuntime,
 } from './tool-handler.js';
 export {
 	OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS,

package/src/resource-definitions.ts

@@ -1,6 +1,6 @@
 import { ResourceTemplate, type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
-import type { BackendRuntime } from '@openfairygui/backend';
+import type { OpenFairyGuiBackendRuntime } from './tool-handler.js';
 
 const JSON_MIME_TYPE = 'application/json';
 
@@ -28,7 +28,7 @@ export const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES = [
 	'openfairygui://backend/job/{sessionId}/{jobId}',
 ] as const;
 
-export function registerOpenFairyGuiBackendResources(server: McpServer, runtime: BackendRuntime): void {
+export function registerOpenFairyGuiBackendResources(server: McpServer, runtime: OpenFairyGuiBackendRuntime): void {
 	server.registerResource(
 		'openfairygui_backend_capabilities',
 		OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI,

package/src/server.ts

@@ -1,9 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { BackendRuntime } from '@openfairygui/backend';
 import { createNodeBackendRuntime } from '@openfairygui/backend/node';
 import { registerOpenFairyGuiBackendPrompts } from './prompt-definitions.js';
 import { registerOpenFairyGuiBackendResources } from './resource-definitions.js';
-import { callOpenFairyGuiBackendTool } from './tool-handler.js';
+import { callOpenFairyGuiBackendTool, type OpenFairyGuiBackendRuntime } from './tool-handler.js';
 import {
 	OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS,
 	type OpenFairyGuiBackendToolName,
@@ -12,7 +11,7 @@ import {
 const PACKAGE_VERSION = process.env.npm_package_version ?? '0.2.0-alpha.0';
 
 export interface CreateOpenFairyGuiMcpServerOptions {
-	runtime?: BackendRuntime;
+	runtime?: OpenFairyGuiBackendRuntime;
 	name?: string;
 	version?: string;
 }

package/src/tool-handler.ts

@@ -2,6 +2,23 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { BackendRuntime } from '@openfairygui/backend';
 import type { OpenFairyGuiBackendToolName } from './tool-definitions.js';
 
+export type OpenFairyGuiBackendRuntime = Pick<
+	BackendRuntime,
+	| 'getCapabilities'
+	| 'openSession'
+	| 'openProjectSession'
+	| 'getSession'
+	| 'applyTransaction'
+	| 'saveSession'
+	| 'closeSession'
+	| 'getEvents'
+	| 'getJob'
+	| 'listJobs'
+	| 'cancelJob'
+	| 'getCacheSnapshot'
+	| 'refreshCache'
+>;
+
 function jsonResult(payload: unknown, isError = false): CallToolResult {
 	return {
 		content: [
@@ -25,7 +42,7 @@ function isBackendFailure(value: unknown): boolean {
 }
 
 export async function callOpenFairyGuiBackendTool(
-	runtime: BackendRuntime,
+	runtime: OpenFairyGuiBackendRuntime,
 	name: OpenFairyGuiBackendToolName,
 	input: Record<string, unknown>,
 ): Promise<CallToolResult> {