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
|
|
@ -8,12 +8,69 @@ import {
|
|||
TransportSendOptions,
|
||||
} from "@modelcontextprotocol/sdk/shared/transport.js";
|
||||
|
||||
/**
|
||||
* JSON-RPC transport using window.postMessage for iframe↔parent communication.
|
||||
*
|
||||
* This transport enables bidirectional communication between MCP Apps running in
|
||||
* iframes and their host applications using the browser's postMessage API. It
|
||||
* implements the MCP SDK's Transport interface.
|
||||
*
|
||||
* ## Security
|
||||
*
|
||||
* The `eventSource` parameter provides origin validation by filtering messages
|
||||
* from specific sources. Guest UIs typically don't need to specify this (they only
|
||||
* communicate with their parent), but hosts should validate the iframe source for
|
||||
* security.
|
||||
*
|
||||
* ## Usage
|
||||
*
|
||||
* **Guest UI (default)**:
|
||||
* ```typescript
|
||||
* const transport = new PostMessageTransport(window.parent);
|
||||
* await app.connect(transport);
|
||||
* ```
|
||||
*
|
||||
* **Host (with source validation)**:
|
||||
* ```typescript
|
||||
* const iframe = document.getElementById('app-iframe') as HTMLIFrameElement;
|
||||
* const transport = new PostMessageTransport(
|
||||
* iframe.contentWindow!,
|
||||
* iframe.contentWindow // Validate messages from this iframe only
|
||||
* );
|
||||
* await bridge.connect(transport);
|
||||
* ```
|
||||
*
|
||||
* @see {@link app.App.connect} for Guest UI usage
|
||||
* @see {@link app-bridge.AppBridge.connect} for Host usage
|
||||
*/
|
||||
export class PostMessageTransport implements Transport {
|
||||
private messageListener: (
|
||||
this: Window,
|
||||
ev: WindowEventMap["message"],
|
||||
) => any | undefined;
|
||||
|
||||
/**
|
||||
* Create a new PostMessageTransport.
|
||||
*
|
||||
* @param eventTarget - Target window to send messages to (default: window.parent)
|
||||
* @param eventSource - Optional source validation. If specified, only messages from
|
||||
* this source will be accepted. Guest UIs typically don't need this (they only
|
||||
* receive from parent), but hosts should validate the iframe source.
|
||||
*
|
||||
* @example Guest UI connecting to parent
|
||||
* ```typescript
|
||||
* const transport = new PostMessageTransport(window.parent);
|
||||
* ```
|
||||
*
|
||||
* @example Host connecting to iframe with validation
|
||||
* ```typescript
|
||||
* const iframe = document.getElementById('app') as HTMLIFrameElement;
|
||||
* const transport = new PostMessageTransport(
|
||||
* iframe.contentWindow!,
|
||||
* iframe.contentWindow // Only accept messages from this iframe
|
||||
* );
|
||||
* ```
|
||||
*/
|
||||
constructor(
|
||||
private eventTarget: Window = window.parent,
|
||||
private eventSource?: MessageEventSource,
|
||||
|
|
@ -37,20 +94,84 @@ export class PostMessageTransport implements Transport {
|
|||
}
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Begin listening for messages from the event source.
|
||||
*
|
||||
* Registers a message event listener on the window. Must be called before
|
||||
* messages can be received.
|
||||
*/
|
||||
async start() {
|
||||
window.addEventListener("message", this.messageListener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a JSON-RPC message to the target window.
|
||||
*
|
||||
* Messages are sent using postMessage with "*" origin, meaning they are visible
|
||||
* to all frames. The receiver should validate the message source for security.
|
||||
*
|
||||
* @param message - JSON-RPC message to send
|
||||
* @param options - Optional send options (currently unused)
|
||||
*/
|
||||
async send(message: JSONRPCMessage, options?: TransportSendOptions) {
|
||||
console.info("[host] Sending message", message);
|
||||
this.eventTarget.postMessage(message, "*");
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop listening for messages and cleanup.
|
||||
*
|
||||
* Removes the message event listener and calls the {@link onclose} callback if set.
|
||||
*/
|
||||
async close() {
|
||||
window.removeEventListener("message", this.messageListener);
|
||||
this.onclose?.();
|
||||
}
|
||||
|
||||
/**
|
||||
* Called when the transport is closed.
|
||||
*
|
||||
* Set this handler to be notified when {@link close} is called.
|
||||
*/
|
||||
onclose?: () => void;
|
||||
|
||||
/**
|
||||
* Called when a message parsing error occurs.
|
||||
*
|
||||
* This handler is invoked when a received message fails JSON-RPC schema
|
||||
* validation. The error parameter contains details about the validation failure.
|
||||
*
|
||||
* @param error - Error describing the validation failure
|
||||
*/
|
||||
onerror?: (error: Error) => void;
|
||||
|
||||
/**
|
||||
* Called when a valid JSON-RPC message is received.
|
||||
*
|
||||
* This handler is invoked after message validation succeeds. The {@link start}
|
||||
* method must be called before messages will be received.
|
||||
*
|
||||
* @param message - The validated JSON-RPC message
|
||||
* @param extra - Optional metadata about the message (unused in this transport)
|
||||
*/
|
||||
onmessage?: (message: JSONRPCMessage, extra?: MessageExtraInfo) => void;
|
||||
|
||||
/**
|
||||
* Optional session identifier for this transport connection.
|
||||
*
|
||||
* Set by the MCP SDK to track the connection session. Not required for
|
||||
* PostMessageTransport functionality.
|
||||
*/
|
||||
sessionId?: string;
|
||||
|
||||
/**
|
||||
* Callback to set the negotiated protocol version.
|
||||
*
|
||||
* The MCP SDK calls this during initialization to communicate the protocol
|
||||
* version negotiated with the peer.
|
||||
*
|
||||
* @param version - The negotiated protocol version string
|
||||
*/
|
||||
setProtocolVersion?: (version: string) => void;
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue