feat: add server helpers and optional connect() transport

ochafik · claude · ochafik · commit f6b87cbf8f32 · 2025-12-16T20:27:37.000Z
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>
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/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,7 @@ 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";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
diff --git a/examples/cohort-heatmap-server/server.ts b/examples/cohort-heatmap-server/server.ts
@@ -4,7 +4,7 @@ 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";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
diff --git a/examples/customer-segmentation-server/server.ts b/examples/customer-segmentation-server/server.ts
@@ -7,7 +7,7 @@ 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";
 import { startServer } from "../shared/server-utils.js";
 import {
   generateCustomers,
diff --git a/examples/scenario-modeler-server/server.ts b/examples/scenario-modeler-server/server.ts
@@ -7,7 +7,7 @@ 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";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
diff --git a/examples/system-monitor-server/server.ts b/examples/system-monitor-server/server.ts
@@ -9,7 +9,7 @@ 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";
 import { startServer } from "../shared/server-utils.js";
 
 // Schemas - types are derived from these using z.infer
diff --git a/examples/threejs-server/server.ts b/examples/threejs-server/server.ts
@@ -9,7 +9,7 @@ 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";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
diff --git a/examples/wiki-explorer-server/server.ts b/examples/wiki-explorer-server/server.ts
@@ -8,7 +8,7 @@ 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";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
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,
@@ -1025,7 +1026,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
    * @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/server/index.test.ts b/src/server/index.test.ts
@@ -0,0 +1,179 @@
+import { describe, it, expect, mock } from "bun:test";
+import {
+  registerAppTool,
+  registerAppResource,
+  RESOURCE_URI_META_KEY,
+  RESOURCE_MIME_TYPE,
+} from "./index";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+describe("registerAppTool", () => {
+  it("should pass through config to server.registerTool", () => {
+    let capturedName: string | undefined;
+    let capturedConfig: Record<string, unknown> | undefined;
+    let capturedHandler: unknown;
+
+    const mockServer = {
+      registerTool: mock(
+        (name: string, config: Record<string, unknown>, handler: unknown) => {
+          capturedName = name;
+          capturedConfig = config;
+          capturedHandler = handler;
+        },
+      ),
+      registerResource: mock(() => {}),
+    };
+
+    const handler = async () => ({
+      content: [{ type: "text" as const, text: "ok" }],
+    });
+
+    registerAppTool(
+      mockServer as unknown as Pick<McpServer, "registerTool">,
+      "my-tool",
+      {
+        title: "My Tool",
+        description: "A test tool",
+        _meta: {
+          [RESOURCE_URI_META_KEY]: "ui://test/widget.html",
+        },
+      },
+      handler,
+    );
+
+    expect(mockServer.registerTool).toHaveBeenCalledTimes(1);
+    expect(capturedName).toBe("my-tool");
+    expect(capturedConfig?.title).toBe("My Tool");
+    expect(capturedConfig?.description).toBe("A test tool");
+    expect(
+      (capturedConfig?._meta as Record<string, unknown>)?.[
+        RESOURCE_URI_META_KEY
+      ],
+    ).toBe("ui://test/widget.html");
+    expect(capturedHandler).toBe(handler);
+  });
+});
+
+describe("registerAppResource", () => {
+  it("should register a resource with default MIME type", () => {
+    let capturedName: string | undefined;
+    let capturedUri: string | undefined;
+    let capturedConfig: Record<string, unknown> | undefined;
+
+    const mockServer = {
+      registerTool: mock(() => {}),
+      registerResource: mock(
+        (name: string, uri: string, config: Record<string, unknown>) => {
+          capturedName = name;
+          capturedUri = uri;
+          capturedConfig = config;
+        },
+      ),
+    };
+
+    const callback = async () => ({
+      contents: [
+        {
+          uri: "ui://test/widget.html",
+          mimeType: RESOURCE_MIME_TYPE,
+          text: "<html/>",
+        },
+      ],
+    });
+
+    registerAppResource(
+      mockServer as unknown as Pick<McpServer, "registerResource">,
+      "My Resource",
+      "ui://test/widget.html",
+      {
+        description: "A test resource",
+        _meta: { ui: {} },
+      },
+      callback,
+    );
+
+    expect(mockServer.registerResource).toHaveBeenCalledTimes(1);
+    expect(capturedName).toBe("My Resource");
+    expect(capturedUri).toBe("ui://test/widget.html");
+    expect(capturedConfig?.mimeType).toBe(RESOURCE_MIME_TYPE);
+    expect(capturedConfig?.description).toBe("A test resource");
+  });
+
+  it("should allow custom MIME type to override default", () => {
+    let capturedConfig: Record<string, unknown> | undefined;
+
+    const mockServer = {
+      registerTool: mock(() => {}),
+      registerResource: mock(
+        (_name: string, _uri: string, config: Record<string, unknown>) => {
+          capturedConfig = config;
+        },
+      ),
+    };
+
+    registerAppResource(
+      mockServer as unknown as Pick<McpServer, "registerResource">,
+      "My Resource",
+      "ui://test/widget.html",
+      {
+        mimeType: "text/html",
+        _meta: { ui: {} },
+      },
+      async () => ({
+        contents: [
+          {
+            uri: "ui://test/widget.html",
+            mimeType: "text/html",
+            text: "<html/>",
+          },
+        ],
+      }),
+    );
+
+    // Custom mimeType should override the default
+    expect(capturedConfig?.mimeType).toBe("text/html");
+  });
+
+  it("should call the callback when handler is invoked", async () => {
+    let capturedHandler: (() => Promise<unknown>) | undefined;
+
+    const mockServer = {
+      registerTool: mock(() => {}),
+      registerResource: mock(
+        (
+          _name: string,
+          _uri: string,
+          _config: unknown,
+          handler: () => Promise<unknown>,
+        ) => {
+          capturedHandler = handler;
+        },
+      ),
+    };
+
+    const expectedResult = {
+      contents: [
+        {
+          uri: "ui://test/widget.html",
+          mimeType: RESOURCE_MIME_TYPE,
+          text: "<html>content</html>",
+        },
+      ],
+    };
+    const callback = mock(async () => expectedResult);
+
+    registerAppResource(
+      mockServer as unknown as Pick<McpServer, "registerResource">,
+      "My Resource",
+      "ui://test/widget.html",
+      { _meta: { ui: {} } },
+      callback,
+    );
+
+    expect(capturedHandler).toBeDefined();
+    const result = await capturedHandler!();
+
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(result).toEqual(expectedResult);
+  });
+});
diff --git a/src/server/index.ts b/src/server/index.ts
