Add API docs (#29)
* Refactor types.ts to use explicit interfaces with JSDoc Replace z.infer<typeof Schema> patterns with explicit interface definitions for all MCP UI types. Add VerifySchemaMatches helper type to ensure compile-time verification that schemas match their interfaces. Add comprehensive JSDoc documentation to all exported types including: - Clear descriptions of purpose and usage - @see references to related types and methods - Code examples where helpful - @internal markers for implementation details 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add JSDoc documentation and TypeDoc tooling Add comprehensive JSDoc documentation to: - AppBridge class and all methods - App class and all methods - PostMessageTransport class and callbacks - React hooks (useApp, useAutoResize) - React module index Set up TypeDoc for API documentation generation: - Add typedoc.json configuration - Add docs and docs:watch npm scripts - Add typedoc dev dependency - Update .gitignore to exclude generated docs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add JSDoc documentation for callback handler setters Document all notification and request handler setters in AppBridge and App classes with comprehensive JSDoc comments including: - Clear descriptions of when handlers are called - Parameter documentation and types - Practical code examples with error handling - Cross-references to related types and methods - Security considerations where relevant Also update types.ts to document optional isError fields in result types and make McpUiInitializedNotification params optional. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add JSDoc for new App methods and fix result type compatibility Document new public APIs introduced in merge commit 74a7b1f: - getHostCapabilities() - getter for host capabilities after connect - getHostVersion() - getter for host implementation info after connect - oncalltool setter - convenience handler for tool call requests - onlisttools setter - convenience handler for tool listing requests - RESOURCE_URI_META_KEY constant - metadata key for resource URIs Add index signatures to McpUiMessageResult and McpUiOpenLinkResult for MCP SDK Protocol class compatibility, matching the existing pattern in McpUiInitializeResult. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add comprehensive JSDoc documentation across library - Document App methods with detailed descriptions and examples - Add JSDoc to AppBridge methods including getters and setters - Document PostMessageTransport callback properties - Improve React hook documentation (useApp, useAutoResize) - Add documentation for types.ts result and notification types - Add @see cross-references between related methods - Fix code examples to use correct syntax and patterns - Clarify error handling behavior in method descriptions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix TypeDoc cross-module link resolution warnings Replace unqualified @link references with module-qualified syntax to fix "Failed to resolve link" warnings during docs generation. TypeDoc cannot resolve links like {@link App.sendOpenLink} without imports, so use the module-qualified format {@link app.App.sendOpenLink} instead. Changes: - types.ts: Fix 9 cross-module links to App and AppBridge methods - app-bridge.ts: Fix 2 references to App.sendSizeChange - message-transport.ts: Fix 2 references to App.connect and AppBridge.connect This eliminates all "Failed to resolve link" warnings without requiring circular imports or removing documentation cross-references. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Remove TypeDoc links to undocumented external types Remove @link references to types that are either: - Not exported (AppOptions) - internal implementation detail - From external packages (@modelcontextprotocol/sdk) - not included in docs This eliminates warnings about resolved but undocumented types. The type information is still available through TypeScript's type system and parameter documentation, but without broken links in the generated documentation. Removed links to: - AppOptions (internal type) - Implementation, CallToolRequest, CallToolResult (MCP SDK types) - ListToolsRequest, LoggingMessageNotification (MCP SDK types) Reduces warnings from 12 to 4 (remaining are about missing example files). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Bump @modelcontextprotocol/sdk to ^1.23.0 Update SDK dependency to fix CI build failures caused by version mismatch. CI was installing 1.23.0 (latest compatible with ^1.22.0) while local builds used 1.22.0. Note: package-lock.json is gitignored, which prevents reproducible builds. Consider committing it to ensure CI uses the same versions as local development. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix Zod type compatibility with @modelcontextprotocol/sdk The SDK imports Zod from 'zod/v4' while this package imported from 'zod'. Although both resolve to the same version (3.25.x), TypeScript sees them as separate modules with incompatible type declarations. This caused type errors when: - Extending SDK schemas like RequestSchema.extend() - Passing SDK schemas to setRequestHandler/setNotificationHandler - Using ZodObject/ZodLiteral types from different import paths Changes: - Import zod from 'zod/v4' to match SDK import path - Update z.record() calls to use Zod v4 signature (requires both key and value schemas) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add GitHub Actions workflow to deploy docs to gh-pages Adds a workflow with manual trigger (workflow_dispatch) that generates TypeDoc documentation and publishes it to the gh-pages branch using peaceiris/actions-gh-pages. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add docs index.html redirect to API documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Revise README for clarity and audience focus - Add API documentation badge linking to GitHub Pages - Reorganize content around two audiences: App Developers and Host Developers - Convert relative links to absolute GitHub URLs for better portability - Simplify installation and examples sections - Add Resources section with links to docs, spec, and discussion 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Update src/app-bridge.ts --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Olivier Chafik <ochafik@anthropic.com>
This commit is contained in:
Jonathan Hefner
GitHub
parent
e6b1e640ab
commit
16a9e6f034
1 changed files with 2136 additions and 133 deletions
578
src/app.ts
578
src/app.ts
|
|
@ -44,9 +44,55 @@ import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
|
|||
export { PostMessageTransport } from "./message-transport.js";
|
||||
export * from "./types";
|
||||
|
||||
/**
|
||||
* Metadata key for associating a resource URI with a tool call.
|
||||
*
|
||||
* MCP servers include this key in tool call result metadata to indicate which
|
||||
* UI resource should be displayed for the tool. When hosts receive a tool result
|
||||
* containing this metadata, they resolve and render the corresponding App.
|
||||
*
|
||||
* **Note**: This constant is provided for reference. MCP servers set this metadata
|
||||
* in their tool handlers; App developers typically don't need to use it directly.
|
||||
*
|
||||
* @example How MCP servers use this key (server-side, not in Apps)
|
||||
* ```typescript
|
||||
* // In an MCP server's tool handler:
|
||||
* return {
|
||||
* content: [{ type: "text", text: "Result" }],
|
||||
* _meta: {
|
||||
* [RESOURCE_URI_META_KEY]: "ui://weather/forecast"
|
||||
* }
|
||||
* };
|
||||
* ```
|
||||
*
|
||||
* @example How hosts check for this metadata (host-side)
|
||||
* ```typescript
|
||||
* const result = await mcpClient.callTool({ name: "weather", arguments: {} });
|
||||
* const uiUri = result._meta?.[RESOURCE_URI_META_KEY];
|
||||
* if (uiUri) {
|
||||
* // Load and display the UI resource
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export const RESOURCE_URI_META_KEY = "ui/resourceUri";
|
||||
|
||||
/**
|
||||
* Options for configuring App behavior.
|
||||
*
|
||||
* Extends ProtocolOptions from the MCP SDK with App-specific configuration.
|
||||
*
|
||||
* @see ProtocolOptions from @modelcontextprotocol/sdk for inherited options
|
||||
*/
|
||||
type AppOptions = ProtocolOptions & {
|
||||
/**
|
||||
* Automatically report size changes to the host using ResizeObserver.
|
||||
*
|
||||
* When enabled, the App monitors `document.body` and `document.documentElement`
|
||||
* for size changes and automatically sends `ui/notifications/size-change`
|
||||
* notifications to the host.
|
||||
*
|
||||
* @default true
|
||||
*/
|
||||
autoResize?: boolean;
|
||||
};
|
||||
|
||||
|
|
@ -54,10 +100,104 @@ type RequestHandlerExtra = Parameters<
|
|||
Parameters<App["setRequestHandler"]>[1]
|
||||
>[1];
|
||||
|
||||
/**
|
||||
* Main class for MCP Apps to communicate with their host.
|
||||
*
|
||||
* The App class provides a framework-agnostic way to build interactive MCP Apps
|
||||
* that run inside host applications. It extends the MCP SDK's Protocol class and
|
||||
* handles the connection lifecycle, initialization handshake, and bidirectional
|
||||
* communication with the host.
|
||||
*
|
||||
* ## Architecture
|
||||
*
|
||||
* Guest UIs (Apps) act as MCP clients connecting to the host via {@link PostMessageTransport}.
|
||||
* The host proxies requests to the actual MCP server and forwards
|
||||
* responses back to the App.
|
||||
*
|
||||
* ## Lifecycle
|
||||
*
|
||||
* 1. **Create**: Instantiate App with info and capabilities
|
||||
* 2. **Connect**: Call `connect()` to establish transport and perform handshake
|
||||
* 3. **Interactive**: Send requests, receive notifications, call tools
|
||||
* 4. **Cleanup**: Host sends teardown request before unmounting
|
||||
*
|
||||
* ## Inherited Methods
|
||||
*
|
||||
* As a subclass of Protocol, App inherits key methods for handling communication:
|
||||
* - `setRequestHandler()` - Register handlers for requests from host
|
||||
* - `setNotificationHandler()` - Register handlers for notifications from host
|
||||
*
|
||||
* @see Protocol from @modelcontextprotocol/sdk for all inherited methods
|
||||
*
|
||||
* ## Notification Setters
|
||||
*
|
||||
* For common notifications, the App class provides convenient setter properties
|
||||
* that simplify handler registration:
|
||||
* - `ontoolinput` - Complete tool arguments from host
|
||||
* - `ontoolinputpartial` - Streaming partial tool arguments
|
||||
* - `ontoolresult` - Tool execution results
|
||||
* - `onhostcontextchanged` - Host context changes (theme, viewport, etc.)
|
||||
*
|
||||
* These setters are convenience wrappers around `setNotificationHandler()`.
|
||||
* Both patterns work; use whichever fits your coding style better.
|
||||
*
|
||||
* @example Basic usage with PostMessageTransport
|
||||
* ```typescript
|
||||
* import {
|
||||
* App,
|
||||
* PostMessageTransport,
|
||||
* McpUiToolInputNotificationSchema
|
||||
* } from '@modelcontextprotocol/ext-apps';
|
||||
*
|
||||
* const app = new App(
|
||||
* { name: "WeatherApp", version: "1.0.0" },
|
||||
* {} // capabilities
|
||||
* );
|
||||
*
|
||||
* // Register notification handler using setter (simpler)
|
||||
* app.ontoolinput = (params) => {
|
||||
* console.log("Tool arguments:", params.arguments);
|
||||
* };
|
||||
*
|
||||
* // OR using inherited setNotificationHandler (more explicit)
|
||||
* app.setNotificationHandler(
|
||||
* McpUiToolInputNotificationSchema,
|
||||
* (notification) => {
|
||||
* console.log("Tool arguments:", notification.params.arguments);
|
||||
* }
|
||||
* );
|
||||
*
|
||||
* await app.connect(new PostMessageTransport(window.parent));
|
||||
* ```
|
||||
*
|
||||
* @example Sending a message to the host's chat
|
||||
* ```typescript
|
||||
* await app.sendMessage({
|
||||
* role: "user",
|
||||
* content: [{ type: "text", text: "Weather updated!" }]
|
||||
* });
|
||||
* ```
|
||||
*/
|
||||
export class App extends Protocol<Request, Notification, Result> {
|
||||
private _hostCapabilities?: McpUiHostCapabilities;
|
||||
private _hostInfo?: Implementation;
|
||||
|
||||
/**
|
||||
* Create a new MCP App instance.
|
||||
*
|
||||
* @param _appInfo - App identification (name and version)
|
||||
* @param _capabilities - Features and capabilities this app provides
|
||||
* @param options - Configuration options including autoResize behavior
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const app = new App(
|
||||
* { name: "MyApp", version: "1.0.0" },
|
||||
* { tools: { listChanged: true } }, // capabilities
|
||||
* { autoResize: true } // options
|
||||
* );
|
||||
* ```
|
||||
*/
|
||||
constructor(
|
||||
private _appInfo: Implementation,
|
||||
private _capabilities: McpUiAppCapabilities = {},
|
||||
|
|
@ -71,14 +211,98 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the host's capabilities discovered during initialization.
|
||||
*
|
||||
* Returns the capabilities that the host advertised during the
|
||||
* {@link connect} handshake. Returns `undefined` if called before
|
||||
* connection is established.
|
||||
*
|
||||
* @returns Host capabilities, or `undefined` if not yet connected
|
||||
*
|
||||
* @example Check host capabilities after connection
|
||||
* ```typescript
|
||||
* await app.connect(transport);
|
||||
* const caps = app.getHostCapabilities();
|
||||
* if (caps === undefined) {
|
||||
* console.error("Not connected");
|
||||
* return;
|
||||
* }
|
||||
* if (caps.serverTools) {
|
||||
* console.log("Host supports server tool calls");
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @see {@link connect} for the initialization handshake
|
||||
* @see {@link McpUiHostCapabilities} for the capabilities structure
|
||||
*/
|
||||
getHostCapabilities(): McpUiHostCapabilities | undefined {
|
||||
return this._hostCapabilities;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the host's implementation info discovered during initialization.
|
||||
*
|
||||
* Returns the host's name and version as advertised during the
|
||||
* {@link connect} handshake. Returns `undefined` if called before
|
||||
* connection is established.
|
||||
*
|
||||
* @returns Host implementation info, or `undefined` if not yet connected
|
||||
*
|
||||
* @example Log host information after connection
|
||||
* ```typescript
|
||||
* await app.connect(transport);
|
||||
* const host = app.getHostVersion();
|
||||
* if (host === undefined) {
|
||||
* console.error("Not connected");
|
||||
* return;
|
||||
* }
|
||||
* console.log(`Connected to ${host.name} v${host.version}`);
|
||||
* ```
|
||||
*
|
||||
* @see {@link connect} for the initialization handshake
|
||||
*/
|
||||
getHostVersion(): Implementation | undefined {
|
||||
return this._hostInfo;
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience handler for receiving complete tool input from the host.
|
||||
*
|
||||
* Set this property to register a handler that will be called when the host
|
||||
* sends a tool's complete arguments. This is sent after a tool call begins
|
||||
* and before the tool result is available.
|
||||
*
|
||||
* This setter is a convenience wrapper around `setNotificationHandler()` that
|
||||
* automatically handles the notification schema and extracts the params for you.
|
||||
*
|
||||
* Register handlers before calling {@link connect} to avoid missing notifications.
|
||||
*
|
||||
* @param callback - Function called with the tool input params
|
||||
*
|
||||
* @example Using the setter (simpler)
|
||||
* ```typescript
|
||||
* // Register before connecting to ensure no notifications are missed
|
||||
* app.ontoolinput = (params) => {
|
||||
* console.log("Tool:", params.arguments);
|
||||
* // Update your UI with the tool arguments
|
||||
* };
|
||||
* await app.connect(transport);
|
||||
* ```
|
||||
*
|
||||
* @example Using setNotificationHandler (more explicit)
|
||||
* ```typescript
|
||||
* app.setNotificationHandler(
|
||||
* McpUiToolInputNotificationSchema,
|
||||
* (notification) => {
|
||||
* console.log("Tool:", notification.params.arguments);
|
||||
* }
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @see {@link setNotificationHandler} for the underlying method
|
||||
* @see {@link McpUiToolInputNotification} for the notification structure
|
||||
*/
|
||||
set ontoolinput(
|
||||
callback: (params: McpUiToolInputNotification["params"]) => void,
|
||||
) {
|
||||
|
|
@ -86,6 +310,33 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
callback(n.params),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience handler for receiving streaming partial tool input from the host.
|
||||
*
|
||||
* Set this property to register a handler that will be called as the host
|
||||
* streams partial tool arguments during tool call initialization. This enables
|
||||
* progressive rendering of tool arguments before they're complete.
|
||||
*
|
||||
* This setter is a convenience wrapper around `setNotificationHandler()` that
|
||||
* automatically handles the notification schema and extracts the params for you.
|
||||
*
|
||||
* Register handlers before calling {@link connect} to avoid missing notifications.
|
||||
*
|
||||
* @param callback - Function called with each partial tool input update
|
||||
*
|
||||
* @example Progressive rendering of tool arguments
|
||||
* ```typescript
|
||||
* app.ontoolinputpartial = (params) => {
|
||||
* console.log("Partial args:", params.arguments);
|
||||
* // Update your UI progressively as arguments stream in
|
||||
* };
|
||||
* ```
|
||||
*
|
||||
* @see {@link setNotificationHandler} for the underlying method
|
||||
* @see {@link McpUiToolInputPartialNotification} for the notification structure
|
||||
* @see {@link ontoolinput} for the complete tool input handler
|
||||
*/
|
||||
set ontoolinputpartial(
|
||||
callback: (params: McpUiToolInputPartialNotification["params"]) => void,
|
||||
) {
|
||||
|
|
@ -93,6 +344,37 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
callback(n.params),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience handler for receiving tool execution results from the host.
|
||||
*
|
||||
* Set this property to register a handler that will be called when the host
|
||||
* sends the result of a tool execution. This is sent after the tool completes
|
||||
* on the MCP server, allowing your app to display the results or update its state.
|
||||
*
|
||||
* This setter is a convenience wrapper around `setNotificationHandler()` that
|
||||
* automatically handles the notification schema and extracts the params for you.
|
||||
*
|
||||
* Register handlers before calling {@link connect} to avoid missing notifications.
|
||||
*
|
||||
* @param callback - Function called with the tool result
|
||||
*
|
||||
* @example Display tool execution results
|
||||
* ```typescript
|
||||
* app.ontoolresult = (params) => {
|
||||
* if (params.content) {
|
||||
* console.log("Tool output:", params.content);
|
||||
* }
|
||||
* if (params.isError) {
|
||||
* console.error("Tool execution failed");
|
||||
* }
|
||||
* };
|
||||
* ```
|
||||
*
|
||||
* @see {@link setNotificationHandler} for the underlying method
|
||||
* @see {@link McpUiToolResultNotification} for the notification structure
|
||||
* @see {@link ontoolinput} for the initial tool input handler
|
||||
*/
|
||||
set ontoolresult(
|
||||
callback: (params: McpUiToolResultNotification["params"]) => void,
|
||||
) {
|
||||
|
|
@ -100,6 +382,37 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
callback(n.params),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience handler for host context changes (theme, viewport, locale, etc.).
|
||||
*
|
||||
* Set this property to register a handler that will be called when the host's
|
||||
* context changes, such as theme switching (light/dark), viewport size changes,
|
||||
* locale changes, or other environmental updates. Apps should respond by
|
||||
* updating their UI accordingly.
|
||||
*
|
||||
* This setter is a convenience wrapper around `setNotificationHandler()` that
|
||||
* automatically handles the notification schema and extracts the params for you.
|
||||
*
|
||||
* Register handlers before calling {@link connect} to avoid missing notifications.
|
||||
*
|
||||
* @param callback - Function called with the updated host context
|
||||
*
|
||||
* @example Respond to theme changes
|
||||
* ```typescript
|
||||
* app.onhostcontextchanged = (params) => {
|
||||
* if (params.theme === "dark") {
|
||||
* document.body.classList.add("dark-theme");
|
||||
* } else {
|
||||
* document.body.classList.remove("dark-theme");
|
||||
* }
|
||||
* };
|
||||
* ```
|
||||
*
|
||||
* @see {@link setNotificationHandler} for the underlying method
|
||||
* @see {@link McpUiHostContextChangedNotification} for the notification structure
|
||||
* @see {@link McpUiHostContext} for the full context structure
|
||||
*/
|
||||
set onhostcontextchanged(
|
||||
callback: (params: McpUiHostContextChangedNotification["params"]) => void,
|
||||
) {
|
||||
|
|
@ -108,6 +421,38 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
(n) => callback(n.params),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience handler for tool call requests from the host.
|
||||
*
|
||||
* Set this property to register a handler that will be called when the host
|
||||
* requests this app to execute a tool. This enables apps to provide their own
|
||||
* tools that can be called by the host or LLM.
|
||||
*
|
||||
* The app must declare tool capabilities in the constructor to use this handler.
|
||||
*
|
||||
* This setter is a convenience wrapper around `setRequestHandler()` that
|
||||
* automatically handles the request schema and extracts the params for you.
|
||||
*
|
||||
* Register handlers before calling {@link connect} to avoid missing requests.
|
||||
*
|
||||
* @param callback - Async function that executes the tool and returns the result.
|
||||
* The callback will only be invoked if the app declared tool capabilities
|
||||
* in the constructor.
|
||||
*
|
||||
* @example Handle tool calls from the host
|
||||
* ```typescript
|
||||
* app.oncalltool = async (params, extra) => {
|
||||
* if (params.name === "greet") {
|
||||
* const name = params.arguments?.name ?? "World";
|
||||
* return { content: [{ type: "text", text: `Hello, ${name}!` }] };
|
||||
* }
|
||||
* throw new Error(`Unknown tool: ${params.name}`);
|
||||
* };
|
||||
* ```
|
||||
*
|
||||
* @see {@link setRequestHandler} for the underlying method
|
||||
*/
|
||||
set oncalltool(
|
||||
callback: (
|
||||
params: CallToolRequest["params"],
|
||||
|
|
@ -118,6 +463,37 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
callback(request.params, extra),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience handler for listing available tools.
|
||||
*
|
||||
* Set this property to register a handler that will be called when the host
|
||||
* requests a list of tools this app provides. This enables dynamic tool
|
||||
* discovery by the host or LLM.
|
||||
*
|
||||
* The app must declare tool capabilities in the constructor to use this handler.
|
||||
*
|
||||
* This setter is a convenience wrapper around `setRequestHandler()` that
|
||||
* automatically handles the request schema and extracts the params for you.
|
||||
*
|
||||
* Register handlers before calling {@link connect} to avoid missing requests.
|
||||
*
|
||||
* @param callback - Async function that returns the list of available tools.
|
||||
* The callback will only be invoked if the app declared tool capabilities
|
||||
* in the constructor.
|
||||
*
|
||||
* @example Return available tools
|
||||
* ```typescript
|
||||
* app.onlisttools = async (params, extra) => {
|
||||
* return {
|
||||
* tools: ["calculate", "convert", "format"]
|
||||
* };
|
||||
* };
|
||||
* ```
|
||||
*
|
||||
* @see {@link setRequestHandler} for the underlying method
|
||||
* @see {@link oncalltool} for handling tool execution
|
||||
*/
|
||||
set onlisttools(
|
||||
callback: (
|
||||
params: ListToolsRequest["params"],
|
||||
|
|
@ -129,9 +505,18 @@ 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 {
|
||||
// TODO
|
||||
}
|
||||
|
||||
/**
|
||||
* Verify that the app declared the capability required for the given request method.
|
||||
* @internal
|
||||
*/
|
||||
assertRequestHandlerCapability(method: Request["method"]): void {
|
||||
switch (method) {
|
||||
case "tools/call":
|
||||
|
|
@ -148,10 +533,50 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
throw new Error(`No handler for method ${method} registered`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Verify that the app supports the capability required for the given notification method.
|
||||
* @internal
|
||||
*/
|
||||
assertNotificationCapability(method: Notification["method"]): void {
|
||||
// TODO
|
||||
}
|
||||
|
||||
/**
|
||||
* Call a tool on the originating MCP server (proxied through the host).
|
||||
*
|
||||
* Apps can call tools to fetch fresh data or trigger server-side actions.
|
||||
* The host proxies the request to the actual MCP server and returns the result.
|
||||
*
|
||||
* @param params - Tool name and arguments
|
||||
* @param options - Request options (timeout, etc.)
|
||||
* @returns Tool execution result
|
||||
*
|
||||
* @throws {Error} If the tool does not exist on the server
|
||||
* @throws {Error} If the request times out or the connection is lost
|
||||
* @throws {Error} If the host rejects the request
|
||||
*
|
||||
* Note: Tool-level execution errors are returned in the result with `isError: true`
|
||||
* rather than throwing exceptions. Always check `result.isError` to distinguish
|
||||
* between transport failures (thrown) and tool execution failures (returned).
|
||||
*
|
||||
* @example Fetch updated weather data
|
||||
* ```typescript
|
||||
* try {
|
||||
* const result = await app.callServerTool({
|
||||
* name: "get_weather",
|
||||
* arguments: { location: "Tokyo" }
|
||||
* });
|
||||
* if (result.isError) {
|
||||
* console.error("Tool returned error:", result.content);
|
||||
* } else {
|
||||
* console.log(result.content);
|
||||
* }
|
||||
* } catch (error) {
|
||||
* console.error("Tool call failed:", error);
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
async callServerTool(
|
||||
params: CallToolRequest["params"],
|
||||
options?: RequestOptions,
|
||||
|
|
@ -163,6 +588,33 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a message to the host's chat interface.
|
||||
*
|
||||
* Enables the app to add messages to the conversation thread. Useful for
|
||||
* user-initiated messages or app-to-conversation communication.
|
||||
*
|
||||
* @param params - Message role and content
|
||||
* @param options - Request options (timeout, etc.)
|
||||
* @returns Result indicating success or error (no message content returned)
|
||||
*
|
||||
* @throws {Error} If the host rejects the message
|
||||
*
|
||||
* @example Send a text message from user interaction
|
||||
* ```typescript
|
||||
* try {
|
||||
* await app.sendMessage({
|
||||
* role: "user",
|
||||
* content: [{ type: "text", text: "Show me details for item #42" }]
|
||||
* });
|
||||
* } catch (error) {
|
||||
* console.error("Failed to send message:", error);
|
||||
* // Handle error appropriately for your app
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @see {@link McpUiMessageRequest} for request structure
|
||||
*/
|
||||
sendMessage(params: McpUiMessageRequest["params"], options?: RequestOptions) {
|
||||
return this.request(
|
||||
<McpUiMessageRequest>{
|
||||
|
|
@ -174,6 +626,25 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Send log messages to the host for debugging and telemetry.
|
||||
*
|
||||
* Logs are not added to the conversation but may be recorded by the host
|
||||
* for debugging purposes.
|
||||
*
|
||||
* @param params - Log level and message
|
||||
*
|
||||
* @example Log app state for debugging
|
||||
* ```typescript
|
||||
* app.sendLog({
|
||||
* level: "info",
|
||||
* data: "Weather data refreshed",
|
||||
* logger: "WeatherApp"
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* @returns Promise that resolves when the log notification is sent
|
||||
*/
|
||||
sendLog(params: LoggingMessageNotification["params"]) {
|
||||
return this.notification(<LoggingMessageNotification>{
|
||||
method: "notifications/message",
|
||||
|
|
@ -181,6 +652,31 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Request the host to open an external URL in the default browser.
|
||||
*
|
||||
* The host may deny this request based on user preferences or security policy.
|
||||
* Apps should handle rejection gracefully.
|
||||
*
|
||||
* @param params - URL to open
|
||||
* @param options - Request options (timeout, etc.)
|
||||
* @returns Result indicating success or error
|
||||
*
|
||||
* @throws {Error} If the host denies the request (e.g., blocked domain, user cancelled)
|
||||
* @throws {Error} If the request times out or the connection is lost
|
||||
*
|
||||
* @example Open documentation link
|
||||
* ```typescript
|
||||
* try {
|
||||
* await app.sendOpenLink({ url: "https://docs.example.com" });
|
||||
* } catch (error) {
|
||||
* console.error("Failed to open link:", error);
|
||||
* // Optionally show fallback: display URL for manual copy
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @see {@link McpUiOpenLinkRequest} for request structure
|
||||
*/
|
||||
sendOpenLink(
|
||||
params: McpUiOpenLinkRequest["params"],
|
||||
options?: RequestOptions,
|
||||
|
|
@ -195,6 +691,26 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Notify the host of UI size changes.
|
||||
*
|
||||
* Apps can manually report size changes to help the host adjust the container.
|
||||
* If `autoResize` is enabled (default), this is called automatically.
|
||||
*
|
||||
* @param params - New width and height in pixels
|
||||
*
|
||||
* @example Manually notify host of size change
|
||||
* ```typescript
|
||||
* app.sendSizeChange({
|
||||
* width: 400,
|
||||
* height: 600
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* @returns Promise that resolves when the notification is sent
|
||||
*
|
||||
* @see {@link McpUiSizeChangeNotification} for notification structure
|
||||
*/
|
||||
sendSizeChange(params: McpUiSizeChangeNotification["params"]) {
|
||||
return this.notification(<McpUiSizeChangeNotification>{
|
||||
method: "ui/notifications/size-change",
|
||||
|
|
@ -202,6 +718,31 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Set up automatic size change notifications using ResizeObserver.
|
||||
*
|
||||
* Observes both `document.documentElement` and `document.body` for size changes
|
||||
* and automatically sends `ui/notifications/size-change` notifications to the host.
|
||||
* The notifications are debounced using requestAnimationFrame to avoid duplicates.
|
||||
*
|
||||
* Note: This method is automatically called by `connect()` if the `autoResize`
|
||||
* option is true (default). You typically don't need to call this manually unless
|
||||
* you disabled autoResize and want to enable it later.
|
||||
*
|
||||
* @returns Cleanup function to disconnect the observer
|
||||
*
|
||||
* @example Manual setup for custom scenarios
|
||||
* ```typescript
|
||||
* const app = new App(appInfo, capabilities, { autoResize: false });
|
||||
* await app.connect(transport);
|
||||
*
|
||||
* // Later, enable auto-resize manually
|
||||
* const cleanup = app.setupSizeChangeNotifications();
|
||||
*
|
||||
* // Clean up when done
|
||||
* cleanup();
|
||||
* ```
|
||||
*/
|
||||
setupSizeChangeNotifications() {
|
||||
let scheduled = false;
|
||||
const sendBodySizeChange = () => {
|
||||
|
|
@ -230,6 +771,43 @@ export class App extends Protocol<Request, Notification, Result> {
|
|||
return () => resizeObserver.disconnect();
|
||||
}
|
||||
|
||||
/**
|
||||
* Establish connection with the host and perform initialization handshake.
|
||||
*
|
||||
* This method performs the following steps:
|
||||
* 1. Connects the transport layer
|
||||
* 2. Sends `ui/initialize` request with app info and capabilities
|
||||
* 3. Receives host capabilities and context in response
|
||||
* 4. Sends `ui/notifications/initialized` notification
|
||||
* 5. Sets up auto-resize using {@link setupSizeChangeNotifications} if enabled (default)
|
||||
*
|
||||
* If initialization fails, the connection is automatically closed and an error
|
||||
* is thrown.
|
||||
*
|
||||
* @param transport - Transport layer (typically PostMessageTransport)
|
||||
* @param options - Request options for the initialize request
|
||||
*
|
||||
* @throws {Error} If initialization fails or connection is lost
|
||||
*
|
||||
* @example Connect with PostMessageTransport
|
||||
* ```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);
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @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,
|
||||
options?: RequestOptions,
|
||||
|
|
|
|||
Loading…
Reference in a new issue