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

ochafik · claude · jonathanhefner · web-flow · commit bea0ae27f5d1 · 2025-12-16T21:25:26.000Z
* feat: add server helpers and optional connect() transport Add `src/server/` with convenience functions for registering MCP App tools and resources: - `registerAppTool(server, name, config, handler)` - `registerAppResource(server, name, uri, config, callback)` The `transport` parameter in `App.connect()` is now optional, defaulting to `PostMessageTransport(window.parent)`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Update src/server/index.ts Co-authored-by: Jonathan Hefner <jonathan@hefner.pro> * fix: refine server helper types - Make RESOURCE_URI_META_KEY required in McpUiAppToolConfig (tools need a UI resource) - Make _meta optional in McpUiAppResourceConfig (not all resources need custom metadata) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: simplify RESOURCE_URI_META_KEY re-export * refactor: consolidate export statements --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>
diff --git a/examples/basic-server-react/server.ts b/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 },
diff --git a/examples/basic-server-vanillajs/README.md b/examples/basic-server-vanillajs/README.md
@@ -52,5 +52,5 @@ button.addEventListener("click", () => {
 });
 
 // Connect to host
-app.connect(new PostMessageTransport(window.parent));
+app.connect();
 ```
diff --git a/examples/basic-server-vanillajs/server.ts b/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 },
diff --git a/examples/basic-server-vanillajs/src/mcp-app.ts b/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();
diff --git a/examples/budget-allocator-server/server.ts b/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,
     {
diff --git a/examples/budget-allocator-server/src/mcp-app.ts b/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();
diff --git a/examples/cohort-heatmap-server/server.ts b/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 },
diff --git a/examples/customer-segmentation-server/server.ts b/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,
       {
diff --git a/examples/customer-segmentation-server/src/mcp-app.ts b/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) {
diff --git a/examples/qr-server/widget.html b/examples/qr-server/widget.html
@@ -47,7 +47,7 @@
       }
     };
 
-    await app.connect(new PostMessageTransport(window.parent));
+    await app.connect();
   </script>
 </body>
 </html>
diff --git a/examples/scenario-modeler-server/server.ts b/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" },
diff --git a/examples/system-monitor-server/server.ts b/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" },
diff --git a/examples/system-monitor-server/src/mcp-app.ts b/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);
diff --git a/examples/threejs-server/server.ts b/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" },
diff --git a/examples/wiki-explorer-server/server.ts b/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 },
diff --git a/examples/wiki-explorer-server/src/mcp-app.ts b/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();
diff --git a/package.json b/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": [
diff --git a/src/app.ts b/src/app.ts
diff --git a/src/server/index.test.ts b/src/server/index.test.ts
diff --git a/src/server/index.ts b/src/server/index.ts

Original file line number	Diff line number	Diff line change
`@@ -463,7 +463,7 @@ app.onhostcontextchanged = (params) => {`
`463`	`463`	`}`
`464`	`464`	`};`
`465`	`465`
`466`		`-app.connect(new PostMessageTransport(window.parent)).then(() => {`
	`466`	`+app.connect().then(() => {`
`467`	`467`	`// Apply initial host context after connection`
`468`	`468`	`const ctx = app.getHostContext();`
`469`	`469`	`if (ctx?.theme) {`
Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,7 @@`
`47`	`47`	`}`
`48`	`48`	`};`
`49`	`49`
`50`		`- await app.connect(new PostMessageTransport(window.parent));`
	`50`	`+ await app.connect();`
`51`	`51`	`</script>`
`52`	`52`	`</body>`
`53`	`53`	`</html>`