feat: add server helpers and optional connect() transport

ochafik · claude · ochafik · commit b0dc59250f79 · 2025-12-16T20:23:21.000Z
## Server Helpers (`src/server/`) Add convenience functions for registering MCP App tools and resources: - `registerAppTool(server, name, config, handler)` - registers a tool with `_meta[RESOURCE_URI_META_KEY]` for the UI resource URI - `registerAppResource(server, name, uri, config, callback)` - registers a resource with default MIME type `text/html;profile=mcp-app` Types use SDK directly: `Pick<McpServer, "registerTool">`, `ToolCallback`, etc. ## Optional Transport in App.connect() `App.connect()` now accepts an optional transport parameter: - Defaults to `PostMessageTransport(window.parent)` when not provided - Simplifies app initialization: `await app.connect()` just works ## Example Updates Updated basic-server-react and basic-server-vanillajs examples to use the new helpers. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/examples/basic-server-react/server.ts b/examples/basic-server-react/server.ts
@@ -1,9 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult } 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 "../../src/server";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -20,14 +25,14 @@ 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(
+  // resource (the UI it renders). Use registerAppTool and registerAppResource
+  // for a cleaner API that automatically sets up the required metadata.
+  registerAppTool(
+    server,
     "get-time",
     {
       title: "Get Time",
       description: "Returns the current server time as an ISO 8601 string.",
-      inputSchema: {},
       _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
     },
     async (): Promise<CallToolResult> => {
@@ -38,19 +43,18 @@ function createServer(): McpServer {
     },
   );
 
-  server.registerResource(
+  registerAppResource(
+    server,
+    "Get Time App",
     RESOURCE_URI,
-    RESOURCE_URI,
-    { mimeType: RESOURCE_MIME_TYPE },
-    async (): Promise<ReadResourceResult> => {
-      const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
-
+    { description: "Interactive time display", mimeType: RESOURCE_MIME_TYPE, _meta: { ui: {} } },
+    async () => {
+      const html = await fs.readFile(
+        path.join(DIST_DIR, "mcp-app.html"),
+        "utf-8",
+      );
       return {
-        contents: [
-          // Per the MCP App specification, "text/html;profile=mcp-app" signals
-          // to the Host that this resource is indeed for an MCP App UI.
-          { uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html },
-        ],
+        contents: [{ uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html }],
       };
     },
   );
diff --git a/examples/basic-server-vanillajs/server.ts b/examples/basic-server-vanillajs/server.ts
@@ -1,9 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult } 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 "../../src/server";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -20,14 +25,14 @@ 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(
+  // resource (the UI it renders). Use registerAppTool and registerAppResource
+  // for a cleaner API that automatically sets up the required metadata.
+  registerAppTool(
+    server,
     "get-time",
     {
       title: "Get Time",
       description: "Returns the current server time as an ISO 8601 string.",
-      inputSchema: {},
       _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
     },
     async (): Promise<CallToolResult> => {
@@ -38,19 +43,18 @@ function createServer(): McpServer {
     },
   );
 
-  server.registerResource(
+  registerAppResource(
+    server,
+    "Get Time App",
     RESOURCE_URI,
-    RESOURCE_URI,
-    { mimeType: RESOURCE_MIME_TYPE },
-    async (): Promise<ReadResourceResult> => {
-      const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
-
+    { description: "Interactive time display", mimeType: RESOURCE_MIME_TYPE, _meta: { ui: {} } },
+    async () => {
+      const html = await fs.readFile(
+        path.join(DIST_DIR, "mcp-app.html"),
+        "utf-8",
+      );
       return {
-        contents: [
-          // Per the MCP App specification, "text/html;profile=mcp-app" signals
-          // to the Host that this resource is indeed for an MCP App UI.
-          { uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html },
-        ],
+        contents: [{ uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html }],
       };
     },
   );
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";
@@ -97,5 +97,5 @@ openLinkBtn.addEventListener("click", async () => {
 });
 
 
-// Connect to host
-app.connect(new PostMessageTransport(window.parent));
+// Connect to host (uses PostMessageTransport by default)
+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
@@ -16,6 +16,7 @@ import {
   PingRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { AppNotification, AppRequest, AppResult } from "./types";
+import { PostMessageTransport } from "./message-transport";
 import {
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
@@ -991,7 +992,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
    * Establish connection with the host and perform initialization handshake.
    *
    * This method performs the following steps:
-   * 1. Connects the transport layer
+   * 1. Connects the transport layer (defaults to PostMessageTransport if not provided)
    * 2. Sends `ui/initialize` request with app info and capabilities
    * 3. Receives host capabilities and context in response
    * 4. Sends `ui/notifications/initialized` notification
@@ -1000,32 +1001,33 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
    * If initialization fails, the connection is automatically closed and an error
    * is thrown.
    *
-   * @param transport - Transport layer (typically PostMessageTransport)
+   * @param transport - Optional transport layer. Defaults to `PostMessageTransport(window.parent)`.
    * @param options - Request options for the initialize request
    *
    * @throws {Error} If initialization fails or connection is lost
    *
-   * @example Connect with PostMessageTransport
+   * @example Connect with default transport (recommended)
    * ```typescript
    * const app = new App(
    *   { name: "MyApp", version: "1.0.0" },
    *   {}
    * );
    *
-   * try {
-   *   await app.connect(new PostMessageTransport(window.parent));
-   *   console.log("Connected successfully!");
-   * } catch (error) {
-   *   console.error("Failed to connect:", error);
-   * }
+   * // Uses PostMessageTransport(window.parent) by default
+   * await app.connect();
+   * ```
+   *
+   * @example Connect with explicit transport
+   * ```typescript
+   * await app.connect(new PostMessageTransport(window.parent));
    * ```
    *
    * @see {@link McpUiInitializeRequest} for the initialization request structure
    * @see {@link McpUiInitializedNotification} for the initialized notification
    * @see {@link PostMessageTransport} for the typical transport implementation
    */
   override async connect(
-    transport: Transport,
+    transport: Transport = new PostMessageTransport(window.parent),
     options?: RequestOptions,
   ): Promise<void> {
     await super.connect(transport);
diff --git a/src/react/useApp.tsx b/src/react/useApp.tsx
@@ -1,7 +1,6 @@
 import { useEffect, useState } from "react";
 import { Implementation } from "@modelcontextprotocol/sdk/types.js";
-import { Client } from "@modelcontextprotocol/sdk/client";
-import { App, McpUiAppCapabilities, PostMessageTransport } from "../app";
+import { App, McpUiAppCapabilities } from "../app";
 export * from "../app";
 
 /**
@@ -117,13 +116,13 @@ export function useApp({
 
     async function connect() {
       try {
-        const transport = new PostMessageTransport(window.parent);
         const app = new App(appInfo, capabilities);
 
         // Register handlers BEFORE connecting
         onAppCreated?.(app);
 
-        await app.connect(transport);
+        // connect() defaults to PostMessageTransport(window.parent)
+        await app.connect();
 
         if (mounted) {
           setApp(app);
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
