skybridge 0.0.0-dev.bef3542 → 0.0.0-dev.befb8f5

package/README.md

@@ -1,198 +1,125 @@
 <div align="center">
 
-# Skybridge
-
-**Skybridge is the TypeScript framework for building ChatGPT apps**
-
-[![By Alpic](https://img.shields.io/badge/Made%20by%20Alpic-f6ffed?logo=alpic)](https://alpic.ai)
+<img alt="Skybridge" src="docs/static/img/github-banner.png" width="100%">
 
-![NPM Downloads](https://img.shields.io/npm/dm/skybridge?color=e90060)
-![NPM Version](https://img.shields.io/npm/v/skybridge?color=e90060)
-![GitHub License](https://img.shields.io/github/license/alpic-ai/skybridge?color=e90060)
+<br />
 
-</div>
-
-Skybridge comes with 2 packages:
+# Skybridge
 
-- `skybridge/server`: A drop-in replacement of the `@modelcontextprotocol/sdk` official `McpServer` class with extra features for widget development.
-- `skybridge/web`: A react library with hooks and components to build widgets on the underlying _OpenAI iFrame skybridge_ runtime.
+**Build ChatGPT Apps. The Modern TypeScript Way.**
 
-## Quick start
+The fullstack TypeScript framework for ChatGPT Apps.<br />
+**Type-safe. React-powered. Zero config.**
 
-To get started in less than a minute, you can [create a new repository](https://github.com/new?template_name=apps-sdk-template&template_owner=alpic-ai) using our [ChatGPT SDK template](https://github.com/alpic-ai/apps-sdk-template). This template includes a basic setup for both the server and the widgets.
+<br />
 
-## Installation
+[![NPM Version](https://img.shields.io/npm/v/skybridge?color=e90060&style=for-the-badge)](https://www.npmjs.com/package/skybridge)
+[![NPM Downloads](https://img.shields.io/npm/dm/skybridge?color=e90060&style=for-the-badge)](https://www.npmjs.com/package/skybridge)
+[![GitHub License](https://img.shields.io/github/license/alpic-ai/skybridge?color=e90060&style=for-the-badge)](https://github.com/alpic-ai/skybridge/blob/main/LICENSE)
 
-```bash
-pnpm add skybridge
-```
+<br />
 
-## Concepts
+[Documentation](https://skybridge.tech) · [Quick Start](https://github.com/new?template_name=apps-sdk-template&template_owner=alpic-ai) · [Examples](https://github.com/alpic-ai/apps-sdk-template)
 
-### Widgets
+</div>
 
-> 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.
+<br />
 
-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.
+## ✨ Why Skybridge?
 
-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:
+ChatGPT Apps let you embed **rich, interactive UIs** directly in conversations. But the raw SDK is low-level—no hooks, no type safety, no dev tools, and no HMR.
 
-_Project structure_
+**Skybridge fixes that.**
 
-```
-server/
-└── src/
-    └── index.ts // Register the widget with McpServer.widget()
-web/
-└── src/
-    └── widgets/
-        └── pokemon.tsx // Use the same widget name as the file name
-```
+| | |
+|:--|:--|
+| 👨‍💻 **Full Dev Environment** — HMR, debug traces, and local devtools. No more refresh loops. | ✅ **End-to-End Type Safety** — tRPC-style inference from server to widget. Autocomplete everywhere. |
+| 🔄 **Widget-to-Model Sync** — Keep the model aware of UI state with `data-llm`. Dual surfaces, one source of truth. | ⚒️ **React Query-style Hooks** — `isPending`, `isError`, callbacks. State management you already know. |
 
-_server/src/index.ts_
+<br />
 
-```ts
-import { McpServer } from "skybridge/server";
+## 🚀 Get Started
 
-const server = new McpServer();
+**Create a new ChatGPT app:**
 
-server.widget(
-  "pokemon"
-  // Remaining arguments...
-);
+```bash
+gh repo create my-app --template alpic-ai/apps-sdk-template --clone
+cd my-app && pnpm install
 ```
 
-_web/src/widgets/pokemon.tsx_
-
-```ts
-import { mountWidget } from "skybridge/web";
-
-const Pokemon: React.FunctionComponent = () => {
-  // Your React component code goes here...
-};
+**Or add to an existing project:**
 
-mountWidget(<Pokemon />);
+```bash
+npm i skybridge
+yarn add skybridge
+pnpm add skybridge
+bun add skybridge
+deno add skybridge
 ```
 
-## Packages
+<div align="center">
 
-### skybridge/server
+**👉 [Read the Docs](https://skybridge.tech) 👈**
 
-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.
+</div>
 
-### skybridge/web
+<br />
 
-The `skybridge/web` package is a react library with hooks and components to build widgets on the underlying _OpenAI iFrame skybridge_ runtime.
+## 📦 The Stack
 
-**Vite plugin**
+- **`skybridge/server`** — Drop-in MCP SDK replacement with widget registration and type inference.
+- **`skybridge/web`** — React hooks and components for ChatGPT's runtime.
 
-The `skybridge/web` package comes with a Vite plugin that allows you to build your widgets as regular Vite apps.
+### Server
 
 ```ts
-import { defineConfig } from "vite";
-import { skybridge } from "skybridge/web";
+import { McpServer } from "skybridge/server";
 
-export default defineConfig({
-  plugins: [skybridge()],
+server.registerWidget("flights", {}, {
+  inputSchema: { destination: z.string() },
+}, async ({ destination }) => {
+  const flights = await searchFlights(destination);
+  return { structuredContent: { flights } };
 });
 ```
 
-**Hooks**
-
-The `skybridge/web` package comes with a set of hooks to help you build your widgets :
+### Widget
 
-- `useOpenAiGlobal`: A generic hook to get any global data from the OpenAI iFrame skybridge runtime (in `window.openai`).
-- `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.
-- `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.
-- `useCallTool`: A @tanstack/react-query inspired hook to send make additional tool calls inside a widget.
+```tsx
+import { useToolInfo } from "skybridge/web";
 
-_useOpenAiGlobal_
+function FlightsWidget() {
+  const { output } = useToolInfo();
 
-```ts
-import { useOpenAiGlobal } from "skybridge/web";
-
-const theme = useOpenAiGlobal("theme");
-```
-
-_useToolOutput_
-
-```ts
-import { useToolOutput } from "skybridge/web";
-
-const toolOutput = useToolOutput();
+  return output.structuredContent.flights.map(f =>
+    <FlightCard key={f.id} flight={f} />
+  );
+}
 ```
 
-_useToolResponseMetadata_
+<br />
 
-```ts
-import { useToolResponseMetadata } from "skybridge/web";
+## 🎯 Features at a Glance
 
-const toolResponseMetadata = useToolResponseMetadata();
-```
+- **Live Reload** — Vite HMR. See changes instantly without reinstalling.
+- **Typed Hooks** — Full autocomplete for tools, inputs, outputs.
+- **Widget → Tool Calls** — Trigger server actions from UI.
+- **Dual Surface Sync** — Keep model aware of what users see with `data-llm`.
+- **React Query-style API** — `isPending`, `isError`, callbacks.
+- **MCP Compatible** — Extends the official SDK. Works with any MCP client.
 
-_useCallTool_ in synchronous mode
+<br />
 
-```ts
-import { useCallTool } from "skybridge/web";
-
-export const TestTool: React.FunctionComponent = () => {
-  const { callTool, isPending } = useCallTool("myToolName");
-
-  return (
-    <div>
-      <button
-        disabled={isPending}
-        onClick={() => {
-          callTool({ input: "test input" }, {
-            onSuccess: (data) => {
-              alert("Tool returned: " + data);
-            },
-          });
-      >
-        Call Tool inside a widget
-      </button>
-    </div>
-  );
-};
-```
-
-_useCallTool_ in asynchronous mode
-
-```ts
-import { useCallTool } from "skybridge/web";
-
-export const TestTool: React.FunctionComponent = () => {
-  const { callToolAsync, isPending } = useCallTool("myToolName");
-
-  return (
-    <div>
-      <button
-        disabled={isPending}
-        onClick={async () => {
-          const data = await callToolAsync({ input: "test input" });
-          alert("Tool returned: " + data);
-        }}
-      >
-        Call Tool inside a widget
-      </button>
-    </div>
-  );
-};
-```
+<div align="center">
 
-## Migrate your existing MCP server to a ChatGPT app
+[![GitHub Discussions](https://img.shields.io/badge/Discussions-Ask%20Questions-blue?style=flat-square&logo=github)](https://github.com/alpic-ai/skybridge/discussions)
+[![GitHub Issues](https://img.shields.io/badge/Issues-Report%20Bugs-red?style=flat-square&logo=github)](https://github.com/alpic-ai/skybridge/issues)
+[![Discord](https://img.shields.io/badge/Discord-Chat-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.com/invite/gNAazGueab)
 
-If you're already using the `@modelcontextprotocol/sdk` to build a MCP server, you can migrate to a ChatGPT app by following these steps:
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions
 
-1. Replace your `McpServer` import from `@modelcontextprotocol/sdk` with the same import from `skybridge/server`
-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:
+<br />
 
-```ts
-import { defineConfig } from "vite";
-import { skybridge } from "skybridge/web";
+**[MIT License](LICENSE)** · Made with ❤️ by **[Alpic](https://alpic.ai)**
 
-export default defineConfig({
-  plugins: [skybridge()],
-});
-```
+</div>

package/dist/src/server/devtoolsStaticServer.d.ts

@@ -0,0 +1,15 @@
+import { type RequestHandler } from "express";
+/**
+ * Serve the built devtools React app
+ * This router serves static files from the devtools's dist directory.
+ * It should be installed at the application root, like so:
+ *
+ *  const app = express();
+ *
+ * if (env.NODE_ENV !== "production") {
+ *   app.use(await devtoolsStaticServer(server));
+ *   app.use(await widgetsDevServer());
+ *                     ^^^^^^^^ Make sure to install the devtoolsStaticServer before the widgetsDevServer
+ * }
+ */
+export declare const devtoolsStaticServer: () => Promise<RequestHandler>;

package/dist/src/server/devtoolsStaticServer.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import cors from "cors";
+import express, {} from "express";
+/**
+ * Serve the built devtools React app
+ * This router serves static files from the devtools's dist directory.
+ * It should be installed at the application root, like so:
+ *
+ *  const app = express();
+ *
+ * if (env.NODE_ENV !== "production") {
+ *   app.use(await devtoolsStaticServer(server));
+ *   app.use(await widgetsDevServer());
+ *                     ^^^^^^^^ Make sure to install the devtoolsStaticServer before the widgetsDevServer
+ * }
+ */
+export const devtoolsStaticServer = async () => {
+    const router = express.Router();
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const devtoolsPath = path.join(currentDir, "..", "devtools");
+    router.use(cors());
+    router.use(express.static(devtoolsPath));
+    router.get("/", (_req, res, next) => {
+        const indexHtmlPath = path.join(devtoolsPath, "index.html");
+        try {
+            const indexHtml = readFileSync(indexHtmlPath, "utf-8");
+            res.setHeader("Content-Type", "text/html");
+            res.send(indexHtml);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    return router;
+};
+//# sourceMappingURL=devtoolsStaticServer.js.map

package/dist/src/server/devtoolsStaticServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtoolsStaticServer.js","sourceRoot":"","sources":["../../../src/server/devtoolsStaticServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,OAAO,EAAE,EAAuB,MAAM,SAAS,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,IAA6B,EAAE;IACtE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAChC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAE7D,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAEnB,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAEzC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAClC,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAC5D,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;YACvD,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;YAC3C,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,CAAC;QACd,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

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

@@ -1,2 +1,5 @@
+export { devtoolsStaticServer } from "./devtoolsStaticServer.js";
+export type { AnyToolRegistry, InferTools, ToolInput, ToolNames, ToolOutput, ToolResponseMetadata, } from "./inferUtilityTypes.js";
+export type { McpServerTypes, ToolDef } from "./server.js";
 export { McpServer } from "./server.js";
 export { widgetsDevServer } from "./widgetsDevServer.js";

package/dist/src/server/index.js

@@ -1,3 +1,4 @@
+export { devtoolsStaticServer } from "./devtoolsStaticServer.js";
 export { McpServer } from "./server.js";
 export { widgetsDevServer } from "./widgetsDevServer.js";
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAUjE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/src/server/inferUtilityTypes.d.ts

@@ -0,0 +1,64 @@
+import type { McpServerTypes, ToolDef } from "./server.js";
+/**
+ * Any tool registry shape (includes both widgets and regular tools).
+ * Used as a constraint for type parameters that accept tool registries.
+ */
+export type AnyToolRegistry = Record<string, ToolDef>;
+/**
+ * Extract the tool registry type from an McpServer instance.
+ * This includes both widgets (registered via widget()) and regular tools (registered via registerTool()).
+ *
+ * Uses the `$types` property pattern for cross-package type inference.
+ * This works across package boundaries because TypeScript uses structural typing
+ * on the shape of `$types`, rather than nominal typing on the McpServer class itself.
+ *
+ * @example
+ * ```ts
+ * type MyTools = InferTools<MyServer>;
+ * // { "search": ToolDef<...>, "calculate": ToolDef<...> }
+ * ```
+ */
+export type InferTools<ServerType> = ServerType extends {
+    $types: McpServerTypes<infer W>;
+} ? W : never;
+type ExtractTool<ServerType, K extends ToolNames<ServerType>> = InferTools<ServerType>[K];
+/**
+ * Get a union of all tool names from an McpServer instance.
+ * This includes both widgets and regular tools.
+ *
+ * @example
+ * ```ts
+ * type Names = ToolNames<MyServer>;
+ * // "search" | "calculate" | "details"
+ * ```
+ */
+export type ToolNames<ServerType> = keyof InferTools<ServerType> & string;
+/**
+ * Get the input type for a specific tool (widget or regular tool).
+ *
+ * @example
+ * ```ts
+ * type SearchInput = ToolInput<MyServer, "search">;
+ * ```
+ */
+export type ToolInput<ServerType, ToolName extends ToolNames<ServerType>> = ExtractTool<ServerType, ToolName>["input"];
+/**
+ * Get the output type for a specific tool (widget or regular tool).
+ *
+ * @example
+ * ```ts
+ * type SearchOutput = ToolOutput<MyServer, "search">;
+ * ```
+ */
+export type ToolOutput<ServerType, ToolName extends ToolNames<ServerType>> = ExtractTool<ServerType, ToolName>["output"];
+/**
+ * Get the responseMetadata type for a specific tool (widget or regular tool).
+ * This is inferred from the `_meta` property of the tool callback's return value.
+ *
+ * @example
+ * ```ts
+ * type SearchMeta = ToolResponseMetadata<MyServer, "search">;
+ * ```
+ */
+export type ToolResponseMetadata<ServerType, ToolName extends ToolNames<ServerType>> = ExtractTool<ServerType, ToolName>["responseMetadata"];
+export {};

package/dist/src/server/inferUtilityTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=inferUtilityTypes.js.map

package/dist/src/server/inferUtilityTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inferUtilityTypes.js","sourceRoot":"","sources":["../../../src/server/inferUtilityTypes.ts"],"names":[],"mappings":""}

package/dist/src/server/server.d.ts

@@ -1,13 +1,65 @@
-import { McpServer as McpServerBase, type ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { Resource } from "@modelcontextprotocol/sdk/types.js";
-import type { ZodRawShape } from "zod";
+import { McpServer as McpServerBase, type RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AnySchema, SchemaOutput, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type { CallToolResult, Resource, ServerNotification, ServerRequest, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+export type ToolDef<TInput = unknown, TOutput = unknown, TResponseMetadata = unknown> = {
+    input: TInput;
+    output: TOutput;
+    responseMetadata: TResponseMetadata;
+};
 type McpServerOriginalResourceConfig = Omit<Resource, "uri" | "name" | "mimeType">;
-type McpServerOriginalToolConfig = Omit<Parameters<McpServer["registerTool"]>[1], "inputSchema" | "outputSchema">;
-export declare class McpServer extends McpServerBase {
-    widget<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape>(name: string, resourceConfig: McpServerOriginalResourceConfig, toolConfig: McpServerOriginalToolConfig & {
-        inputSchema?: InputArgs;
-        outputSchema?: OutputArgs;
-    }, toolCallback: ToolCallback<InputArgs>): void;
+type McpServerOriginalToolConfig = Omit<Parameters<typeof McpServerBase.prototype.registerTool<ZodRawShapeCompat, ZodRawShapeCompat>>[1], "inputSchema" | "outputSchema">;
+type ExtractStructuredContent<T> = T extends {
+    structuredContent: infer SC;
+} ? SC : never;
+type ExtractMeta<T> = Extract<T, {
+    _meta: unknown;
+}> extends {
+    _meta: infer M;
+} ? M : unknown;
+/**
+ * Type-level marker interface for cross-package type inference.
+ * This enables TypeScript to infer tool types across package boundaries
+ * using structural typing on the $types property, rather than relying on
+ * class generic inference which fails when McpServer comes from different
+ * package installations.
+ *
+ * Inspired by tRPC's _def pattern and Hono's type markers.
+ */
+export interface McpServerTypes<TTools extends Record<string, ToolDef>> {
+    readonly tools: TTools;
+}
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+};
+type ShapeOutput<Shape extends ZodRawShapeCompat> = Simplify<{
+    [K in keyof Shape as undefined extends SchemaOutput<Shape[K]> ? never : K]: SchemaOutput<Shape[K]>;
+} & {
+    [K in keyof Shape as undefined extends SchemaOutput<Shape[K]> ? K : never]?: SchemaOutput<Shape[K]>;
+}>;
+type AddTool<TTools, TName extends string, TInput extends ZodRawShapeCompat, TOutput, TResponseMetadata = unknown> = McpServer<TTools & {
+    [K in TName]: ToolDef<ShapeOutput<TInput>, TOutput, TResponseMetadata>;
+}>;
+type ToolConfig<TInput extends ZodRawShapeCompat | AnySchema> = {
+    title?: string;
+    description?: string;
+    inputSchema?: TInput;
+    outputSchema?: ZodRawShapeCompat | AnySchema;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+};
+type ToolHandler<TInput extends ZodRawShapeCompat, TReturn extends CallToolResult = CallToolResult> = (args: ShapeOutput<TInput>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => TReturn | Promise<TReturn>;
+export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>> extends McpServerBase {
+    readonly $types: McpServerTypes<TTools>;
+    registerWidget<TName extends string, TInput extends ZodRawShapeCompat, TReturn extends CallToolResult>(name: TName, resourceConfig: McpServerOriginalResourceConfig, toolConfig: McpServerOriginalToolConfig & {
+        inputSchema?: TInput;
+        outputSchema?: ZodRawShapeCompat | AnySchema;
+    }, toolCallback: ToolHandler<TInput, TReturn>): AddTool<TTools, TName, TInput, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>>;
+    registerTool<TName extends string, InputArgs extends ZodRawShapeCompat, TReturn extends CallToolResult>(name: TName, config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs, TReturn>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>>;
+    registerTool<InputArgs extends ZodRawShapeCompat>(name: string, config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs>): RegisteredTool;
+    private registerWidgetResource;
     private lookupDistFile;
+    private lookupDistFileWithIndexFallback;
+    private readManifest;
 }
 export {};

package/dist/src/server/server.js

@@ -1,57 +1,73 @@
-import { McpServer as McpServerBase, } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { templateHelper } from "./templateHelper.js";
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { McpServer as McpServerBase, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { templateHelper } from "./templateHelper.js";
 export class McpServer extends McpServerBase {
-    widget(name, resourceConfig, toolConfig, toolCallback) {
-        const uri = `ui://widgets/${name}.html`;
+    registerWidget(name, resourceConfig, toolConfig, toolCallback) {
         const resourceMetadata = {
             ...(resourceConfig._meta ?? {}),
         };
         if (toolConfig.description !== undefined) {
             resourceMetadata["openai/widgetDescription"] = toolConfig.description;
         }
-        this.resource(name, uri, {
-            ...resourceConfig,
-            _meta: resourceMetadata,
-        }, async (_uri, extra) => {
-            const serverUrl = process.env.NODE_ENV === "production"
-                ? `https://${extra?.requestInfo?.headers?.["x-forwarded-host"] ??
-                    extra?.requestInfo?.headers?.host}`
-                : `http://localhost:3000`;
-            const html = process.env.NODE_ENV === "production"
-                ? templateHelper.renderProduction({
-                    serverUrl,
-                    widgetFile: this.lookupDistFile(`src/widgets/${name}.tsx`),
-                    styleFile: this.lookupDistFile("style.css"),
-                })
-                : templateHelper.renderDevelopment({
-                    serverUrl,
-                    widgetName: name,
-                });
-            return {
-                contents: [
-                    {
-                        uri,
-                        mimeType: "text/html+skybridge",
-                        text: html,
-                    },
-                ],
-            };
+        const appsSdkUri = `ui://widgets/apps-sdk/${name}.html`;
+        this.registerWidgetResource({
+            name,
+            uri: appsSdkUri,
+            mimeType: "text/html+skybridge",
+            resourceConfig,
+            resourceMetadata,
+        });
+        const extAppsUri = `ui://widgets/ext-apps/${name}.html`;
+        this.registerWidgetResource({
+            name,
+            uri: extAppsUri,
+            mimeType: "text/html;profile=mcp-app",
+            resourceConfig,
+            resourceMetadata,
         });
         const toolMeta = {
             ...toolConfig._meta,
-            "openai/outputTemplate": uri,
-            "ui/resourceUri": uri,
+            "openai/outputTemplate": appsSdkUri,
+            "ui/resourceUri": extAppsUri,
         };
         this.registerTool(name, {
             ...toolConfig,
             _meta: toolMeta,
         }, toolCallback);
+        return this;
+    }
+    registerTool(name, config, cb) {
+        super.registerTool(name, config, cb);
+        return this;
+    }
+    registerWidgetResource({ name, uri, mimeType, resourceConfig, resourceMetadata, }) {
+        this.registerResource(name, uri, { ...resourceConfig, _meta: resourceMetadata }, async (_uri, extra) => {
+            const serverUrl = process.env.NODE_ENV === "production"
+                ? `https://${extra?.requestInfo?.headers?.["x-forwarded-host"] ?? extra?.requestInfo?.headers?.host}`
+                : `http://localhost:3000`;
+            const html = process.env.NODE_ENV === "production"
+                ? templateHelper.renderProduction({
+                    serverUrl,
+                    widgetFile: this.lookupDistFileWithIndexFallback(`src/widgets/${name}.tsx`),
+                    styleFile: this.lookupDistFile("style.css"),
+                })
+                : templateHelper.renderDevelopment({ serverUrl, widgetName: name });
+            return { contents: [{ uri, mimeType, text: html }] };
+        });
     }
     lookupDistFile(key) {
-        const manifest = JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
+        const manifest = this.readManifest();
         return manifest[key]?.file;
     }
+    lookupDistFileWithIndexFallback(basePath) {
+        const manifest = this.readManifest();
+        const flatFileKey = `${basePath}.tsx`;
+        const indexFileKey = `${basePath}/index.tsx`;
+        return manifest[flatFileKey]?.file ?? manifest[indexFileKey]?.file;
+    }
+    readManifest() {
+        return JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
+    }
 }
 //# sourceMappingURL=server.js.map

package/dist/src/server/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/server/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,IAAI,aAAa,GAE3B,MAAM,yCAAyC,CAAC;AAGjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AA+C7B,MAAM,OAAO,SAAU,SAAQ,aAAa;IAC1C,MAAM,CACJ,IAAY,EACZ,cAA+C,EAC/C,UAGC,EACD,YAAqC;QAErC,MAAM,GAAG,GAAG,gBAAgB,IAAI,OAAO,CAAC;QACxC,MAAM,gBAAgB,GAAiB;YACrC,GAAG,CAAC,cAAc,CAAC,KAAK,IAAI,EAAE,CAAC;SAChC,CAAC;QACF,IAAI,UAAU,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACzC,gBAAgB,CAAC,0BAA0B,CAAC,GAAG,UAAU,CAAC,WAAW,CAAC;QACxE,CAAC;QAED,IAAI,CAAC,QAAQ,CACX,IAAI,EACJ,GAAG,EACH;YACE,GAAG,cAAc;YACjB,KAAK,EAAE,gBAAgB;SACxB,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;YACpB,MAAM,SAAS,GACb,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;gBACnC,CAAC,CAAC,WACE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,kBAAkB,CAAC;oBACjD,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,IAC/B,EAAE;gBACJ,CAAC,CAAC,uBAAuB,CAAC;YAE9B,MAAM,IAAI,GACR,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;gBACnC,CAAC,CAAC,cAAc,CAAC,gBAAgB,CAAC;oBAC9B,SAAS;oBACT,UAAU,EAAE,IAAI,CAAC,cAAc,CAAC,eAAe,IAAI,MAAM,CAAC;oBAC1D,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC;iBAC5C,CAAC;gBACJ,CAAC,CAAC,cAAc,CAAC,iBAAiB,CAAC;oBAC/B,SAAS;oBACT,UAAU,EAAE,IAAI;iBACjB,CAAC,CAAC;YAET,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG;wBACH,QAAQ,EAAE,qBAAqB;wBAC/B,IAAI,EAAE,IAAI;qBACX;iBACF;aACF,CAAC;QACJ,CAAC,CACF,CAAC;QAEF,MAAM,QAAQ,GAAa;YACzB,GAAG,UAAU,CAAC,KAAK;YACnB,uBAAuB,EAAE,GAAG;YAC5B,gBAAgB,EAAE,GAAG;SACtB,CAAC;QAEF,IAAI,CAAC,YAAY,CACf,IAAI,EACJ;YACE,GAAG,UAAU;YACb,KAAK,EAAE,QAAQ;SAChB,EACD,YAAY,CACb,CAAC;IACJ,CAAC;IAEO,cAAc,CAAC,GAAW;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CACV,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,CAAC,EACpE,OAAO,CACR,CACF,CAAC;QAEF,OAAO,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IAC7B,CAAC;CACF"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/server/server.ts"],"names":[],"mappings":"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"}

package/dist/src/server/templateHelper.js

@@ -1,14 +1,15 @@
-import Handlebars from "handlebars";
 import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import Handlebars from "handlebars";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 class TemplateHelper {
     templateCache = new Map();
     loadTemplate(templateName) {
-        if (this.templateCache.has(templateName)) {
-            return this.templateCache.get(templateName);
+        const cached = this.templateCache.get(templateName);
+        if (cached) {
+            return cached;
         }
         const templatePath = join(__dirname, "templates", `${templateName}.hbs`);
         const templateSource = readFileSync(templatePath, "utf-8");