feat: add server helpers, make connect() to default to parent post transport

examples/basic-server-react/server.ts

@@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "@modelcontextprotocol/ext-apps/server";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -22,7 +22,7 @@ function createServer(): McpServer {
   // MCP Apps require two-part registration: a tool (what the LLM calls) and a
   // resource (the UI it renders). The `_meta` field on the tool links to the
   // resource URI, telling hosts which UI to display when the tool executes.
-  server.registerTool(
+  registerAppTool(server,
     "get-time",
     {
       title: "Get Time",
@@ -38,7 +38,7 @@ function createServer(): McpServer {
     },
   );
 
-  server.registerResource(
+  registerAppResource(server,
     RESOURCE_URI,
     RESOURCE_URI,
     { mimeType: RESOURCE_MIME_TYPE },

examples/basic-server-vanillajs/README.md

@@ -52,5 +52,5 @@ button.addEventListener("click", () => {
 });
 
 // Connect to host
-app.connect(new PostMessageTransport(window.parent));
+app.connect();
 ```

examples/basic-server-vanillajs/server.ts

@@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "@modelcontextprotocol/ext-apps/server";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -22,7 +22,7 @@ function createServer(): McpServer {
   // MCP Apps require two-part registration: a tool (what the LLM calls) and a
   // resource (the UI it renders). The `_meta` field on the tool links to the
   // resource URI, telling hosts which UI to display when the tool executes.
-  server.registerTool(
+  registerAppTool(server,
     "get-time",
     {
       title: "Get Time",
@@ -38,7 +38,7 @@ function createServer(): McpServer {
     },
   );
 
-  server.registerResource(
+  registerAppResource(server,
     RESOURCE_URI,
     RESOURCE_URI,
     { mimeType: RESOURCE_MIME_TYPE },

examples/basic-server-vanillajs/src/mcp-app.ts

@@ -1,7 +1,7 @@
 /**
  * @file App that demonstrates a few features using MCP Apps SDK with vanilla JS.
  */
-import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";
+import { App } from "@modelcontextprotocol/ext-apps";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import "./global.css";
 import "./mcp-app.css";
@@ -98,4 +98,4 @@ openLinkBtn.addEventListener("click", async () => {
 
 
 // Connect to host
-app.connect(new PostMessageTransport(window.parent));
+app.connect();

examples/budget-allocator-server/server.ts

@@ -13,7 +13,10 @@ import type {
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import {
+  RESOURCE_MIME_TYPE,
+  RESOURCE_URI_META_KEY,
+} from "@modelcontextprotocol/ext-apps/server";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -235,7 +238,8 @@ function createServer(): McpServer {
     version: "1.0.0",
   });
 
-  server.registerTool(
+  registerAppTool(
+    server,
     "get-budget-data",
     {
       title: "Get Budget Data",
@@ -277,7 +281,8 @@ function createServer(): McpServer {
     },
   );
 
-  server.registerResource(
+  registerAppResource(
+    server,
     resourceUri,
     resourceUri,
     {

examples/budget-allocator-server/src/mcp-app.ts

@@ -1,7 +1,7 @@
 /**
  * Budget Allocator App - Interactive budget allocation with real-time visualization
  */
-import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";
+import { App } from "@modelcontextprotocol/ext-apps";
 import { Chart, registerables } from "chart.js";
 import "./global.css";
 import "./mcp-app.css";
@@ -631,4 +631,4 @@ window
   });
 
 // Connect to host
-app.connect(new PostMessageTransport(window.parent));
+app.connect();

examples/cohort-heatmap-server/server.ts

@@ -4,7 +4,10 @@ import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import {
+  RESOURCE_MIME_TYPE,
+  RESOURCE_URI_META_KEY,
+} from "@modelcontextprotocol/ext-apps/server";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -156,7 +159,8 @@ function createServer(): McpServer {
   // Register tool and resource
   const resourceUri = "ui://get-cohort-data/mcp-app.html";
 
-  server.registerTool(
+  registerAppTool(
+    server,
     "get-cohort-data",
     {
       title: "Get Cohort Retention Data",
@@ -179,7 +183,8 @@ function createServer(): McpServer {
     },
   );
 
-  server.registerResource(
+  registerAppResource(
+    server,
     resourceUri,
     resourceUri,
     { mimeType: RESOURCE_MIME_TYPE },

examples/customer-segmentation-server/server.ts

@@ -7,7 +7,10 @@ import type {
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import {
+  RESOURCE_MIME_TYPE,
+  RESOURCE_URI_META_KEY,
+} from "@modelcontextprotocol/ext-apps/server";
 import { startServer } from "../shared/server-utils.js";
 import {
   generateCustomers,
@@ -65,7 +68,8 @@ function createServer(): McpServer {
   {
     const resourceUri = "ui://customer-segmentation/mcp-app.html";
 
-    server.registerTool(
+    registerAppTool(
+      server,
       "get-customer-data",
       {
         title: "Get Customer Data",
@@ -83,7 +87,8 @@ function createServer(): McpServer {
       },
     );
 
-    server.registerResource(
+    registerAppResource(
+      server,
       resourceUri,
       resourceUri,
       {

examples/customer-segmentation-server/src/mcp-app.ts

@@ -463,7 +463,7 @@ app.onhostcontextchanged = (params) => {
   }
 };
 
-app.connect(new PostMessageTransport(window.parent)).then(() => {
+app.connect().then(() => {
   // Apply initial host context after connection
   const ctx = app.getHostContext();
   if (ctx?.theme) {

examples/qr-server/widget.html

@@ -47,7 +47,7 @@
       }
     };
 
-    await app.connect(new PostMessageTransport(window.parent));
+    await app.connect();
   </script>
 </body>
 </html>

examples/scenario-modeler-server/server.ts

@@ -7,7 +7,10 @@ import type {
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import {
+  RESOURCE_MIME_TYPE,
+  RESOURCE_URI_META_KEY,
+} from "@modelcontextprotocol/ext-apps/server";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -256,7 +259,8 @@ function createServer(): McpServer {
   {
     const resourceUri = "ui://scenario-modeler/mcp-app.html";
 
-    server.registerTool(
+    registerAppTool(
+      server,
       "get-scenario-data",
       {
         title: "Get Scenario Data",
@@ -288,7 +292,8 @@ function createServer(): McpServer {
       },
     );
 
-    server.registerResource(
+    registerAppResource(
+      server,
       resourceUri,
       resourceUri,
       { mimeType: RESOURCE_MIME_TYPE, description: "SaaS Scenario Modeler UI" },

examples/system-monitor-server/server.ts

@@ -9,7 +9,10 @@ import os from "node:os";
 import path from "node:path";
 import si from "systeminformation";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import {
+  RESOURCE_MIME_TYPE,
+  RESOURCE_URI_META_KEY,
+} from "@modelcontextprotocol/ext-apps/server";
 import { startServer } from "../shared/server-utils.js";
 
 // Schemas - types are derived from these using z.infer
@@ -111,7 +114,8 @@ function createServer(): McpServer {
   // Register the get-system-stats tool and its associated UI resource
   const resourceUri = "ui://system-monitor/mcp-app.html";
 
-  server.registerTool(
+  registerAppTool(
+    server,
     "get-system-stats",
     {
       title: "Get System Stats",
@@ -149,7 +153,8 @@ function createServer(): McpServer {
     },
   );
 
-  server.registerResource(
+  registerAppResource(
+    server,
     resourceUri,
     resourceUri,
     { mimeType: RESOURCE_MIME_TYPE, description: "System Monitor UI" },

examples/system-monitor-server/src/mcp-app.ts

@@ -1,7 +1,7 @@
 /**
  * @file System Monitor App - displays real-time OS metrics with Chart.js
  */
-import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";
+import { App } from "@modelcontextprotocol/ext-apps";
 import { Chart, registerables } from "chart.js";
 import "./global.css";
 import "./mcp-app.css";
@@ -360,7 +360,7 @@ window
 // Register handlers and connect
 app.onerror = log.error;
 
-app.connect(new PostMessageTransport(window.parent));
+app.connect();
 
 // Auto-start polling after a short delay
 setTimeout(startPolling, 500);

examples/threejs-server/server.ts

@@ -9,7 +9,10 @@ import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import {
+  RESOURCE_MIME_TYPE,
+  RESOURCE_URI_META_KEY,
+} from "@modelcontextprotocol/ext-apps/server";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -142,7 +145,8 @@ function createServer(): McpServer {
   });
 
   // Tool 1: show_threejs_scene
-  server.registerTool(
+  registerAppTool(
+    server,
     "show_threejs_scene",
     {
       title: "Show Three.js Scene",
@@ -175,7 +179,8 @@ function createServer(): McpServer {
   );
 
   // Tool 2: learn_threejs
-  server.registerTool(
+  registerAppTool(
+    server,
     "learn_threejs",
     {
       title: "Learn Three.js",
@@ -191,7 +196,8 @@ function createServer(): McpServer {
   );
 
   // Resource registration
-  server.registerResource(
+  registerAppResource(
+    server,
     resourceUri,
     resourceUri,
     { mimeType: RESOURCE_MIME_TYPE, description: "Three.js Widget UI" },

examples/wiki-explorer-server/server.ts

@@ -8,7 +8,10 @@ import * as cheerio from "cheerio";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import {
+  RESOURCE_MIME_TYPE,
+  RESOURCE_URI_META_KEY,
+} from "@modelcontextprotocol/ext-apps/server";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -76,7 +79,8 @@ function createServer(): McpServer {
   // Register the get-first-degree-links tool and its associated UI resource
   const resourceUri = "ui://wiki-explorer/mcp-app.html";
 
-  server.registerTool(
+  registerAppTool(
+    server,
     "get-first-degree-links",
     {
       title: "Get First-Degree Links",
@@ -124,7 +128,8 @@ function createServer(): McpServer {
     },
   );
 
-  server.registerResource(
+  registerAppResource(
+    server,
     resourceUri,
     resourceUri,
     { mimeType: RESOURCE_MIME_TYPE },

examples/wiki-explorer-server/src/mcp-app.ts

@@ -1,7 +1,7 @@
 /**
  * Wiki Explorer - Force-directed graph visualization of Wikipedia link networks
  */
-import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";
+import { App } from "@modelcontextprotocol/ext-apps";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import {
   forceCenter,
@@ -367,4 +367,4 @@ app.onerror = (err) => {
 };
 
 // Connect to host
-app.connect(new PostMessageTransport(window.parent));
+app.connect();

package.json

@@ -23,6 +23,10 @@
       "types": "./dist/src/app-bridge.d.ts",
       "default": "./dist/src/app-bridge.js"
     },
+    "./server": {
+      "types": "./dist/src/server/index.d.ts",
+      "default": "./dist/src/server/index.js"
+    },
     "./schema.json": "./dist/src/generated/schema.json"
   },
   "files": [