create-skybridge 0.0.0-dev.e0ed208 → 0.0.0-dev.e38035c

package/template-ecom/README.md

@@ -0,0 +1,89 @@
+# Ecommerce Carousel Example
+
+## What This Example Showcases
+This "Ecommerce Carousel" example demonstrates key Skybridge capabilities:
+- **Interactive Widget Rendering**: A React-based widget that displays an interactive product carousel directly in ChatGPT
+- **Tool Info Access**: Widgets access tool input, output, and metadata via `useToolInfo()` hook
+- **Theme Support**: Adapts to light/dark mode using the `useLayout()` hook
+- **Localization**: Translates UI based on user locale via `useUser()` hook
+- **Persistent State**: Maintains cart state across re-renders using `useWidgetState()` hook
+- **Modal Dialogs**: Opens checkout modal via `useRequestModal()` hook
+- **External Links**: Opens external URL for checkout completion via `useOpenExternal()` hook
+- **External API Integration**: Demonstrates fetching data from REST APIs
+- **Hot Module Replacement**: Live reloading of widget components during development
+
+This example serves as a comprehensive reference for building sophisticated, interactive widgets that leverage Skybridge's full feature set.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 22+
+- HTTP tunnel such as [ngrok](https://ngrok.com/download)
+
+### Local Development
+
+#### 1. Install
+
+```bash
+npm install
+# or
+yarn install
+# or
+pnpm install
+# or
+bun install
+```
+
+#### 2. Start your local server
+
+Run the development server from the root directory:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+This command starts an Express server on port 3000. This server packages:
+
+- an MCP endpoint on `/mcp` (the app backend)
+- a React application on Vite HMR dev server (the UI elements to be displayed in ChatGPT)
+
+#### 3. Connect to ChatGPT
+
+- ChatGPT requires connectors to be publicly accessible. To expose your server on the Internet, run:
+```bash
+ngrok http 3000
+```
+- In ChatGPT, navigate to **Settings → Connectors → Create** and add the forwarding URL provided by ngrok suffixed with `/mcp` (e.g. `https://3785c5ddc4b6.ngrok-free.app/mcp`)
+
+### Create your first widget
+
+#### 1. Add a new widget
+
+- Register a widget in `server/server.ts` with a unique name (e.g., `my-widget`)
+- Create a matching React component at `web/src/widgets/my-widget.tsx`. The file name must match the widget name exactly
+
+#### 2. Edit widgets with Hot Module Replacement (HMR)
+
+Edit and save components in `web/src/widgets/` — changes appear instantly in ChatGPT
+
+#### 3. Edit server code
+
+Modify files in `server/` and reload your ChatGPT connector in **Settings → Connectors → [Your connector] → Reload**
+
+## Deploy to Production
+
+- Use [Alpic](https://alpic.ai/) to deploy your OpenAI App to production
+- In ChatGPT, navigate to **Settings → Connectors → Create** and add your MCP server URL (e.g., `https://your-app-name.alpic.live`)
+
+## Resources
+
+- [Apps SDK Documentation](https://developers.openai.com/apps-sdk)
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
+- [Alpic Documentation](https://docs.alpic.ai/)

package/template-ecom/alpic.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://assets.alpic.ai/alpic.json",
+  "buildOutputDir": "server/dist"
+}

package/template-ecom/nodemon.json

@@ -0,0 +1,5 @@
+{
+  "watch": ["server/src"],
+  "ext": "ts,json",
+  "exec": "tsx server/src/index.ts"
+}

package/template-ecom/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ecom-carousel",
+  "version": "0.0.1",
+  "private": true,
+  "description": "An e-commerce carousel example",
+  "type": "module",
+  "scripts": {
+    "dev": "nodemon",
+    "build": "vite build -c web/vite.config.ts && shx rm -rf server/dist && tsc -p tsconfig.server.json && shx cp -r web/dist server/dist/assets",
+    "start": "node server/dist/index.js",
+    "inspector": "mcp-inspector http://localhost:3000/mcp",
+    "server:build": "tsc -p tsconfig.server.json",
+    "server:start": "node server/dist/index.js",
+    "web:build": "tsc -b web && vite build -c web/vite.config.ts",
+    "web:preview": "vite preview -c web/vite.config.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "express": "^5.2.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "skybridge": ">=0.16.8 <1.0.0",
+    "vite": "^7.3.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.18.0",
+    "@skybridge/devtools": "^0.16.2",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.19.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "nodemon": "^3.1.11",
+    "shx": "^0.4.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "workspaces": []
+}

package/template-ecom/server/src/index.ts

@@ -0,0 +1,39 @@
+import express, { type Express } from "express";
+import { devtoolsStaticServer, widgetsDevServer } from "skybridge/server";
+import type { ViteDevServer } from "vite";
+import { mcp } from "./middleware.js";
+import server from "./server.js";
+
+const app = express() as Express & { vite: ViteDevServer };
+
+app.use(express.json());
+
+app.use(mcp(server));
+
+const env = process.env.NODE_ENV || "development";
+
+if (env !== "production") {
+  app.use(await devtoolsStaticServer());
+  app.use(await widgetsDevServer());
+}
+
+app.listen(3000, (error) => {
+  if (error) {
+    console.error("Failed to start server:", error);
+    process.exit(1);
+  }
+
+  console.log(`Server listening on port 3000 - ${env}`);
+  console.log(
+    "Make your local server accessible with 'ngrok http 3000' and connect to ChatGPT with URL https://xxxxxx.ngrok-free.app/mcp",
+  );
+
+  if (env !== "production") {
+    console.log("Devtools available at http://localhost:3000");
+  }
+});
+
+process.on("SIGINT", async () => {
+  console.log("Server shutdown complete");
+  process.exit(0);
+});

package/template-ecom/server/src/middleware.ts

@@ -0,0 +1,54 @@
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { NextFunction, Request, Response } from "express";
+
+import type { McpServer } from "skybridge/server";
+
+export const mcp =
+  (server: McpServer) =>
+  async (req: Request, res: Response, next: NextFunction) => {
+    // Only handle requests to the /mcp path
+    if (req.path !== "/mcp") {
+      return next();
+    }
+
+    if (req.method === "POST") {
+      try {
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: undefined,
+        });
+
+        res.on("close", () => {
+          transport.close();
+        });
+
+        await server.connect(transport);
+
+        await transport.handleRequest(req, res, req.body);
+      } catch (error) {
+        console.error("Error handling MCP request:", error);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: "2.0",
+            error: {
+              code: -32603,
+              message: "Internal server error",
+            },
+            id: null,
+          });
+        }
+      }
+    } else if (req.method === "GET" || req.method === "DELETE") {
+      res.writeHead(405).end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: {
+            code: -32000,
+            message: "Method not allowed.",
+          },
+          id: null,
+        }),
+      );
+    } else {
+      next();
+    }
+  };

package/template-ecom/server/src/server.ts

@@ -0,0 +1,73 @@
+import { McpServer } from "skybridge/server";
+import { z } from "zod";
+
+interface Product {
+  id: number;
+  title: string;
+  price: number;
+  description: string;
+  category: string;
+  image: string;
+  rating: {
+    rate: number;
+    count: number;
+  };
+}
+
+const server = new McpServer(
+  {
+    name: "ecom-carousel-app",
+    version: "0.0.1",
+  },
+  { capabilities: {} },
+).registerWidget(
+  "ecom-carousel",
+  {
+    description: "E-commerce Product Carousel",
+  },
+  {
+    description: "Display a carousel of products from the store.",
+    inputSchema: {
+      category: z
+        .enum(["electronics", "jewelery", "men's clothing", "women's clothing"])
+        .optional()
+        .describe("Filter by product category"),
+      maxPrice: z.number().optional().describe("Maximum price filter"),
+    },
+  },
+  async ({ category, maxPrice }) => {
+    try {
+      const response = await fetch("https://fakestoreapi.com/products");
+      if (!response.ok) {
+        throw new Error(`API request failed: ${response.status}`);
+      }
+
+      const products: Product[] = await response.json();
+      const filtered: Product[] = [];
+
+      for (const product of products) {
+        if (category && product.category !== category) {
+          continue;
+        }
+        if (maxPrice !== undefined && product.price > maxPrice) {
+          continue;
+        }
+        filtered.push(product);
+      }
+
+      return {
+        structuredContent: { products: filtered },
+        content: [{ type: "text", text: JSON.stringify(filtered) }],
+        isError: false,
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error: ${error}` }],
+        isError: true,
+      };
+    }
+  },
+);
+
+export default server;
+export type AppType = typeof server;

package/template-ecom/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+
+    "noEmit": true
+  },
+  "include": ["server/src", "web/src", "web/vite.config.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/template-ecom/tsconfig.server.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "server/dist",
+    "sourceMap": true,
+    "declaration": true
+  },
+  "include": ["server/src"],
+  "exclude": ["dist", "node_modules"]
+}

package/template-ecom/web/src/helpers.ts

@@ -0,0 +1,4 @@
+import { generateHelpers } from "skybridge/web";
+import type { AppType } from "../../server/src/server";
+
+export const { useToolInfo } = generateHelpers<AppType>();

package/template-ecom/web/src/index.css

@@ -0,0 +1,194 @@
+.light {
+  --bg: #fff;
+  --bg-alt: #f5f5f5;
+  --text: #333;
+  --text-muted: #666;
+  --shadow: rgba(0, 0, 0, 0.1);
+}
+
+.dark {
+  --bg: #2a2a2a;
+  --bg-alt: #333;
+  --text: #eee;
+  --text-muted: #aaa;
+  --shadow: rgba(0, 0, 0, 0.3);
+}
+
+.container,
+.checkout {
+  --accent: mediumseagreen;
+  --accent-text: #fff;
+  display: flex;
+  flex-direction: column;
+  font-family: sans-serif;
+}
+
+.carousel {
+  display: flex;
+  gap: 1rem;
+  padding: 1rem;
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+
+.product-wrapper {
+  flex: 0 0 150px;
+  max-width: 150px;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.product-card {
+  background: var(--bg);
+  border: none;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px var(--shadow);
+  cursor: pointer;
+  padding: 0;
+  text-align: left;
+}
+
+.product-card.selected {
+  outline: 2px solid var(--accent);
+}
+
+.product-image {
+  width: 100%;
+  height: 100px;
+  object-fit: contain;
+  background: var(--bg-alt);
+  padding: 0.5rem;
+  box-sizing: border-box;
+  border-radius: 8px 8px 0 0;
+}
+
+.product-info {
+  padding: 0.5rem;
+}
+
+.product-title {
+  font-size: 0.75rem;
+  color: var(--text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.product-price {
+  font-size: 0.875rem;
+  font-weight: bold;
+  color: var(--accent);
+  margin-top: 0.25rem;
+}
+
+.product-detail {
+  margin: 0 1rem 1rem;
+  padding: 1rem;
+  background: var(--bg);
+  border-radius: 8px;
+  box-shadow: 0 2px 8px var(--shadow);
+}
+
+.detail-title {
+  font-weight: bold;
+  color: var(--text);
+  margin-bottom: 0.5rem;
+}
+
+.detail-rating {
+  font-size: 0.875rem;
+  color: var(--text-muted);
+  margin-bottom: 0.5rem;
+}
+
+.detail-description {
+  font-size: 0.8rem;
+  color: var(--text-muted);
+  line-height: 1.4;
+}
+
+.message {
+  margin: 1rem;
+  padding: 1rem;
+  background: var(--bg);
+  border-radius: 8px;
+  box-shadow: 0 2px 8px var(--shadow);
+  color: var(--text-muted);
+  text-align: center;
+}
+
+.cart-indicator {
+  padding: 0.5rem 1rem;
+  align-self: flex-end;
+  color: var(--accent-text);
+  background: var(--accent);
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font-weight: bold;
+  margin-right: 1rem;
+}
+
+.cart-indicator:disabled {
+  background: var(--bg-alt);
+  color: var(--text-muted);
+  cursor: default;
+}
+
+.cart-button {
+  padding: 0.5rem;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  background: var(--accent);
+  color: var(--accent-text);
+}
+
+.cart-button.in-cart {
+  background: var(--bg-alt);
+  color: var(--text-muted);
+}
+
+.checkout {
+  gap: 1rem;
+  padding: 1.25rem;
+}
+
+.checkout-title {
+  font-weight: bold;
+  font-size: 1rem;
+  color: var(--text);
+}
+
+.checkout-items {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.checkout-item {
+  display: flex;
+  justify-content: space-between;
+  font-size: 0.875rem;
+  color: var(--text);
+}
+
+.checkout-total {
+  display: flex;
+  justify-content: space-between;
+  font-weight: bold;
+  color: var(--text);
+  border-top: 1px solid var(--bg-alt);
+  padding-top: 0.5rem;
+}
+
+.checkout-button {
+  padding: 0.75rem;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  background: var(--accent);
+  color: var(--accent-text);
+  font-weight: bold;
+}