skybridge 0.0.0-dev.ea7f5b5 → 0.0.0-dev.eab2782

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 (159) hide show
  1. package/LICENSE +21 -674
  2. package/dist/src/server/devtoolsStaticServer.d.ts +19 -0
  3. package/dist/src/server/devtoolsStaticServer.js +48 -0
  4. package/dist/src/server/devtoolsStaticServer.js.map +1 -0
  5. package/dist/src/server/index.d.ts +3 -2
  6. package/dist/src/server/index.js +1 -0
  7. package/dist/src/server/index.js.map +1 -1
  8. package/dist/src/server/inferUtilityTypes.d.ts +10 -0
  9. package/dist/src/server/server.d.ts +43 -17
  10. package/dist/src/server/server.js +53 -33
  11. package/dist/src/server/server.js.map +1 -1
  12. package/dist/src/server/templateHelper.d.ts +3 -0
  13. package/dist/src/server/templateHelper.js +5 -4
  14. package/dist/src/server/templateHelper.js.map +1 -1
  15. package/dist/src/server/templates/development.hbs +3 -2
  16. package/dist/src/server/templates/production.hbs +1 -0
  17. package/dist/src/server/widgetsDevServer.js +2 -3
  18. package/dist/src/server/widgetsDevServer.js.map +1 -1
  19. package/dist/src/test/utils.d.ts +54 -8
  20. package/dist/src/test/utils.js +81 -3
  21. package/dist/src/test/utils.js.map +1 -1
  22. package/dist/src/test/widget.test.js +82 -26
  23. package/dist/src/test/widget.test.js.map +1 -1
  24. package/dist/src/web/bridges/adaptors/apps-sdk-adaptor.d.ts +13 -0
  25. package/dist/src/web/bridges/adaptors/apps-sdk-adaptor.js +33 -0
  26. package/dist/src/web/bridges/adaptors/apps-sdk-adaptor.js.map +1 -0
  27. package/dist/src/web/bridges/adaptors/mcp-app-adaptor.d.ts +16 -0
  28. package/dist/src/web/bridges/adaptors/mcp-app-adaptor.js +115 -0
  29. package/dist/src/web/bridges/adaptors/mcp-app-adaptor.js.map +1 -0
  30. package/dist/src/web/bridges/apps-sdk-bridge.d.ts +10 -0
  31. package/dist/src/web/bridges/apps-sdk-bridge.js +46 -0
  32. package/dist/src/web/bridges/apps-sdk-bridge.js.map +1 -0
  33. package/dist/src/web/bridges/hooks/use-adaptor.d.ts +2 -0
  34. package/dist/src/web/bridges/hooks/use-adaptor.js +8 -0
  35. package/dist/src/web/bridges/hooks/use-adaptor.js.map +1 -0
  36. package/dist/src/web/bridges/hooks/use-apps-sdk-bridge.d.ts +2 -0
  37. package/dist/src/web/bridges/hooks/use-apps-sdk-bridge.js +7 -0
  38. package/dist/src/web/bridges/hooks/use-apps-sdk-bridge.js.map +1 -0
  39. package/dist/src/web/bridges/hooks/use-bridge.d.ts +2 -0
  40. package/dist/src/web/bridges/hooks/use-bridge.js +8 -0
  41. package/dist/src/web/bridges/hooks/use-bridge.js.map +1 -0
  42. package/dist/src/web/bridges/hooks/use-mcp-app-bridge.d.ts +5 -0
  43. package/dist/src/web/bridges/hooks/use-mcp-app-bridge.js +7 -0
  44. package/dist/src/web/bridges/hooks/use-mcp-app-bridge.js.map +1 -0
  45. package/dist/src/web/bridges/hooks/use-mcp-app-bridge.test.js +41 -0
  46. package/dist/src/web/bridges/hooks/use-mcp-app-bridge.test.js.map +1 -0
  47. package/dist/src/web/bridges/index.d.ts +4 -0
  48. package/dist/src/web/bridges/index.js +5 -0
  49. package/dist/src/web/bridges/index.js.map +1 -0
  50. package/dist/src/web/bridges/mcp-app-bridge.d.ts +38 -0
  51. package/dist/src/web/bridges/mcp-app-bridge.js +162 -0
  52. package/dist/src/web/bridges/mcp-app-bridge.js.map +1 -0
  53. package/dist/src/web/bridges/types.d.ts +57 -0
  54. package/dist/src/web/bridges/types.js +2 -0
  55. package/dist/src/web/bridges/types.js.map +1 -0
  56. package/dist/src/web/create-store.js +1 -1
  57. package/dist/src/web/create-store.js.map +1 -1
  58. package/dist/src/web/create-store.test.js +1 -1
  59. package/dist/src/web/create-store.test.js.map +1 -1
  60. package/dist/src/web/data-llm.js +6 -4
  61. package/dist/src/web/data-llm.js.map +1 -1
  62. package/dist/src/web/data-llm.test.js.map +1 -1
  63. package/dist/src/web/generate-helpers.d.ts +9 -7
  64. package/dist/src/web/generate-helpers.js +4 -2
  65. package/dist/src/web/generate-helpers.js.map +1 -1
  66. package/dist/src/web/generate-helpers.test-d.js +59 -3
  67. package/dist/src/web/generate-helpers.test-d.js.map +1 -1
  68. package/dist/src/web/generate-helpers.test.js +1 -1
  69. package/dist/src/web/generate-helpers.test.js.map +1 -1
  70. package/dist/src/web/helpers/state.js +1 -1
  71. package/dist/src/web/helpers/state.js.map +1 -1
  72. package/dist/src/web/helpers/state.test.js +2 -2
  73. package/dist/src/web/helpers/state.test.js.map +1 -1
  74. package/dist/src/web/hooks/index.d.ts +4 -5
  75. package/dist/src/web/hooks/index.js +3 -4
  76. package/dist/src/web/hooks/index.js.map +1 -1
  77. package/dist/src/web/hooks/test/utils.d.ts +10 -0
  78. package/dist/src/web/hooks/test/utils.js +40 -0
  79. package/dist/src/web/hooks/test/utils.js.map +1 -0
  80. package/dist/src/web/hooks/use-call-tool.d.ts +1 -1
  81. package/dist/src/web/hooks/use-call-tool.js +12 -4
  82. package/dist/src/web/hooks/use-call-tool.js.map +1 -1
  83. package/dist/src/web/hooks/use-call-tool.test-d.js +1 -1
  84. package/dist/src/web/hooks/use-call-tool.test-d.js.map +1 -1
  85. package/dist/src/web/hooks/use-call-tool.test.js +35 -15
  86. package/dist/src/web/hooks/use-call-tool.test.js.map +1 -1
  87. package/dist/src/web/hooks/use-display-mode.d.ts +1 -1
  88. package/dist/src/web/hooks/use-display-mode.js +6 -3
  89. package/dist/src/web/hooks/use-display-mode.js.map +1 -1
  90. package/dist/src/web/hooks/use-display-mode.test.js +3 -2
  91. package/dist/src/web/hooks/use-display-mode.test.js.map +1 -1
  92. package/dist/src/web/hooks/use-files.test.js +1 -1
  93. package/dist/src/web/hooks/use-files.test.js.map +1 -1
  94. package/dist/src/web/hooks/use-layout.d.ts +22 -0
  95. package/dist/src/web/hooks/use-layout.js +23 -0
  96. package/dist/src/web/hooks/use-layout.js.map +1 -0
  97. package/dist/src/web/hooks/use-layout.test.js +95 -0
  98. package/dist/src/web/hooks/use-layout.test.js.map +1 -0
  99. package/dist/src/web/hooks/use-open-external.js +5 -3
  100. package/dist/src/web/hooks/use-open-external.js.map +1 -1
  101. package/dist/src/web/hooks/use-open-external.test.js +43 -17
  102. package/dist/src/web/hooks/use-open-external.test.js.map +1 -1
  103. package/dist/src/web/hooks/use-openai-global.d.ts +3 -2
  104. package/dist/src/web/hooks/use-openai-global.js +3 -20
  105. package/dist/src/web/hooks/use-openai-global.js.map +1 -1
  106. package/dist/src/web/hooks/use-request-modal.d.ts +6 -3
  107. package/dist/src/web/hooks/use-request-modal.js +6 -1
  108. package/dist/src/web/hooks/use-request-modal.js.map +1 -1
  109. package/dist/src/web/hooks/use-request-modal.test.js +37 -4
  110. package/dist/src/web/hooks/use-request-modal.test.js.map +1 -1
  111. package/dist/src/web/hooks/use-send-follow-up-message.js +3 -6
  112. package/dist/src/web/hooks/use-send-follow-up-message.js.map +1 -1
  113. package/dist/src/web/hooks/use-tool-info.d.ts +13 -2
  114. package/dist/src/web/hooks/use-tool-info.js +15 -11
  115. package/dist/src/web/hooks/use-tool-info.js.map +1 -1
  116. package/dist/src/web/hooks/use-tool-info.test-d.js +40 -5
  117. package/dist/src/web/hooks/use-tool-info.test-d.js.map +1 -1
  118. package/dist/src/web/hooks/use-tool-info.test.js +119 -48
  119. package/dist/src/web/hooks/use-tool-info.test.js.map +1 -1
  120. package/dist/src/web/hooks/use-user.d.ts +18 -0
  121. package/dist/src/web/hooks/use-user.js +19 -0
  122. package/dist/src/web/hooks/use-user.js.map +1 -0
  123. package/dist/src/web/hooks/use-user.test.js +93 -0
  124. package/dist/src/web/hooks/use-user.test.js.map +1 -0
  125. package/dist/src/web/hooks/use-widget-state.js +3 -3
  126. package/dist/src/web/hooks/use-widget-state.js.map +1 -1
  127. package/dist/src/web/hooks/use-widget-state.test.js +3 -2
  128. package/dist/src/web/hooks/use-widget-state.test.js.map +1 -1
  129. package/dist/src/web/index.d.ts +5 -4
  130. package/dist/src/web/index.js +5 -4
  131. package/dist/src/web/index.js.map +1 -1
  132. package/dist/src/web/plugin/plugin.js +10 -4
  133. package/dist/src/web/plugin/plugin.js.map +1 -1
  134. package/dist/src/web/plugin/transform-data-llm.js +6 -3
  135. package/dist/src/web/plugin/transform-data-llm.js.map +1 -1
  136. package/dist/src/web/proxy.js +6 -1
  137. package/dist/src/web/proxy.js.map +1 -1
  138. package/dist/src/web/types.d.ts +30 -14
  139. package/dist/src/web/types.js.map +1 -1
  140. package/package.json +23 -18
  141. package/README.md +0 -457
  142. package/dist/src/web/hooks/use-locale.d.ts +0 -1
  143. package/dist/src/web/hooks/use-locale.js +0 -5
  144. package/dist/src/web/hooks/use-locale.js.map +0 -1
  145. package/dist/src/web/hooks/use-locale.test.js +0 -21
  146. package/dist/src/web/hooks/use-locale.test.js.map +0 -1
  147. package/dist/src/web/hooks/use-theme.d.ts +0 -1
  148. package/dist/src/web/hooks/use-theme.js +0 -5
  149. package/dist/src/web/hooks/use-theme.js.map +0 -1
  150. package/dist/src/web/hooks/use-theme.test.js +0 -26
  151. package/dist/src/web/hooks/use-theme.test.js.map +0 -1
  152. package/dist/src/web/hooks/use-user-agent.d.ts +0 -1
  153. package/dist/src/web/hooks/use-user-agent.js +0 -5
  154. package/dist/src/web/hooks/use-user-agent.js.map +0 -1
  155. package/dist/src/web/hooks/use-user-agent.test.js +0 -31
  156. package/dist/src/web/hooks/use-user-agent.test.js.map +0 -1
  157. /package/dist/src/web/{hooks/use-locale.test.d.ts → bridges/hooks/use-mcp-app-bridge.test.d.ts} +0 -0
  158. /package/dist/src/web/hooks/{use-theme.test.d.ts → use-layout.test.d.ts} +0 -0
  159. /package/dist/src/web/hooks/{use-user-agent.test.d.ts → use-user.test.d.ts} +0 -0
@@ -1,6 +1,8 @@
1
1
  import "react";
2
+ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
3
+ import type { WidgetHostType } from "../server/index.js";
2
4
  declare module "react" {
3
- interface HTMLAttributes<T extends Element = HTMLElement> {
5
+ interface HTMLAttributes<T> {
4
6
  "data-llm"?: string;
5
7
  }
6
8
  }
@@ -10,7 +12,7 @@ export type Prettify<T> = {
10
12
  } & {};
11
13
  export type Objectify<T> = T & UnknownObject;
12
14
  type RequiredKeys<T> = {
13
- [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
15
+ [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
14
16
  }[keyof T];
15
17
  export type HasRequiredKeys<T> = RequiredKeys<T> extends never ? false : true;
16
18
  type WidgetState = UnknownObject;
@@ -28,19 +30,24 @@ export declare class ToolResponseEvent extends CustomEvent<{
28
30
  }
29
31
  declare global {
30
32
  interface Window {
31
- openai: API<WidgetState> & OpenAiGlobals;
33
+ skybridge: SkybridgeProperties;
34
+ openai: OpenAiMethods<WidgetState> & OpenAiProperties;
32
35
  }
33
36
  interface WindowEventMap {
34
37
  [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent;
35
38
  }
36
39
  }
37
- export type OpenAiGlobals<ToolInput extends UnknownObject = {}, ToolOutput extends UnknownObject = UnknownObject, ToolResponseMetadata extends UnknownObject = UnknownObject, WidgetState extends UnknownObject = UnknownObject> = {
40
+ export type SkybridgeProperties = {
41
+ hostType: WidgetHostType;
42
+ };
43
+ export type OpenAiProperties<ToolInput extends UnknownObject = Record<never, unknown>, ToolOutput extends UnknownObject = UnknownObject, ToolResponseMetadata extends UnknownObject = UnknownObject, WidgetState extends UnknownObject = UnknownObject> = {
38
44
  theme: Theme;
39
45
  userAgent: UserAgent;
40
46
  locale: string;
41
47
  maxHeight: number;
42
48
  displayMode: DisplayMode;
43
49
  safeArea: SafeArea;
50
+ view: View;
44
51
  toolInput: ToolInput;
45
52
  toolOutput: ToolOutput | {
46
53
  text: string;
@@ -50,16 +57,23 @@ export type OpenAiGlobals<ToolInput extends UnknownObject = {}, ToolOutput exten
50
57
  };
51
58
  export type CallToolArgs = Record<string, unknown> | null;
52
59
  export type CallToolResponse = {
53
- content: {
54
- type: "text";
55
- text: string;
56
- }[];
60
+ content: CallToolResult["content"];
57
61
  structuredContent: Record<string, unknown>;
58
62
  isError: boolean;
59
63
  result: string;
60
64
  meta: Record<string, unknown>;
61
65
  };
62
- type API<WidgetState extends UnknownObject> = {
66
+ export type RequestModalOptions = {
67
+ title?: string;
68
+ params?: Record<string, unknown>;
69
+ anchor?: {
70
+ top?: number;
71
+ left?: number;
72
+ width?: number;
73
+ height?: number;
74
+ };
75
+ };
76
+ export type OpenAiMethods<WidgetState extends UnknownObject = UnknownObject> = {
63
77
  /** Calls a tool on your MCP. Returns the full response. */
64
78
  callTool: <ToolArgs extends CallToolArgs = null, ToolResponse extends CallToolResponse = CallToolResponse>(name: string, args: ToolArgs) => Promise<ToolResponse>;
65
79
  /** Triggers a followup turn in the ChatGPT conversation */
@@ -89,9 +103,7 @@ type API<WidgetState extends UnknownObject> = {
89
103
  * Opens a modal portaled outside of the widget iFrame.
90
104
  * This ensures the modal is correctly displayed and not limited to the widget's area.
91
105
  */
92
- requestModal: (args: {
93
- title: string;
94
- }) => Promise<void>;
106
+ requestModal: (args: RequestModalOptions) => Promise<void>;
95
107
  /** Uploads a new file to the host */
96
108
  uploadFile: (file: File) => Promise<FileMetadata>;
97
109
  /**
@@ -104,12 +116,16 @@ type API<WidgetState extends UnknownObject> = {
104
116
  };
105
117
  export declare const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
106
118
  export declare class SetGlobalsEvent extends CustomEvent<{
107
- globals: Partial<OpenAiGlobals>;
119
+ globals: Partial<OpenAiProperties>;
108
120
  }> {
109
121
  readonly type = "openai:set_globals";
110
122
  }
111
123
  export type CallTool = (name: string, args: Record<string, unknown>) => Promise<CallToolResponse>;
112
- export type DisplayMode = "pip" | "inline" | "fullscreen";
124
+ export type DisplayMode = "pip" | "inline" | "fullscreen" | "modal";
125
+ export type View = {
126
+ mode: DisplayMode;
127
+ params?: Record<string, unknown>;
128
+ };
113
129
  export type Theme = "light" | "dark";
114
130
  export type SafeAreaInsets = {
115
131
  top: number;
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/web/types.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,CAAC;AAuBf,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AAC/D,MAAM,OAAO,iBAAkB,SAAQ,WAErC;IACkB,IAAI,GAAG,wBAAwB,CAAC;CACnD;AA8FD,sDAAsD;AACtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAC3D,MAAM,OAAO,eAAgB,SAAQ,WAEnC;IACkB,IAAI,GAAG,sBAAsB,CAAC;CACjD"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/web/types.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,CAAC;AAyBf,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AAC/D,MAAM,OAAO,iBAAkB,SAAQ,WAErC;IACkB,IAAI,GAAG,wBAAwB,CAAC;CACnD;AAuGD,sDAAsD;AACtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAC3D,MAAM,OAAO,eAAgB,SAAQ,WAEnC;IACkB,IAAI,GAAG,sBAAsB,CAAC;CACjD"}
package/package.json CHANGED
@@ -1,7 +1,11 @@
1
1
  {
2
2
  "name": "skybridge",
3
- "version": "0.0.0-dev.ea7f5b5",
3
+ "version": "0.0.0-dev.eab2782",
4
4
  "description": "Skybridge is a framework for building ChatGPT apps",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "https://github.com/alpic-ai/skybridge.git"
8
+ },
5
9
  "type": "module",
6
10
  "files": [
7
11
  "dist"
@@ -16,16 +20,6 @@
16
20
  "default": "./dist/src/web/index.js"
17
21
  }
18
22
  },
19
- "scripts": {
20
- "build": "tsc && pnpm run build:templates",
21
- "build:templates": "cp -r src/server/templates dist/src/server/",
22
- "test": "pnpm run test:unit && pnpm run test:type",
23
- "test:unit": "vitest run",
24
- "test:type": "tsc --noEmit",
25
- "docs:dev": "pnpm --filter @skybridge/docs start",
26
- "docs:build": "pnpm --filter @skybridge/docs build",
27
- "docs:serve": "pnpm --filter @skybridge/docs serve"
28
- },
29
23
  "keywords": [
30
24
  "chatgpt",
31
25
  "app",
@@ -35,35 +29,46 @@
35
29
  "author": "Frédéric Barthelet",
36
30
  "license": "ISC",
37
31
  "peerDependencies": {
32
+ "@modelcontextprotocol/sdk": ">=1.0.0",
38
33
  "react": ">=18.0.0",
39
34
  "react-dom": ">=18.0.0"
40
35
  },
41
36
  "dependencies": {
42
37
  "@babel/core": "^7.28.5",
43
- "@modelcontextprotocol/sdk": "^1.20.0",
44
38
  "cors": "^2.8.5",
39
+ "dequal": "^2.0.3",
45
40
  "express": "^5.1.0",
46
41
  "handlebars": "^4.7.8",
47
42
  "superjson": "^2.2.6",
48
43
  "vite": "^7.1.11",
49
- "zod": "^3.25.51",
50
44
  "zustand": "^5.0.9"
51
45
  },
52
46
  "devDependencies": {
47
+ "@modelcontextprotocol/ext-apps": "^0.2.2",
48
+ "@modelcontextprotocol/sdk": "^1.24.3",
53
49
  "@testing-library/dom": "^10.4.1",
54
- "@testing-library/react": "^16.3.0",
50
+ "@testing-library/react": "^16.3.1",
55
51
  "@total-typescript/tsconfig": "^1.0.4",
56
52
  "@types/babel__core": "^7.20.5",
57
53
  "@types/cors": "^2.8.19",
58
54
  "@types/express": "^5.0.3",
59
- "@types/jsdom": "^21.1.6",
55
+ "@types/jsdom": "^21.1.7",
60
56
  "@types/node": "^22.15.30",
61
57
  "@types/react": "^19.2.2",
62
58
  "@types/react-dom": "^19.2.2",
63
59
  "@vitest/ui": "^2.1.8",
64
60
  "jsdom": "^25.0.1",
65
61
  "typescript": "^5.9.3",
66
- "vitest": "^2.1.8"
62
+ "vitest": "^2.1.8",
63
+ "zod": "^4.3.5"
67
64
  },
68
- "packageManager": "pnpm@10.17.1"
69
- }
65
+ "scripts": {
66
+ "build": "tsc && pnpm run build:templates",
67
+ "build:templates": "cp -r src/server/templates dist/src/server/",
68
+ "format": "biome check --write --error-on-warnings",
69
+ "test": "pnpm run test:unit && pnpm run test:type && pnpm run test:format",
70
+ "test:unit": "vitest run",
71
+ "test:type": "tsc --noEmit",
72
+ "test:format": "biome ci"
73
+ }
74
+ }
package/README.md DELETED
@@ -1,457 +0,0 @@
1
- <div align="center">
2
-
3
- # Skybridge
4
-
5
- **Skybridge is the TypeScript framework for building ChatGPT apps**
6
-
7
- [![By Alpic](https://img.shields.io/badge/Made%20by%20Alpic-f6ffed?logo=alpic)](https://alpic.ai)
8
-
9
- ![NPM Downloads](https://img.shields.io/npm/dm/skybridge?color=e90060)
10
- ![NPM Version](https://img.shields.io/npm/v/skybridge?color=e90060)
11
- ![GitHub License](https://img.shields.io/github/license/alpic-ai/skybridge?color=e90060)
12
-
13
- </div>
14
-
15
- Skybridge is a fullstack library. It comes with modular packages aiming at simplifying the development of ChatGPT apps:
16
-
17
- - HMR server for development and build pipeline for production including end-to-end (tools-to-widget) type safety
18
- - collection of React hooks for state management, async data fetching
19
- - attribute for widget-to-context synchronization
20
-
21
- ### <a href="https://skybridge.tech">Read the docs →</b></a>
22
-
23
- ## Get Involved
24
-
25
- We welcome issues and pull requests!</br>
26
- Participate in [GitHub discussions](https://github.com/alpic-ai/skybridge/discussions)</br>
27
- Chat with the community on [Discord](https://discord.com/invite/gNAazGueab)</br>
28
- See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions
29
-
30
- ## Installation
31
-
32
- ```bash
33
- pnpm add skybridge
34
- ```
35
-
36
- ## Concepts
37
-
38
- ### Widgets
39
-
40
- > A widget is a UI component that turns structured tool results into a human-friendly UI. Those are built using React components. They are rendered inside an iframe inline with the conversation on ChatGPT.
41
-
42
- Each widget in your app must have a unique name. The name is used to bridge the tool invocation result with the widget React component.
43
-
44
- For example, in order to register a new widget named `pokemon` on your ChatGPT app. You should have the following file structure and file contents:
45
-
46
- _Project structure_
47
-
48
- ```
49
- server/
50
- └── src/
51
- └── index.ts // Register the widget with McpServer.widget()
52
- web/
53
- └── src/
54
- └── widgets/
55
- └── pokemon.tsx // Use the same widget name as the file name
56
- ```
57
-
58
- _server/src/index.ts_
59
-
60
- ```ts
61
- import { McpServer } from "skybridge/server";
62
-
63
- const server = new McpServer();
64
-
65
- server.widget(
66
- "pokemon"
67
- // Remaining arguments...
68
- );
69
- ```
70
-
71
- _web/src/widgets/pokemon.tsx_
72
-
73
- ```ts
74
- import { mountWidget } from "skybridge/web";
75
-
76
- const Pokemon: React.FunctionComponent = () => {
77
- // Your React component code goes here...
78
- };
79
-
80
- mountWidget(<Pokemon />);
81
- ```
82
-
83
- ## Packages
84
-
85
- ### skybridge/server
86
-
87
- The `skybridge/server` package is a drop-in replacement of the `@modelcontextprotocol/sdk` official `McpServer` class with extra features for widget development. If you're already using the `@modelcontextprotocol/sdk`, you can simply replace your `McpServer` import with `skybridge/server` and you're good to go.
88
-
89
- ### skybridge/web
90
-
91
- The `skybridge/web` package is a react library with hooks and components to build widgets on the underlying _OpenAI iFrame skybridge_ runtime.
92
-
93
- **Vite plugin**
94
-
95
- The `skybridge/web` package comes with a Vite plugin that allows you to build your widgets as regular Vite apps.
96
-
97
- ```ts
98
- import { defineConfig } from "vite";
99
- import { skybridge } from "skybridge/web";
100
-
101
- export default defineConfig({
102
- plugins: [skybridge()],
103
- });
104
- ```
105
-
106
- **Typed Hooks**
107
-
108
- Skybridge provides fully typed hooks that give you autocomplete for tool names and type inference for inputs/outputs - similar to tRPC. This is opt-in and requires exporting your server type.
109
-
110
- > **Tip:** For the best TypeScript experience, use typed hooks throughout your application. They provide autocomplete, type safety, and better IDE support.
111
-
112
- > **Important:** For `generateHelpers` to work correctly, your MCP server must be defined using method chaining (e.g., `server.widget(...).widget(...).registerTool(...)`). This ensures TypeScript can properly infer the tool registry type from the chained calls.
113
-
114
- **Examples:**
115
-
116
- ✅ **Works** - Using method chaining:
117
-
118
- ```ts
119
- import { McpServer } from "skybridge/server";
120
- import { z } from "zod";
121
-
122
- const server = new McpServer({ name: "my-app", version: "1.0" }, {})
123
- .widget(
124
- "search-voyage",
125
- {},
126
- {
127
- inputSchema: { destination: z.string() },
128
- },
129
- async ({ destination }) => {
130
- return {
131
- content: [{ type: "text", text: `Found trips to ${destination}` }],
132
- };
133
- }
134
- )
135
- .registerTool(
136
- "calculate-price",
137
- {
138
- inputSchema: { tripId: z.string() },
139
- },
140
- async ({ tripId }) => {
141
- return { content: [{ type: "text", text: `Price for ${tripId}` }] };
142
- }
143
- );
144
-
145
- export type AppType = typeof server; // ✅ Type inference works correctly
146
- ```
147
-
148
- ❌ **Doesn't work** - Without method chaining:
149
-
150
- ```ts
151
- import { McpServer } from "skybridge/server";
152
- import { z } from "zod";
153
-
154
- const server = new McpServer({ name: "my-app", version: "1.0" }, {});
155
-
156
- server.widget(
157
- "search-voyage",
158
- {},
159
- {
160
- inputSchema: { destination: z.string() },
161
- },
162
- async ({ destination }) => {
163
- return {
164
- content: [{ type: "text", text: `Found trips to ${destination}` }],
165
- };
166
- }
167
- );
168
-
169
- server.registerTool(
170
- "calculate-price",
171
- {
172
- inputSchema: { tripId: z.string() },
173
- },
174
- async ({ tripId }) => {
175
- return { content: [{ type: "text", text: `Price for ${tripId}` }] };
176
- }
177
- );
178
-
179
- export type AppType = typeof server; // ❌ Type inference fails - tool registry is empty
180
- ```
181
-
182
- _Server setup (server/src/index.ts)_
183
-
184
- ```ts
185
- import { McpServer } from "skybridge/server";
186
- import { z } from "zod";
187
-
188
- const server = new McpServer({ name: "my-app", version: "1.0" }, {})
189
- .widget(
190
- "search-voyage",
191
- {},
192
- {
193
- description: "Search for trips",
194
- inputSchema: {
195
- destination: z.string(),
196
- departureDate: z.string().optional(),
197
- },
198
- outputSchema: {
199
- results: z.array(z.object({ id: z.string(), name: z.string() })),
200
- totalCount: z.number(),
201
- },
202
- },
203
- async ({ destination }) => {
204
- // Your tool logic here...
205
- return {
206
- content: [{ type: "text", text: `Found trips to ${destination}` }],
207
- };
208
- }
209
- )
210
- .widget(
211
- "get-details",
212
- {},
213
- {
214
- inputSchema: { tripId: z.string() },
215
- },
216
- async ({ tripId }) => {
217
- return { content: [{ type: "text", text: `Details for ${tripId}` }] };
218
- }
219
- );
220
-
221
- // Export the server type for the client
222
- export type AppType = typeof server;
223
- ```
224
-
225
- _One-time setup (web/src/skybridge.ts)_
226
-
227
- Create typed hooks once and export them for use across your app. This file acts as a bridge between your server types and your widgets:
228
-
229
- ```ts
230
- import type { AppType } from "../server"; // type-only import
231
- import { generateHelpers } from "skybridge/web";
232
-
233
- export const { useCallTool, useToolInfo } = generateHelpers<AppType>();
234
- ```
235
-
236
- _Usage in widgets (web/src/widgets/search.tsx)_
237
-
238
- ```tsx
239
- import { useCallTool, useToolInfo } from "../skybridge"; // import typed hooks
240
-
241
- export function SearchWidget() {
242
- const { callTool, data, isPending } = useCallTool("search-voyage");
243
- // ^ autocomplete for tool names
244
- const toolInfo = useToolInfo<"search-voyage">();
245
- // ^ autocomplete for widget names
246
-
247
- const handleSearch = () => {
248
- callTool({ destination: "Spain" });
249
- // ^ autocomplete for input fields
250
- };
251
-
252
- return (
253
- <div>
254
- <button onClick={handleSearch} disabled={isPending}>
255
- Search
256
- </button>
257
- {toolInfo.isSuccess && (
258
- <div>Found {toolInfo.output.structuredContent.totalCount} results</div>
259
- // ^ typed output
260
- )}
261
- </div>
262
- );
263
- }
264
- ```
265
-
266
- **Hooks**
267
-
268
- The `skybridge/web` package comes with a set of hooks to help you build your widgets :
269
-
270
- - `useOpenAiGlobal`: A generic hook to get any global data from the OpenAI iFrame skybridge runtime (in `window.openai`).
271
- - `useToolOutput`: A hook to get the initial tool `structuredContent` returned when rendering the widget for the first time. The data inside this hook is not updated when the tool is called again.
272
- - `useToolResponseMetadata`: A hook to get the initial tool `meta` returned when rendering the widget for the first time. The data inside this hook is not updated when the tool is called again.
273
- - `useToolInfo`: A hook to get the tool input, output, and response metadata with type inference. Provides a discriminated union based on status (pending/success).
274
- - `useCallTool`: A @tanstack/react-query inspired hook to send make additional tool calls inside a widget.
275
- - `generateHelpers`: A factory that creates typed versions of `useCallTool` and `useToolInfo` with full type inference from your server type.
276
-
277
- _useOpenAiGlobal_
278
-
279
- ```ts
280
- import { useOpenAiGlobal } from "skybridge/web";
281
-
282
- const theme = useOpenAiGlobal("theme");
283
- ```
284
-
285
- _useToolOutput_
286
-
287
- ```ts
288
- import { useToolOutput } from "skybridge/web";
289
-
290
- const toolOutput = useToolOutput();
291
- ```
292
-
293
- _useToolResponseMetadata_
294
-
295
- ```ts
296
- import { useToolResponseMetadata } from "skybridge/web";
297
-
298
- const toolResponseMetadata = useToolResponseMetadata();
299
- ```
300
-
301
- _useToolInfo_
302
-
303
- ```ts
304
- import { useToolInfo } from "skybridge/web";
305
-
306
- const toolInfo = useToolInfo<{
307
- input: { query: string };
308
- output: { results: string[] };
309
- responseMetadata: { id: number };
310
- }>();
311
-
312
- // toolInfo.input is typed based on the input type
313
- // toolInfo.output.structuredContent is typed based on the output type (undefined when pending)
314
- // toolInfo.status narrows correctly: "pending" | "success"
315
-
316
- if (toolInfo.isPending) {
317
- // toolInfo.output is undefined here (pending state)
318
- console.log(toolInfo.input.query);
319
- }
320
-
321
- if (toolInfo.isSuccess) {
322
- // toolInfo.output.structuredContent is typed here
323
- console.log(toolInfo.output.structuredContent.results);
324
- }
325
- ```
326
-
327
- _useToolInfo_ with typed hooks (recommended)
328
-
329
- ```tsx
330
- import { useToolInfo } from "../skybridge"; // import typed hooks
331
-
332
- export function SearchWidget() {
333
- const toolInfo = useToolInfo<"search-voyage">();
334
- // ^ autocomplete for widget names
335
- // toolInfo.input is typed as { destination: string; departureDate?: string; ... }
336
- // toolInfo.output.structuredContent is typed as { results: Array<...>; totalCount: number; }
337
-
338
- if (toolInfo.isSuccess) {
339
- return (
340
- <div>Found {toolInfo.output.structuredContent.totalCount} results</div>
341
- );
342
- }
343
-
344
- return <div>Searching for {toolInfo.input.destination}...</div>;
345
- }
346
- ```
347
-
348
- _useCallTool_ in synchronous mode
349
-
350
- ```ts
351
- import { useCallTool } from "skybridge/web";
352
-
353
- export const TestTool: React.FunctionComponent = () => {
354
- const { callTool, isPending } = useCallTool("myToolName");
355
-
356
- return (
357
- <div>
358
- <button
359
- disabled={isPending}
360
- onClick={() => {
361
- callTool({ input: "test input" }, {
362
- onSuccess: (data) => {
363
- alert("Tool returned: " + data);
364
- },
365
- });
366
- >
367
- Call Tool inside a widget
368
- </button>
369
- </div>
370
- );
371
- };
372
- ```
373
-
374
- _useCallTool_ in asynchronous mode
375
-
376
- ```ts
377
- import { useCallTool } from "skybridge/web";
378
-
379
- export const TestTool: React.FunctionComponent = () => {
380
- const { callToolAsync, isPending } = useCallTool("myToolName");
381
-
382
- return (
383
- <div>
384
- <button
385
- disabled={isPending}
386
- onClick={async () => {
387
- const data = await callToolAsync({ input: "test input" });
388
- alert("Tool returned: " + data);
389
- }}
390
- >
391
- Call Tool inside a widget
392
- </button>
393
- </div>
394
- );
395
- };
396
- ```
397
-
398
- **State Management**
399
-
400
- The `skybridge/web` package provides `createStore` for creating Zustand stores with automatic persistence to `window.openai.widgetState`. This is useful when you need more advanced state management than what `useWidgetState` provides.
401
-
402
- _createStore_
403
-
404
- ```ts
405
- import { createStore } from "skybridge/web";
406
-
407
- type CounterState = {
408
- count: number;
409
- increment: () => void;
410
- decrement: () => void;
411
- };
412
-
413
- const useCounterStore = createStore<CounterState>(
414
- (set) => ({
415
- count: 0,
416
- increment: () => set((state) => ({ count: state.count + 1 })),
417
- decrement: () => set((state) => ({ count: state.count - 1 })),
418
- }),
419
- { count: 0 } // Optional default state
420
- );
421
-
422
- // Use in your component
423
- function CounterWidget() {
424
- const { count, increment, decrement } = useCounterStore();
425
-
426
- return (
427
- <div>
428
- <p>Count: {count}</p>
429
- <button onClick={increment}>Increment</button>
430
- <button onClick={decrement}>Decrement</button>
431
- </div>
432
- );
433
- }
434
- ```
435
-
436
- The `createStore` function:
437
-
438
- - Automatically persists state to `window.openai.widgetState`
439
- - Syncs with external state changes from the host
440
- - Only serializes state data, not methods
441
-
442
- ## Migrate your existing MCP server to a ChatGPT app
443
-
444
- If you're already using the `@modelcontextprotocol/sdk` to build a MCP server, you can migrate to a ChatGPT app by following these steps:
445
-
446
- 1. Replace your `McpServer` import from `@modelcontextprotocol/sdk` with the same import from `skybridge/server`
447
- 2. Create a new vite project in a folder named `web` and install the `skybridge` package
448
- 3. Replace the `vite.config.ts` file with the following:
449
-
450
- ```ts
451
- import { defineConfig } from "vite";
452
- import { skybridge } from "skybridge/web";
453
-
454
- export default defineConfig({
455
- plugins: [skybridge()],
456
- });
457
- ```
@@ -1 +0,0 @@
1
- export declare function useLocale(): string;
@@ -1,5 +0,0 @@
1
- import { useOpenAiGlobal } from "./use-openai-global.js";
2
- export function useLocale() {
3
- return useOpenAiGlobal("locale");
4
- }
5
- //# sourceMappingURL=use-locale.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"use-locale.js","sourceRoot":"","sources":["../../../../src/web/hooks/use-locale.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,UAAU,SAAS;IACvB,OAAO,eAAe,CAAC,QAAQ,CAAE,CAAC;AACpC,CAAC"}
@@ -1,21 +0,0 @@
1
- import { useLocale } from "./use-locale.js";
2
- import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
3
- import { renderHook } from "@testing-library/react";
4
- describe("useLocale", () => {
5
- let OpenaiMock;
6
- beforeEach(() => {
7
- OpenaiMock = {
8
- locale: "en-US",
9
- };
10
- vi.stubGlobal("openai", OpenaiMock);
11
- });
12
- afterEach(() => {
13
- vi.unstubAllGlobals();
14
- vi.resetAllMocks();
15
- });
16
- it("should return the current locale from window.openai.locale", () => {
17
- const { result } = renderHook(() => useLocale());
18
- expect(result.current).toBe("en-US");
19
- });
20
- });
21
- //# sourceMappingURL=use-locale.test.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"use-locale.test.js","sourceRoot":"","sources":["../../../../src/web/hooks/use-locale.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,IAAI,UAEH,CAAC;IAEF,UAAU,CAAC,GAAG,EAAE;QACd,UAAU,GAAG;YACX,MAAM,EAAE,OAAO;SAChB,CAAC;QACF,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,gBAAgB,EAAE,CAAC;QACtB,EAAE,CAAC,aAAa,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;QACpE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;QAEjD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
@@ -1 +0,0 @@
1
- export declare function useTheme(): import("../types.js").Theme;