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

package/README.md

@@ -10,9 +10,12 @@ It maps the backend P2 runtime surface into MCP tools:
 
 - `getCapabilities`
 - `openSession`
+- `openProjectSession`
 - `getSession`
+- `getProjectOutline`
 - `applyTransaction`
 - `saveSession`
+- `materializeSession`
 - `closeSession`
 - `getEvents`
 - `getJob`
@@ -33,11 +36,13 @@ P1 also registers MCP-native ergonomics around the same backend surface:
 - read-only resources for identity snapshots:
   - `openfairygui://backend/capabilities`
   - `openfairygui://backend/session/{sessionId}`
+  - `openfairygui://backend/session/{sessionId}/outline`
   - `openfairygui://backend/cache/{sessionId}`
   - `openfairygui://backend/job/{sessionId}/{jobId}`
-- prompts for capability inspection, session open/inspect, revision-checked transactions, save, and runtime polling
+- prompts for capability inspection, session open/inspect, project-outline inspection, revision-checked transactions, save, and runtime polling
 
 Resources return `application/json` text containing the unchanged backend result envelope. Parameterized polling remains tool-based: `getEvents` and `listJobs` are not exposed as resource URI query grammars.
+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.
 
 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`.
 

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_stdio = require("./stdio-Ckmxm29z.cjs");
+const require_stdio = require("./stdio-BqoMZ4QC.cjs");
 exports.OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = require_stdio.OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI;
 exports.OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS = require_stdio.OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS;
 exports.OPENFAIRYGUI_BACKEND_PROMPT_NAMES = require_stdio.OPENFAIRYGUI_BACKEND_PROMPT_NAMES;

package/dist/index.d.cts

@@ -6,9 +6,9 @@ import { z } from "zod";
 
 //#region src/tool-definitions.d.ts
 declare const OPENFAIRYGUI_BACKEND_TOOL_PREFIX = "openfairygui_backend_";
-declare const OPENFAIRYGUI_BACKEND_TOOL_NAMES: readonly ["openfairygui_backend_get_capabilities", "openfairygui_backend_open_session", "openfairygui_backend_open_project_session", "openfairygui_backend_get_session", "openfairygui_backend_apply_transaction", "openfairygui_backend_save_session", "openfairygui_backend_close_session", "openfairygui_backend_get_events", "openfairygui_backend_get_job", "openfairygui_backend_list_jobs", "openfairygui_backend_cancel_job", "openfairygui_backend_get_cache_snapshot", "openfairygui_backend_refresh_cache"];
+declare const OPENFAIRYGUI_BACKEND_TOOL_NAMES: readonly ["openfairygui_backend_get_capabilities", "openfairygui_backend_open_session", "openfairygui_backend_open_project_session", "openfairygui_backend_get_session", "openfairygui_backend_get_project_outline", "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"];
 type OpenFairyGuiBackendToolName = typeof OPENFAIRYGUI_BACKEND_TOOL_NAMES[number];
-type BackendMethodName = 'getCapabilities' | 'openSession' | 'openProjectSession' | 'getSession' | 'applyTransaction' | 'saveSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache';
+type BackendMethodName = 'getCapabilities' | 'openSession' | 'openProjectSession' | 'getSession' | 'getProjectOutline' | 'applyTransaction' | 'saveSession' | 'materializeSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache';
 interface OpenFairyGuiBackendToolDefinition {
   name: OpenFairyGuiBackendToolName;
   backendMethod: BackendMethodName;
@@ -116,6 +116,27 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
     readonly idempotentHint: true;
     readonly openWorldHint: false;
   };
+}, {
+  readonly name: "openfairygui_backend_get_project_outline";
+  readonly backendMethod: "getProjectOutline";
+  readonly title: "Get Project Outline";
+  readonly description: "Return a revision-bound project/package/resource/component identity outline without source bytes or full property payloads.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
 }, {
   readonly name: "openfairygui_backend_apply_transaction";
   readonly backendMethod: "applyTransaction";
@@ -149,6 +170,33 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
     sessionId: z.ZodString;
     expectedRevision: z.ZodOptional<z.ZodNumber>;
     targetPath: z.ZodOptional<z.ZodString>;
+    force: z.ZodOptional<z.ZodBoolean>;
+    mode: z.ZodOptional<z.ZodLiteral<"materializeCleanSession">>;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly idempotentHint: false;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_materialize_session";
+  readonly backendMethod: "materializeSession";
+  readonly title: "Materialize Backend Session";
+  readonly description: "Force materialize the current backend session project through the configured project storage without requiring a dirty edit revision.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    expectedRevision: z.ZodOptional<z.ZodNumber>;
+    mode: z.ZodOptional<z.ZodLiteral<"fullProject">>;
+    reason: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>;
   readonly outputSchema: z.ZodObject<{
     backendResult: z.ZodObject<{
@@ -168,7 +216,7 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
   readonly name: "openfairygui_backend_close_session";
   readonly backendMethod: "closeSession";
   readonly title: "Close Backend Session";
-  readonly description: "Close a backend session and release its backend-local advisory lock.";
+  readonly description: "Close a backend session and release its backend-local session lock.";
   readonly inputSchema: z.ZodObject<{
     sessionId: z.ZodString;
   }, z.core.$strip>;
@@ -334,7 +382,7 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
 }];
 //#endregion
 //#region src/tool-handler.d.ts
-type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, 'getCapabilities' | 'openSession' | 'openProjectSession' | 'getSession' | 'applyTransaction' | 'saveSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache'>;
+type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, 'getCapabilities' | 'openSession' | 'openProjectSession' | 'getSession' | 'getProjectOutline' | 'applyTransaction' | 'saveSession' | 'materializeSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache'>;
 declare function callOpenFairyGuiBackendTool(runtime: OpenFairyGuiBackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>): Promise<CallToolResult>;
 //#endregion
 //#region src/server.d.ts
@@ -346,7 +394,7 @@ interface CreateOpenFairyGuiMcpServerOptions {
 declare function createOpenFairyGuiMcpServer(options?: CreateOpenFairyGuiMcpServerOptions): McpServer;
 //#endregion
 //#region src/prompt-definitions.d.ts
-declare const OPENFAIRYGUI_BACKEND_PROMPT_NAMES: readonly ["openfairygui_inspect_capabilities", "openfairygui_open_and_inspect_session", "openfairygui_plan_revision_checked_transaction", "openfairygui_save_session", "openfairygui_poll_runtime_state"];
+declare const OPENFAIRYGUI_BACKEND_PROMPT_NAMES: readonly ["openfairygui_inspect_capabilities", "openfairygui_open_and_inspect_session", "openfairygui_inspect_project_outline", "openfairygui_plan_revision_checked_transaction", "openfairygui_save_session", "openfairygui_poll_runtime_state"];
 type OpenFairyGuiBackendPromptName = typeof OPENFAIRYGUI_BACKEND_PROMPT_NAMES[number];
 declare const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS: readonly [{
   readonly name: "openfairygui_inspect_capabilities";
@@ -358,6 +406,11 @@ declare const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS: readonly [{
   readonly title: "Open and Inspect an OpenFairyGUI Session";
   readonly description: "Guide a client through opening and reading a backend session.";
   readonly text: string;
+}, {
+  readonly name: "openfairygui_inspect_project_outline";
+  readonly title: "Inspect an OpenFairyGUI Project Outline";
+  readonly description: "Guide a client through selector discovery before a revision-checked transaction.";
+  readonly text: string;
 }, {
   readonly name: "openfairygui_plan_revision_checked_transaction";
   readonly title: "Plan a Revision-Checked OpenFairyGUI Transaction";
@@ -377,6 +430,6 @@ declare const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS: readonly [{
 //#endregion
 //#region src/resource-definitions.d.ts
 declare const OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = "openfairygui://backend/capabilities";
-declare const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES: readonly ["openfairygui://backend/session/{sessionId}", "openfairygui://backend/cache/{sessionId}", "openfairygui://backend/job/{sessionId}/{jobId}"];
+declare const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES: readonly ["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_OUTPUT_SCHEMA, OPENFAIRYGUI_BACKEND_TOOL_PREFIX, type OpenFairyGuiBackendPromptName, type OpenFairyGuiBackendRuntime, type OpenFairyGuiBackendToolDefinition, type OpenFairyGuiBackendToolName, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer };

package/dist/index.d.mts

@@ -6,9 +6,9 @@ import { BackendRuntime } from "@openfairygui/backend";
 
 //#region src/tool-definitions.d.ts
 declare const OPENFAIRYGUI_BACKEND_TOOL_PREFIX = "openfairygui_backend_";
-declare const OPENFAIRYGUI_BACKEND_TOOL_NAMES: readonly ["openfairygui_backend_get_capabilities", "openfairygui_backend_open_session", "openfairygui_backend_open_project_session", "openfairygui_backend_get_session", "openfairygui_backend_apply_transaction", "openfairygui_backend_save_session", "openfairygui_backend_close_session", "openfairygui_backend_get_events", "openfairygui_backend_get_job", "openfairygui_backend_list_jobs", "openfairygui_backend_cancel_job", "openfairygui_backend_get_cache_snapshot", "openfairygui_backend_refresh_cache"];
+declare const OPENFAIRYGUI_BACKEND_TOOL_NAMES: readonly ["openfairygui_backend_get_capabilities", "openfairygui_backend_open_session", "openfairygui_backend_open_project_session", "openfairygui_backend_get_session", "openfairygui_backend_get_project_outline", "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"];
 type OpenFairyGuiBackendToolName = typeof OPENFAIRYGUI_BACKEND_TOOL_NAMES[number];
-type BackendMethodName = 'getCapabilities' | 'openSession' | 'openProjectSession' | 'getSession' | 'applyTransaction' | 'saveSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache';
+type BackendMethodName = 'getCapabilities' | 'openSession' | 'openProjectSession' | 'getSession' | 'getProjectOutline' | 'applyTransaction' | 'saveSession' | 'materializeSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache';
 interface OpenFairyGuiBackendToolDefinition {
   name: OpenFairyGuiBackendToolName;
   backendMethod: BackendMethodName;
@@ -116,6 +116,27 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
     readonly idempotentHint: true;
     readonly openWorldHint: false;
   };
+}, {
+  readonly name: "openfairygui_backend_get_project_outline";
+  readonly backendMethod: "getProjectOutline";
+  readonly title: "Get Project Outline";
+  readonly description: "Return a revision-bound project/package/resource/component identity outline without source bytes or full property payloads.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+  };
 }, {
   readonly name: "openfairygui_backend_apply_transaction";
   readonly backendMethod: "applyTransaction";
@@ -149,6 +170,33 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
     sessionId: z.ZodString;
     expectedRevision: z.ZodOptional<z.ZodNumber>;
     targetPath: z.ZodOptional<z.ZodString>;
+    force: z.ZodOptional<z.ZodBoolean>;
+    mode: z.ZodOptional<z.ZodLiteral<"materializeCleanSession">>;
+  }, z.core.$strip>;
+  readonly outputSchema: z.ZodObject<{
+    backendResult: z.ZodObject<{
+      ok: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodUnknown>;
+      meta: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+  }, z.core.$strip>;
+  readonly annotations: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly idempotentHint: false;
+    readonly openWorldHint: false;
+  };
+}, {
+  readonly name: "openfairygui_backend_materialize_session";
+  readonly backendMethod: "materializeSession";
+  readonly title: "Materialize Backend Session";
+  readonly description: "Force materialize the current backend session project through the configured project storage without requiring a dirty edit revision.";
+  readonly inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    expectedRevision: z.ZodOptional<z.ZodNumber>;
+    mode: z.ZodOptional<z.ZodLiteral<"fullProject">>;
+    reason: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>;
   readonly outputSchema: z.ZodObject<{
     backendResult: z.ZodObject<{
@@ -168,7 +216,7 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
   readonly name: "openfairygui_backend_close_session";
   readonly backendMethod: "closeSession";
   readonly title: "Close Backend Session";
-  readonly description: "Close a backend session and release its backend-local advisory lock.";
+  readonly description: "Close a backend session and release its backend-local session lock.";
   readonly inputSchema: z.ZodObject<{
     sessionId: z.ZodString;
   }, z.core.$strip>;
@@ -334,7 +382,7 @@ declare const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS: readonly [{
 }];
 //#endregion
 //#region src/tool-handler.d.ts
-type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, 'getCapabilities' | 'openSession' | 'openProjectSession' | 'getSession' | 'applyTransaction' | 'saveSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache'>;
+type OpenFairyGuiBackendRuntime = Pick<BackendRuntime, 'getCapabilities' | 'openSession' | 'openProjectSession' | 'getSession' | 'getProjectOutline' | 'applyTransaction' | 'saveSession' | 'materializeSession' | 'closeSession' | 'getEvents' | 'getJob' | 'listJobs' | 'cancelJob' | 'getCacheSnapshot' | 'refreshCache'>;
 declare function callOpenFairyGuiBackendTool(runtime: OpenFairyGuiBackendRuntime, name: OpenFairyGuiBackendToolName, input: Record<string, unknown>): Promise<CallToolResult>;
 //#endregion
 //#region src/server.d.ts
@@ -346,7 +394,7 @@ interface CreateOpenFairyGuiMcpServerOptions {
 declare function createOpenFairyGuiMcpServer(options?: CreateOpenFairyGuiMcpServerOptions): McpServer;
 //#endregion
 //#region src/prompt-definitions.d.ts
-declare const OPENFAIRYGUI_BACKEND_PROMPT_NAMES: readonly ["openfairygui_inspect_capabilities", "openfairygui_open_and_inspect_session", "openfairygui_plan_revision_checked_transaction", "openfairygui_save_session", "openfairygui_poll_runtime_state"];
+declare const OPENFAIRYGUI_BACKEND_PROMPT_NAMES: readonly ["openfairygui_inspect_capabilities", "openfairygui_open_and_inspect_session", "openfairygui_inspect_project_outline", "openfairygui_plan_revision_checked_transaction", "openfairygui_save_session", "openfairygui_poll_runtime_state"];
 type OpenFairyGuiBackendPromptName = typeof OPENFAIRYGUI_BACKEND_PROMPT_NAMES[number];
 declare const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS: readonly [{
   readonly name: "openfairygui_inspect_capabilities";
@@ -358,6 +406,11 @@ declare const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS: readonly [{
   readonly title: "Open and Inspect an OpenFairyGUI Session";
   readonly description: "Guide a client through opening and reading a backend session.";
   readonly text: string;
+}, {
+  readonly name: "openfairygui_inspect_project_outline";
+  readonly title: "Inspect an OpenFairyGUI Project Outline";
+  readonly description: "Guide a client through selector discovery before a revision-checked transaction.";
+  readonly text: string;
 }, {
   readonly name: "openfairygui_plan_revision_checked_transaction";
   readonly title: "Plan a Revision-Checked OpenFairyGUI Transaction";
@@ -377,6 +430,6 @@ declare const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS: readonly [{
 //#endregion
 //#region src/resource-definitions.d.ts
 declare const OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = "openfairygui://backend/capabilities";
-declare const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES: readonly ["openfairygui://backend/session/{sessionId}", "openfairygui://backend/cache/{sessionId}", "openfairygui://backend/job/{sessionId}/{jobId}"];
+declare const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES: readonly ["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_OUTPUT_SCHEMA, OPENFAIRYGUI_BACKEND_TOOL_PREFIX, type OpenFairyGuiBackendPromptName, type OpenFairyGuiBackendRuntime, type OpenFairyGuiBackendToolDefinition, type OpenFairyGuiBackendToolName, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA, c as OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI, d as OPENFAIRYGUI_BACKEND_PROMPT_NAMES, i as OPENFAIRYGUI_BACKEND_TOOL_NAMES, l as OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES, n as createOpenFairyGuiMcpServer, o as OPENFAIRYGUI_BACKEND_TOOL_PREFIX, r as OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS, s as callOpenFairyGuiBackendTool, t as connectOpenFairyGuiMcpStdio, u as OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS } from "./stdio-DT1cUPJ3.mjs";
+import { a as OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA, c as OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI, d as OPENFAIRYGUI_BACKEND_PROMPT_NAMES, i as OPENFAIRYGUI_BACKEND_TOOL_NAMES, l as OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES, n as createOpenFairyGuiMcpServer, o as OPENFAIRYGUI_BACKEND_TOOL_PREFIX, r as OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS, s as callOpenFairyGuiBackendTool, t as connectOpenFairyGuiMcpStdio, u as OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS } from "./stdio-C69hamhI.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_OUTPUT_SCHEMA, OPENFAIRYGUI_BACKEND_TOOL_PREFIX, callOpenFairyGuiBackendTool, connectOpenFairyGuiMcpStdio, createOpenFairyGuiMcpServer };

package/dist/{stdio-Ckmxm29z.cjs → stdio-BqoMZ4QC.cjs}

@@ -1,5 +1,6 @@
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
 let _openfairygui_backend_node = require("@openfairygui/backend/node");
+let node_module = require("node:module");
 let zod = require("zod");
 let _modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
 let node_url = require("node:url");
@@ -7,6 +8,7 @@ let node_url = require("node:url");
 const OPENFAIRYGUI_BACKEND_PROMPT_NAMES = [
 	"openfairygui_inspect_capabilities",
 	"openfairygui_open_and_inspect_session",
+	"openfairygui_inspect_project_outline",
 	"openfairygui_plan_revision_checked_transaction",
 	"openfairygui_save_session",
 	"openfairygui_poll_runtime_state"
@@ -32,6 +34,17 @@ const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS = [
 			"Close the session with openfairygui_backend_close_session when finished."
 		].join("\n")
 	},
+	{
+		name: "openfairygui_inspect_project_outline",
+		title: "Inspect an OpenFairyGUI Project Outline",
+		description: "Guide a client through selector discovery before a revision-checked transaction.",
+		text: [
+			"Use openfairygui_backend_get_project_outline with the active sessionId before planning mutations.",
+			"Use package, resource, folder, display node, controller page, and transition identities from the returned outline.",
+			"Pass the returned revision as expectedRevision when calling openfairygui_backend_apply_transaction.",
+			"Read a new outline if the backend reports a stale revision; the outline intentionally excludes source bytes and full property payloads."
+		].join("\n")
+	},
 	{
 		name: "openfairygui_plan_revision_checked_transaction",
 		title: "Plan a Revision-Checked OpenFairyGUI Transaction",
@@ -96,6 +109,7 @@ function jsonResource(uri, backendResult) {
 const OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = "openfairygui://backend/capabilities";
 const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES = [
 	"openfairygui://backend/session/{sessionId}",
+	"openfairygui://backend/session/{sessionId}/outline",
 	"openfairygui://backend/cache/{sessionId}",
 	"openfairygui://backend/job/{sessionId}/{jobId}"
 ];
@@ -110,6 +124,11 @@ function registerOpenFairyGuiBackendResources(server, runtime) {
 		description: "Read a backend session envelope by backend-local session id.",
 		mimeType: JSON_MIME_TYPE
 	}, (uri, variables) => jsonResource(uri, runtime.getSession({ sessionId: firstVariable(variables.sessionId) })));
+	server.registerResource("openfairygui_backend_project_outline", new _modelcontextprotocol_sdk_server_mcp_js.ResourceTemplate("openfairygui://backend/session/{sessionId}/outline", { list: void 0 }), {
+		title: "OpenFairyGUI Project Outline",
+		description: "Read a revision-bound project identity outline without source bytes or full property payloads.",
+		mimeType: JSON_MIME_TYPE
+	}, (uri, variables) => jsonResource(uri, runtime.getProjectOutline({ sessionId: firstVariable(variables.sessionId) })));
 	server.registerResource("openfairygui_backend_cache", new _modelcontextprotocol_sdk_server_mcp_js.ResourceTemplate("openfairygui://backend/cache/{sessionId}", { list: void 0 }), {
 		title: "OpenFairyGUI Backend Cache Snapshot",
 		description: "Read a derived backend cache envelope by backend-local session id.",
@@ -159,6 +178,9 @@ async function callOpenFairyGuiBackendTool(runtime, name, input) {
 		case "openfairygui_backend_get_session":
 			result = runtime.getSession({ sessionId: String(input.sessionId) });
 			break;
+		case "openfairygui_backend_get_project_outline":
+			result = runtime.getProjectOutline({ sessionId: String(input.sessionId) });
+			break;
 		case "openfairygui_backend_apply_transaction":
 			result = await runtime.applyTransaction({
 				sessionId: String(input.sessionId),
@@ -170,7 +192,17 @@ async function callOpenFairyGuiBackendTool(runtime, name, input) {
 			result = await runtime.saveSession({
 				sessionId: String(input.sessionId),
 				expectedRevision: input.expectedRevision === void 0 ? void 0 : Number(input.expectedRevision),
-				targetPath: input.targetPath === void 0 ? void 0 : String(input.targetPath)
+				targetPath: input.targetPath === void 0 ? void 0 : String(input.targetPath),
+				force: input.force === void 0 ? void 0 : Boolean(input.force),
+				mode: input.mode
+			});
+			break;
+		case "openfairygui_backend_materialize_session":
+			result = await runtime.materializeSession({
+				sessionId: String(input.sessionId),
+				expectedRevision: input.expectedRevision === void 0 ? void 0 : Number(input.expectedRevision),
+				mode: input.mode,
+				reason: input.reason === void 0 ? void 0 : String(input.reason)
 			});
 			break;
 		case "openfairygui_backend_close_session":
@@ -224,8 +256,10 @@ const OPENFAIRYGUI_BACKEND_TOOL_NAMES = [
 	"openfairygui_backend_open_session",
 	"openfairygui_backend_open_project_session",
 	"openfairygui_backend_get_session",
+	"openfairygui_backend_get_project_outline",
 	"openfairygui_backend_apply_transaction",
 	"openfairygui_backend_save_session",
+	"openfairygui_backend_materialize_session",
 	"openfairygui_backend_close_session",
 	"openfairygui_backend_get_events",
 	"openfairygui_backend_get_job",
@@ -302,6 +336,19 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 			openWorldHint: false
 		}
 	},
+	{
+		name: "openfairygui_backend_get_project_outline",
+		backendMethod: "getProjectOutline",
+		title: "Get Project Outline",
+		description: "Return a revision-bound project/package/resource/component identity outline without source bytes or full property payloads.",
+		inputSchema: zod.z.object({ sessionId }),
+		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	},
 	{
 		name: "openfairygui_backend_apply_transaction",
 		backendMethod: "applyTransaction",
@@ -328,7 +375,28 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		inputSchema: zod.z.object({
 			sessionId,
 			expectedRevision: expectedRevision.optional(),
-			targetPath: zod.z.string().min(1).optional()
+			targetPath: zod.z.string().min(1).optional(),
+			force: zod.z.boolean().optional(),
+			mode: zod.z.literal("materializeCleanSession").optional()
+		}),
+		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: false,
+			openWorldHint: false
+		}
+	},
+	{
+		name: "openfairygui_backend_materialize_session",
+		backendMethod: "materializeSession",
+		title: "Materialize Backend Session",
+		description: "Force materialize the current backend session project through the configured project storage without requiring a dirty edit revision.",
+		inputSchema: zod.z.object({
+			sessionId,
+			expectedRevision: expectedRevision.optional(),
+			mode: zod.z.literal("fullProject").optional(),
+			reason: zod.z.string().min(1).optional()
 		}),
 		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
@@ -342,7 +410,7 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		name: "openfairygui_backend_close_session",
 		backendMethod: "closeSession",
 		title: "Close Backend Session",
-		description: "Close a backend session and release its backend-local advisory lock.",
+		description: "Close a backend session and release its backend-local session lock.",
 		inputSchema: zod.z.object({ sessionId }),
 		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
@@ -462,7 +530,21 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 ];
 //#endregion
 //#region src/server.ts
-const PACKAGE_VERSION = process.env.npm_package_version ?? "0.2.0-alpha.0";
+const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+function getInjectedPackageVersion() {
+	const version = "0.3.0-alpha.1";
+	return typeof version === "string" && true ? version : null;
+}
+function readPackageVersion() {
+	const injectedVersion = getInjectedPackageVersion();
+	if (injectedVersion) return injectedVersion;
+	try {
+		const pkg = require$1("../package.json");
+		if (typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
+	} catch {}
+	return "0.0.0-dev";
+}
+const PACKAGE_VERSION = readPackageVersion();
 function createOpenFairyGuiMcpServer(options = {}) {
 	const runtime = options.runtime ?? (0, _openfairygui_backend_node.createNodeBackendRuntime)();
 	const server = new _modelcontextprotocol_sdk_server_mcp_js.McpServer({

package/dist/{stdio-DT1cUPJ3.mjs → stdio-C69hamhI.mjs}

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createNodeBackendRuntime } from "@openfairygui/backend/node";
 import { z } from "zod";
@@ -7,6 +8,7 @@ import { pathToFileURL } from "node:url";
 const OPENFAIRYGUI_BACKEND_PROMPT_NAMES = [
 	"openfairygui_inspect_capabilities",
 	"openfairygui_open_and_inspect_session",
+	"openfairygui_inspect_project_outline",
 	"openfairygui_plan_revision_checked_transaction",
 	"openfairygui_save_session",
 	"openfairygui_poll_runtime_state"
@@ -32,6 +34,17 @@ const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS = [
 			"Close the session with openfairygui_backend_close_session when finished."
 		].join("\n")
 	},
+	{
+		name: "openfairygui_inspect_project_outline",
+		title: "Inspect an OpenFairyGUI Project Outline",
+		description: "Guide a client through selector discovery before a revision-checked transaction.",
+		text: [
+			"Use openfairygui_backend_get_project_outline with the active sessionId before planning mutations.",
+			"Use package, resource, folder, display node, controller page, and transition identities from the returned outline.",
+			"Pass the returned revision as expectedRevision when calling openfairygui_backend_apply_transaction.",
+			"Read a new outline if the backend reports a stale revision; the outline intentionally excludes source bytes and full property payloads."
+		].join("\n")
+	},
 	{
 		name: "openfairygui_plan_revision_checked_transaction",
 		title: "Plan a Revision-Checked OpenFairyGUI Transaction",
@@ -96,6 +109,7 @@ function jsonResource(uri, backendResult) {
 const OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = "openfairygui://backend/capabilities";
 const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES = [
 	"openfairygui://backend/session/{sessionId}",
+	"openfairygui://backend/session/{sessionId}/outline",
 	"openfairygui://backend/cache/{sessionId}",
 	"openfairygui://backend/job/{sessionId}/{jobId}"
 ];
@@ -110,6 +124,11 @@ function registerOpenFairyGuiBackendResources(server, runtime) {
 		description: "Read a backend session envelope by backend-local session id.",
 		mimeType: JSON_MIME_TYPE
 	}, (uri, variables) => jsonResource(uri, runtime.getSession({ sessionId: firstVariable(variables.sessionId) })));
+	server.registerResource("openfairygui_backend_project_outline", new ResourceTemplate("openfairygui://backend/session/{sessionId}/outline", { list: void 0 }), {
+		title: "OpenFairyGUI Project Outline",
+		description: "Read a revision-bound project identity outline without source bytes or full property payloads.",
+		mimeType: JSON_MIME_TYPE
+	}, (uri, variables) => jsonResource(uri, runtime.getProjectOutline({ sessionId: firstVariable(variables.sessionId) })));
 	server.registerResource("openfairygui_backend_cache", new ResourceTemplate("openfairygui://backend/cache/{sessionId}", { list: void 0 }), {
 		title: "OpenFairyGUI Backend Cache Snapshot",
 		description: "Read a derived backend cache envelope by backend-local session id.",
@@ -159,6 +178,9 @@ async function callOpenFairyGuiBackendTool(runtime, name, input) {
 		case "openfairygui_backend_get_session":
 			result = runtime.getSession({ sessionId: String(input.sessionId) });
 			break;
+		case "openfairygui_backend_get_project_outline":
+			result = runtime.getProjectOutline({ sessionId: String(input.sessionId) });
+			break;
 		case "openfairygui_backend_apply_transaction":
 			result = await runtime.applyTransaction({
 				sessionId: String(input.sessionId),
@@ -170,7 +192,17 @@ async function callOpenFairyGuiBackendTool(runtime, name, input) {
 			result = await runtime.saveSession({
 				sessionId: String(input.sessionId),
 				expectedRevision: input.expectedRevision === void 0 ? void 0 : Number(input.expectedRevision),
-				targetPath: input.targetPath === void 0 ? void 0 : String(input.targetPath)
+				targetPath: input.targetPath === void 0 ? void 0 : String(input.targetPath),
+				force: input.force === void 0 ? void 0 : Boolean(input.force),
+				mode: input.mode
+			});
+			break;
+		case "openfairygui_backend_materialize_session":
+			result = await runtime.materializeSession({
+				sessionId: String(input.sessionId),
+				expectedRevision: input.expectedRevision === void 0 ? void 0 : Number(input.expectedRevision),
+				mode: input.mode,
+				reason: input.reason === void 0 ? void 0 : String(input.reason)
 			});
 			break;
 		case "openfairygui_backend_close_session":
@@ -224,8 +256,10 @@ const OPENFAIRYGUI_BACKEND_TOOL_NAMES = [
 	"openfairygui_backend_open_session",
 	"openfairygui_backend_open_project_session",
 	"openfairygui_backend_get_session",
+	"openfairygui_backend_get_project_outline",
 	"openfairygui_backend_apply_transaction",
 	"openfairygui_backend_save_session",
+	"openfairygui_backend_materialize_session",
 	"openfairygui_backend_close_session",
 	"openfairygui_backend_get_events",
 	"openfairygui_backend_get_job",
@@ -302,6 +336,19 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 			openWorldHint: false
 		}
 	},
+	{
+		name: "openfairygui_backend_get_project_outline",
+		backendMethod: "getProjectOutline",
+		title: "Get Project Outline",
+		description: "Return a revision-bound project/package/resource/component identity outline without source bytes or full property payloads.",
+		inputSchema: z.object({ sessionId }),
+		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	},
 	{
 		name: "openfairygui_backend_apply_transaction",
 		backendMethod: "applyTransaction",
@@ -328,7 +375,28 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		inputSchema: z.object({
 			sessionId,
 			expectedRevision: expectedRevision.optional(),
-			targetPath: z.string().min(1).optional()
+			targetPath: z.string().min(1).optional(),
+			force: z.boolean().optional(),
+			mode: z.literal("materializeCleanSession").optional()
+		}),
+		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: false,
+			openWorldHint: false
+		}
+	},
+	{
+		name: "openfairygui_backend_materialize_session",
+		backendMethod: "materializeSession",
+		title: "Materialize Backend Session",
+		description: "Force materialize the current backend session project through the configured project storage without requiring a dirty edit revision.",
+		inputSchema: z.object({
+			sessionId,
+			expectedRevision: expectedRevision.optional(),
+			mode: z.literal("fullProject").optional(),
+			reason: z.string().min(1).optional()
 		}),
 		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
@@ -342,7 +410,7 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		name: "openfairygui_backend_close_session",
 		backendMethod: "closeSession",
 		title: "Close Backend Session",
-		description: "Close a backend session and release its backend-local advisory lock.",
+		description: "Close a backend session and release its backend-local session lock.",
 		inputSchema: z.object({ sessionId }),
 		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: {
@@ -462,7 +530,21 @@ const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 ];
 //#endregion
 //#region src/server.ts
-const PACKAGE_VERSION = process.env.npm_package_version ?? "0.2.0-alpha.0";
+const require = createRequire(import.meta.url);
+function getInjectedPackageVersion() {
+	const version = "0.3.0-alpha.1";
+	return typeof version === "string" && true ? version : null;
+}
+function readPackageVersion() {
+	const injectedVersion = getInjectedPackageVersion();
+	if (injectedVersion) return injectedVersion;
+	try {
+		const pkg = require("../package.json");
+		if (typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
+	} catch {}
+	return "0.0.0-dev";
+}
+const PACKAGE_VERSION = readPackageVersion();
 function createOpenFairyGuiMcpServer(options = {}) {
 	const runtime = options.runtime ?? createNodeBackendRuntime();
 	const server = new McpServer({

package/dist/stdio.cjs

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

package/dist/stdio.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/mcp",
-  "version": "0.2.0-alpha.3",
+  "version": "0.3.0-alpha.1",
   "description": "FairyGUI Headless Authoring SDK - MCP server adapter for the backend runtime.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -58,12 +58,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6",
-    "@openfairygui/backend": "0.2.0-alpha.3"
+    "@openfairygui/backend": "0.3.0-alpha.1"
   },
   "devDependencies": {
     "ava": "^7.0.0",
     "tsx": "^4.0.0",
-    "@openfairygui/core": "0.2.0-alpha.3"
+    "@openfairygui/test-utils": "0.2.0-alpha.10",
+    "@openfairygui/core": "0.3.0-alpha.1"
   },
   "ava": {
     "extensions": {
@@ -78,8 +79,8 @@
     ]
   },
   "scripts": {
-    "build": "tsdown src/index.ts src/stdio.ts --format esm,cjs --platform node --external node:fs --external node:path --external node:fs/promises --env.PACKAGE_VERSION=$npm_package_version",
-    "build:watch": "tsdown src/index.ts src/stdio.ts --watch --format esm,cjs --platform node --env.PACKAGE_VERSION=$npm_package_version",
+    "build": "tsdown src/index.ts src/stdio.ts --format esm,cjs --platform node --external node:fs --external node:path --external node:fs/promises",
+    "build:watch": "tsdown src/index.ts src/stdio.ts --watch --format esm,cjs --platform node",
     "test": "ava test/**/*.test.ts --no-worker-threads"
   }
 }

package/src/prompt-definitions.ts

@@ -3,6 +3,7 @@ import type { GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
 export const OPENFAIRYGUI_BACKEND_PROMPT_NAMES = [
 	'openfairygui_inspect_capabilities',
 	'openfairygui_open_and_inspect_session',
+	'openfairygui_inspect_project_outline',
 	'openfairygui_plan_revision_checked_transaction',
 	'openfairygui_save_session',
 	'openfairygui_poll_runtime_state',
@@ -38,6 +39,17 @@ export const OPENFAIRYGUI_BACKEND_PROMPT_DEFINITIONS = [
 			'Close the session with openfairygui_backend_close_session when finished.',
 		].join('\n'),
 	},
+	{
+		name: 'openfairygui_inspect_project_outline',
+		title: 'Inspect an OpenFairyGUI Project Outline',
+		description: 'Guide a client through selector discovery before a revision-checked transaction.',
+		text: [
+			'Use openfairygui_backend_get_project_outline with the active sessionId before planning mutations.',
+			'Use package, resource, folder, display node, controller page, and transition identities from the returned outline.',
+			'Pass the returned revision as expectedRevision when calling openfairygui_backend_apply_transaction.',
+			'Read a new outline if the backend reports a stale revision; the outline intentionally excludes source bytes and full property payloads.',
+		].join('\n'),
+	},
 	{
 		name: 'openfairygui_plan_revision_checked_transaction',
 		title: 'Plan a Revision-Checked OpenFairyGUI Transaction',

package/src/resource-definitions.ts

@@ -24,6 +24,7 @@ export const OPENFAIRYGUI_BACKEND_CAPABILITIES_RESOURCE_URI = 'openfairygui://ba
 
 export const OPENFAIRYGUI_BACKEND_RESOURCE_TEMPLATES = [
 	'openfairygui://backend/session/{sessionId}',
+	'openfairygui://backend/session/{sessionId}/outline',
 	'openfairygui://backend/cache/{sessionId}',
 	'openfairygui://backend/job/{sessionId}/{jobId}',
 ] as const;
@@ -53,6 +54,19 @@ export function registerOpenFairyGuiBackendResources(server: McpServer, runtime:
 		})),
 	);
 
+	server.registerResource(
+		'openfairygui_backend_project_outline',
+		new ResourceTemplate('openfairygui://backend/session/{sessionId}/outline', { list: undefined }),
+		{
+			title: 'OpenFairyGUI Project Outline',
+			description: 'Read a revision-bound project identity outline without source bytes or full property payloads.',
+			mimeType: JSON_MIME_TYPE,
+		},
+		(uri: URL, variables) => jsonResource(uri, runtime.getProjectOutline({
+			sessionId: firstVariable(variables.sessionId),
+		})),
+	);
+
 	server.registerResource(
 		'openfairygui_backend_cache',
 		new ResourceTemplate('openfairygui://backend/cache/{sessionId}', { list: undefined }),

package/src/server.ts

@@ -1,5 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { createNodeBackendRuntime } from '@openfairygui/backend/node';
+import { createRequire } from 'node:module';
 import { registerOpenFairyGuiBackendPrompts } from './prompt-definitions.js';
 import { registerOpenFairyGuiBackendResources } from './resource-definitions.js';
 import { callOpenFairyGuiBackendTool, type OpenFairyGuiBackendRuntime } from './tool-handler.js';
@@ -8,7 +9,29 @@ import {
 	type OpenFairyGuiBackendToolName,
 } from './tool-definitions.js';
 
-const PACKAGE_VERSION = process.env.npm_package_version ?? '0.2.0-alpha.0';
+const require = createRequire(import.meta.url);
+declare const __OPENFAIRYGUI_PACKAGE_VERSION__: string | undefined;
+
+function getInjectedPackageVersion(): string | null {
+	const version = typeof __OPENFAIRYGUI_PACKAGE_VERSION__ === 'string' ? __OPENFAIRYGUI_PACKAGE_VERSION__ : null;
+	return typeof version === 'string' && version.length > 0 ? version : null;
+}
+
+function readPackageVersion(): string {
+	const injectedVersion = getInjectedPackageVersion();
+	if (injectedVersion) return injectedVersion;
+	try {
+		const pkg = require('../package.json') as { version?: unknown };
+		if (typeof pkg.version === 'string' && pkg.version.length > 0) {
+			return pkg.version;
+		}
+	} catch {
+		// Keep the MCP server usable when executed from a bundled artifact missing package.json.
+	}
+	return '0.0.0-dev';
+}
+
+const PACKAGE_VERSION = readPackageVersion();
 
 export interface CreateOpenFairyGuiMcpServerOptions {
 	runtime?: OpenFairyGuiBackendRuntime;

package/src/tool-definitions.ts

@@ -7,8 +7,10 @@ export const OPENFAIRYGUI_BACKEND_TOOL_NAMES = [
 	'openfairygui_backend_open_session',
 	'openfairygui_backend_open_project_session',
 	'openfairygui_backend_get_session',
+	'openfairygui_backend_get_project_outline',
 	'openfairygui_backend_apply_transaction',
 	'openfairygui_backend_save_session',
+	'openfairygui_backend_materialize_session',
 	'openfairygui_backend_close_session',
 	'openfairygui_backend_get_events',
 	'openfairygui_backend_get_job',
@@ -25,8 +27,10 @@ export type BackendMethodName =
 	| 'openSession'
 	| 'openProjectSession'
 	| 'getSession'
+	| 'getProjectOutline'
 	| 'applyTransaction'
 	| 'saveSession'
+	| 'materializeSession'
 	| 'closeSession'
 	| 'getEvents'
 	| 'getJob'
@@ -108,6 +112,15 @@ export const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
 	},
+	{
+		name: 'openfairygui_backend_get_project_outline',
+		backendMethod: 'getProjectOutline',
+		title: 'Get Project Outline',
+		description: 'Return a revision-bound project/package/resource/component identity outline without source bytes or full property payloads.',
+		inputSchema: z.object({ sessionId }),
+		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
+		annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+	},
 	{
 		name: 'openfairygui_backend_apply_transaction',
 		backendMethod: 'applyTransaction',
@@ -130,6 +143,22 @@ export const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 			sessionId,
 			expectedRevision: expectedRevision.optional(),
 			targetPath: z.string().min(1).optional(),
+			force: z.boolean().optional(),
+			mode: z.literal('materializeCleanSession').optional(),
+		}),
+		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
+		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+	},
+	{
+		name: 'openfairygui_backend_materialize_session',
+		backendMethod: 'materializeSession',
+		title: 'Materialize Backend Session',
+		description: 'Force materialize the current backend session project through the configured project storage without requiring a dirty edit revision.',
+		inputSchema: z.object({
+			sessionId,
+			expectedRevision: expectedRevision.optional(),
+			mode: z.literal('fullProject').optional(),
+			reason: z.string().min(1).optional(),
 		}),
 		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
@@ -138,7 +167,7 @@ export const OPENFAIRYGUI_BACKEND_TOOL_DEFINITIONS = [
 		name: 'openfairygui_backend_close_session',
 		backendMethod: 'closeSession',
 		title: 'Close Backend Session',
-		description: 'Close a backend session and release its backend-local advisory lock.',
+		description: 'Close a backend session and release its backend-local session lock.',
 		inputSchema: z.object({ sessionId }),
 		outputSchema: OPENFAIRYGUI_BACKEND_TOOL_OUTPUT_SCHEMA,
 		annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: false },

package/src/tool-handler.ts

@@ -8,8 +8,10 @@ export type OpenFairyGuiBackendRuntime = Pick<
 	| 'openSession'
 	| 'openProjectSession'
 	| 'getSession'
+	| 'getProjectOutline'
 	| 'applyTransaction'
 	| 'saveSession'
+	| 'materializeSession'
 	| 'closeSession'
 	| 'getEvents'
 	| 'getJob'
@@ -69,6 +71,11 @@ export async function callOpenFairyGuiBackendTool(
 				sessionId: String(input.sessionId),
 			});
 			break;
+		case 'openfairygui_backend_get_project_outline':
+			result = runtime.getProjectOutline({
+				sessionId: String(input.sessionId),
+			});
+			break;
 		case 'openfairygui_backend_apply_transaction':
 			result = await runtime.applyTransaction({
 				sessionId: String(input.sessionId),
@@ -81,6 +88,16 @@ export async function callOpenFairyGuiBackendTool(
 				sessionId: String(input.sessionId),
 				expectedRevision: input.expectedRevision === undefined ? undefined : Number(input.expectedRevision),
 				targetPath: input.targetPath === undefined ? undefined : String(input.targetPath),
+				force: input.force === undefined ? undefined : Boolean(input.force),
+				mode: input.mode as Parameters<BackendRuntime['saveSession']>[0]['mode'],
+			});
+			break;
+		case 'openfairygui_backend_materialize_session':
+			result = await runtime.materializeSession({
+				sessionId: String(input.sessionId),
+				expectedRevision: input.expectedRevision === undefined ? undefined : Number(input.expectedRevision),
+				mode: input.mode as Parameters<BackendRuntime['materializeSession']>[0]['mode'],
+				reason: input.reason === undefined ? undefined : String(input.reason),
 			});
 			break;
 		case 'openfairygui_backend_close_session':