refactor(types): use explicit type unions for AppBridge protocol types

- Add AppBridgeRequest, AppBridgeNotification, AppBridgeResult type unions
  that explicitly list all valid types for the protocol
- Replace generic SDK Request/Notification/Result with our specific types
- Remove all type casts by using `as const` on method literals
- Add index signature to McpUiHostContext for forward compatibility

This improves type safety and documents exactly what the AppBridge supports.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: ochafik

src/app-bridge.ts

@@ -5,6 +5,7 @@ import {
   CallToolRequestSchema,
   CallToolResult,
   CallToolResultSchema,
+  EmptyResult,
   Implementation,
   ListPromptsRequest,
   ListPromptsRequestSchema,
@@ -18,9 +19,10 @@ import {
   ListResourceTemplatesRequestSchema,
   ListResourceTemplatesResult,
   ListResourceTemplatesResultSchema,
+  ListToolsRequest,
+  ListToolsResult,
   LoggingMessageNotification,
   LoggingMessageNotificationSchema,
-  Notification,
   PingRequest,
   PingRequestSchema,
   PromptListChangedNotification,
@@ -29,10 +31,8 @@ import {
   ReadResourceRequestSchema,
   ReadResourceResult,
   ReadResourceResultSchema,
-  Request,
   ResourceListChangedNotification,
   ResourceListChangedNotificationSchema,
-  Result,
   ToolListChangedNotification,
   ToolListChangedNotificationSchema,
 } from "@modelcontextprotocol/sdk/types.js";
@@ -66,6 +66,7 @@ import {
   McpUiOpenLinkRequestSchema,
   McpUiOpenLinkResult,
   McpUiResourceTeardownRequest,
+  McpUiResourceTeardownResult,
   McpUiResourceTeardownResultSchema,
   McpUiSandboxProxyReadyNotification,
   McpUiSandboxProxyReadyNotificationSchema,
@@ -75,6 +76,73 @@ export * from "./types";
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE } from "./app";
 export { PostMessageTransport } from "./message-transport";
 
+/**
+ * All request types in the MCP Apps protocol.
+ *
+ * Includes:
+ * - MCP UI requests (initialize, open-link, message, resource-teardown)
+ * - MCP server requests forwarded from the app (tools/call, resources/*, prompts/list)
+ * - Protocol requests (ping)
+ */
+export type AppRequest =
+  | McpUiInitializeRequest
+  | McpUiOpenLinkRequest
+  | McpUiMessageRequest
+  | McpUiResourceTeardownRequest
+  | CallToolRequest
+  | ListToolsRequest
+  | ListResourcesRequest
+  | ListResourceTemplatesRequest
+  | ReadResourceRequest
+  | ListPromptsRequest
+  | PingRequest;
+
+/**
+ * All notification types in the MCP Apps protocol.
+ *
+ * Host to app:
+ * - Tool lifecycle (input, input-partial, result, cancelled)
+ * - Host context changes
+ * - MCP list changes (tools, resources, prompts)
+ * - Sandbox resource ready
+ *
+ * App to host:
+ * - Initialized, size-changed, sandbox-proxy-ready
+ * - Logging messages
+ */
+export type AppNotification =
+  // Sent to app
+  | McpUiHostContextChangedNotification
+  | McpUiToolInputNotification
+  | McpUiToolInputPartialNotification
+  | McpUiToolResultNotification
+  | McpUiToolCancelledNotification
+  | McpUiSandboxResourceReadyNotification
+  | ToolListChangedNotification
+  | ResourceListChangedNotification
+  | PromptListChangedNotification
+  // Received from app
+  | McpUiInitializedNotification
+  | McpUiSizeChangedNotification
+  | McpUiSandboxProxyReadyNotification
+  | LoggingMessageNotification;
+
+/**
+ * All result types in the MCP Apps protocol.
+ */
+export type AppResult =
+  | McpUiInitializeResult
+  | McpUiOpenLinkResult
+  | McpUiMessageResult
+  | McpUiResourceTeardownResult
+  | CallToolResult
+  | ListToolsResult
+  | ListResourcesResult
+  | ListResourceTemplatesResult
+  | ReadResourceResult
+  | ListPromptsResult
+  | EmptyResult;
+
 /**
  * Options for configuring AppBridge behavior.
  *
@@ -164,7 +232,11 @@ type RequestHandlerExtra = Parameters<
  * await bridge.connect(transport);
  * ```
  */
-export class AppBridge extends Protocol<Request, Notification, Result> {
+export class AppBridge extends Protocol<
+  AppRequest,
+  AppNotification,
+  AppResult
+> {
   private _appCapabilities?: McpUiAppCapabilities;
   private _hostContext: McpUiHostContext = {};
   private _appInfo?: Implementation;
@@ -805,23 +877,23 @@ export class AppBridge extends Protocol<Request, Notification, Result> {
    * Verify that the guest supports the capability required for the given request method.
    * @internal
    */
-  assertCapabilityForMethod(method: Request["method"]): void {
+  assertCapabilityForMethod(method: AppRequest["method"]): void {
     // TODO
   }
 
   /**
    * Verify that a request handler is registered and supported for the given method.
    * @internal
    */
-  assertRequestHandlerCapability(method: Request["method"]): void {
+  assertRequestHandlerCapability(method: AppRequest["method"]): void {
     // TODO
   }
 
   /**
    * Verify that the host supports the capability required for the given notification method.
    * @internal
    */
-  assertNotificationCapability(method: Notification["method"]): void {
+  assertNotificationCapability(method: AppNotification["method"]): void {
     // TODO
   }
 
@@ -939,7 +1011,7 @@ export class AppBridge extends Protocol<Request, Notification, Result> {
     return this.notification({
       method: "ui/notifications/host-context-changed" as const,
       params,
-    } as Notification);
+    });
   }
 
   /**
@@ -965,8 +1037,8 @@ export class AppBridge extends Protocol<Request, Notification, Result> {
    * @see {@link sendToolResult} for sending results after execution
    */
   sendToolInput(params: McpUiToolInputNotification["params"]) {
-    return this.notification(<McpUiToolInputNotification>{
-      method: "ui/notifications/tool-input",
+    return this.notification({
+      method: "ui/notifications/tool-input" as const,
       params,
     });
   }
@@ -999,8 +1071,8 @@ export class AppBridge extends Protocol<Request, Notification, Result> {
    * @see {@link sendToolInput} for sending complete arguments
    */
   sendToolInputPartial(params: McpUiToolInputPartialNotification["params"]) {
-    return this.notification(<McpUiToolInputPartialNotification>{
-      method: "ui/notifications/tool-input-partial",
+    return this.notification({
+      method: "ui/notifications/tool-input-partial" as const,
       params,
     });
   }
@@ -1030,8 +1102,8 @@ export class AppBridge extends Protocol<Request, Notification, Result> {
    * @see {@link sendToolInput} for sending tool arguments before results
    */
   sendToolResult(params: McpUiToolResultNotification["params"]) {
-    return this.notification(<McpUiToolResultNotification>{
-      method: "ui/notifications/tool-result",
+    return this.notification({
+      method: "ui/notifications/tool-result" as const,
       params,
     });
   }
@@ -1067,8 +1139,8 @@ export class AppBridge extends Protocol<Request, Notification, Result> {
    * @see {@link sendToolInput} for sending tool arguments
    */
   sendToolCancelled(params: McpUiToolCancelledNotification["params"]) {
-    return this.notification(<McpUiToolCancelledNotification>{
-      method: "ui/notifications/tool-cancelled",
+    return this.notification({
+      method: "ui/notifications/tool-cancelled" as const,
       params,
     });
   }
@@ -1091,8 +1163,8 @@ export class AppBridge extends Protocol<Request, Notification, Result> {
   sendSandboxResourceReady(
     params: McpUiSandboxResourceReadyNotification["params"],
   ) {
-    return this.notification(<McpUiSandboxResourceReadyNotification>{
-      method: "ui/notifications/sandbox-resource-ready",
+    return this.notification({
+      method: "ui/notifications/sandbox-resource-ready" as const,
       params,
     });
   }
@@ -1126,8 +1198,8 @@ export class AppBridge extends Protocol<Request, Notification, Result> {
     options?: RequestOptions,
   ) {
     return this.request(
-      <McpUiResourceTeardownRequest>{
-        method: "ui/resource-teardown",
+      {
+        method: "ui/resource-teardown" as const,
         params,
       },
       McpUiResourceTeardownResultSchema,

src/app.ts

@@ -13,11 +13,13 @@ import {
   ListToolsRequest,
   ListToolsRequestSchema,
   LoggingMessageNotification,
-  Notification,
   PingRequestSchema,
-  Request,
-  Result,
 } from "@modelcontextprotocol/sdk/types.js";
+import {
+  AppNotification,
+  AppRequest,
+  AppResult,
+} from "./app-bridge";
 import {
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
@@ -189,7 +191,7 @@ type RequestHandlerExtra = Parameters<
  * });
  * ```
  */
-export class App extends Protocol<Request, Notification, Result> {
+export class App extends Protocol<AppRequest, AppNotification, AppResult> {
   private _hostCapabilities?: McpUiHostCapabilities;
   private _hostInfo?: Implementation;
   private _hostContext?: McpUiHostContext;
@@ -642,15 +644,15 @@ export class App extends Protocol<Request, Notification, Result> {
    * Verify that the host supports the capability required for the given request method.
    * @internal
    */
-  assertCapabilityForMethod(method: Request["method"]): void {
+  assertCapabilityForMethod(method: AppRequest["method"]): void {
     // TODO
   }
 
   /**
    * Verify that the app declared the capability required for the given request method.
    * @internal
    */
-  assertRequestHandlerCapability(method: Request["method"]): void {
+  assertRequestHandlerCapability(method: AppRequest["method"]): void {
     switch (method) {
       case "tools/call":
       case "tools/list":
@@ -672,7 +674,7 @@ export class App extends Protocol<Request, Notification, Result> {
    * Verify that the app supports the capability required for the given notification method.
    * @internal
    */
-  assertNotificationCapability(method: Notification["method"]): void {
+  assertNotificationCapability(method: AppNotification["method"]): void {
     // TODO
   }
 

src/generated/schema.json

@@ -381,7 +381,7 @@
               "additionalProperties": false
             }
           },
-          "additionalProperties": false
+          "additionalProperties": {}
         }
       },
       "required": ["method", "params"],
@@ -667,7 +667,7 @@
           "additionalProperties": false
         }
       },
-      "additionalProperties": false
+      "additionalProperties": {}
     },
     "McpUiInitializeRequest": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -1135,7 +1135,7 @@
               "additionalProperties": false
             }
           },
-          "additionalProperties": false
+          "additionalProperties": {}
         }
       },
       "required": [

src/generated/schema.ts

@@ -337,7 +337,7 @@ export const McpUiToolResultNotificationSchema = z.object({
 /**
  * @description Rich context about the host environment provided to Guest UIs.
  */
-export const McpUiHostContextSchema = z.object({
+export const McpUiHostContextSchema = z.looseObject({
   /** @description Metadata of the tool call that instantiated this App. */
   toolInfo: z
     .object({

src/spec.types.ts

@@ -184,6 +184,8 @@ export interface McpUiToolCancelledNotification {
  * @description Rich context about the host environment provided to Guest UIs.
  */
 export interface McpUiHostContext {
+  /** @description Allow additional properties for forward compatibility. */
+  [key: string]: unknown;
   /** @description Metadata of the tool call that instantiated this App. */
   toolInfo?: {
     /** @description JSON-RPC id of the tools/call request. */