create-skybridge 0.0.0-dev.1b2b016 → 0.0.0-dev.1b2cb1b

package/templates/ecom/src/server.ts

@@ -0,0 +1,125 @@
+import { existsSync } from "node:fs";
+import { McpServer } from "skybridge/server";
+import { z } from "zod";
+import {
+  type NarrateSearchResultsInput,
+  narrateSearchResults,
+} from "./lib/format.js";
+
+// Load .env into process.env when present (native to Node, no dependency).
+if (existsSync(".env")) {
+  process.loadEnvFile();
+}
+
+// @todo: how many products the carousel curates toward. CAROUSEL_RANGE is
+// interpolated into the prompts below so the model aims for the right amount.
+const CAROUSEL_MAX_SIZE = 6;
+const CAROUSEL_RANGE = `${Math.ceil(CAROUSEL_MAX_SIZE / 2)}-${CAROUSEL_MAX_SIZE}`;
+
+// @todo: minimum number of searches the model runs before rendering. Feeds the
+// prompts below to enforce multi-call exploration; raise for deeper results.
+const MIN_SEARCH_ITERATIONS = 2;
+
+const inputSchema = {
+  // @todo: tune this guidance to your catalog's vocabulary. The model reads
+  // it to turn conversational input into a good keyword.
+  keyword: z.string().describe(
+    `\
+Short noun phrases extracted from conversational input. Never pass full sentences. \
+ALWAYS use the singular form, not the plural. \
+Include color, material, and style descriptors for accuracy. \
+For vague gift or occasion queries without a clear product type, use broad category terms. \
+Preserve the existing keyword across filter refinements; only replace when the user makes a completely different request.`,
+  ),
+
+  // @todo: set the sort options your backend supports (or remove).
+  sort: z.enum(["price-asc", "price-desc"]).optional().describe("Sort order."),
+
+  // @todo: declare the filters your catalog supports. Add one param per
+  // facet (category, color, size...), each optional so the model only sends
+  // what the user asked for. `priceRange` below is just an example, remove it.
+  priceRange: z
+    .string()
+    .optional()
+    .describe(
+      "Price range in dollars. Format: 'min-max' e.g. '0-500', '1000-2000'.",
+    ),
+};
+
+type SearchInput = z.infer<z.ZodObject<typeof inputSchema>>;
+
+function search(input: SearchInput): NarrateSearchResultsInput {
+  // @todo: plug in your product API / DB. Query it with the input params and map
+  // each result into `products` below. `pages` and `totalHits` are optional.
+  return {
+    keyword: input.keyword,
+    products: [], // { id: string; properties: { name: string; value: string[] }[] }[]
+    pages: { current: 1, total: 1 },
+    totalHits: 0,
+    carouselMaxSize: CAROUSEL_MAX_SIZE,
+  };
+}
+
+const server = new McpServer(
+  {
+    // @todo: name and version your app.
+    name: "skybridge-ecom",
+    version: "0.0.1",
+  },
+  {
+    // @todo: adapt this server-wide prompt to your catalog.
+    instructions: `\
+Two phases:
+
+SEARCH: Call search_products ${MIN_SEARCH_ITERATIONS}+ times before presenting—never off one call. \
+Vary the keyword, apply filters from a prior response, or page deeper. \
+Stay silent while searching: emit NO text between calls. Speak only \
+once the carousel renders. Never call a category unavailable before searching.`,
+  },
+).registerTool(
+  {
+    name: "search_products",
+    // @todo: describe YOUR catalog and how the agent should search and curate
+    // it. This is the model's main guide: be specific about your categories,
+    // the multi-call search loop, and when to render vs. keep searching.
+    description: `\
+Search the product catalog. Handles any query: specific products, broad categories, gifts, occasions, or open discovery.
+Never assume a category is unavailable: always search before responding.
+
+The response is data only: a list of matching products (name, ID, price, description, and any product-specific attributes) plus pagination and the available filters. The raw results are for your eyes only: the client never sees them.
+
+NEVER describe or characterize the raw results to the client: do not mention how many there are, what categories they fall into, or that they look off-topic. While searching, stay silent: do not narrate what you are doing, announce searches, or report progress between tool calls. Speak only once the carousel is rendered.
+
+Act on the response as follows:
+
+- FIRST SEARCH: use the keyword only (plus sort if needed). Read the available filters in the response; these are the only valid filter options for follow-ups.
+- REFINEMENT: if the user's intent matches an available filter, apply it. If it doesn't match any filter, start a new keyword search.
+- ITERATE: a single search is never enough. Run several searches (${MIN_SEARCH_ITERATIONS} minimum) before rendering: vary the keyword, apply a filter, or page deeper, and compare results across them. Quality comes from this multi-call exploration; one call then render gives shallow results.
+- CURATION: read results and pick the best matches for the client's intent, grounding your choice in each product's description. If zero results, broaden the keyword or relax filters and search again: do NOT call render-carousel. If fewer than 3 results and the user didn't ask for a specific product, search again with broader terms. Only after exploring across several searches, call render-carousel with the selected IDs.
+- PRESENT: Once you have ${CAROUSEL_RANGE} distinct, relevant products, call render-carousel with their IDs. Recommend ONLY AFTER the carousel displays, in carousel order.
+
+The sweet spot is ${CAROUSEL_RANGE} products.
+`,
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: false,
+      destructiveHint: false,
+    },
+    // @todo: customize the status messages shown in ChatGPT while the tool runs.
+    _meta: {
+      "openai/toolInvocation/invoking": "Searching",
+      "openai/toolInvocation/invoked": "Done searching",
+    },
+    inputSchema,
+    outputSchema: {},
+  },
+  (input) => {
+    const results = search(input);
+    const { content } = narrateSearchResults(results);
+    return { structuredContent: {}, content, isError: false };
+  },
+);
+
+export default await server.run();
+
+export type AppType = typeof server;

package/templates/ecom/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "skybridge/tsconfig",
+
+  "include": ["src", ".skybridge/**/*.d.ts"]
+}

package/templates/ecom/vite.config.ts

@@ -0,0 +1,6 @@
+import { skybridge } from "skybridge/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [skybridge()],
+});

package/template/.cursor/mcp.json

@@ -1,7 +0,0 @@
-{
-  "mcpServers": {
-    "local": {
-      "url": "http://localhost:3000/mcp"
-    }
-  }
-}

package/template/.nvmrc

@@ -1 +0,0 @@
-lts/jod

package/template/.vscode/launch.json

@@ -1,16 +0,0 @@
-{
-  "version": "0.0.1",
-  "configurations": [
-    {
-      "name": "Debug MCP Server",
-      "type": "node",
-      "request": "launch",
-      "program": "${workspaceFolder}/dist/index.js",
-      "console": "integratedTerminal",
-      "sourceMaps": true,
-      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "preLaunchTask": "npm: build",
-      "stopOnEntry": false
-    }
-  ]
-}

package/template/.vscode/settings.json

@@ -1,3 +0,0 @@
-{
-  "editor.formatOnSave": true
-}

package/template/.vscode/tasks.json

@@ -1,14 +0,0 @@
-{
-  "version": "2.0.0",
-  "tasks": [
-    {
-      "type": "shell",
-      "command": "npm",
-      "args": ["build"],
-      "group": "build",
-      "label": "npm: build",
-      "detail": "npm build",
-      "problemMatcher": ["$tsc"]
-    }
-  ]
-}

package/template/README.md

@@ -1,116 +0,0 @@
-# ChatGPT Apps SDK Alpic Starter
-
-This repository is a minimal Typescript application demonstrating how to build an OpenAI Apps SDK compatible MCP server with widget rendering in ChatGPT.
-
-![Demo](docs/demo.gif)
-
-## Overview
-
-This project shows how to integrate a Typescript express application with the ChatGPT Apps SDK using the Model Context Protocol (MCP). It includes a working MCP server that exposes tools and resources that can be called from ChatGPT, with responses rendered natively in ChatGPT. It also includes MCP tools without UI widgets.
-
-## Getting Started
-
-### Prerequisites
-
-- Node.js 22+ (see `.nvmrc` for exact version)
-- pnpm (install with `npm install -g pnpm`)
-- Ngrok
-
-### Local Development with Hot Module Replacement (HMR)
-
-This project uses Vite for React widget development with full HMR support, allowing you to see changes in real-time, directly within ChatGPT conversation, without restarting the server.
-
-#### 1. Install
-
-```bash
-pnpm install
-```
-
-#### 2. Start the Development Server
-
-Run the development server from the root directory:
-
-```bash
-pnpm dev
-```
-
-This command starts an Express server on port 3000. This server packages:
-
-- an MCP endpoint on `/mcp` - aka the ChatGPT App Backend
-- a React application on Vite HMR dev server - aka the ChatGPT App Frontend
-
-#### 3. Expose Your Local Server
-
-In a separate terminal, expose your local server using ngrok:
-
-```bash
-ngrok http 3000
-```
-
-Copy the forwarding URL from ngrok output:
-
-```bash
-Forwarding     https://3785c5ddc4b6.ngrok-free.app -> http://localhost:3000
-```
-
-#### 4. Connect to ChatGPT
-
-- Enable **Settings → Connectors → Advanced → Developer mode** in the ChatGPT client
-- Navigate to **Settings → Connectors → Create**
-- Enter your ngrok URL with the `/mcp` path (e.g., `https://3785c5ddc4b6.ngrok-free.app/mcp`)
-- Click **Create**
-
-#### 5. Test Your Integration
-
-- Start a new conversation in ChatGPT
-- Select your newly created connector using **the + button → Your connector**
-- Try prompting the model (e.g., "Show me pikachu details")
-
-#### 6. Develop with HMR
-
-Now you can edit React components in `web` and see changes instantly:
-
-- Make changes to any component
-- Save the file
-- The widget will automatically update in ChatGPT without refreshing or reconnecting
-- The Express server and MCP server continue running without interruption
-
-**Note:** When you modify widget components, changes will be reflected immediately. If you modify MCP server code (in `src/`), you may need to reload your connector in **Settings → Connectors → [Your connector] → Reload**.
-
-## Widget Naming Convention
-
-**Important:** For a widget to work properly, the name of the endpoint in your MCP server must match the file name of the corresponding React component in `web/src/widgets/`.
-
-For example:
-
-- If you create a widget endpoint named `pokemon-card`, you must create a corresponding React component file at `web/src/widgets/pokemon-card.tsx`
-- The endpoint name and the widget file name (without the `.tsx` extension) must be identical
-
-This naming convention allows the system to automatically map widget requests to their corresponding React components.
-
-## Deploy to Production
-
-Use Alpic to deploy your OpenAI App to production.
-
-[![Deploy on Alpic](https://assets.alpic.ai/button.svg)](https://app.alpic.ai/new/clone?repositoryUrl=https%3A%2F%2Fgithub.com%2Falpic-ai%2Fapps-sdk-template)
-
-- In ChatGPT, navigate to **Settings → Connectors → Create** and add your MCP server URL (e.g., `https://your-app-name.alpic.live`)
-
-## Project Structure
-
-```
-.
-├── server/
-│   ├── app.ts          # OpenAI App extension class with widget API implementation
-│   ├── server.ts       # MCP server with tool/resource/prompt registration
-│   └── index.ts        # Express server definition
-└── web/
-    └── src/
-        └── widgets/    # React widget components (must match endpoint names)
-```
-
-## 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/_gitignore

@@ -1,194 +0,0 @@
-# =============================================================================
-# OPERATING SYSTEM FILES
-# =============================================================================
-.DS_Store
-.DS_Store?
-._*
-.Spotlight-V100
-.Trashes
-ehthumbs.db
-Thumbs.db
-
-# =============================================================================
-# NODE.JS & PACKAGE MANAGERS
-# =============================================================================
-node_modules/
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-.pnpm-debug.log*
-.npm
-.pnp.js
-.pnp.cjs
-.pnp.mjs
-.pnp.json
-.pnp.ts
-
-# =============================================================================
-# TYPESCRIPT & JAVASCRIPT
-# =============================================================================
-*.tsbuildinfo
-.tscache/
-*.js.map
-*.mjs.map
-*.cjs.map
-*.d.ts.map
-*.d.ts
-!*.d.ts.template
-*.tgz
-.eslintcache
-.rollup.cache
-
-# =============================================================================
-# PYTHON
-# =============================================================================
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-develop-eggs/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-.pytest_cache/
-.coverage
-htmlcov/
-.tox/
-.venv
-venv/
-ENV/
-
-# =============================================================================
-# JAVA
-# =============================================================================
-*.class
-*.jar
-*.war
-*.nar
-*.ear
-hs_err_pid*
-target/
-.gradle/
-
-# =============================================================================
-# RUBY
-# =============================================================================
-*.gem
-*.rbc
-/.config
-/coverage/
-/InstalledFiles
-/pkg/
-/spec/reports/
-/spec/examples.txt
-/test/tmp/
-/test/version_tmp/
-/tmp/
-.byebug_history
-
-# =============================================================================
-# BUILD & DISTRIBUTION
-# =============================================================================
-build/
-dist/
-dist-ssr/
-out/
-
-# =============================================================================
-# COMPILED FILES
-# =============================================================================
-*.com
-*.dll
-*.exe
-*.o
-
-# =============================================================================
-# PACKAGE & ARCHIVE FILES
-# =============================================================================
-*.7z
-*.dmg
-*.gz
-*.iso
-*.rar
-*.tar
-*.tar.gz
-*.zip
-
-# =============================================================================
-# LOGS & DATABASES
-# =============================================================================
-*.log
-*.sql
-*.sqlite
-*.sqlite3
-logs/
-
-# =============================================================================
-# TESTING & COVERAGE
-# =============================================================================
-coverage/
-.nyc_output/
-
-# =============================================================================
-# CACHE & TEMPORARY FILES
-# =============================================================================
-.cache/
-.parcel-cache/
-*.bak
-
-# =============================================================================
-# ENVIRONMENT & CONFIGURATION
-# =============================================================================
-.env
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-.sample-env
-sample.*
-!sample.template.*
-*.local
-mcp-servers.json
-mcp-config.json
-
-# =============================================================================
-# DEMO & EXAMPLE DIRECTORIES
-# =============================================================================
-demo/
-demos/
-example/
-examples/
-samples/
-
-# =============================================================================
-# GENERATED DOCUMENTATION
-# =============================================================================
-docs/api/
-
-# =============================================================================
-# EDITOR DIRECTORIES AND FILES
-# =============================================================================
-.vscode/*
-!.vscode/extensions.json
-.idea
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?
-
-# =============================================================================
-# APPLICATION SPECIFIC
-# =============================================================================
-repomix-output*
-duckdata/
-.claude

package/template/alpic.json

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

package/template/package.json

@@ -1,22 +0,0 @@
-{
-  "name": "apps-sdk-template",
-  "version": "0.0.1",
-  "private": true,
-  "description": "Alpic MCP Server Template",
-  "type": "module",
-  "packageManager": "pnpm@10.18.3",
-  "scripts": {
-    "dev": "pnpm --filter @apps-sdk-template/server dev",
-    "build": "pnpm web:build && rm -rf server/dist && pnpm --filter=@apps-sdk-template/server --prod deploy server/dist && cp -r web/dist server/dist/assets && pnpm --filter=@apps-sdk-template/server build",
-    "lint": "biome ci",
-    "start": "pnpm server:start",
-    "inspector": "pnpm --filter @apps-sdk-template/server inspector",
-    "server:build": "pnpm --filter @apps-sdk-template/server build",
-    "server:start": "pnpm --filter @apps-sdk-template/server start",
-    "web:build": "pnpm --filter @apps-sdk-template/web build",
-    "web:preview": "pnpm --filter @apps-sdk-template/web preview"
-  },
-  "devDependencies": {
-    "tsx": "^4.19.4"
-  }
-}