initial commit

Co-authored-by: bryant-openai <bryant-openai@users.noCo-authored-by: bryant-openai <bryant-openai@users.noreply.github.com>

Author: katia-openai

.gitignore

@@ -0,0 +1,36 @@
+# Dependency directories
+node_modules/
+.pnpm-store/
+
+# Build outputs
+/assets
+dist/
+build/
+.vite/
+coverage/
+
+# Logs and caches
+*.log
+pnpm-debug.log
+npm-debug.log
+yarn-error.log
+*.tsbuildinfo
+.eslintcache
+
+# Environment files
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# Editor and OS files
+.DS_Store
+.idea/
+.vscode/
+
+# Python artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,136 @@
+# Apps SDK Examples Gallery
+
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+This repository showcases example UI components to be used with the Apps SDK, as well as example MCP servers that expose a collection of components as tools.
+It is meant to be used as a starting point and source of inspiration to build your own apps for ChatGPT.
+
+## MCP + Apps SDK overview
+
+The Model Context Protocol (MCP) is an open specification for connecting large language model clients to external tools, data, and user interfaces. An MCP server exposes tools that a model can call during a conversation and returns results according to the tool contracts. Those results can include extra metadata—such as inline HTML—that the Apps SDK uses to render rich UI components (widgets) alongside assistant messages.
+
+Within the Apps SDK, MCP keeps the server, model, and UI in sync. By standardizing the wire format, authentication, and metadata, it lets ChatGPT reason about your connector the same way it reasons about built-in tools. A minimal MCP integration for Apps SDK implements three capabilities:
+
+1. **List tools** – Your server advertises the tools it supports, including their JSON Schema input/output contracts and optional annotations (for example, `readOnlyHint`).
+2. **Call tools** – When a model selects a tool, it issues a `call_tool` request with arguments that match the user intent. Your server executes the action and returns structured content the model can parse.
+3. **Return widgets** – Alongside structured content, return embedded resources in the response metadata so the Apps SDK can render the interface inline in the Apps SDK client (ChatGPT).
+
+Because the protocol is transport agnostic, you can host the server over Server-Sent Events or streaming HTTP—Apps SDK supports both.
+
+The MCP servers in this demo highlight how each tool can light up widgets by combining structured payloads with `_meta.openai/outputTemplate` metadata returned from the MCP servers.
+
+## Repository structure
+
+- `src/` – Source for each widget example.
+- `assets/` – Generated HTML, JS, and CSS bundles after running the build step.
+- `pizzaz_server_node/` – MCP server implemented with the official TypeScript SDK.
+- `pizzaz_server_python/` – Python MCP server that returns the Pizzaz widgets.
+- `solar-system_server_python/` – Python MCP server for the 3D solar system widget.
+- `build-all.mts` – Vite build orchestrator that produces hashed bundles for every widget entrypoint.
+
+## Prerequisites
+
+- Node.js 18+
+- pnpm (recommended) or npm/yarn
+- Python 3.10+ (for the Python MCP server)
+
+## Install dependencies
+
+Clone the repository and install the workspace dependencies:
+
+```bash
+pnpm install
+```
+
+> Using npm or yarn? Install the root dependencies with your preferred client and adjust the commands below accordingly.
+
+## Build the components gallery
+
+The components are bundled into standalone assets that the MCP servers serve as reusable UI resources.
+
+```bash
+pnpm run build
+```
+
+This command runs `build-all.mts`, producing versioned `.html`, `.js`, and `.css` files inside `assets/`. Each widget is wrapped with the CSS it needs so you can host the bundles directly or ship them with your own server.
+
+To iterate locally, you can also launch the Vite dev server:
+
+```bash
+pnpm run dev
+```
+
+## Serve the static assets
+
+If you want to preview the generated bundles without the MCP servers, start the static file server after running a build:
+
+```bash
+pnpm run serve
+```
+
+The assets are exposed at [`http://localhost:4444`](http://localhost:4444) with CORS enabled so that local tooling (including MCP inspectors) can fetch them.
+
+## Run the MCP servers
+
+The repository ships several demo MCP servers that highlight different widget bundles:
+
+- **Pizzaz (Node & Python)** – pizza-inspired collection of tools and components
+- **Solar system (Python)** – 3D solar system viewer
+
+Every tool response includes plain text content, structured JSON, and `_meta.openai/outputTemplate` metadata so the Apps SDK can hydrate the matching widget.
+
+### Pizzaz Node server
+
+```bash
+cd pizzaz_server_node
+pnpm start
+```
+
+### Pizzaz Python server
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r pizzaz_server_python/requirements.txt
+uvicorn pizzaz_server_python.main:app --port 8000
+```
+
+### Solar system Python server
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r solar-system_server_python/requirements.txt
+uvicorn solar-system_server_python.main:app --port 8000
+```
+
+You can reuse the same virtual environment for all Python servers—install the dependencies once and run whichever entry point you need.
+
+## Testing in ChatGPT
+
+To add these apps to ChatGPT, enable [developer mode](https://platform.openai.com/docs/guides/developer-mode), and add your apps in Settings > Connectors.
+
+To add your local server without deploying it, you can use a tool like [ngrok](https://ngrok.com/) to expose your local server to the internet.
+
+For example, once your mcp servers are running, you can run:
+
+```bash
+ngrok http 8000
+```
+
+You will get a public URL that you can use to add your local server to ChatGPT in Settings > Connectors.
+
+For example: `https://<custom_endpoint>.ngrok-free.app/mcp`
+
+## Next steps
+
+- Customize the widget data: edit the handlers in `pizzaz_server_node/src`, `pizzaz_server_python/main.py`, or the solar system server to fetch data from your systems.
+- Create your own components and add them to the gallery: drop new entries into `src/` and they will be picked up automatically by the build script.
+
+## Contributing
+
+You are welcome to open issues or submit PRs to improve this app, however, please note that we may not review all suggestions.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](./LICENSE) for details.

build-all.mts

@@ -0,0 +1,196 @@
+import { build, type InlineConfig, type Plugin } from "vite";
+import react from "@vitejs/plugin-react";
+import fg from "fast-glob";
+import path from "path";
+import fs from "fs";
+import crypto from "crypto";
+import pkg from "./package.json" with { type: "json" };
+import tailwindcss from "@tailwindcss/vite";
+
+const entries = fg.sync("src/**/index.{tsx,jsx}");
+const outDir = "assets";
+
+const PER_ENTRY_CSS_GLOB = "**/*.{css,pcss,scss,sass}";
+const PER_ENTRY_CSS_IGNORE = "**/*.module.*".split(",").map((s) => s.trim());
+const GLOBAL_CSS_LIST = [path.resolve("src/index.css")];
+
+const targets: string[] = [
+  "todo",
+  "solar-system",
+  "pizzaz",
+  "pizzaz-carousel",
+  "pizzaz-list",
+  "pizzaz-albums",
+  "pizzaz-video",
+];
+const builtNames: string[] = [];
+
+function wrapEntryPlugin(
+  virtualId: string,
+  entryFile: string,
+  cssPaths: string[]
+): Plugin {
+  return {
+    name: `virtual-entry-wrapper:${entryFile}`,
+    resolveId(id) {
+      if (id === virtualId) return id;
+    },
+    load(id) {
+      if (id !== virtualId) {
+        return null;
+      }
+
+      const cssImports = cssPaths
+        .map((css) => `import ${JSON.stringify(css)};`)
+        .join("\n");
+
+      return `
+    ${cssImports}
+    export * from ${JSON.stringify(entryFile)};
+
+    import * as __entry from ${JSON.stringify(entryFile)};
+    export default (__entry.default ?? __entry.App);
+
+    import ${JSON.stringify(entryFile)};
+  `;
+    },
+  };
+}
+
+fs.rmSync(outDir, { recursive: true, force: true });
+
+for (const file of entries) {
+  const name = path.basename(path.dirname(file));
+  if (targets.length && !targets.includes(name)) {
+    continue;
+  }
+
+  const entryAbs = path.resolve(file);
+  const entryDir = path.dirname(entryAbs);
+
+  // Collect CSS for this entry using the glob(s) rooted at its directory
+  const perEntryCss = fg.sync(PER_ENTRY_CSS_GLOB, {
+    cwd: entryDir,
+    absolute: true,
+    dot: false,
+    ignore: PER_ENTRY_CSS_IGNORE,
+  });
+
+  // Global CSS (Tailwind, etc.), only include those that exist
+  const globalCss = GLOBAL_CSS_LIST.filter((p) => fs.existsSync(p));
+
+  // Final CSS list (global first for predictable cascade)
+  const cssToInclude = [...globalCss, ...perEntryCss].filter((p) =>
+    fs.existsSync(p)
+  );
+
+  const virtualId = `\0virtual-entry:${entryAbs}`;
+
+  const createConfig = (): InlineConfig => ({
+    plugins: [
+      wrapEntryPlugin(virtualId, entryAbs, cssToInclude),
+      tailwindcss(),
+      react(),
+      {
+        name: "remove-manual-chunks",
+        outputOptions(options) {
+          if ("manualChunks" in options) {
+            delete (options as any).manualChunks;
+          }
+          return options;
+        },
+      },
+    ],
+    esbuild: {
+      jsx: "automatic",
+      jsxImportSource: "react",
+      target: "es2022",
+    },
+    build: {
+      target: "es2022",
+      outDir,
+      emptyOutDir: false,
+      chunkSizeWarningLimit: 2000,
+      minify: "esbuild",
+      cssCodeSplit: false,
+      rollupOptions: {
+        input: virtualId,
+        output: {
+          format: "es",
+          entryFileNames: `${name}.js`,
+          inlineDynamicImports: true,
+          assetFileNames: (info) =>
+            (info.name || "").endsWith(".css")
+              ? `${name}.css`
+              : `[name]-[hash][extname]`,
+        },
+        preserveEntrySignatures: "allow-extension",
+        treeshake: true,
+      },
+    },
+  });
+
+  console.group(`Building ${name} (react)`);
+  await build(createConfig());
+  console.groupEnd();
+  builtNames.push(name);
+  console.log(`Built ${name}`);
+}
+
+const outputs = fs
+  .readdirSync("assets")
+  .filter((f) => f.endsWith(".js") || f.endsWith(".css"))
+  .map((f) => path.join("assets", f))
+  .filter((p) => fs.existsSync(p));
+
+const renamed = [];
+
+const h = crypto
+  .createHash("sha256")
+  .update(pkg.version, "utf8")
+  .digest("hex")
+  .slice(0, 4);
+
+console.group("Hashing outputs");
+for (const out of outputs) {
+  const dir = path.dirname(out);
+  const ext = path.extname(out);
+  const base = path.basename(out, ext);
+  const newName = path.join(dir, `${base}-${h}${ext}`);
+
+  fs.renameSync(out, newName);
+  renamed.push({ old: out, neu: newName });
+  console.log(`${out} -> ${newName}`);
+}
+console.groupEnd();
+
+console.log("new hash: ", h);
+
+for (const name of builtNames) {
+  const dir = outDir;
+  const htmlPath = path.join(dir, `${name}-${h}.html`);
+  const cssPath = path.join(dir, `${name}-${h}.css`);
+  const jsPath = path.join(dir, `${name}-${h}.js`);
+
+  const css = fs.existsSync(cssPath)
+    ? fs.readFileSync(cssPath, { encoding: "utf8" })
+    : "";
+  const js = fs.existsSync(jsPath)
+    ? fs.readFileSync(jsPath, { encoding: "utf8" })
+    : "";
+
+  const cssBlock = css ? `\n  <style>\n${css}\n  </style>\n` : "";
+  const jsBlock = js ? `\n  <script type="module">\n${js}\n  </script>` : "";
+
+  const html = [
+    "<!doctype html>",
+    "<html>",
+    `<head>${cssBlock}</head>`,
+    "<body>",
+    `  <div id="${name}-root"></div>${jsBlock}`,
+    "</body>",
+    "</html>",
+  ].join("\n");
+  fs.writeFileSync(htmlPath, html, { encoding: "utf8" });
+  console.log(`${htmlPath} (generated)`);
+}