@openfairygui/mcp 0.4.0 → 0.5.0-alpha.2

package/README.md

@@ -14,6 +14,8 @@ It maps the backend P2 runtime surface into MCP tools:
 - `getSession`
 - `getProjectOutline`
 - `queryEntity`
+- `readSessionState`
+- `readResourceBytes`
 - `validateSession`
 - `preflightTransaction`
 - `applyTransaction`
@@ -34,7 +36,7 @@ Each tool exposes a method-specific output schema for `structuredContent.backend
 - `error?`
 - `meta?`
 
-The factory advertises the fixed 18-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:
 
@@ -49,6 +51,8 @@ P1 also registers MCP-native ergonomics around the same backend surface:
 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.
 The project outline is revision-bound and exposes package, resource, folder, display-node, controller-page, and transition identities for transaction planning. It intentionally omits source bytes and full property payloads. `validateSession` returns the backend-owned read-only project validation report; the MCP adapter does not reinterpret its diagnostics.
 
+`readSessionState` returns a detached public UAM model without primary asset bytes, plus the current edit revision and source-read diagnostics. `readResourceBytes` reads one already-loaded primary asset with a required matching revision. Neither reads storage or changes the session. Both tools enforce their native response limits and a separate 16 MiB complete MCP response limit; see the installed method schemas and [workflow](../backend/docs/workflow.md).
+
 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.
@@ -67,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-B0OU-oZC.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
@@ -11,6 +11,8 @@ interface BackendToolMetadata {
   backendMethod: BackendMethodName$1;
   title: string;
   description: string;
+  /** Bound the complete CallToolResult JSON; bounded reads use compact text JSON. */
+  maxResponseBytes?: number;
   annotations: {
     readOnlyHint?: boolean;
     destructiveHint?: boolean;
@@ -78,6 +80,28 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_METADATA: readonly [{
     readonly idempotentHint: true;
     readonly openWorldHint: false;
   };
+}, {
+  readonly name: "openfairygui_backend_read_session_state";
+  readonly backendMethod: "readSessionState";
+  readonly title: "Read Session State";
+  readonly description: "Read a detached copy of the currently committed public UAM model without primary asset sourceBytes, with revision, dirty state and source-read diagnostics. Optional expectedRevision rejects stale reads. Does not hydrate, write, reserve history or guarantee downstream usability. Complete tool response is limited to 16 MiB.";
+  readonly maxResponseBytes: 16777216;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_read_resource_bytes";
+  readonly backendMethod: "readResourceBytes";
+  readonly title: "Read Resource Bytes";
+  readonly description: "Read a detached copy of one asset resource primary sourceBytes already held in the session, using exact packageId/resourceId and the required model edit revision. No filesystem hydration or auxiliary-file discovery. Stale reads require restarting the model/bytes read. Complete tool response is limited to 16 MiB.";
+  readonly maxResponseBytes: 16777216;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
 }, {
   readonly name: "openfairygui_backend_validate_session";
   readonly backendMethod: "validateSession";
@@ -206,7 +230,7 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_METADATA: readonly [{
 //#region src/tool-definitions.d.ts
 declare const OPENFAIRYGUI_BACKEND_TOOL_PREFIX = "openfairygui_backend_";
 type OpenFairyGuiBackendToolName = typeof OPENFAIRYGUI_BACKEND_TOOL_METADATA[number]['name'];
-declare const OPENFAIRYGUI_BACKEND_TOOL_NAMES: ("openfairygui_backend_get_capabilities" | "openfairygui_backend_open_session" | "openfairygui_backend_open_project_session" | "openfairygui_backend_get_session" | "openfairygui_backend_get_project_outline" | "openfairygui_backend_query_entity" | "openfairygui_backend_validate_session" | "openfairygui_backend_preflight_transaction" | "openfairygui_backend_apply_transaction" | "openfairygui_backend_save_session" | "openfairygui_backend_materialize_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")[];
+declare const OPENFAIRYGUI_BACKEND_TOOL_NAMES: ("openfairygui_backend_get_capabilities" | "openfairygui_backend_open_session" | "openfairygui_backend_open_project_session" | "openfairygui_backend_get_session" | "openfairygui_backend_get_project_outline" | "openfairygui_backend_query_entity" | "openfairygui_backend_read_session_state" | "openfairygui_backend_read_resource_bytes" | "openfairygui_backend_validate_session" | "openfairygui_backend_preflight_transaction" | "openfairygui_backend_apply_transaction" | "openfairygui_backend_save_session" | "openfairygui_backend_materialize_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")[];
 interface OpenFairyGuiBackendToolDefinition extends BackendToolMetadata {
   name: OpenFairyGuiBackendToolName;
   inputSchema: z.ZodObject;
@@ -216,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 {
@@ -225,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
@@ -267,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 {
@@ -11,6 +11,8 @@ interface BackendToolMetadata {
   backendMethod: BackendMethodName$1;
   title: string;
   description: string;
+  /** Bound the complete CallToolResult JSON; bounded reads use compact text JSON. */
+  maxResponseBytes?: number;
   annotations: {
     readOnlyHint?: boolean;
     destructiveHint?: boolean;
@@ -78,6 +80,28 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_METADATA: readonly [{
     readonly idempotentHint: true;
     readonly openWorldHint: false;
   };
+}, {
+  readonly name: "openfairygui_backend_read_session_state";
+  readonly backendMethod: "readSessionState";
+  readonly title: "Read Session State";
+  readonly description: "Read a detached copy of the currently committed public UAM model without primary asset sourceBytes, with revision, dirty state and source-read diagnostics. Optional expectedRevision rejects stale reads. Does not hydrate, write, reserve history or guarantee downstream usability. Complete tool response is limited to 16 MiB.";
+  readonly maxResponseBytes: 16777216;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_read_resource_bytes";
+  readonly backendMethod: "readResourceBytes";
+  readonly title: "Read Resource Bytes";
+  readonly description: "Read a detached copy of one asset resource primary sourceBytes already held in the session, using exact packageId/resourceId and the required model edit revision. No filesystem hydration or auxiliary-file discovery. Stale reads require restarting the model/bytes read. Complete tool response is limited to 16 MiB.";
+  readonly maxResponseBytes: 16777216;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
 }, {
   readonly name: "openfairygui_backend_validate_session";
   readonly backendMethod: "validateSession";
@@ -206,7 +230,7 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_METADATA: readonly [{
 //#region src/tool-definitions.d.ts
 declare const OPENFAIRYGUI_BACKEND_TOOL_PREFIX = "openfairygui_backend_";
 type OpenFairyGuiBackendToolName = typeof OPENFAIRYGUI_BACKEND_TOOL_METADATA[number]['name'];
-declare const OPENFAIRYGUI_BACKEND_TOOL_NAMES: ("openfairygui_backend_get_capabilities" | "openfairygui_backend_open_session" | "openfairygui_backend_open_project_session" | "openfairygui_backend_get_session" | "openfairygui_backend_get_project_outline" | "openfairygui_backend_query_entity" | "openfairygui_backend_validate_session" | "openfairygui_backend_preflight_transaction" | "openfairygui_backend_apply_transaction" | "openfairygui_backend_save_session" | "openfairygui_backend_materialize_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")[];
+declare const OPENFAIRYGUI_BACKEND_TOOL_NAMES: ("openfairygui_backend_get_capabilities" | "openfairygui_backend_open_session" | "openfairygui_backend_open_project_session" | "openfairygui_backend_get_session" | "openfairygui_backend_get_project_outline" | "openfairygui_backend_query_entity" | "openfairygui_backend_read_session_state" | "openfairygui_backend_read_resource_bytes" | "openfairygui_backend_validate_session" | "openfairygui_backend_preflight_transaction" | "openfairygui_backend_apply_transaction" | "openfairygui_backend_save_session" | "openfairygui_backend_materialize_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")[];
 interface OpenFairyGuiBackendToolDefinition extends BackendToolMetadata {
   name: OpenFairyGuiBackendToolName;
   inputSchema: z.ZodObject;
@@ -216,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 {
@@ -225,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
@@ -267,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-9ka7bvOr.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-9ka7bvOr.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;
@@ -304,6 +314,30 @@ const OPENFAIRYGUI_BACKEND_TOOL_METADATA = [
 			openWorldHint: false
 		}
 	},
+	{
+		name: "openfairygui_backend_read_session_state",
+		backendMethod: "readSessionState",
+		title: "Read Session State",
+		description: "Read a detached copy of the currently committed public UAM model without primary asset sourceBytes, with revision, dirty state and source-read diagnostics. Optional expectedRevision rejects stale reads. Does not hydrate, write, reserve history or guarantee downstream usability. Complete tool response is limited to 16 MiB.",
+		maxResponseBytes: 16777216,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	},
+	{
+		name: "openfairygui_backend_read_resource_bytes",
+		backendMethod: "readResourceBytes",
+		title: "Read Resource Bytes",
+		description: "Read a detached copy of one asset resource primary sourceBytes already held in the session, using exact packageId/resourceId and the required model edit revision. No filesystem hydration or auxiliary-file discovery. Stale reads require restarting the model/bytes read. Complete tool response is limited to 16 MiB.",
+		maxResponseBytes: 16777216,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	},
 	{
 		name: "openfairygui_backend_validate_session",
 		backendMethod: "validateSession",
@@ -495,8 +529,8 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = OPENFAIRYGUI_BACKEND_TOOL_METADATA
 });
 //#endregion
 //#region src/tool-handler.ts
-function jsonResult(payload, isError = false) {
-	const text = JSON.stringify(payload, (_key, value) => value instanceof Uint8Array ? [...value] : value, 2);
+function jsonResult(payload, isError = false, compact = false) {
+	const text = JSON.stringify(payload, (_key, value) => value instanceof Uint8Array ? [...value] : value, compact ? void 0 : 2);
 	const wirePayload = JSON.parse(text);
 	return {
 		content: [{
@@ -528,16 +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]);
-		const response = jsonResult(result, isBackendFailure(result));
-		definition.outputSchema.parse(response.structuredContent);
+		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);
+			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);
@@ -547,7 +599,7 @@ async function callOpenFairyGuiBackendTool(runtime, name, input) {
 //#region src/server.ts
 const require = createRequire(import.meta.url);
 function getInjectedPackageVersion() {
-	const version = "0.4.0";
+	const version = "0.5.0-alpha.2";
 	return typeof version === "string" && true ? version : null;
 }
 function readPackageVersion() {
@@ -561,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,
@@ -576,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-B0OU-oZC.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;
@@ -327,6 +337,30 @@ const OPENFAIRYGUI_BACKEND_TOOL_METADATA = [
 			openWorldHint: false
 		}
 	},
+	{
+		name: "openfairygui_backend_read_session_state",
+		backendMethod: "readSessionState",
+		title: "Read Session State",
+		description: "Read a detached copy of the currently committed public UAM model without primary asset sourceBytes, with revision, dirty state and source-read diagnostics. Optional expectedRevision rejects stale reads. Does not hydrate, write, reserve history or guarantee downstream usability. Complete tool response is limited to 16 MiB.",
+		maxResponseBytes: 16777216,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	},
+	{
+		name: "openfairygui_backend_read_resource_bytes",
+		backendMethod: "readResourceBytes",
+		title: "Read Resource Bytes",
+		description: "Read a detached copy of one asset resource primary sourceBytes already held in the session, using exact packageId/resourceId and the required model edit revision. No filesystem hydration or auxiliary-file discovery. Stale reads require restarting the model/bytes read. Complete tool response is limited to 16 MiB.",
+		maxResponseBytes: 16777216,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	},
 	{
 		name: "openfairygui_backend_validate_session",
 		backendMethod: "validateSession",
@@ -518,8 +552,8 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = OPENFAIRYGUI_BACKEND_TOOL_METADATA
 });
 //#endregion
 //#region src/tool-handler.ts
-function jsonResult(payload, isError = false) {
-	const text = JSON.stringify(payload, (_key, value) => value instanceof Uint8Array ? [...value] : value, 2);
+function jsonResult(payload, isError = false, compact = false) {
+	const text = JSON.stringify(payload, (_key, value) => value instanceof Uint8Array ? [...value] : value, compact ? void 0 : 2);
 	const wirePayload = JSON.parse(text);
 	return {
 		content: [{
@@ -551,16 +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]);
-		const response = jsonResult(result, isBackendFailure(result));
-		definition.outputSchema.parse(response.structuredContent);
+		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);
+			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);
@@ -570,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.4.0";
+	const version = "0.5.0-alpha.2";
 	return typeof version === "string" && true ? version : null;
 }
 function readPackageVersion() {
@@ -584,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,
@@ -599,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-B0OU-oZC.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-9ka7bvOr.mjs";
+import { t as connectOpenFairyGuiMcpStdio } from "./stdio--4YykL4s.mjs";
 export { connectOpenFairyGuiMcpStdio };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/mcp",
-  "version": "0.4.0",
+  "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.4.0"
+    "@openfairygui/backend": "0.5.0-alpha.2"
   },
   "devDependencies": {
     "ava": "^7.0.0",
     "tsx": "^4.0.0",
-    "@openfairygui/core": "0.4.0",
-    "@openfairygui/test-utils": "0.3.0"
+    "@openfairygui/test-utils": "0.3.0",
+    "@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,
@@ -12,12 +13,20 @@ import {
 } from './tool-definitions.js';
 
 import { decodeToolBytes, CONTRACT_SNAPSHOT } from './contract-schema.js';
-import type { McpUnhandledFailure } from './tool-metadata.js';
+import type { McpUnhandledFailure, McpResponseBudgetFailure } from './tool-metadata.js';
 
 export type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, BackendMethodName>;
 
-function jsonResult(payload: unknown, isError = false): CallToolResult {
-	const text = JSON.stringify(payload, (_key, value) => value instanceof Uint8Array ? [...value] : value, 2);
+/** 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;
 	return {
 		content: [
@@ -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,9 +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]);
-		const response = jsonResult(result, isBackendFailure(result));
-		definition.outputSchema.parse(response.structuredContent);
+		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;
+		}
+		if (hostFailure === undefined) definition.outputSchema.parse(response.structuredContent);
+		else policy!.failureSchema.parse(response.structuredContent?.backendResult);
 		return response;
 	} catch {
 		return jsonResult(unhandledBackendFailure(startedAt), true);

package/src/tool-metadata.ts

@@ -5,6 +5,8 @@ export interface BackendToolMetadata {
 	backendMethod: BackendMethodName;
 	title: string;
 	description: string;
+	/** Bound the complete CallToolResult JSON; bounded reads use compact text JSON. */
+	maxResponseBytes?: number;
 	annotations: {
 		readOnlyHint?: boolean;
 		destructiveHint?: boolean;
@@ -20,6 +22,12 @@ export interface McpUnhandledFailure {
 	error: { code: 'backend_unhandled_error'; message: string };
 }
 
+export interface McpResponseBudgetFailure {
+	ok: false;
+	meta: BackendResponseMeta;
+	error: { code: 'mcp_response_budget_exceeded'; message: string; maxBytes: number };
+}
+
 /** Host objects cannot cross JSON; materialize keeps its existing MCP target boundary. */
 export const MCP_OMITTED_INPUT_FIELDS = {
 	openProjectSession: ['storage'],
@@ -70,6 +78,22 @@ export const OPENFAIRYGUI_BACKEND_TOOL_METADATA = [
 		description: 'Read revision-bound project/package settings, resource, component-property, display-node, controller (including pages/actions), or transition (including items) snapshots. Project queries use only kind; other queries use formal selectors. Settings snapshots include the complete settings payload for updateProjectSettings/updatePackageSettings. No source bytes; fixed projection with explicit response limits.',
 		annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
 	},
+	{
+		name: 'openfairygui_backend_read_session_state',
+		backendMethod: 'readSessionState',
+		title: 'Read Session State',
+		description: 'Read a detached copy of the currently committed public UAM model without primary asset sourceBytes, with revision, dirty state and source-read diagnostics. Optional expectedRevision rejects stale reads. Does not hydrate, write, reserve history or guarantee downstream usability. Complete tool response is limited to 16 MiB.',
+		maxResponseBytes: 16777216,
+		annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+	},
+	{
+		name: 'openfairygui_backend_read_resource_bytes',
+		backendMethod: 'readResourceBytes',
+		title: 'Read Resource Bytes',
+		description: 'Read a detached copy of one asset resource primary sourceBytes already held in the session, using exact packageId/resourceId and the required model edit revision. No filesystem hydration or auxiliary-file discovery. Stale reads require restarting the model/bytes read. Complete tool response is limited to 16 MiB.',
+		maxResponseBytes: 16777216,
+		annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+	},
 	{
 		name: 'openfairygui_backend_validate_session',
 		backendMethod: 'validateSession',