@openfairygui/mcp 0.5.0-alpha.1 → 0.5.0-alpha.2

package/README.md

@@ -36,7 +36,7 @@ Each tool exposes a method-specific output schema for `structuredContent.backend
 - `error?`
 - `meta?`
 
-The factory advertises the fixed 20-method Backend catalog. Input/output schemas come from the canonical installed contract; discovery uses self-contained draft-07 `definitions`/`$ref` to reuse repeated structures without loosening the 41-operation union, call validators or input budgets. Installed operation documentation remains available through `openfairygui://contracts/operations` and `openfairygui://docs/index`.
+The factory registers the 20-method Backend catalog. The SDK owns dynamic discovery and dispatch, including Host tools added through `server.registerTool()`. Input/output schemas come from the canonical installed contract; discovery uses self-contained draft-07 `definitions`/`$ref` to reuse repeated structures without loosening the 41-operation union, call validators or input budgets. Installed operation documentation remains available through `openfairygui://contracts/operations` and `openfairygui://docs/index`.
 
 P1 also registers MCP-native ergonomics around the same backend surface:
 
@@ -71,6 +71,47 @@ For stdio clients, use the package binary:
 ofgui-mcp
 ```
 
+### Host composition
+
+Pass `instructions` to the factory to publish Host guidance in the SDK initialize handshake.
+
+Use `toolPolicies` to gate selected tools before Backend executes. Each policy declares a synchronous Zod `failureSchema` and a `beforeCall` callback. The callback receives a detached copy of the validated wire input and may be async. Returning `undefined` invokes the original Backend method once with the original input; returning a declared `ok: false` envelope stops the call and produces matching text/`structuredContent.backendResult` with `isError: true`.
+
+```ts
+import { createOpenFairyGuiMcpServer, type OpenFairyGuiMcpToolPolicy } from '@openfairygui/mcp';
+import { z } from 'zod';
+
+const policy: OpenFairyGuiMcpToolPolicy = {
+  failureSchema: z.strictObject({
+    ok: z.literal(false),
+    error: z.strictObject({
+      code: z.literal('save_approval_required'),
+      approvalRequestId: z.string(),
+      approvalPath: z.string(),
+    }),
+  }),
+  beforeCall(input) {
+    // Host-owned grant store: bind the grant to session, revision, operation and all options.
+    if (hostGrants.consume('saveSession', input)) return undefined;
+    return { ok: false, error: {
+      code: 'save_approval_required',
+      approvalRequestId: hostGrants.request('saveSession', input),
+      approvalPath: '/#save-approvals',
+    } };
+  },
+};
+const server = createOpenFairyGuiMcpServer({ runtime, instructions: 'Host writes require owner approval.', toolPolicies: {
+  openfairygui_backend_save_session: policy,
+} });
+server.registerTool('host_probe', { inputSchema: z.object({}) }, async () => ({
+  content: [{ type: 'text', text: 'ok' }],
+}));
+```
+
+`runtime` and `hostGrants` belong to the embedding Host. Configure `materialize_session` separately when it also requires approval; grants must distinguish the two operations. The policy must consume approval before allowing the call and must not call the Backend write itself. Backend still checks revision, paths and disk state after approval; failures are not retried automatically. Read tools without policies do not require grants.
+
+The selected tool's advertised output includes its declared Host failure branch. `_meta['openfairygui/hostPolicy']` marks that extension; the contract digest and installed documentation describe the unchanged Backend branch. Host failures do not become Backend error codes. Unknown tool-policy names fail server construction. Invalid inputs never reach the policy; throwing policies or invalid policy results stop before Backend and return `backend_unhandled_error`. Backend results always pass their canonical schema, even if a Host schema would accept them. Method response budgets also apply to policy failures. The direct `callOpenFairyGuiBackendTool(runtime, name, input, policy)` entry accepts the same policy as its optional fourth argument.
+
 Example local MCP client configuration:
 
 ```json

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_stdio = require("./stdio-CB98zdOf.cjs");
+const require_stdio = require("./stdio-D33c37mD.cjs");
 let _openfairygui_backend_docs = require("@openfairygui/backend/docs");
 exports.OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = require_stdio.OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI;
 exports.OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS = require_stdio.OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS;

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { connectOpenFairyGuiMcpStdio } from "./stdio.cjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { BackendMethodName, BackendMethodName as BackendMethodName$1, BackendRuntime } from "@openfairygui/backend";
 import { z } from "zod";
+import { BackendMethodName, BackendMethodName as BackendMethodName$1, BackendRuntime } from "@openfairygui/backend";
 import { OPENFAIRYGUI_OPERATION_CATALOG_URI, OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE, getOpenFairyGuiOperationCatalog, getOpenFairyGuiOperationSchema } from "@openfairygui/backend/docs";
 
 //#region src/tool-metadata.d.ts
@@ -240,7 +240,20 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly OpenFairyGuiBacken
 //#endregion
 //#region src/tool-handler.d.ts
 type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, BackendMethodName$1>;
-declare function callOpenFairyGuiBackendTool(runtime: OpenFairyGuiBackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>): Promise<CallToolResult>;
+/** Host policy runs after input validation, before the single Backend invocation. */
+interface OpenFairyGuiMcpToolPolicy {
+  /** Explicit Host-owned failure envelope, carried in structuredContent.backendResult. */
+  failureSchema: z.ZodType<{
+    ok: false;
+  }>;
+  /** Return a declared failure to stop, or undefined to call Backend with the original input. */
+  beforeCall(input: Readonly<Record<string, unknown>>): {
+    ok: false;
+  } | undefined | Promise<{
+    ok: false;
+  } | undefined>;
+}
+declare function callOpenFairyGuiBackendTool(runtime: OpenFairyGuiBackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>, policy?: OpenFairyGuiMcpToolPolicy): Promise<CallToolResult>;
 //#endregion
 //#region src/server.d.ts
 interface CreateOpenFairyGuiMcpServerOptions {
@@ -249,6 +262,10 @@ interface CreateOpenFairyGuiMcpServerOptions {
   allowedProjectRoots?: readonly string[];
   name?: string;
   version?: string;
+  /** Host guidance returned by the SDK initialize handshake. */
+  instructions?: string;
+  /** Per-tool Host failures do not change the canonical Backend contracts. */
+  toolPolicies?: Partial<Record<OpenFairyGuiBackendToolName, OpenFairyGuiMcpToolPolicy>>;
 }
 declare function createOpenFairyGuiMcpServer(options?: CreateOpenFairyGuiMcpServerOptions): McpServer;
 //#endregion
@@ -291,4 +308,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://docs/methods/{method}", "openfairygui://docs/cli/{command}", "openfairygui://docs/diagnostics/{code}", "openfairygui://contracts/operations/{kind}", "openfairygui://backend/session/{sessionId}", "openfairygui://backend/session/{sessionId}/outline", "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_PREFIX, OPENFAIRYGUI_OPERATION_CATALOG_URI, OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE, type OpenFairyGuiBackendPromptName, type OpenFairyGuiBackendRuntime, type OpenFairyGuiBackendToolDefinition, type OpenFairyGuiBackendToolName, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer, getOpenFairyGuiOperationCatalog, getOpenFairyGuiOperationSchema };
+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_PREFIX, OPENFAIRYGUI_OPERATION_CATALOG_URI, OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE, type OpenFairyGuiBackendPromptName, type OpenFairyGuiBackendRuntime, type OpenFairyGuiBackendToolDefinition, type OpenFairyGuiBackendToolName, type OpenFairyGuiMcpToolPolicy, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer, getOpenFairyGuiOperationCatalog, getOpenFairyGuiOperationSchema };

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import { connectOpenFairyGuiMcpStdio } from "./stdio.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { BackendMethodName, BackendMethodName as BackendMethodName$1, BackendRuntime } from "@openfairygui/backend";
 import { OPENFAIRYGUI_OPERATION_CATALOG_URI, OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE, getOpenFairyGuiOperationCatalog, getOpenFairyGuiOperationSchema } from "@openfairygui/backend/docs";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 
 //#region src/tool-metadata.d.ts
 interface BackendToolMetadata {
@@ -240,7 +240,20 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly OpenFairyGuiBacken
 //#endregion
 //#region src/tool-handler.d.ts
 type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, BackendMethodName$1>;
-declare function callOpenFairyGuiBackendTool(runtime: OpenFairyGuiBackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>): Promise<CallToolResult>;
+/** Host policy runs after input validation, before the single Backend invocation. */
+interface OpenFairyGuiMcpToolPolicy {
+  /** Explicit Host-owned failure envelope, carried in structuredContent.backendResult. */
+  failureSchema: z.ZodType<{
+    ok: false;
+  }>;
+  /** Return a declared failure to stop, or undefined to call Backend with the original input. */
+  beforeCall(input: Readonly<Record<string, unknown>>): {
+    ok: false;
+  } | undefined | Promise<{
+    ok: false;
+  } | undefined>;
+}
+declare function callOpenFairyGuiBackendTool(runtime: OpenFairyGuiBackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>, policy?: OpenFairyGuiMcpToolPolicy): Promise<CallToolResult>;
 //#endregion
 //#region src/server.d.ts
 interface CreateOpenFairyGuiMcpServerOptions {
@@ -249,6 +262,10 @@ interface CreateOpenFairyGuiMcpServerOptions {
   allowedProjectRoots?: readonly string[];
   name?: string;
   version?: string;
+  /** Host guidance returned by the SDK initialize handshake. */
+  instructions?: string;
+  /** Per-tool Host failures do not change the canonical Backend contracts. */
+  toolPolicies?: Partial<Record<OpenFairyGuiBackendToolName, OpenFairyGuiMcpToolPolicy>>;
 }
 declare function createOpenFairyGuiMcpServer(options?: CreateOpenFairyGuiMcpServerOptions): McpServer;
 //#endregion
@@ -291,4 +308,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://docs/methods/{method}", "openfairygui://docs/cli/{command}", "openfairygui://docs/diagnostics/{code}", "openfairygui://contracts/operations/{kind}", "openfairygui://backend/session/{sessionId}", "openfairygui://backend/session/{sessionId}/outline", "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_PREFIX, OPENFAIRYGUI_OPERATION_CATALOG_URI, OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE, type OpenFairyGuiBackendPromptName, type OpenFairyGuiBackendRuntime, type OpenFairyGuiBackendToolDefinition, type OpenFairyGuiBackendToolName, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer, getOpenFairyGuiOperationCatalog, getOpenFairyGuiOperationSchema };
+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_PREFIX, OPENFAIRYGUI_OPERATION_CATALOG_URI, OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE, type OpenFairyGuiBackendPromptName, type OpenFairyGuiBackendRuntime, type OpenFairyGuiBackendToolDefinition, type OpenFairyGuiBackendToolName, type OpenFairyGuiMcpToolPolicy, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer, getOpenFairyGuiOperationCatalog, getOpenFairyGuiOperationSchema };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as OPENFAIRYGUI_BACKEND_TOOL_NAMES, c as OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES, d as getOpenFairyGuiOperationCatalog, f as getOpenFairyGuiOperationSchema, i as OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS, l as OPENFAIRYGUI_OPERATION_CATALOG_URI, m as OPENFAIRYGUI_BACKEND_PROMPT_NAMES, n as createOpenFairyGuiMcpServer, o as OPENFAIRYGUI_BACKEND_TOOL_PREFIX, p as OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS, r as callOpenFairyGuiBackendTool, s as OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI, t as connectOpenFairyGuiMcpStdio, u as OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE } from "./stdio-BNobuRxx.mjs";
+import { a as OPENFAIRYGUI_BACKEND_TOOL_NAMES, c as OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES, d as getOpenFairyGuiOperationCatalog, f as getOpenFairyGuiOperationSchema, i as OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS, l as OPENFAIRYGUI_OPERATION_CATALOG_URI, m as OPENFAIRYGUI_BACKEND_PROMPT_NAMES, n as createOpenFairyGuiMcpServer, o as OPENFAIRYGUI_BACKEND_TOOL_PREFIX, p as OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS, r as callOpenFairyGuiBackendTool, s as OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI, t as connectOpenFairyGuiMcpStdio, u as OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE } from "./stdio--4YykL4s.mjs";
 export { 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_PREFIX, OPENFAIRYGUI_OPERATION_CATALOG_URI, OPENFAIRYGUI_OPERATION_SCHEMA_TEMPLATE, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer, getOpenFairyGuiOperationCatalog, getOpenFairyGuiOperationSchema };

package/dist/{stdio-BNobuRxx.mjs → stdio--4YykL4s.mjs}

@@ -1,6 +1,5 @@
 import { createRequire } from "node:module";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ListToolsRequestSchema, ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import { createNodeBackendRuntime } from "@openfairygui/backend/node";
 import { z } from "zod";
 import { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_CONTRACT_VERSION, BACKEND_DIAGNOSTICS_URI, BACKEND_DIAGNOSTIC_TEMPLATE, getBackendDiagnosticCatalog, getBackendDiagnosticGuide } from "@openfairygui/backend";
@@ -113,6 +112,17 @@ function contractObjectSchema(schema) {
 	if (!(result instanceof z.ZodObject)) throw new TypeError("Tool contract must be an object");
 	return result;
 }
+/** Keep SDK discovery dynamic without expanding shared contract definitions. */
+function compactToolSchema(schema, io) {
+	return z.looseObject({}).superRefine((value, context) => {
+		const parsed = schema.safeParse(value);
+		if (!parsed.success) for (const issue of parsed.error.issues) context.addIssue({ ...issue });
+	}).meta(z.toJSONSchema(schema, {
+		target: "draft-07",
+		io,
+		reused: "ref"
+	}));
+}
 /** Decode only generated Uint8Array locations; arbitrary JSON metadata is not rewritten. */
 function decodeToolBytes(input, paths) {
 	if (!paths.length) return input;
@@ -552,24 +562,34 @@ function unhandledBackendFailure(startedAt) {
 		}
 	};
 }
-async function callOpenFairyGuiBackendTool(runtime, name, input) {
+async function callOpenFairyGuiBackendTool(runtime, name, input, policy) {
 	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 decoded = decodeToolBytes(definition.inputSchema.parse(input), CONTRACT_SNAPSHOT.tools[definition.backendMethod].bytePaths);
+	const parsed = definition.inputSchema.parse(input);
+	const decoded = decodeToolBytes(parsed, CONTRACT_SNAPSHOT.tools[definition.backendMethod].bytePaths);
 	const startedAt = Date.now();
 	try {
-		const result = await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === "getCapabilities" ? [] : [decoded]);
+		let hostFailure = await policy?.beforeCall(structuredClone(parsed));
+		if (hostFailure !== void 0) {
+			hostFailure = policy.failureSchema.parse(hostFailure);
+			if (!isBackendFailure(hostFailure)) throw new TypeError("Host policy must return a failure or undefined.");
+		}
+		const result = hostFailure ?? await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === "getCapabilities" ? [] : [decoded]);
 		let response = jsonResult(result, isBackendFailure(result), definition.maxResponseBytes !== void 0);
-		if (definition.maxResponseBytes !== void 0 && 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
-			}
-		}, true);
-		definition.outputSchema.parse(response.structuredContent);
+		if (definition.maxResponseBytes !== void 0 && 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
+				}
+			}, true);
+			hostFailure = void 0;
+		}
+		if (hostFailure === void 0) definition.outputSchema.parse(response.structuredContent);
+		else policy.failureSchema.parse(response.structuredContent?.backendResult);
 		return response;
 	} catch {
 		return jsonResult(unhandledBackendFailure(startedAt), true);
@@ -579,7 +599,7 @@ async function callOpenFairyGuiBackendTool(runtime, name, input) {
 //#region src/server.ts
 const require = createRequire(import.meta.url);
 function getInjectedPackageVersion() {
-	const version = "0.5.0-alpha.1";
+	const version = "0.5.0-alpha.2";
 	return typeof version === "string" && true ? version : null;
 }
 function readPackageVersion() {
@@ -593,13 +613,15 @@ function readPackageVersion() {
 }
 const PACKAGE_VERSION = readPackageVersion();
 function createOpenFairyGuiMcpServer(options = {}) {
+	for (const name of Object.keys(options.toolPolicies ?? {})) if (!OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS.some((definition) => definition.name === name)) throw new RangeError(`Unknown OpenFairyGUI backend MCP tool policy: ${name}`);
 	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 = [];
+	}, { instructions: options.instructions });
 	for (const definition of OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS) {
+		const policy = options.toolPolicies?.[definition.name];
+		const outputSchema = policy ? definition.outputSchema.extend({ backendResult: z.union([definition.outputSchema.shape.backendResult, policy.failureSchema]) }) : definition.outputSchema;
 		const metadata = {
 			name: definition.name,
 			title: definition.title,
@@ -608,29 +630,16 @@ function createOpenFairyGuiMcpServer(options = {}) {
 			_meta: {
 				"openfairygui/backendMethod": definition.backendMethod,
 				"openfairygui/adapter": "thin-backend-p2",
-				"openfairygui/contractDigest": CONTRACT_SNAPSHOT.digest
+				"openfairygui/contractDigest": CONTRACT_SNAPSHOT.digest,
+				...policy ? { "openfairygui/hostPolicy": true } : {}
 			}
 		};
 		server.registerTool(definition.name, {
 			...metadata,
-			inputSchema: definition.inputSchema,
-			outputSchema: definition.outputSchema
-		}, async (args) => callOpenFairyGuiBackendTool(runtime, definition.name, 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"
-			})
-		}));
+			inputSchema: compactToolSchema(definition.inputSchema, "input"),
+			outputSchema: compactToolSchema(outputSchema, "output")
+		}, async (args) => callOpenFairyGuiBackendTool(runtime, definition.name, args, policy));
 	}
-	server.server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: structuredClone(tools) }));
 	registerOpenFairyGuiBackendResources(server, runtime);
 	registerOpenFairyGuiBackendPrompts(server);
 	return server;

package/dist/{stdio-CB98zdOf.cjs → stdio-D33c37mD.cjs}

@@ -21,7 +21,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
-let _modelcontextprotocol_sdk_types_js = require("@modelcontextprotocol/sdk/types.js");
 let _openfairygui_backend_node = require("@openfairygui/backend/node");
 let node_module = require("node:module");
 let zod = require("zod");
@@ -136,6 +135,17 @@ function contractObjectSchema(schema) {
 	if (!(result instanceof zod.z.ZodObject)) throw new TypeError("Tool contract must be an object");
 	return result;
 }
+/** Keep SDK discovery dynamic without expanding shared contract definitions. */
+function compactToolSchema(schema, io) {
+	return zod.z.looseObject({}).superRefine((value, context) => {
+		const parsed = schema.safeParse(value);
+		if (!parsed.success) for (const issue of parsed.error.issues) context.addIssue({ ...issue });
+	}).meta(zod.z.toJSONSchema(schema, {
+		target: "draft-07",
+		io,
+		reused: "ref"
+	}));
+}
 /** Decode only generated Uint8Array locations; arbitrary JSON metadata is not rewritten. */
 function decodeToolBytes(input, paths) {
 	if (!paths.length) return input;
@@ -575,24 +585,34 @@ function unhandledBackendFailure(startedAt) {
 		}
 	};
 }
-async function callOpenFairyGuiBackendTool(runtime, name, input) {
+async function callOpenFairyGuiBackendTool(runtime, name, input, policy) {
 	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 decoded = decodeToolBytes(definition.inputSchema.parse(input), CONTRACT_SNAPSHOT.tools[definition.backendMethod].bytePaths);
+	const parsed = definition.inputSchema.parse(input);
+	const decoded = decodeToolBytes(parsed, CONTRACT_SNAPSHOT.tools[definition.backendMethod].bytePaths);
 	const startedAt = Date.now();
 	try {
-		const result = await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === "getCapabilities" ? [] : [decoded]);
+		let hostFailure = await policy?.beforeCall(structuredClone(parsed));
+		if (hostFailure !== void 0) {
+			hostFailure = policy.failureSchema.parse(hostFailure);
+			if (!isBackendFailure(hostFailure)) throw new TypeError("Host policy must return a failure or undefined.");
+		}
+		const result = hostFailure ?? await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === "getCapabilities" ? [] : [decoded]);
 		let response = jsonResult(result, isBackendFailure(result), definition.maxResponseBytes !== void 0);
-		if (definition.maxResponseBytes !== void 0 && 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
-			}
-		}, true);
-		definition.outputSchema.parse(response.structuredContent);
+		if (definition.maxResponseBytes !== void 0 && 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
+				}
+			}, true);
+			hostFailure = void 0;
+		}
+		if (hostFailure === void 0) definition.outputSchema.parse(response.structuredContent);
+		else policy.failureSchema.parse(response.structuredContent?.backendResult);
 		return response;
 	} catch {
 		return jsonResult(unhandledBackendFailure(startedAt), true);
@@ -602,7 +622,7 @@ async function callOpenFairyGuiBackendTool(runtime, name, input) {
 //#region src/server.ts
 const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
 function getInjectedPackageVersion() {
-	const version = "0.5.0-alpha.1";
+	const version = "0.5.0-alpha.2";
 	return typeof version === "string" && true ? version : null;
 }
 function readPackageVersion() {
@@ -616,13 +636,15 @@ function readPackageVersion() {
 }
 const PACKAGE_VERSION = readPackageVersion();
 function createOpenFairyGuiMcpServer(options = {}) {
+	for (const name of Object.keys(options.toolPolicies ?? {})) if (!OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS.some((definition) => definition.name === name)) throw new RangeError(`Unknown OpenFairyGUI backend MCP tool policy: ${name}`);
 	const runtime = options.runtime ?? (0, _openfairygui_backend_node.createNodeBackendRuntime)({ allowedProjectRoots: options.allowedProjectRoots ?? [process.cwd()] });
 	const server = new _modelcontextprotocol_sdk_server_mcp_js.McpServer({
 		name: options.name ?? "openfairygui-mcp",
 		version: options.version ?? PACKAGE_VERSION
-	});
-	const tools = [];
+	}, { instructions: options.instructions });
 	for (const definition of OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS) {
+		const policy = options.toolPolicies?.[definition.name];
+		const outputSchema = policy ? definition.outputSchema.extend({ backendResult: zod.z.union([definition.outputSchema.shape.backendResult, policy.failureSchema]) }) : definition.outputSchema;
 		const metadata = {
 			name: definition.name,
 			title: definition.title,
@@ -631,29 +653,16 @@ function createOpenFairyGuiMcpServer(options = {}) {
 			_meta: {
 				"openfairygui/backendMethod": definition.backendMethod,
 				"openfairygui/adapter": "thin-backend-p2",
-				"openfairygui/contractDigest": CONTRACT_SNAPSHOT.digest
+				"openfairygui/contractDigest": CONTRACT_SNAPSHOT.digest,
+				...policy ? { "openfairygui/hostPolicy": true } : {}
 			}
 		};
 		server.registerTool(definition.name, {
 			...metadata,
-			inputSchema: definition.inputSchema,
-			outputSchema: definition.outputSchema
-		}, async (args) => callOpenFairyGuiBackendTool(runtime, definition.name, args));
-		tools.push(_modelcontextprotocol_sdk_types_js.ToolSchema.parse({
-			...metadata,
-			inputSchema: zod.z.toJSONSchema(definition.inputSchema, {
-				target: "draft-07",
-				io: "input",
-				reused: "ref"
-			}),
-			outputSchema: zod.z.toJSONSchema(definition.outputSchema, {
-				target: "draft-07",
-				io: "output",
-				reused: "ref"
-			})
-		}));
+			inputSchema: compactToolSchema(definition.inputSchema, "input"),
+			outputSchema: compactToolSchema(outputSchema, "output")
+		}, async (args) => callOpenFairyGuiBackendTool(runtime, definition.name, args, policy));
 	}
-	server.server.setRequestHandler(_modelcontextprotocol_sdk_types_js.ListToolsRequestSchema, () => ({ tools: structuredClone(tools) }));
 	registerOpenFairyGuiBackendResources(server, runtime);
 	registerOpenFairyGuiBackendPrompts(server);
 	return server;

package/dist/stdio.cjs

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

package/dist/stdio.mjs

@@ -1,2 +1,2 @@
-import { t as connectOpenFairyGuiMcpStdio } from "./stdio-BNobuRxx.mjs";
+import { t as connectOpenFairyGuiMcpStdio } from "./stdio--4YykL4s.mjs";
 export { connectOpenFairyGuiMcpStdio };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/mcp",
-  "version": "0.5.0-alpha.1",
+  "version": "0.5.0-alpha.2",
   "description": "FairyGUI Headless Authoring SDK - MCP server adapter for the backend runtime.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -61,13 +61,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6",
-    "@openfairygui/backend": "0.5.0-alpha.1"
+    "@openfairygui/backend": "0.5.0-alpha.2"
   },
   "devDependencies": {
     "ava": "^7.0.0",
     "tsx": "^4.0.0",
     "@openfairygui/test-utils": "0.3.0",
-    "@openfairygui/core": "0.5.0-alpha.1"
+    "@openfairygui/core": "0.5.0-alpha.2"
   },
   "ava": {
     "extensions": {

package/src/contract-schema.ts

@@ -10,6 +10,16 @@ export function contractObjectSchema(schema: ContractSchema): z.ZodObject {
 	return result;
 }
 
+/** Keep SDK discovery dynamic without expanding shared contract definitions. */
+export function compactToolSchema(schema: z.ZodObject, io: 'input' | 'output'): z.ZodObject {
+	// Zod metadata supplies the wire schema; validation still delegates to the original schema.
+	// A separate object avoids Zod's cycle extraction overwriting the metadata's definitions.
+	return z.looseObject({}).superRefine((value, context) => {
+		const parsed = schema.safeParse(value);
+		if (!parsed.success) for (const issue of parsed.error.issues) context.addIssue({ ...issue });
+	}).meta(z.toJSONSchema(schema, { target: 'draft-07', io, reused: 'ref' }));
+}
+
 /** 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;

package/src/index.ts

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

package/src/server.ts

@@ -1,12 +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 { compactToolSchema, CONTRACT_SNAPSHOT } from './contract-schema.js';
+import { callOpenFairyGuiBackendTool, type OpenFairyGuiBackendRuntime, type OpenFairyGuiMcpToolPolicy } from './tool-handler.js';
 import {
 	OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS,
 	type OpenFairyGuiBackendToolName,
@@ -42,19 +41,31 @@ export interface CreateOpenFairyGuiMcpServerOptions {
 	allowedProjectRoots?: readonly string[];
 	name?: string;
 	version?: string;
+	/** Host guidance returned by the SDK initialize handshake. */
+	instructions?: string;
+	/** Per-tool Host failures do not change the canonical Backend contracts. */
+	toolPolicies?: Partial<Record<OpenFairyGuiBackendToolName, OpenFairyGuiMcpToolPolicy>>;
 }
 
 export function createOpenFairyGuiMcpServer(options: CreateOpenFairyGuiMcpServerOptions = {}): McpServer {
+	for (const name of Object.keys(options.toolPolicies ?? {})) {
+		if (!OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS.some((definition) => definition.name === name)) {
+			throw new RangeError(`Unknown OpenFairyGUI backend MCP tool policy: ${name}`);
+		}
+	}
 	const runtime = options.runtime ?? createNodeBackendRuntime({
 		allowedProjectRoots: options.allowedProjectRoots ?? [process.cwd()],
 	});
 	const server = new McpServer({
 		name: options.name ?? 'openfairygui-mcp',
 		version: options.version ?? PACKAGE_VERSION,
-	});
+	}, { instructions: options.instructions });
 
-	const tools: Tool[] = [];
 	for (const definition of OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS) {
+		const policy = options.toolPolicies?.[definition.name];
+		const outputSchema = policy ? definition.outputSchema.extend({
+			backendResult: z.union([definition.outputSchema.shape.backendResult, policy.failureSchema]),
+		}) : definition.outputSchema;
 		const metadata = {
 			name: definition.name, title: definition.title, description: definition.description,
 			annotations: definition.annotations,
@@ -62,26 +73,19 @@ export function createOpenFairyGuiMcpServer(options: CreateOpenFairyGuiMcpServer
 				'openfairygui/backendMethod': definition.backendMethod,
 				'openfairygui/adapter': 'thin-backend-p2',
 				'openfairygui/contractDigest': CONTRACT_SNAPSHOT.digest,
+				...(policy ? { 'openfairygui/hostPolicy': true } : {}),
 			},
 		};
 		server.registerTool(
 			definition.name,
 			{
 				...metadata,
-				inputSchema: definition.inputSchema,
-				outputSchema: definition.outputSchema,
+				inputSchema: compactToolSchema(definition.inputSchema, 'input'),
+				outputSchema: compactToolSchema(outputSchema, 'output'),
 			},
-			async (args: Record<string, unknown>) => callOpenFairyGuiBackendTool(runtime, definition.name as OpenFairyGuiBackendToolName, args),
+			async (args: Record<string, unknown>) => callOpenFairyGuiBackendTool(runtime, definition.name, args, policy),
 		);
-		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/tool-handler.ts

@@ -1,4 +1,5 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { z } from 'zod';
 import {
 	BACKEND_CAPABILITY_SCHEMA_VERSION,
 	BACKEND_CONTRACT_VERSION,
@@ -16,6 +17,14 @@ import type { McpUnhandledFailure, McpResponseBudgetFailure } from './tool-metad
 
 export type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, BackendMethodName>;
 
+/** Host policy runs after input validation, before the single Backend invocation. */
+export interface OpenFairyGuiMcpToolPolicy {
+	/** Explicit Host-owned failure envelope, carried in structuredContent.backendResult. */
+	failureSchema: z.ZodType<{ ok: false }>;
+	/** Return a declared failure to stop, or undefined to call Backend with the original input. */
+	beforeCall(input: Readonly<Record<string, unknown>>): { ok: false } | undefined | Promise<{ ok: false } | undefined>;
+}
+
 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;
@@ -63,6 +72,7 @@ export async function callOpenFairyGuiBackendTool(
 	runtime: OpenFairyGuiBackendRuntime,
 	name: OpenFairyGuiBackendToolName,
 	input: Record<string, unknown>,
+	policy?: OpenFairyGuiMcpToolPolicy,
 ): Promise<CallToolResult> {
 	if (!isOpenFairyGuiMcpPayloadWithinBudget(input)) {
 		throw new RangeError('MCP input exceeds the depth, node, key, string, or byte budget.');
@@ -73,15 +83,22 @@ export async function callOpenFairyGuiBackendTool(
 	const decoded = decodeToolBytes(parsed, CONTRACT_SNAPSHOT.tools[definition.backendMethod].bytePaths);
 	const startedAt = Date.now();
 	try {
-		const result = await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === 'getCapabilities' ? [] : [decoded]);
+		let hostFailure = await policy?.beforeCall(structuredClone(parsed));
+		if (hostFailure !== undefined) {
+			hostFailure = policy!.failureSchema.parse(hostFailure);
+			if (!isBackendFailure(hostFailure)) throw new TypeError('Host policy must return a failure or undefined.');
+		}
+		const result = hostFailure ?? 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);
+			hostFailure = undefined;
 		}
-		definition.outputSchema.parse(response.structuredContent);
+		if (hostFailure === undefined) definition.outputSchema.parse(response.structuredContent);
+		else policy!.failureSchema.parse(response.structuredContent?.backendResult);
 		return response;
 	} catch {
 		return jsonResult(unhandledBackendFailure(startedAt), true);