@openfairygui/mcp 0.4.0 → 0.5.0-alpha.1

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 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`.
 
 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.

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-CB98zdOf.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

@@ -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;

package/dist/index.d.mts

@@ -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;

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-BNobuRxx.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-BNobuRxx.mjs}

@@ -304,6 +304,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 +519,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: [{
@@ -536,7 +560,15 @@ async function callOpenFairyGuiBackendTool(runtime, name, input) {
 	const startedAt = Date.now();
 	try {
 		const result = await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === "getCapabilities" ? [] : [decoded]);
-		const response = jsonResult(result, isBackendFailure(result));
+		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);
 		return response;
 	} catch {
@@ -547,7 +579,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.1";
 	return typeof version === "string" && true ? version : null;
 }
 function readPackageVersion() {

package/dist/{stdio-B0OU-oZC.cjs → stdio-CB98zdOf.cjs}

@@ -327,6 +327,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 +542,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: [{
@@ -559,7 +583,15 @@ async function callOpenFairyGuiBackendTool(runtime, name, input) {
 	const startedAt = Date.now();
 	try {
 		const result = await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === "getCapabilities" ? [] : [decoded]);
-		const response = jsonResult(result, isBackendFailure(result));
+		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);
 		return response;
 	} catch {
@@ -570,7 +602,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.1";
 	return typeof version === "string" && true ? version : null;
 }
 function readPackageVersion() {

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-CB98zdOf.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-BNobuRxx.mjs";
 export { connectOpenFairyGuiMcpStdio };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/mcp",
-  "version": "0.4.0",
+  "version": "0.5.0-alpha.1",
   "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.1"
   },
   "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.1"
   },
   "ava": {
     "extensions": {

package/src/tool-handler.ts

@@ -12,12 +12,12 @@ 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);
+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: [
@@ -74,7 +74,13 @@ export async function callOpenFairyGuiBackendTool(
 	const startedAt = Date.now();
 	try {
 		const result = await Reflect.apply(runtime[definition.backendMethod], runtime, definition.backendMethod === 'getCapabilities' ? [] : [decoded]);
-		const response = jsonResult(result, isBackendFailure(result));
+		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);
+		}
 		definition.outputSchema.parse(response.structuredContent);
 		return response;
 	} catch {

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',