skybridge 0.0.0-dev.f49389e → 0.0.0-dev.f615683

package/README.md

@@ -1,198 +1,123 @@
 <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)
-
-![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)
-
-</div>
+<img alt="Skybridge" src="docs/static/img/logo.png" width="220">
 
-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 emulator. 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**
+### Widget
 
-The `skybridge/web` package comes with a set of hooks to help you build your widgets :
+```tsx
+import { useToolInfo } from "skybridge/web";
 
-- `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.
+function FlightsWidget() {
+  const { output } = useToolInfo();
 
-_useOpenAiGlobal_
-
-```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_
-
-```ts
-import { useToolResponseMetadata } from "skybridge/web";
-
-const toolResponseMetadata = useToolResponseMetadata();
-```
+<br />
 
-_useCallTool_ in synchronous mode
+## 🎯 Features at a Glance
 
-```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>
-  );
-};
-```
+- **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 asynchronous mode
+<br />
 
-```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";
+**[GPL-3.0 License](LICENSE)** · Made with ❤️ by **[Alpic](https://alpic.ai)**
 
-export default defineConfig({
-  plugins: [skybridge()],
-});
-```
+</div>