skybridge 0.0.0-dev.3b1b0b4 → 0.0.0-dev.4eb7532

package/README.md

@@ -27,6 +27,53 @@ To get started in less than a minute, you can [create a new repository](https://
 pnpm add skybridge
 ```
 
+## Concepts
+
+### Widgets
+
+> 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.
+
+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.
+
+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:
+
+_Project structure_
+
+```
+server/
+└── src/
+    └── index.ts // Register the widget with McpServer.widget()
+web/
+└── src/
+    └── widgets/
+        └── pokemon.tsx // Use the same widget name as the file name
+```
+
+_server/src/index.ts_
+
+```ts
+import { McpServer } from "skybridge/server";
+
+const server = new McpServer();
+
+server.widget(
+  "pokemon"
+  // Remaining arguments...
+);
+```
+
+_web/src/widgets/pokemon.tsx_
+
+```ts
+import { mountWidget } from "skybridge/web";
+
+const Pokemon: React.FunctionComponent = () => {
+  // Your React component code goes here...
+};
+
+mountWidget(<Pokemon />);
+```
+
 ## Packages
 
 ### skybridge/server
@@ -50,9 +97,30 @@ export default defineConfig({
 });
 ```
 
+**Hooks**
+
+The `skybridge/web` package comes with a set of hooks to help you build your widgets.
+
+```ts
+import { useToolOutput } from "skybridge/web";
+
+// Initial data returned by the tool invocation on structuredOutput
+const toolOutput = useToolOutput();
+```
+
 ## Migrate your existing MCP server to a ChatGPT app
 
 If you're already using the `@modelcontextprotocol/sdk` to build a MCP server, you can migrate to a ChatGPT app by following these steps:
 
 1. Replace your `McpServer` import from `@modelcontextprotocol/sdk` with the same import from `skybridge/server`
-2. Create a new node project named `web` and install the `skybridge` package
+2. Create a new vite project in a folder named `web` and install the `skybridge` package
+3. Replace the `vite.config.ts` file with the following:
+
+```ts
+import { defineConfig } from "vite";
+import { skybridge } from "skybridge/web";
+
+export default defineConfig({
+  plugins: [skybridge()],
+});
+```

package/dist/src/server/templates/development.hbs

@@ -0,0 +1,11 @@
+<script type="module">
+  import { injectIntoGlobalHook } from "{{serverUrl}}/@react-refresh";
+  injectIntoGlobalHook(window); window.$RefreshReg$ = () => {};
+  window.$RefreshSig$ = () => (type) => type;
+  window.__vite_plugin_react_preamble_installed__ = true;
+</script>
+<script type="module" src="{{serverUrl}}/@vite/client"></script>
+<div id="root"></div>
+<script type="module">
+  import('{{serverUrl}}/src/widgets/{{widgetName}}.tsx');
+</script>

package/dist/src/server/templates/production.hbs

@@ -0,0 +1,5 @@
+<div id="root"></div>
+<script type="module">
+  import('{{serverUrl}}/assets/{{widgetName}}.js');
+</script>
+<link rel="stylesheet" crossorigin href="{{serverUrl}}/assets/style.css" />

package/dist/src/web/index.d.ts

@@ -1,4 +1,6 @@
 export { useOpenAiGlobal } from "./use-openai-global.js";
 export { useToolOutput } from "./use-tool-output.js";
+export { useToolResponseMetadata } from "./use-tool-response-metadata.js";
 export * from "./types.js";
 export { mountWidget } from "./mount-widget.js";
+export { skybridge } from "./plugin.js";

package/dist/src/web/index.js

@@ -1,5 +1,7 @@
 export { useOpenAiGlobal } from "./use-openai-global.js";
 export { useToolOutput } from "./use-tool-output.js";
+export { useToolResponseMetadata } from "./use-tool-response-metadata.js";
 export * from "./types.js";
 export { mountWidget } from "./mount-widget.js";
+export { skybridge } from "./plugin.js";
 //# sourceMappingURL=index.js.map

package/dist/src/web/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/web/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/web/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/web/plugin.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function skybridge(): Plugin;

package/dist/src/web/plugin.js

@@ -0,0 +1,30 @@
+export function skybridge() {
+    return {
+        name: "skybridge",
+        async config(config) {
+            // Dynamic imports to ensure Node modules are only loaded in Node.js context
+            const { globSync } = await import("node:fs");
+            const { resolve } = await import("node:path");
+            const projectRoot = config.root || process.cwd();
+            const widgetsPattern = resolve(projectRoot, "src/widgets/*.{js,ts,jsx,tsx,html}");
+            const input = Object.fromEntries(globSync(widgetsPattern).map((file) => [
+                file.match(/src\/widgets\/(.+)\.tsx$/)?.[1],
+                file,
+            ]));
+            return {
+                build: {
+                    minify: true,
+                    cssCodeSplit: false,
+                    rollupOptions: {
+                        input,
+                        output: {
+                            entryFileNames: "[name].js",
+                            assetFileNames: "[name][extname]",
+                        },
+                    },
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/src/web/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../src/web/plugin.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,SAAS;IACvB,OAAO;QACL,IAAI,EAAE,WAAW;QAEjB,KAAK,CAAC,MAAM,CAAC,MAAM;YACjB,4EAA4E;YAC5E,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;YAC7C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;YAE9C,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YACjD,MAAM,cAAc,GAAG,OAAO,CAC5B,WAAW,EACX,oCAAoC,CACrC,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAC9B,QAAQ,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;gBACrC,IAAI,CAAC,KAAK,CAAC,0BAA0B,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC3C,IAAI;aACL,CAAC,CACH,CAAC;YAEF,OAAO;gBACL,KAAK,EAAE;oBACL,MAAM,EAAE,IAAI;oBACZ,YAAY,EAAE,KAAK;oBACnB,aAAa,EAAE;wBACb,KAAK;wBACL,MAAM,EAAE;4BACN,cAAc,EAAE,WAAW;4BAC3B,cAAc,EAAE,iBAAiB;yBAClC;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/web/types.d.ts

@@ -38,12 +38,20 @@ export type OpenAiGlobals<ToolInput extends UnknownObject = UnknownObject, ToolO
     toolResponseMetadata: ToolResponseMetadata | null;
     widgetState: WidgetState | null;
 };
+export type CallToolArgs = Record<string, unknown> | null;
 export type CallToolResponse = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+    isError: boolean;
     result: string;
+    meta: Record<string, unknown>;
 };
 type API<WidgetState extends UnknownObject> = {
     /** Calls a tool on your MCP. Returns the full response. */
-    callTool: (name: string, args: Record<string, unknown>) => Promise<CallToolResponse>;
+    callTool: <ToolArgs extends CallToolArgs = null, ToolResponse extends CallToolResponse = CallToolResponse>(name: string, args: ToolArgs) => Promise<ToolResponse>;
     /** Triggers a followup turn in the ChatGPT conversation */
     sendFollowUpMessage: (args: {
         prompt: string;

package/dist/src/web/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/web/types.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AAC/D,MAAM,OAAO,iBAAkB,SAAQ,WAErC;IACkB,IAAI,GAAG,wBAAwB,CAAC;CACnD;AA+DD,sDAAsD;AACtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAC3D,MAAM,OAAO,eAAgB,SAAQ,WAEnC;IACkB,IAAI,GAAG,sBAAsB,CAAC;CACjD"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/web/types.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AAC/D,MAAM,OAAO,iBAAkB,SAAQ,WAErC;IACkB,IAAI,GAAG,wBAAwB,CAAC;CACnD;AA2ED,sDAAsD;AACtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAC3D,MAAM,OAAO,eAAgB,SAAQ,WAEnC;IACkB,IAAI,GAAG,sBAAsB,CAAC;CACjD"}

package/dist/src/web/use-call-tool.d.ts

@@ -0,0 +1,39 @@
+import type { CallToolArgs, CallToolResponse } from "./types.js";
+export declare const useCallTool: <ToolArgs extends CallToolArgs = null, ToolResponse extends CallToolResponse = CallToolResponse>(name: string) => {
+    callTool: (toolArgs: ToolArgs) => void;
+    callToolAsync: (toolArgs: ToolArgs) => Promise<ToolResponse | undefined>;
+    status: "idle";
+    response: undefined;
+    isIdle: true;
+    isPending: false;
+    isSuccess: false;
+    isError: false;
+} | {
+    callTool: (toolArgs: ToolArgs) => void;
+    callToolAsync: (toolArgs: ToolArgs) => Promise<ToolResponse | undefined>;
+    status: "pending";
+    response: undefined;
+    isIdle: false;
+    isPending: true;
+    isSuccess: false;
+    isError: false;
+} | {
+    callTool: (toolArgs: ToolArgs) => void;
+    callToolAsync: (toolArgs: ToolArgs) => Promise<ToolResponse | undefined>;
+    status: "error";
+    error: unknown;
+    response: undefined;
+    isIdle: false;
+    isPending: false;
+    isSuccess: false;
+    isError: true;
+} | {
+    callTool: (toolArgs: ToolArgs) => void;
+    callToolAsync: (toolArgs: ToolArgs) => Promise<ToolResponse | undefined>;
+    status: "success";
+    response: ToolResponse;
+    isIdle: false;
+    isPending: false;
+    isSuccess: true;
+    isError: false;
+};

package/dist/src/web/use-call-tool.js

@@ -0,0 +1,53 @@
+import { useState } from "react";
+export const useCallTool = (name) => {
+    const [callToolState, setCallToolState] = useState({
+        status: "idle",
+        response: undefined,
+        isIdle: true,
+        isPending: false,
+        isSuccess: false,
+        isError: false,
+    });
+    const callToolAsync = async (toolArgs) => {
+        setCallToolState({
+            status: "pending",
+            response: undefined,
+            isIdle: false,
+            isPending: true,
+            isSuccess: false,
+            isError: false,
+        });
+        try {
+            const response = await window.openai.callTool(name, toolArgs);
+            setCallToolState({
+                status: "success",
+                response,
+                isIdle: false,
+                isPending: false,
+                isSuccess: true,
+                isError: false,
+            });
+            return response;
+        }
+        catch (error) {
+            setCallToolState({
+                status: "error",
+                response: undefined,
+                error,
+                isIdle: false,
+                isPending: false,
+                isSuccess: false,
+                isError: true,
+            });
+        }
+    };
+    const callTool = (toolArgs) => {
+        void callToolAsync(toolArgs);
+    };
+    return {
+        ...callToolState,
+        callTool,
+        callToolAsync,
+    };
+};
+//# sourceMappingURL=use-call-tool.js.map

package/dist/src/web/use-call-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-call-tool.js","sourceRoot":"","sources":["../../../src/web/use-call-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AA4CjC,MAAM,CAAC,MAAM,WAAW,GAAG,CAIzB,IAAY,EACZ,EAAE;IACF,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAEhD;QACA,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,SAAS;QACnB,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,KAAK;QAChB,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,KAAK;KACf,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,KAAK,EAAE,QAAkB,EAAE,EAAE;QACjD,gBAAgB,CAAC;YACf,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,SAAS;YACnB,MAAM,EAAE,KAAK;YACb,SAAS,EAAE,IAAI;YACf,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,KAAK;SACf,CAAC,CAAC;QACH,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,CAC3C,IAAI,EACJ,QAAQ,CACT,CAAC;YACF,gBAAgB,CAAC;gBACf,MAAM,EAAE,SAAS;gBACjB,QAAQ;gBACR,MAAM,EAAE,KAAK;gBACb,SAAS,EAAE,KAAK;gBAChB,SAAS,EAAE,IAAI;gBACf,OAAO,EAAE,KAAK;aACf,CAAC,CAAC;YAEH,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,gBAAgB,CAAC;gBACf,MAAM,EAAE,OAAO;gBACf,QAAQ,EAAE,SAAS;gBACnB,KAAK;gBACL,MAAM,EAAE,KAAK;gBACb,SAAS,EAAE,KAAK;gBAChB,SAAS,EAAE,KAAK;gBAChB,OAAO,EAAE,IAAI;aACd,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,QAAkB,EAAE,EAAE;QACtC,KAAK,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC,CAAC;IAEF,OAAO;QACL,GAAG,aAAa;QAChB,QAAQ;QACR,aAAa;KACd,CAAC;AACJ,CAAC,CAAC"}

package/dist/src/web/use-tool-response-metadata.d.ts

@@ -0,0 +1,3 @@
+export declare function useToolResponseMetadata(): {
+    [x: string]: unknown;
+} | null | undefined;

package/dist/src/web/use-tool-response-metadata.js

@@ -0,0 +1,5 @@
+import { useOpenAiGlobal } from "./use-openai-global.js";
+export function useToolResponseMetadata() {
+    return useOpenAiGlobal("toolResponseMetadata");
+}
+//# sourceMappingURL=use-tool-response-metadata.js.map

package/dist/src/web/use-tool-response-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tool-response-metadata.js","sourceRoot":"","sources":["../../../src/web/use-tool-response-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,UAAU,uBAAuB;IACrC,OAAO,eAAe,CAAC,sBAAsB,CAAC,CAAC;AACjD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skybridge",
-  "version": "0.0.0-dev.3b1b0b4",
+  "version": "0.0.0-dev.4eb7532",
   "description": "Skybridge is a framework for building ChatGPT apps",
   "type": "module",
   "files": [
@@ -17,7 +17,8 @@
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && pnpm run build:templates",
+    "build:templates": "cp -r src/server/templates dist/src/server/",
     "test": "vitest run --silent"
   },
   "keywords": [
@@ -44,10 +45,10 @@
     "@total-typescript/tsconfig": "^1.0.4",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
+    "@types/jsdom": "^21.1.6",
     "@types/node": "^22.15.30",
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
-    "@types/jsdom": "^21.1.6",
     "@vitest/ui": "^2.1.8",
     "jsdom": "^25.0.1",
     "typescript": "^5.9.3",