feat(basic-host): improve host UI with collapsible panels and SDK types (#244)

* refactor(basic-host): use SDK types for ModelContext and AppMessage

- Import McpUiUpdateModelContextRequest and McpUiMessageRequest from SDK
- Replace custom ModelContext with McpUiUpdateModelContextRequest['params']
- Replace custom AppMessage with McpUiMessageRequest['params']
- Pass full message params instead of extracting text
- Format messages by extracting text from content blocks in display

* feat(basic-host): handle non-text content blocks in display

- Add formatContentBlock helper for text, image, audio, resource types
- Show placeholders like <image: image/png> for non-text content
- Apply to both messages and model context display

* test: update shadertoy screenshot

* test: update screenshots from CI (linux x64)

examples/basic-host/src/implementation.ts

@@ -1,4 +1,4 @@
-import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions, buildAllowAttribute, type McpUiUpdateModelContextRequest, type McpUiMessageRequest } from "@modelcontextprotocol/ext-apps/app-bridge";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
@@ -122,12 +122,19 @@ async function getUiResource(serverInfo: ServerInfo, uri: string): Promise<UiRes
 export function loadSandboxProxy(
   iframe: HTMLIFrameElement,
   csp?: McpUiResourceCsp,
+  permissions?: McpUiResourcePermissions,
 ): Promise<boolean> {
   // Prevent reload
   if (iframe.src) return Promise.resolve(false);
 
   iframe.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms");
 
+  // Set Permission Policy allow attribute based on requested permissions
+  const allowAttribute = buildAllowAttribute(permissions);
+  if (allowAttribute) {
+    iframe.setAttribute("allow", allowAttribute);
+  }
+
   const readyNotification: McpUiSandboxProxyReadyNotification["method"] =
     "ui/notifications/sandbox-proxy-ready";
 
@@ -215,12 +222,26 @@ function hookInitializedCallback(appBridge: AppBridge): Promise<void> {
 }
 
 
-export function newAppBridge(serverInfo: ServerInfo, iframe: HTMLIFrameElement): AppBridge {
+export type ModelContext = McpUiUpdateModelContextRequest["params"];
+export type AppMessage = McpUiMessageRequest["params"];
+
+export interface AppBridgeCallbacks {
+  onContextUpdate?: (context: ModelContext | null) => void;
+  onMessage?: (message: AppMessage) => void;
+}
+
+export function newAppBridge(
+  serverInfo: ServerInfo,
+  iframe: HTMLIFrameElement,
+  callbacks?: AppBridgeCallbacks,
+): AppBridge {
   const serverCapabilities = serverInfo.client.getServerCapabilities();
   const appBridge = new AppBridge(serverInfo.client, IMPLEMENTATION, {
     openLinks: {},
     serverTools: serverCapabilities?.tools,
     serverResources: serverCapabilities?.resources,
+    // Declare support for model context updates
+    updateModelContext: { text: {} },
   });
 
   // Register all handlers before calling connect(). The Guest UI can start
@@ -229,6 +250,7 @@ export function newAppBridge(serverInfo: ServerInfo, iframe: HTMLIFrameElement):
 
   appBridge.onmessage = async (params, _extra) => {
     log.info("Message from MCP App:", params);
+    callbacks?.onMessage?.(params);
     return {};
   };
 
@@ -242,6 +264,15 @@ export function newAppBridge(serverInfo: ServerInfo, iframe: HTMLIFrameElement):
     log.info("Log message from MCP App:", params);
   };
 
+  appBridge.onupdatemodelcontext = async (params) => {
+    log.info("Model context update from MCP App:", params);
+    // Normalize: empty content array means clear context
+    const hasContent = params.content && params.content.length > 0;
+    const hasStructured = params.structuredContent && Object.keys(params.structuredContent).length > 0;
+    callbacks?.onContextUpdate?.(hasContent || hasStructured ? params : null);
+    return {};
+  };
+
   appBridge.onsizechange = async ({ width, height }) => {
     // The MCP App has requested a `width` and `height`, but if
     // `box-sizing: border-box` is applied to the outer iframe element, then we

examples/basic-host/src/index.module.css

@@ -126,6 +126,46 @@
   min-width: 0;
 }
 
+.appOutputPanel {
+  flex: 1;
+  min-width: 0;
+}
+
+.appHeader {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.5rem;
+  font-size: 1.25rem;
+  font-weight: 600;
+  position: relative;
+
+  .toolName {
+    font-family: monospace;
+  }
+
+  .closeButton {
+    position: absolute;
+    top: 0;
+    right: 0;
+    width: 1.5rem;
+    height: 1.5rem;
+    padding: 0;
+    border: none;
+    border-radius: 4px;
+    background: #e0e0e0;
+    font-size: 1.25rem;
+    line-height: 1;
+    color: #666;
+    cursor: pointer;
+
+    &:hover {
+      background: #d0d0d0;
+      color: #333;
+    }
+  }
+}
+
 .jsonBlock {
   flex-grow: 1;
   min-height: 0;
@@ -148,6 +188,66 @@
   }
 }
 
+.collapsiblePanel {
+  margin: 0.5rem 0;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 4px;
+  background-color: #fafafa;
+  font-size: 0.875rem;
+  cursor: pointer;
+  transition: background-color 0.15s;
+
+  &:hover {
+    background-color: #f0f0f0;
+  }
+}
+
+.collapsibleHeader {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.collapsibleLabel {
+  font-weight: 600;
+  color: #555;
+}
+
+.collapsibleSize {
+  color: #888;
+  font-size: 0.75rem;
+}
+
+.collapsibleToggle {
+  margin-left: auto;
+  color: #888;
+  font-size: 0.75rem;
+}
+
+.collapsiblePreview {
+  margin-top: 0.25rem;
+  color: #666;
+  font-family: monospace;
+  font-size: 0.8rem;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.collapsibleFull {
+  margin: 0.5rem 0 0;
+  padding: 0.5rem;
+  border-radius: 4px;
+  background-color: #f5f5f5;
+  font-family: monospace;
+  font-size: 0.8rem;
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 200px;
+  overflow: auto;
+}
+
 .error {
   padding: 1.5rem;
   background-color: #ddd;

examples/basic-host/src/index.tsx

@@ -1,7 +1,7 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { Component, type ErrorInfo, type ReactNode, StrictMode, Suspense, use, useEffect, useMemo, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
-import { callTool, connectToServer, hasAppHtml, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo } from "./implementation";
+import { callTool, connectToServer, hasAppHtml, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo, type ModelContext, type AppMessage } from "./implementation";
 import styles from "./index.module.css";
 
 
@@ -207,23 +207,41 @@ function ToolCallInfoPanel({ toolCallInfo, isDestroying, onRequestClose, onClose
       className={styles.toolCallInfoPanel}
       style={isDestroying ? { opacity: 0.5, pointerEvents: "none" } : undefined}
     >
-      <div className={styles.inputInfoPanel}>
-        <h2>
-          <span>{toolCallInfo.serverInfo.name}</span>
-          <span className={styles.toolName}>{toolCallInfo.tool.name}</span>
-          {onRequestClose && !isDestroying && (
-            <button
-              className={styles.closeButton}
-              onClick={onRequestClose}
-              title="Close"
-            >
-              ×
-            </button>
-          )}
-        </h2>
-        <JsonBlock value={toolCallInfo.input} />
-      </div>
-      <div className={styles.outputInfoPanel}>
+      {/* For non-app tools, show input/output side by side */}
+      {!isApp && (
+        <div className={styles.inputInfoPanel}>
+          <h2>
+            <span>{toolCallInfo.serverInfo.name}</span>
+            <span className={styles.toolName}>{toolCallInfo.tool.name}</span>
+            {onRequestClose && !isDestroying && (
+              <button
+                className={styles.closeButton}
+                onClick={onRequestClose}
+                title="Close"
+              >
+                ×
+              </button>
+            )}
+          </h2>
+          <JsonBlock value={toolCallInfo.input} />
+        </div>
+      )}
+      <div className={isApp ? styles.appOutputPanel : styles.outputInfoPanel}>
+        {/* For apps, show header above the app: ServerName:tool_name */}
+        {isApp && (
+          <div className={styles.appHeader}>
+            <span>{toolCallInfo.serverInfo.name}:<span className={styles.toolName}>{toolCallInfo.tool.name}</span></span>
+            {onRequestClose && !isDestroying && (
+              <button
+                className={styles.closeButton}
+                onClick={onRequestClose}
+                title="Close"
+              >
+                ×
+              </button>
+            )}
+          </div>
+        )}
         <ErrorBoundary>
           <Suspense fallback="Loading...">
             {
@@ -252,6 +270,43 @@ function JsonBlock({ value }: { value: object }) {
 }
 
 
+interface CollapsiblePanelProps {
+  icon: string;
+  label: string;
+  content: string;
+  badge?: string;
+  defaultExpanded?: boolean;
+}
+function CollapsiblePanel({ icon, label, content, badge, defaultExpanded = false }: CollapsiblePanelProps) {
+  const [expanded, setExpanded] = useState(defaultExpanded);
+
+  return (
+    <div
+      className={styles.collapsiblePanel}
+      onClick={() => setExpanded(!expanded)}
+      title={expanded ? "Click to collapse" : "Click to expand"}
+    >
+      <div className={styles.collapsibleHeader}>
+        <span className={styles.collapsibleLabel}>{icon} {label}</span>
+        <span className={styles.collapsibleSize}>
+          {badge ?? `${content.length} chars`}
+        </span>
+        <span className={styles.collapsibleToggle}>
+          {expanded ? "▼" : "▶"}
+        </span>
+      </div>
+      {expanded ? (
+        <pre className={styles.collapsibleFull}>{content}</pre>
+      ) : (
+        <div className={styles.collapsiblePreview}>
+          {content.slice(0, 100)}{content.length > 100 ? "…" : ""}
+        </div>
+      )}
+    </div>
+  );
+}
+
+
 interface AppIFramePanelProps {
   toolCallInfo: Required<ToolCallInfo>;
   isDestroying?: boolean;
@@ -260,25 +315,34 @@ interface AppIFramePanelProps {
 function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppIFramePanelProps) {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const appBridgeRef = useRef<ReturnType<typeof newAppBridge> | null>(null);
+  const [modelContext, setModelContext] = useState<ModelContext | null>(null);
+  const [toolResult, setToolResult] = useState<object | null>(null);
+  const [messages, setMessages] = useState<AppMessage[]>([]);
 
   useEffect(() => {
     const iframe = iframeRef.current!;
 
-    // First get CSP from resource, then load sandbox with CSP in query param
-    // This ensures CSP is set via HTTP headers (tamper-proof)
-    toolCallInfo.appResourcePromise.then(({ csp }) => {
-      loadSandboxProxy(iframe, csp).then((firstTime) => {
+    // First get CSP and permissions from resource, then load sandbox
+    // CSP is set via HTTP headers (tamper-proof), permissions via iframe allow attribute
+    toolCallInfo.appResourcePromise.then(({ csp, permissions }) => {
+      loadSandboxProxy(iframe, csp, permissions).then((firstTime) => {
         // The `firstTime` check guards against React Strict Mode's double
         // invocation (mount → unmount → remount simulation in development).
         // Outside of Strict Mode, this `useEffect` runs only once per
         // `toolCallInfo`.
         if (firstTime) {
-          const appBridge = newAppBridge(toolCallInfo.serverInfo, iframe);
+          const appBridge = newAppBridge(toolCallInfo.serverInfo, iframe, {
+            onContextUpdate: setModelContext,
+            onMessage: (msg) => setMessages((prev) => [...prev, msg]),
+          });
           appBridgeRef.current = appBridge;
           initializeApp(iframe, appBridge, toolCallInfo);
         }
       });
     });
+
+    // Track tool result for display
+    toolCallInfo.resultPromise.then(setToolResult).catch(() => {});
   }, [toolCallInfo]);
 
   // Graceful teardown: wait for guest to respond before unmounting
@@ -303,9 +367,57 @@ function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppI
       });
   }, [isDestroying, onTeardownComplete]);
 
+  // Format content blocks - handle text, images, resources, etc.
+  const formatContentBlock = (c: { type: string; [key: string]: unknown }) => {
+    switch (c.type) {
+      case "text":
+        return (c as { type: "text"; text: string }).text;
+      case "image":
+        return `<image: ${(c as { mimeType?: string }).mimeType ?? "unknown"}>`;
+      case "audio":
+        return `<audio: ${(c as { mimeType?: string }).mimeType ?? "unknown"}>`;
+      case "resource":
+        return `<resource: ${(c as { resource?: { uri?: string } }).resource?.uri ?? "unknown"}>`;
+      default:
+        return `<${c.type}>`;
+    }
+  };
+
+  // Format context for display
+  const contextText = modelContext?.content?.map(formatContentBlock).join("\n") ?? "";
+  const contextJson = modelContext?.structuredContent
+    ? JSON.stringify(modelContext.structuredContent, null, 2)
+    : "";
+  const fullContext = [contextText, contextJson].filter(Boolean).join("\n\n");
+
+  const inputJson = JSON.stringify(toolCallInfo.input, null, 2);
+  const resultJson = toolResult ? JSON.stringify(toolResult, null, 2) : null;
+
+  // Format messages
+  const formatMessage = (m: AppMessage) => {
+    const content = m.content.map(formatContentBlock).join("\n");
+    return `[${m.role}] ${content}`;
+  };
+  const messagesText = messages.map(formatMessage).join("\n\n");
+
   return (
     <div className={styles.appIframePanel}>
+      <CollapsiblePanel icon="📥" label="Tool Input" content={inputJson} />
       <iframe ref={iframeRef} />
+      {resultJson && (
+        <CollapsiblePanel icon="📤" label="Tool Result" content={resultJson} />
+      )}
+      {messages.length > 0 && (
+        <CollapsiblePanel
+          icon="💬"
+          label="Messages"
+          content={messagesText}
+          badge={`${messages.length} message${messages.length > 1 ? "s" : ""}`}
+        />
+      )}
+      {modelContext && (
+        <CollapsiblePanel icon="📋" label="Model Context" content={fullContext} />
+      )}
     </div>
   );
 }

examples/basic-host/src/sandbox.ts

@@ -1,4 +1,5 @@
 import type { McpUiSandboxProxyReadyNotification, McpUiSandboxResourceReadyNotification } from "../../../dist/src/types";
+import { buildAllowAttribute } from "../../../dist/src/app-bridge";
 
 const ALLOWED_REFERRER_PATTERN = /^http:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/;
 
@@ -43,6 +44,8 @@ try {
 const inner = document.createElement("iframe");
 inner.style = "width:100%; height:100%; border:none;";
 inner.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms");
+// Note: allow attribute is set later when receiving sandbox-resource-ready notification
+// based on the permissions requested by the app
 document.body.appendChild(inner);
 
 const RESOURCE_READY_NOTIFICATION: McpUiSandboxResourceReadyNotification["method"] =
@@ -66,24 +69,6 @@ const PROXY_READY_NOTIFICATION: McpUiSandboxProxyReadyNotification["method"] =
 // Security: CSP is enforced via HTTP headers on sandbox.html (set by serve.ts
 // based on ?csp= query param). This is tamper-proof unlike meta tags.
 
-// Build iframe allow attribute from permissions
-function buildAllowAttribute(permissions?: {
-  camera?: boolean;
-  microphone?: boolean;
-  geolocation?: boolean;
-  clipboardWrite?: boolean;
-}): string {
-  if (!permissions) return "";
-
-  const allowList: string[] = [];
-  if (permissions.camera) allowList.push("camera");
-  if (permissions.microphone) allowList.push("microphone");
-  if (permissions.geolocation) allowList.push("geolocation");
-  if (permissions.clipboardWrite) allowList.push("clipboard-write");
-
-  return allowList.join("; ");
-}
-
 window.addEventListener("message", async (event) => {
   if (event.source === window.parent) {
     // Validate that messages from parent come from the expected host origin.

src/app-bridge.ts

@@ -76,6 +76,7 @@ import {
   McpUiRequestDisplayModeRequest,
   McpUiRequestDisplayModeRequestSchema,
   McpUiRequestDisplayModeResult,
+  McpUiResourcePermissions,
 } from "./types";
 export * from "./types";
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE } from "./app";
@@ -126,6 +127,36 @@ export function getToolUiResourceUri(tool: {
   return undefined;
 }
 
+/**
+ * Build iframe `allow` attribute string from permissions.
+ *
+ * Maps McpUiResourcePermissions to the Permission Policy allow attribute
+ * format used by iframes (e.g., "microphone; clipboard-write").
+ *
+ * @param permissions - Permissions requested by the UI resource
+ * @returns Space-separated permission directives, or empty string if none
+ *
+ * @example
+ * ```typescript
+ * const allow = buildAllowAttribute({ microphone: {}, clipboardWrite: {} });
+ * // Returns: "microphone; clipboard-write"
+ * iframe.setAttribute("allow", allow);
+ * ```
+ */
+export function buildAllowAttribute(
+  permissions: McpUiResourcePermissions | undefined,
+): string {
+  if (!permissions) return "";
+
+  const allowList: string[] = [];
+  if (permissions.camera) allowList.push("camera");
+  if (permissions.microphone) allowList.push("microphone");
+  if (permissions.geolocation) allowList.push("geolocation");
+  if (permissions.clipboardWrite) allowList.push("clipboard-write");
+
+  return allowList.join("; ");
+}
+
 /**
  * Options for configuring AppBridge behavior.
  *