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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* Add docs index.html redirect to API documentation

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

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

* 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 <[email protected]>

* Update src/app-bridge.ts

---------

Co-authored-by: Claude <[email protected]>
Co-authored-by: Olivier Chafik <[email protected]>

Author: 3 people

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Deploy Documentation
+
+on:
+  workflow_dispatch:
+  # Future: Uncomment to auto-deploy on release
+  # release:
+  #   types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm install
+      - run: npm run build
+      - run: npm run docs
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          publish_branch: gh-pages
+          force_orphan: true

.gitignore

@@ -4,3 +4,5 @@ node_modules/
 package-lock.json
 yarn.lock
 .vscode/
+docs/api/
+tmp/

README.md

@@ -1,59 +1,37 @@
 # @modelcontextprotocol/ext-apps
 
-This repo contains the SDK and [specification](./specification/draft/apps.mdx) for MCP Apps Extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)).
+[![API Documentation](https://img.shields.io/badge/docs-API%20Reference-blue)](https://modelcontextprotocol.github.io/ext-apps/)
 
-MCP Apps are proposed standard inspired by [MCP-UI](https://mcpui.dev/) and [OpenAI's Apps SDK](https://developers.openai.com/apps-sdk/) to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots.
+This repo contains the SDK and [specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) for MCP Apps Extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)).
 
-This repo provides:
+MCP Apps are a proposed standard inspired by [MCP-UI](https://mcpui.dev/) and [OpenAI's Apps SDK](https://developers.openai.com/apps-sdk/) to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots.
 
-- [specification/draft/apps.mdx](./specification/draft/apps.mdx): The Draft Extension Specification. It's still... in flux! Feedback welcome! (also see discussions in [SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)).
+## Overview
 
-- [types.ts](./src/types.ts): Types of JSON-RPC messages used to communicate between Apps & their host
-  - Note that MCP Apps also use some standard MCP messages (e.g. `tools/call` for the App to trigger actions on its originating Server - these calls are proxied through the Host), but these types are the additional messages defined by the extension
-- [examples/simple-example](./examples/simple-server): Example Server + Apps
-  - [server.ts](./examples/simple-server/server.ts): MCP server with three tools that declare UI resources of Apps to be show in the chat when called
-  - [ui-react.tsx](./examples/simple-server/src/ui-react.tsx): React App returned by the `create-ui-react` tool shows how to use the `useApp` hook to register MCP callbacks
-  - [ui-vanilla.tsx](./examples/simple-server/src/ui-vanilla.ts): vanilla App returned by the `create-ui-vanilla`
-  - [ui-raw.tsx](./examples/simple-server/src/ui-raw.ts): same as vanilla App but doesn't use the SDK runtime (just its types)
+This SDK serves two audiences:
 
-- [examples/simple-host](./examples/simple-host): bare-bone examples on how to host MCP Apps (both use the [AppBridge](./src/app-bridge.ts) class to talk to a hosted App)
-  - [example-host-react.tsx](./examples/simple-host/src/example-host-react.tsx) uses React (esp. [AppRenderer.tsx](./examples/simple-host/src/AppRenderer.tsx))
-  - [example-host-vanilla.tsx](./examples/simple-host/src/example-host-vanilla.tsx) doesn't use React
+### App Developers
 
-- [message-transport](./src/message-transport.ts): `PostMessageTransport` class that uses `postMessage` to exchange JSON-RPC messages between windows / iframes
+Build interactive UIs that run inside MCP-enabled chat clients.
 
-- [app.ts](./src/app.ts): `App` class used by an App to talk to its host
+- **SDK for Apps**: `@modelcontextprotocol/ext-apps` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/modules/_modelcontextprotocol_ext_apps.html)
+- **React hooks**: `@modelcontextprotocol/ext-apps/react` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/modules/_modelcontextprotocol_ext_apps_react.html)
 
-- [app-bridge.ts](./src/app-bridge.ts): `AppBridge` class used by the host to talk to a single App
+### Host Developers
 
-- _Soon_: more examples!
+Embed and communicate with MCP Apps in your chat application.
 
-What this repo does NOT provide:
+- **SDK for Hosts**: `@modelcontextprotocol/ext-apps/app-bridge` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/modules/_modelcontextprotocol_ext_apps_app_bridge.html)
 
-- There's no _supported_ host implementation in this repo (beyond the [examples/simple-host](./examples/simple-host) example)
-  - We have [contributed a tentative implementation](https://github.com/MCP-UI-Org/mcp-ui/pull/147) of hosting / iframing / sandboxing logic to the [MCP-UI](https://github.com/idosal/mcp-ui) repository, and expect OSS clients may use it, while other clients might roll their own hosting logic.
+There's no _supported_ host implementation in this repo (beyond the [examples/simple-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/simple-host) example).
 
-## Using the SDK
+We have [contributed a tentative implementation](https://github.com/MCP-UI-Org/mcp-ui/pull/147) of hosting / iframing / sandboxing logic to the [MCP-UI](https://github.com/idosal/mcp-ui) repository, and expect OSS clients may use it, while other clients might roll their own hosting logic.
 
-### Run examples
+## Installation
 
-Run the examples in this repo end-to-end:
+This repo is in flux and isn't published to npm yet. When it is, it will use the `@modelcontextprotocol/ext-apps` package.
 
-```
-npm i
-npm start
-```
-
-open http://localhost:8080/
-
-> [!NOTE]  
-> Please bear with us while we add more examples!
-
-### Using the SDK in your project
-
-This repo is in flux and isn't published to npm yet: when it is, it will use the `@modelcontextprotocol/ext-apps` package.
-
-In the meantime you can depend on the SDK library in a Node.js project by installing it w/ its git URL:
+In the meantime you can depend on the SDK library in a Node.js project by installing it with its git URL:
 
 ```bash
 npm install -S git+https://github.com/modelcontextprotocol/ext-apps.git
@@ -63,15 +41,33 @@ Your `package.json` will then look like:
 
 ```json
 {
-  ...
   "dependencies": {
-    ...
     "@modelcontextprotocol/ext-apps": "git+https://github.com/modelcontextprotocol/ext-apps.git"
   }
 }
 ```
 
-> [!NOTE]  
+> [!NOTE]
 > The build tools (`esbuild`, `tsx`, `typescript`) are in `dependencies` rather than `devDependencies`. This is intentional: it allows the `prepare` script to run when the package is installed from git, since npm doesn't install devDependencies for git dependencies.
 >
 > Once the package is published to npm with pre-built `dist/`, these can be moved back to `devDependencies`.
+
+## Examples
+
+- [examples/simple-server](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/simple-server) — Example MCP server with tools that return UI Apps
+- [examples/simple-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/simple-host) — Bare-bones example of hosting MCP Apps
+
+To run the examples end-to-end:
+
+```
+npm i
+npm start
+```
+
+Then open http://localhost:8080/
+
+## Resources
+
+- [API Documentation](https://modelcontextprotocol.github.io/ext-apps/)
+- [Draft Specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx)
+- [SEP-1865 Discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)

docs/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="refresh" content="0; url=api/">
+  <title>Redirecting...</title>
+</head>
+<body>
+  <p>Redirecting to <a href="api/">API Documentation</a>...</p>
+  <script>window.location.href = 'api/';</script>
+</body>
+</html>

package.json

@@ -31,6 +31,8 @@
     "start": "NODE_ENV=development npm run build && concurrently 'npm run start:example-host' 'npm run start:example-mcp-server'",
     "build": "bun build.bun.ts",
     "prepare": "npm run build && husky",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
     "prettier:base-cmd": "prettier -u --ignore-path ./.gitignore --ignore-path ./.prettierignore",
     "prettier": "yarn prettier:base-cmd \"$(pwd)/**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --check",
     "prettier:fix": "yarn prettier:base-cmd \"$(pwd)/**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --write --list-different"
@@ -45,10 +47,11 @@
     "express": "^5.1.0",
     "husky": "^9.1.7",
     "prettier": "^3.6.2",
+    "typedoc": "^0.28.14",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.22.0",
+    "@modelcontextprotocol/sdk": "^1.23.0",
     "bun": "^1.3.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",