@modelcontextprotocol/ext-apps 0.3.0 → 0.3.1

package/dist/src/server/index.d.ts

@@ -4,7 +4,7 @@
  * @module server-helpers
  */
 import { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE, McpUiResourceMeta, McpUiToolMeta } from "../app.js";
-import type { McpServer, ResourceMetadata, ToolCallback, ReadResourceCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer, RegisteredTool, ResourceMetadata, ToolCallback, ReadResourceCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { AnySchema, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE };
@@ -16,6 +16,7 @@ export interface ToolConfig {
     title?: string;
     description?: string;
     inputSchema?: ZodRawShapeCompat | AnySchema;
+    outputSchema?: ZodRawShapeCompat | AnySchema;
     annotations?: ToolAnnotations;
     _meta?: Record<string, unknown>;
 }
@@ -76,9 +77,10 @@ export interface McpUiAppResourceConfig extends ResourceMetadata {
  * });
  * ```
  */
-export declare function registerAppTool<TInputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined>(server: Pick<McpServer, "registerTool">, name: string, config: Omit<McpUiAppToolConfig, "inputSchema"> & {
-    inputSchema?: TInputSchema;
-}, handler: ToolCallback<TInputSchema>): void;
+export declare function registerAppTool<OutputArgs extends ZodRawShapeCompat | AnySchema, InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined>(server: Pick<McpServer, "registerTool">, name: string, config: McpUiAppToolConfig & {
+    inputSchema?: InputArgs;
+    outputSchema?: OutputArgs;
+}, cb: ToolCallback<InputArgs>): RegisteredTool;
 /**
  * Register an app resource with the MCP server.
  *

package/dist/src/server/index.js

@@ -58,4 +58,4 @@ Note: This type uses \`Record<K, string | undefined>\` rather than \`Partial<Rec
 for compatibility with Zod schema generation. Both are functionally equivalent for validation.`),G6=l.object({method:l.literal("ui/open-link"),params:l.object({url:l.string().describe("URL to open in the host's browser")})}),le=l.object({isError:l.boolean().optional().describe("True if the host failed to open the URL (e.g., due to security policy).")}).passthrough(),Ie=l.object({isError:l.boolean().optional().describe("True if the host rejected or failed to deliver the message.")}).passthrough(),W6=l.object({method:l.literal("ui/notifications/sandbox-proxy-ready"),params:l.object({})}),E6=l.object({method:l.literal("ui/notifications/sandbox-resource-ready"),params:l.object({html:l.string().describe("HTML content to load into the inner iframe."),sandbox:l.string().optional().describe("Optional override for the inner iframe's sandbox attribute."),csp:l.object({connectDomains:l.array(l.string()).optional().describe("Origins for network requests (fetch/XHR/WebSocket)."),resourceDomains:l.array(l.string()).optional().describe("Origins for static resources (scripts, images, styles, fonts).")}).optional().describe("CSP configuration from resource metadata.")})}),V6=l.object({method:l.literal("ui/notifications/size-changed"),params:l.object({width:l.number().optional().describe("New width in pixels."),height:l.number().optional().describe("New height in pixels.")})}),ce=l.object({method:l.literal("ui/notifications/tool-input"),params:l.object({arguments:l.record(l.string(),l.unknown().describe("Complete tool call arguments as key-value pairs.")).optional().describe("Complete tool call arguments as key-value pairs.")})}),be=l.object({method:l.literal("ui/notifications/tool-input-partial"),params:l.object({arguments:l.record(l.string(),l.unknown().describe("Partial tool call arguments (incomplete, may change).")).optional().describe("Partial tool call arguments (incomplete, may change).")})}),_e=l.object({method:l.literal("ui/notifications/tool-cancelled"),params:l.object({reason:l.string().optional().describe('Optional reason for the cancellation (e.g., "user action", "timeout").')})}),PI=l.object({fonts:l.string().optional().describe("CSS for font loading (@font-face rules or")}),jI=l.object({variables:L6.optional().describe("CSS variables for theming the app."),css:PI.optional().describe("CSS blocks that apps can inject.")}),Ue=l.object({method:l.literal("ui/resource-teardown"),params:l.object({})}),X6=l.record(l.string(),l.unknown()),JI=l.object({experimental:l.object({}).optional().describe("Experimental features (structure TBD)."),openLinks:l.object({}).optional().describe("Host supports opening external URLs."),serverTools:l.object({listChanged:l.boolean().optional().describe("Host supports tools/list_changed notifications.")}).optional().describe("Host can proxy tool calls to the MCP server."),serverResources:l.object({listChanged:l.boolean().optional().describe("Host supports resources/list_changed notifications.")}).optional().describe("Host can proxy resource reads to the MCP server."),logging:l.object({}).optional().describe("Host accepts log messages.")}),LI=l.object({experimental:l.object({}).optional().describe("Experimental features (structure TBD)."),tools:l.object({listChanged:l.boolean().optional().describe("App supports tools/list_changed notifications.")}).optional().describe("App exposes MCP-style tools that the host can call.")}),A6=l.object({method:l.literal("ui/notifications/initialized"),params:l.object({}).optional()}),GI=l.object({connectDomains:l.array(l.string()).optional().describe("Origins for network requests (fetch/XHR/WebSocket)."),resourceDomains:l.array(l.string()).optional().describe("Origins for static resources (scripts, images, styles, fonts).")}),K6=l.object({csp:GI.optional().describe("Content Security Policy configuration."),domain:l.string().optional().describe("Dedicated origin for widget sandbox."),prefersBorder:l.boolean().optional().describe("Visual boundary preference - true if UI prefers a visible border.")}),q6=l.object({method:l.literal("ui/request-display-mode"),params:l.object({mode:Uo.describe("The display mode being requested.")})}),ke=l.object({mode:Uo.describe("The display mode that was actually set. May differ from requested if not supported.")}).passthrough(),WI=l.union([l.literal("model"),l.literal("app")]).describe("Tool visibility scope - who can access the tool."),Q6=l.object({resourceUri:l.string().optional(),visibility:l.array(WI).optional().describe(`Who can access this tool. Default: ["model", "app"]
 - "model": Tool visible to and callable by the agent
 - "app": Tool callable by the app from this server only`)}),Y6=l.object({method:l.literal("ui/message"),params:l.object({role:l.literal("user").describe('Message role, currently only "user" is supported.'),content:l.array(O6).describe("Message content blocks (text, image, etc.).")})}),De=l.object({method:l.literal("ui/notifications/tool-result"),params:S6.describe("Standard MCP tool execution result.")}),we=l.object({toolInfo:l.object({id:P6.optional().describe("JSON-RPC id of the tools/call request."),tool:j6.describe("Tool definition including name, inputSchema, etc.")}).optional().describe("Metadata of the tool call that instantiated this App."),theme:SI.optional().describe("Current color theme preference."),styles:jI.optional().describe("Style configuration for theming the app."),displayMode:Uo.optional().describe("How the UI is currently displayed."),availableDisplayModes:l.array(l.string()).optional().describe("Display modes the host supports."),containerDimensions:l.union([l.object({height:l.number().describe("Fixed container height in pixels.")}),l.object({maxHeight:l.union([l.number(),l.undefined()]).optional().describe("Maximum container height in pixels.")})]).and(l.union([l.object({width:l.number().describe("Fixed container width in pixels.")}),l.object({maxWidth:l.union([l.number(),l.undefined()]).optional().describe("Maximum container width in pixels.")})])).optional().describe(`Container dimensions. Represents the dimensions of the iframe or other
-container holding the app. Specify either width or maxWidth, and either height or maxHeight.`),locale:l.string().optional().describe("User's language and region preference in BCP 47 format."),timeZone:l.string().optional().describe("User's timezone in IANA format."),userAgent:l.string().optional().describe("Host application identifier."),platform:l.union([l.literal("web"),l.literal("desktop"),l.literal("mobile")]).optional().describe("Platform type for responsive design decisions."),deviceCapabilities:l.object({touch:l.boolean().optional().describe("Whether the device supports touch input."),hover:l.boolean().optional().describe("Whether the device supports hover interactions.")}).optional().describe("Device input capabilities."),safeAreaInsets:l.object({top:l.number().describe("Top safe area inset in pixels."),right:l.number().describe("Right safe area inset in pixels."),bottom:l.number().describe("Bottom safe area inset in pixels."),left:l.number().describe("Left safe area inset in pixels.")}).optional().describe("Mobile safe area boundaries in pixels.")}).passthrough(),Ne=l.object({method:l.literal("ui/notifications/host-context-changed"),params:we.describe("Partial context update containing only changed fields.")}),F6=l.object({method:l.literal("ui/initialize"),params:l.object({appInfo:OI.describe("App identification (name and version)."),appCapabilities:LI.describe("Features and capabilities this app provides."),protocolVersion:l.string().describe("Protocol version this app supports.")})}),Oe=l.object({protocolVersion:l.string().describe('Negotiated protocol version string (e.g., "2025-11-21").'),hostInfo:OI.describe("Host application identification and version."),hostCapabilities:JI.describe("Features and capabilities provided by the host."),hostContext:we.describe("Rich context about the host environment.")}).passthrough();var Se="ui/resourceUri",EI="text/html;profile=mcp-app";class M6 extends m6{_appInfo;_capabilities;options;_hostCapabilities;_hostInfo;_hostContext;constructor(r,i={},v={autoResize:!0}){super(v);this._appInfo=r;this._capabilities=i;this.options=v;this.setRequestHandler(z6,(t)=>{return console.log("Received ping:",t.params),{}}),this.onhostcontextchanged=()=>{}}getHostCapabilities(){return this._hostCapabilities}getHostVersion(){return this._hostInfo}getHostContext(){return this._hostContext}set ontoolinput(r){this.setNotificationHandler(ce,(i)=>r(i.params))}set ontoolinputpartial(r){this.setNotificationHandler(be,(i)=>r(i.params))}set ontoolresult(r){this.setNotificationHandler(De,(i)=>r(i.params))}set ontoolcancelled(r){this.setNotificationHandler(_e,(i)=>r(i.params))}set onhostcontextchanged(r){this.setNotificationHandler(Ne,(i)=>{this._hostContext={...this._hostContext,...i.params},r(i.params)})}set onteardown(r){this.setRequestHandler(Ue,(i,v)=>r(i.params,v))}set oncalltool(r){this.setRequestHandler(T6,(i,v)=>r(i.params,v))}set onlisttools(r){this.setRequestHandler(H6,(i,v)=>r(i.params,v))}assertCapabilityForMethod(r){}assertRequestHandlerCapability(r){switch(r){case"tools/call":case"tools/list":if(!this._capabilities.tools)throw Error(`Client does not support tool capability (required for ${r})`);return;case"ping":case"ui/resource-teardown":return;default:throw Error(`No handler for method ${r} registered`)}}assertNotificationCapability(r){}assertTaskCapability(r){throw Error("Tasks are not supported in MCP Apps")}assertTaskHandlerCapability(r){throw Error("Task handlers are not supported in MCP Apps")}async callServerTool(r,i){return await this.request({method:"tools/call",params:r},B6,i)}sendMessage(r,i){return this.request({method:"ui/message",params:r},Ie,i)}sendLog(r){return this.notification({method:"notifications/message",params:r})}openLink(r,i){return this.request({method:"ui/open-link",params:r},le,i)}sendOpenLink=this.openLink;requestDisplayMode(r,i){return this.request({method:"ui/request-display-mode",params:r},ke,i)}sendSizeChanged(r){return this.notification({method:"ui/notifications/size-changed",params:r})}setupSizeChangedNotifications(){let r=!1,i=0,v=0,t=()=>{if(r)return;r=!0,requestAnimationFrame(()=>{r=!1;let o=document.documentElement,u=o.style.width,$=o.style.height;o.style.width="fit-content",o.style.height="fit-content";let e=o.getBoundingClientRect();o.style.width=u,o.style.height=$;let g=window.innerWidth-o.clientWidth,c=Math.ceil(e.width+g),_=Math.ceil(e.height);if(c!==i||_!==v)i=c,v=_,this.sendSizeChanged({width:c,height:_})})};t();let n=new ResizeObserver(t);return n.observe(document.documentElement),n.observe(document.body),()=>n.disconnect()}async connect(r=new Qn(window.parent,window.parent),i){await super.connect(r);try{let v=await this.request({method:"ui/initialize",params:{appCapabilities:this._capabilities,appInfo:this._appInfo,protocolVersion:ko}},Oe,i);if(v===void 0)throw Error(`Server sent invalid initialize result: ${v}`);if(this._hostCapabilities=v.hostCapabilities,this._hostInfo=v.hostInfo,this._hostContext=v.hostContext,await this.notification({method:"ui/notifications/initialized"}),this.options?.autoResize)this.setupSizeChangedNotifications()}catch(v){throw this.close(),v}}}function Mk(r,i,v,t){let n=v._meta,o=n.ui,u=n[Se],$=n;if(o?.resourceUri&&!u)$={...n,[Se]:o.resourceUri};else if(u&&!o?.resourceUri)$={...n,ui:{...o,resourceUri:u}};r.registerTool(i,{...v,_meta:$},t)}function Rk(r,i,v,t,n){r.registerResource(i,v,{mimeType:EI,...t},n)}export{Mk as registerAppTool,Rk as registerAppResource,Se as RESOURCE_URI_META_KEY,EI as RESOURCE_MIME_TYPE};
+container holding the app. Specify either width or maxWidth, and either height or maxHeight.`),locale:l.string().optional().describe("User's language and region preference in BCP 47 format."),timeZone:l.string().optional().describe("User's timezone in IANA format."),userAgent:l.string().optional().describe("Host application identifier."),platform:l.union([l.literal("web"),l.literal("desktop"),l.literal("mobile")]).optional().describe("Platform type for responsive design decisions."),deviceCapabilities:l.object({touch:l.boolean().optional().describe("Whether the device supports touch input."),hover:l.boolean().optional().describe("Whether the device supports hover interactions.")}).optional().describe("Device input capabilities."),safeAreaInsets:l.object({top:l.number().describe("Top safe area inset in pixels."),right:l.number().describe("Right safe area inset in pixels."),bottom:l.number().describe("Bottom safe area inset in pixels."),left:l.number().describe("Left safe area inset in pixels.")}).optional().describe("Mobile safe area boundaries in pixels.")}).passthrough(),Ne=l.object({method:l.literal("ui/notifications/host-context-changed"),params:we.describe("Partial context update containing only changed fields.")}),F6=l.object({method:l.literal("ui/initialize"),params:l.object({appInfo:OI.describe("App identification (name and version)."),appCapabilities:LI.describe("Features and capabilities this app provides."),protocolVersion:l.string().describe("Protocol version this app supports.")})}),Oe=l.object({protocolVersion:l.string().describe('Negotiated protocol version string (e.g., "2025-11-21").'),hostInfo:OI.describe("Host application identification and version."),hostCapabilities:JI.describe("Features and capabilities provided by the host."),hostContext:we.describe("Rich context about the host environment.")}).passthrough();var Se="ui/resourceUri",EI="text/html;profile=mcp-app";class M6 extends m6{_appInfo;_capabilities;options;_hostCapabilities;_hostInfo;_hostContext;constructor(r,i={},v={autoResize:!0}){super(v);this._appInfo=r;this._capabilities=i;this.options=v;this.setRequestHandler(z6,(t)=>{return console.log("Received ping:",t.params),{}}),this.onhostcontextchanged=()=>{}}getHostCapabilities(){return this._hostCapabilities}getHostVersion(){return this._hostInfo}getHostContext(){return this._hostContext}set ontoolinput(r){this.setNotificationHandler(ce,(i)=>r(i.params))}set ontoolinputpartial(r){this.setNotificationHandler(be,(i)=>r(i.params))}set ontoolresult(r){this.setNotificationHandler(De,(i)=>r(i.params))}set ontoolcancelled(r){this.setNotificationHandler(_e,(i)=>r(i.params))}set onhostcontextchanged(r){this.setNotificationHandler(Ne,(i)=>{this._hostContext={...this._hostContext,...i.params},r(i.params)})}set onteardown(r){this.setRequestHandler(Ue,(i,v)=>r(i.params,v))}set oncalltool(r){this.setRequestHandler(T6,(i,v)=>r(i.params,v))}set onlisttools(r){this.setRequestHandler(H6,(i,v)=>r(i.params,v))}assertCapabilityForMethod(r){}assertRequestHandlerCapability(r){switch(r){case"tools/call":case"tools/list":if(!this._capabilities.tools)throw Error(`Client does not support tool capability (required for ${r})`);return;case"ping":case"ui/resource-teardown":return;default:throw Error(`No handler for method ${r} registered`)}}assertNotificationCapability(r){}assertTaskCapability(r){throw Error("Tasks are not supported in MCP Apps")}assertTaskHandlerCapability(r){throw Error("Task handlers are not supported in MCP Apps")}async callServerTool(r,i){return await this.request({method:"tools/call",params:r},B6,i)}sendMessage(r,i){return this.request({method:"ui/message",params:r},Ie,i)}sendLog(r){return this.notification({method:"notifications/message",params:r})}openLink(r,i){return this.request({method:"ui/open-link",params:r},le,i)}sendOpenLink=this.openLink;requestDisplayMode(r,i){return this.request({method:"ui/request-display-mode",params:r},ke,i)}sendSizeChanged(r){return this.notification({method:"ui/notifications/size-changed",params:r})}setupSizeChangedNotifications(){let r=!1,i=0,v=0,t=()=>{if(r)return;r=!0,requestAnimationFrame(()=>{r=!1;let o=document.documentElement,u=o.style.width,$=o.style.height;o.style.width="fit-content",o.style.height="fit-content";let e=o.getBoundingClientRect();o.style.width=u,o.style.height=$;let g=window.innerWidth-o.clientWidth,c=Math.ceil(e.width+g),_=Math.ceil(e.height);if(c!==i||_!==v)i=c,v=_,this.sendSizeChanged({width:c,height:_})})};t();let n=new ResizeObserver(t);return n.observe(document.documentElement),n.observe(document.body),()=>n.disconnect()}async connect(r=new Qn(window.parent,window.parent),i){await super.connect(r);try{let v=await this.request({method:"ui/initialize",params:{appCapabilities:this._capabilities,appInfo:this._appInfo,protocolVersion:ko}},Oe,i);if(v===void 0)throw Error(`Server sent invalid initialize result: ${v}`);if(this._hostCapabilities=v.hostCapabilities,this._hostInfo=v.hostInfo,this._hostContext=v.hostContext,await this.notification({method:"ui/notifications/initialized"}),this.options?.autoResize)this.setupSizeChangedNotifications()}catch(v){throw this.close(),v}}}function Mk(r,i,v,t){let n=v._meta,o=n.ui,u=n[Se],$=n;if(o?.resourceUri&&!u)$={...n,[Se]:o.resourceUri};else if(u&&!o?.resourceUri)$={...n,ui:{...o,resourceUri:u}};return r.registerTool(i,{...v,_meta:$},t)}function Rk(r,i,v,t,n){r.registerResource(i,v,{mimeType:EI,...t},n)}export{Mk as registerAppTool,Rk as registerAppResource,Se as RESOURCE_URI_META_KEY,EI as RESOURCE_MIME_TYPE};

package/package.json

@@ -5,7 +5,7 @@
     "url": "https://github.com/modelcontextprotocol/ext-apps"
   },
   "homepage": "https://github.com/modelcontextprotocol/ext-apps",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "MIT",
   "description": "MCP Apps SDK — Enable MCP servers to display interactive user interfaces in conversational clients.",
   "type": "module",
@@ -15,10 +15,18 @@
       "types": "./dist/src/app.d.ts",
       "default": "./dist/src/app.js"
     },
+    "./app-with-deps": {
+      "types": "./dist/src/app.d.ts",
+      "default": "./dist/src/app-with-deps.js"
+    },
     "./react": {
       "types": "./dist/src/react/index.d.ts",
       "default": "./dist/src/react/index.js"
     },
+    "./react-with-deps": {
+      "types": "./dist/src/react/index.d.ts",
+      "default": "./dist/src/react/react-with-deps.js"
+    },
     "./app-bridge": {
       "types": "./dist/src/app-bridge.d.ts",
       "default": "./dist/src/app-bridge.js"
@@ -41,13 +49,14 @@
     "generate:schemas": "tsx scripts/generate-schemas.ts && prettier --write \"src/generated/**/*\"",
     "build": "npm run generate:schemas && node scripts/run-bun.mjs build.bun.ts",
     "prepack": "npm run build",
-    "build:all": "npm run build && npm run examples:build",
+    "build:all": "npm run examples:build",
     "test": "bun test src",
     "test:e2e": "playwright test",
     "test:e2e:update": "playwright test --update-snapshots",
     "test:e2e:ui": "playwright test --ui",
     "test:e2e:docker": "docker run --rm -v $(pwd):/work -w /work -it mcr.microsoft.com/playwright:v1.57.0-noble sh -c 'npm i -g bun && npm ci && npx playwright test'",
     "test:e2e:docker:update": "docker run --rm -v $(pwd):/work -w /work -it mcr.microsoft.com/playwright:v1.57.0-noble sh -c 'npm i -g bun && npm ci && npx playwright test --update-snapshots'",
+    "preexamples:build": "npm run build",
     "examples:build": "bun examples/run-all.ts build",
     "examples:start": "NODE_ENV=development npm run build && bun examples/run-all.ts start",
     "examples:dev": "NODE_ENV=development bun examples/run-all.ts dev",
@@ -56,7 +65,8 @@
     "docs": "typedoc",
     "docs:watch": "typedoc --watch",
     "prettier": "prettier -u \"**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --check",
-    "prettier:fix": "prettier -u \"**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --write"
+    "prettier:fix": "prettier -u \"**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --write",
+    "check:versions": "node scripts/check-versions.mjs"
   },
   "author": "Olivier Chafik",
   "devDependencies": {