@modelcontextprotocol/ext-apps 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/README.md +1 -1
  2. package/dist/src/app-bridge.d.ts +310 -26
  3. package/dist/src/app-bridge.js +38 -25
  4. package/dist/src/app.d.ts +41 -9
  5. package/dist/src/app.js +38 -25
  6. package/dist/src/generated/schema.d.ts +101 -5
  7. package/dist/src/generated/schema.test.d.ts +8 -1
  8. package/dist/src/react/index.d.ts +4 -0
  9. package/dist/src/react/index.js +38 -25
  10. package/dist/src/react/useDocumentTheme.d.ts +46 -0
  11. package/dist/src/react/useHostStyles.d.ts +56 -0
  12. package/dist/src/server/index.d.ts +109 -0
  13. package/dist/src/server/index.js +42 -0
  14. package/dist/src/server/index.test.d.ts +1 -0
  15. package/dist/src/spec.types.d.ts +74 -1
  16. package/dist/src/styles.d.ts +89 -0
  17. package/dist/src/types.d.ts +31 -2
  18. package/package.json +51 -16
package/dist/src/styles.d.ts ADDED
@@ -0,0 +1,89 @@
1
+ import { McpUiStyles, McpUiTheme } from "./types";
2
+ /**
3
+ * Get the current document theme from the root HTML element.
4
+ *
5
+ * Reads the theme from the `data-theme` attribute on `document.documentElement`.
6
+ * Falls back to checking for a `dark` class for compatibility with Tailwind CSS
7
+ * dark mode conventions.
8
+ *
9
+ * @returns The current theme ("light" or "dark")
10
+ *
11
+ * @example Check current theme
12
+ * ```typescript
13
+ * import { getDocumentTheme } from '@modelcontextprotocol/ext-apps';
14
+ *
15
+ * const theme = getDocumentTheme();
16
+ * console.log(`Current theme: ${theme}`);
17
+ * ```
18
+ *
19
+ * @see {@link applyDocumentTheme} to set the theme
20
+ * @see {@link McpUiTheme} for the theme type
21
+ */
22
+ export declare function getDocumentTheme(): McpUiTheme;
23
+ /**
24
+ * Apply a theme to the document root element.
25
+ *
26
+ * Sets the `data-theme` attribute and CSS `color-scheme` property on
27
+ * `document.documentElement`. This enables CSS selectors like
28
+ * `[data-theme="dark"]` and ensures native elements (scrollbars, form controls)
29
+ * respect the theme.
30
+ *
31
+ * @param theme - The theme to apply ("light" or "dark")
32
+ *
33
+ * @example Apply theme from host context
34
+ * ```typescript
35
+ * import { applyDocumentTheme } from '@modelcontextprotocol/ext-apps';
36
+ *
37
+ * app.onhostcontextchanged = (params) => {
38
+ * if (params.theme) {
39
+ * applyDocumentTheme(params.theme);
40
+ * }
41
+ * };
42
+ * ```
43
+ *
44
+ * @example Use with CSS selectors
45
+ * ```css
46
+ * [data-theme="dark"] {
47
+ * --bg-color: #1a1a1a;
48
+ * }
49
+ * [data-theme="light"] {
50
+ * --bg-color: #ffffff;
51
+ * }
52
+ * ```
53
+ *
54
+ * @see {@link getDocumentTheme} to read the current theme
55
+ * @see {@link McpUiTheme} for the theme type
56
+ */
57
+ export declare function applyDocumentTheme(theme: McpUiTheme): void;
58
+ /**
59
+ * Apply host style variables as CSS custom properties on an element.
60
+ *
61
+ * This function takes the `variables` object from `McpUiHostContext.styles` and sets
62
+ * each CSS variable on the specified root element (defaults to `document.documentElement`).
63
+ * This allows apps to use the host's theming values via CSS variables like
64
+ * `var(--color-background-primary)`.
65
+ *
66
+ * @param styles - The styles object from `McpUiHostContext.styles.variables`
67
+ * @param root - The element to apply styles to (defaults to `document.documentElement`)
68
+ *
69
+ * @example Apply style variables from host context
70
+ * ```typescript
71
+ * import { applyHostStyleVariables } from '@modelcontextprotocol/ext-apps';
72
+ *
73
+ * app.onhostcontextchanged = (params) => {
74
+ * if (params.styles?.variables) {
75
+ * applyHostStyleVariables(params.styles.variables);
76
+ * }
77
+ * };
78
+ * ```
79
+ *
80
+ * @example Apply to a specific element
81
+ * ```typescript
82
+ * const container = document.getElementById('app-root');
83
+ * applyHostStyleVariables(hostContext.styles?.variables, container);
84
+ * ```
85
+ *
86
+ * @see {@link McpUiStyles} for the available CSS variables
87
+ * @see {@link McpUiHostContext} for the full host context structure
88
+ */
89
+ export declare function applyHostStyleVariables(styles: McpUiStyles, root?: HTMLElement): void;
package/dist/src/types.d.ts CHANGED
@@ -8,5 +8,34 @@
8
8
  * @see generated/schema.ts for auto-generated Zod schemas
9
9
  * @see generated/schema.test.ts for compile-time verification
10
10
  */
11
- export { LATEST_PROTOCOL_VERSION, type McpUiTheme, type McpUiDisplayMode, type McpUiOpenLinkRequest, type McpUiOpenLinkResult, type McpUiMessageRequest, type McpUiMessageResult, type McpUiSandboxProxyReadyNotification, type McpUiSandboxResourceReadyNotification, type McpUiSizeChangedNotification, type McpUiToolInputNotification, type McpUiToolInputPartialNotification, type McpUiToolResultNotification, type McpUiToolCancelledNotification, type McpUiHostContext, type McpUiHostContextChangedNotification, type McpUiResourceTeardownRequest, type McpUiResourceTeardownResult, type McpUiHostCapabilities, type McpUiAppCapabilities, type McpUiInitializeRequest, type McpUiInitializeResult, type McpUiInitializedNotification, type McpUiResourceCsp, type McpUiResourceMeta, } from "./spec.types.js";
12
- export { McpUiThemeSchema, McpUiDisplayModeSchema, McpUiOpenLinkRequestSchema, McpUiOpenLinkResultSchema, McpUiMessageRequestSchema, McpUiMessageResultSchema, McpUiSandboxProxyReadyNotificationSchema, McpUiSandboxResourceReadyNotificationSchema, McpUiSizeChangedNotificationSchema, McpUiToolInputNotificationSchema, McpUiToolInputPartialNotificationSchema, McpUiToolResultNotificationSchema, McpUiToolCancelledNotificationSchema, McpUiHostContextSchema, McpUiHostContextChangedNotificationSchema, McpUiResourceTeardownRequestSchema, McpUiResourceTeardownResultSchema, McpUiHostCapabilitiesSchema, McpUiAppCapabilitiesSchema, McpUiInitializeRequestSchema, McpUiInitializeResultSchema, McpUiInitializedNotificationSchema, McpUiResourceCspSchema, McpUiResourceMetaSchema, } from "./generated/schema.js";
11
+ export { LATEST_PROTOCOL_VERSION, type McpUiTheme, type McpUiDisplayMode, type McpUiStyleVariableKey, type McpUiStyles, type McpUiHostStyles, type McpUiOpenLinkRequest, type McpUiOpenLinkResult, type McpUiMessageRequest, type McpUiMessageResult, type McpUiSandboxProxyReadyNotification, type McpUiSandboxResourceReadyNotification, type McpUiSizeChangedNotification, type McpUiToolInputNotification, type McpUiToolInputPartialNotification, type McpUiToolResultNotification, type McpUiToolCancelledNotification, type McpUiHostContext, type McpUiHostContextChangedNotification, type McpUiResourceTeardownRequest, type McpUiResourceTeardownResult, type McpUiHostCapabilities, type McpUiAppCapabilities, type McpUiInitializeRequest, type McpUiInitializeResult, type McpUiInitializedNotification, type McpUiResourceCsp, type McpUiResourceMeta, type McpUiRequestDisplayModeRequest, type McpUiRequestDisplayModeResult, type McpUiToolVisibility, type McpUiToolMeta, } from "./spec.types.js";
12
+ import type { McpUiInitializeRequest, McpUiOpenLinkRequest, McpUiMessageRequest, McpUiResourceTeardownRequest, McpUiRequestDisplayModeRequest, McpUiHostContextChangedNotification, McpUiToolInputNotification, McpUiToolInputPartialNotification, McpUiToolResultNotification, McpUiToolCancelledNotification, McpUiSandboxResourceReadyNotification, McpUiInitializedNotification, McpUiSizeChangedNotification, McpUiSandboxProxyReadyNotification, McpUiInitializeResult, McpUiOpenLinkResult, McpUiMessageResult, McpUiResourceTeardownResult, McpUiRequestDisplayModeResult } from "./spec.types.js";
13
+ export { McpUiThemeSchema, McpUiDisplayModeSchema, McpUiHostStylesSchema, McpUiOpenLinkRequestSchema, McpUiOpenLinkResultSchema, McpUiMessageRequestSchema, McpUiMessageResultSchema, McpUiSandboxProxyReadyNotificationSchema, McpUiSandboxResourceReadyNotificationSchema, McpUiSizeChangedNotificationSchema, McpUiToolInputNotificationSchema, McpUiToolInputPartialNotificationSchema, McpUiToolResultNotificationSchema, McpUiToolCancelledNotificationSchema, McpUiHostContextSchema, McpUiHostContextChangedNotificationSchema, McpUiResourceTeardownRequestSchema, McpUiResourceTeardownResultSchema, McpUiHostCapabilitiesSchema, McpUiAppCapabilitiesSchema, McpUiInitializeRequestSchema, McpUiInitializeResultSchema, McpUiInitializedNotificationSchema, McpUiResourceCspSchema, McpUiResourceMetaSchema, McpUiRequestDisplayModeRequestSchema, McpUiRequestDisplayModeResultSchema, McpUiToolVisibilitySchema, McpUiToolMetaSchema, } from "./generated/schema.js";
14
+ import { CallToolRequest, CallToolResult, EmptyResult, ListPromptsRequest, ListPromptsResult, ListResourcesRequest, ListResourcesResult, ListResourceTemplatesRequest, ListResourceTemplatesResult, ListToolsRequest, ListToolsResult, LoggingMessageNotification, PingRequest, PromptListChangedNotification, ReadResourceRequest, ReadResourceResult, ResourceListChangedNotification, ToolListChangedNotification } from "@modelcontextprotocol/sdk/types.js";
15
+ /**
16
+ * All request types in the MCP Apps protocol.
17
+ *
18
+ * Includes:
19
+ * - MCP UI requests (initialize, open-link, message, resource-teardown, request-display-mode)
20
+ * - MCP server requests forwarded from the app (tools/call, resources/*, prompts/list)
21
+ * - Protocol requests (ping)
22
+ */
23
+ export type AppRequest = McpUiInitializeRequest | McpUiOpenLinkRequest | McpUiMessageRequest | McpUiResourceTeardownRequest | McpUiRequestDisplayModeRequest | CallToolRequest | ListToolsRequest | ListResourcesRequest | ListResourceTemplatesRequest | ReadResourceRequest | ListPromptsRequest | PingRequest;
24
+ /**
25
+ * All notification types in the MCP Apps protocol.
26
+ *
27
+ * Host to app:
28
+ * - Tool lifecycle (input, input-partial, result, cancelled)
29
+ * - Host context changes
30
+ * - MCP list changes (tools, resources, prompts)
31
+ * - Sandbox resource ready
32
+ *
33
+ * App to host:
34
+ * - Initialized, size-changed, sandbox-proxy-ready
35
+ * - Logging messages
36
+ */
37
+ export type AppNotification = McpUiHostContextChangedNotification | McpUiToolInputNotification | McpUiToolInputPartialNotification | McpUiToolResultNotification | McpUiToolCancelledNotification | McpUiSandboxResourceReadyNotification | ToolListChangedNotification | ResourceListChangedNotification | PromptListChangedNotification | McpUiInitializedNotification | McpUiSizeChangedNotification | McpUiSandboxProxyReadyNotification | LoggingMessageNotification;
38
+ /**
39
+ * All result types in the MCP Apps protocol.
40
+ */
41
+ export type AppResult = McpUiInitializeResult | McpUiOpenLinkResult | McpUiMessageResult | McpUiResourceTeardownResult | McpUiRequestDisplayModeResult | CallToolResult | ListToolsResult | ListResourcesResult | ListResourceTemplatesResult | ReadResourceResult | ListPromptsResult | EmptyResult;
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "url": "https://github.com/modelcontextprotocol/ext-apps"
6
6
  },
7
7
  "homepage": "https://github.com/modelcontextprotocol/ext-apps",
8
- "version": "0.1.0",
8
+ "version": "0.2.0",
9
9
  "license": "MIT",
10
10
  "description": "MCP Apps SDK — Enable MCP servers to display interactive user interfaces in conversational clients.",
11
11
  "type": "module",
@@ -23,6 +23,10 @@
23
23
  "types": "./dist/src/app-bridge.d.ts",
24
24
  "default": "./dist/src/app-bridge.js"
25
25
  },
26
+ "./server": {
27
+ "types": "./dist/src/server/index.d.ts",
28
+ "default": "./dist/src/server/index.js"
29
+ },
26
30
  "./schema.json": "./dist/src/generated/schema.json"
27
31
  },
28
32
  "files": [
@@ -32,51 +36,82 @@
32
36
  "examples/*"
33
37
  ],
34
38
  "scripts": {
35
- "generate:schemas": "tsx scripts/generate-schemas.ts && prettier --write 'src/generated/**/*'",
36
- "build": "npm run generate:schemas && bun build.bun.ts",
39
+ "postinstall": "node scripts/setup-bun.mjs || echo 'setup-bun.mjs failed or not available'",
40
+ "generate:schemas": "tsx scripts/generate-schemas.ts && prettier --write \"src/generated/**/*\"",
41
+ "build": "npm run generate:schemas && node scripts/run-bun.mjs build.bun.ts",
37
42
  "prepack": "npm run build",
38
43
  "build:all": "npm run build && npm run examples:build",
39
- "test": "bun test",
44
+ "test": "bun test src",
45
+ "test:e2e": "playwright test",
46
+ "test:e2e:update": "playwright test --update-snapshots",
47
+ "test:e2e:ui": "playwright test --ui",
48
+ "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'",
49
+ "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'",
40
50
  "examples:build": "bun examples/run-all.ts build",
41
51
  "examples:start": "NODE_ENV=development npm run build && bun examples/run-all.ts start",
42
52
  "examples:dev": "NODE_ENV=development bun examples/run-all.ts dev",
43
53
  "watch": "nodemon --watch src --ext ts,tsx --exec 'bun build.bun.ts'",
44
- "prepare": "npm run build && husky",
54
+ "prepare": "node scripts/setup-bun.mjs && npm run build && husky",
45
55
  "docs": "typedoc",
46
56
  "docs:watch": "typedoc --watch",
47
- "prettier:base-cmd": "prettier -u --ignore-path ./.gitignore --ignore-path ./.prettierignore",
48
- "prettier": "yarn prettier:base-cmd \"$(pwd)/**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --check",
49
- "prettier:fix": "yarn prettier:base-cmd \"$(pwd)/**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --write --list-different"
57
+ "prettier": "prettier -u \"**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --check",
58
+ "prettier:fix": "prettier -u \"**/*.{js,jsx,ts,tsx,mjs,json,md,yml,yaml}\" --write"
50
59
  },
51
60
  "author": "Olivier Chafik",
52
61
  "devDependencies": {
62
+ "@modelcontextprotocol/sdk": "^1.24.0",
63
+ "@playwright/test": "^1.52.0",
53
64
  "@types/bun": "^1.3.2",
54
- "bun": "^1.3.2",
55
65
  "@types/react": "^19.2.2",
56
66
  "@types/react-dom": "^19.2.2",
57
67
  "concurrently": "^9.2.1",
58
68
  "cors": "^2.8.5",
69
+ "cross-env": "^10.1.0",
59
70
  "esbuild": "^0.25.12",
60
71
  "express": "^5.1.0",
61
72
  "husky": "^9.1.7",
62
73
  "nodemon": "^3.1.0",
63
- "prettier": "^3.6.2",
74
+ "react": "^19.2.0",
75
+ "react-dom": "^19.2.0",
64
76
  "ts-to-zod": "^5.1.0",
65
77
  "tsx": "^4.21.0",
66
78
  "typedoc": "^0.28.14",
67
- "typescript": "^5.9.3"
79
+ "typescript": "^5.9.3",
80
+ "zod": "^4.1.13"
81
+ },
82
+ "peerDependencies": {
83
+ "@modelcontextprotocol/sdk": "^1.24.0",
84
+ "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
85
+ "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0",
86
+ "zod": "^3.25.0 || ^4.0.0"
87
+ },
88
+ "peerDependenciesMeta": {
89
+ "react": {
90
+ "optional": true
91
+ },
92
+ "react-dom": {
93
+ "optional": true
94
+ }
68
95
  },
69
96
  "dependencies": {
70
- "@modelcontextprotocol/sdk": "^1.24.3",
71
- "react": "^19.2.0",
72
- "react-dom": "^19.2.0",
73
- "zod": "^3.25"
97
+ "prettier": "^3.6.2"
74
98
  },
75
99
  "optionalDependencies": {
100
+ "@oven/bun-darwin-aarch64": "^1.3.4",
101
+ "@oven/bun-darwin-x64": "^1.3.4",
102
+ "@oven/bun-darwin-x64-baseline": "^1.3.4",
103
+ "@oven/bun-linux-aarch64": "^1.3.4",
104
+ "@oven/bun-linux-aarch64-musl": "^1.3.4",
105
+ "@oven/bun-linux-x64": "^1.3.4",
106
+ "@oven/bun-linux-x64-baseline": "^1.3.4",
107
+ "@oven/bun-linux-x64-musl": "^1.3.4",
108
+ "@oven/bun-linux-x64-musl-baseline": "^1.3.4",
109
+ "@oven/bun-windows-x64": "^1.3.4",
110
+ "@oven/bun-windows-x64-baseline": "^1.3.4",
76
111
  "@rollup/rollup-darwin-arm64": "^4.53.3",
77
112
  "@rollup/rollup-darwin-x64": "^4.53.3",
78
- "@rollup/rollup-linux-x64-gnu": "^4.53.3",
79
113
  "@rollup/rollup-linux-arm64-gnu": "^4.53.3",
114
+ "@rollup/rollup-linux-x64-gnu": "^4.53.3",
80
115
  "@rollup/rollup-win32-x64-msvc": "^4.53.3"
81
116
  }
82
117
  }