pizzaz-mcp 1.0.0

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+	"html.autoClosingTags": false
+}

package/README.md

@@ -0,0 +1,139 @@
+# Pizzaz MCP Server
+
+A Model Context Protocol (MCP) server that serves pizza UI widgets for ChatGPT's Apps SDK. Deployed on Render to bypass proxy restrictions, using OpenAI's exact component architecture, styling system, and design tokens.
+
+## Live URL
+
+```
+https://pizzaz-mcp.onrender.com/mcp
+```
+
+## What It Does
+
+- Exposes 5 pizza widgets via MCP tools: map, carousel, list, albums, shop
+- Uses `@openai/apps-sdk-ui` components (Button, Image) exactly as OpenAI does
+- Tailwind CSS v4 + OpenAI design tokens for theming
+- Each widget is a self-contained HTML file served from `/assets/`
+- Auto-deploys to Render on every push to `main`
+
+## Project Structure
+
+```
+pizzaz-mcp/
+├── src/                          # React widget source (OpenAI SDK architecture)
+│   ├── index.css                 # Tailwind + @openai/apps-sdk-ui/css
+│   ├── types.ts                  # OpenAI globals / widget types
+│   ├── use-openai-global.ts      # Hook: reads window.openai globals
+│   ├── use-widget-props.ts       # Hook: reads toolOutput props
+│   ├── use-widget-state.ts       # Hook: reads/writes widget state
+│   ├── use-display-mode.ts       # Hook: pip | inline | fullscreen
+│   ├── use-max-height.ts         # Hook: max height constraint
+│   ├── media-queries.ts          # Shared media query helpers
+│   ├── pizzaz/                   # Pizza map widget + markers data
+│   ├── pizzaz-carousel/          # Pizza carousel widget
+│   ├── pizzaz-list/              # Pizza list widget
+│   ├── pizzaz-albums/            # Pizza albums widget
+│   └── pizzaz-shop/              # Pizza shop / cart widget
+├── server/
+│   └── server.ts                 # MCP server (SSE transport)
+├── assets/                       # Build output (committed to git)
+│   ├── pizzaz.html
+│   ├── pizzaz-carousel.html
+│   ├── pizzaz-list.html
+│   ├── pizzaz-albums.html
+│   ├── pizzaz-shop.html
+│   └── *.js / *.css              # Hashed bundles
+├── build-all.mts                 # Vite multi-entry build script
+├── vite.config.mts               # Vite dev server config
+├── tailwind.config.ts            # Tailwind content paths
+├── tsconfig.json                 # TypeScript project references
+├── package.json                  # Dependencies + scripts
+└── render.yaml                   # Render deployment config
+```
+
+## Architecture
+
+The app follows OpenAI's exact widget architecture from `openai-apps-sdk-examples`:
+
+- Components use `@openai/apps-sdk-ui/components/Button` and `Image` directly
+- CSS uses Tailwind v4 with `@import "@openai/apps-sdk-ui/css"` for design tokens
+- Hooks (`useWidgetProps`, `useWidgetState`, `useOpenAiGlobal`) match the SDK pattern
+- Each widget entry is `src/<name>/index.{tsx,jsx}` — Vite builds each to `assets/<name>.js` + `assets/<name>.css`
+- The build script generates `assets/<name>.html` with absolute URLs pointing to the Render deployment
+- The MCP server reads those HTML files at startup and serves them via `text/html+skybridge` MIME type
+
+## Available MCP Tools
+
+| Tool | Widget | Description |
+|------|--------|-------------|
+| `pizza-map` | pizzaz | Interactive pizza map of SF |
+| `pizza-carousel` | pizzaz-carousel | Scrollable pizza place cards |
+| `pizza-list` | pizzaz-list | Ranked list of pizzerias |
+| `pizza-albums` | pizzaz-albums | Album-style pizza gallery |
+| `pizza-shop` | pizzaz-shop | Full cart + checkout experience |
+
+## Quick Start
+
+### Local Development
+
+```bash
+npm install
+npm run dev
+# Open http://localhost:4444
+```
+
+### Build
+
+```bash
+npm run build
+# Outputs to assets/
+```
+
+### Deploy to Render
+
+1. Push to GitHub
+2. On [Render Dashboard](https://dashboard.render.com/): New → Web Service → connect repo
+3. Render auto-detects `render.yaml` and deploys
+4. Add MCP connector in ChatGPT: `https://pizzaz-mcp.onrender.com/mcp`
+
+```bash
+git add .
+git commit -m "Deploy"
+git push origin main
+```
+
+## Using in ChatGPT
+
+1. Go to https://chatgpt.com
+2. Settings → Beta Features → enable Developer Mode
+3. Add MCP connector: `https://pizzaz-mcp.onrender.com/mcp`
+4. Try: "Show me the pizza carousel" or "Open the Pizzaz shop"
+
+## Theming
+
+Theming is handled by `@openai/apps-sdk-ui`'s CSS custom properties. The `src/index.css` imports the full token set:
+
+```css
+@import "tailwindcss";
+@import "@openai/apps-sdk-ui/css";
+```
+
+To customize colors, override the CSS variables in `src/index.css`:
+
+```css
+:root {
+  --color-background-primary-solid: #ff6b35;
+}
+```
+
+## Notes
+
+- Render free tier spins down after 15 min of inactivity — first request takes ~30s
+- The MCP endpoint is `GET /mcp` (SSE) and `POST /mcp/messages` (messages)
+- Build output is committed to git so Render only needs `npm install && npm start`
+
+## References
+
+- [OpenAI Apps SDK Examples](https://github.com/openai/openai-apps-sdk-examples)
+- [MCP Protocol](https://modelcontextprotocol.io/)
+- [Render Docs](https://render.com/docs)

package/build-all.mts

@@ -0,0 +1,188 @@
+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[] = [
+  "pizzaz",
+  "pizzaz-carousel",
+  "pizzaz-list",
+  "pizzaz-albums",
+  "pizzaz-shop",
+];
+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 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);
+  console.log(`${out} -> ${newName}`);
+}
+console.groupEnd();
+
+console.log("new hash: ", h);
+
+const defaultBaseUrl = "https://pizzaz-mcp.onrender.com";
+const baseUrlCandidate = process.env.BASE_URL?.trim() ?? "";
+const baseUrlRaw = baseUrlCandidate.length > 0 ? baseUrlCandidate : defaultBaseUrl;
+const normalizedBaseUrl = baseUrlRaw.replace(/\/+$/, "") || defaultBaseUrl;
+console.log(`Using BASE_URL ${normalizedBaseUrl} for generated HTML`);
+
+for (const name of builtNames) {
+  const dir = outDir;
+  const hashedHtmlPath = path.join(dir, `${name}-${h}.html`);
+  const liveHtmlPath = path.join(dir, `${name}.html`);
+  const html = `<!doctype html>
+<html>
+<head>
+  <script type="module" src="${normalizedBaseUrl}/${name}-${h}.js"></script>
+  <link rel="stylesheet" href="${normalizedBaseUrl}/${name}-${h}.css">
+</head>
+<body>
+  <div id="${name}-root"></div>
+</body>
+</html>
+`;
+  fs.writeFileSync(hashedHtmlPath, html, { encoding: "utf8" });
+  fs.writeFileSync(liveHtmlPath, html, { encoding: "utf8" });
+  console.log(`${liveHtmlPath}`);
+}

package/docs/DEPLOYMENT_GUIDE.md

@@ -0,0 +1,226 @@
+# Pizza Carousel MCP Deployment Guide
+
+## Overview
+Your pizza carousel with dual styling is ready to deploy! The MCP server is already configured to serve both carousel variants that users can switch between using commands in ChatGPT.
+
+## What's Already Configured
+
+### MCP Server Tools
+The server (`src/server.ts`) already has two tools configured:
+
+1. **`pizza-carousel-default`** - Shows carousel with OpenAI default styling
+   - Green color scheme (#10a37f)
+   - 12px button border radius
+   - System fonts
+
+2. **`pizza-carousel-custom`** - Shows carousel with custom branding
+   - Cyan color scheme (#00caff)
+   - 20px button border radius
+   - Custom fonts
+
+### File Structure
+```
+assets/
+├── tokens/
+│   ├── default-tokens.css    ✅ Ready
+│   └── custom-tokens.css      ✅ Ready
+├── pizzaz-carousel-default.html  ✅ Ready
+└── pizzaz-carousel-custom.html   ✅ Ready
+```
+
+### Static Asset Serving
+The server is configured to serve static files from `/assets/` path, which means:
+- Token CSS files are accessible at `/assets/tokens/default-tokens.css`
+- Token CSS files are accessible at `/assets/tokens/custom-tokens.css`
+- HTML files correctly reference tokens with relative path: `href="tokens/default-tokens.css"`
+
+## Deployment Steps
+
+### 1. Start the MCP Server Locally
+
+```bash
+npm start
+```
+
+Expected output:
+```
+Pizzaz MCP server listening on http://localhost:8000
+  SSE stream: GET http://localhost:8000/mcp
+  Message post endpoint: POST http://localhost:8000/mcp/messages?sessionId=...
+```
+
+### 2. Test the Server Locally
+
+Open a new terminal and test the endpoints:
+
+```bash
+# Test that token files are accessible
+curl http://localhost:8000/assets/tokens/default-tokens.css
+curl http://localhost:8000/assets/tokens/custom-tokens.css
+
+# Test that HTML files load
+curl http://localhost:8000/assets/pizzaz-carousel-default.html
+curl http://localhost:8000/assets/pizzaz-carousel-custom.html
+```
+
+All should return the file contents without 404 errors.
+
+### 3. Configure ChatGPT to Use Your MCP Server
+
+You need to add your MCP server to ChatGPT's configuration:
+
+1. Open ChatGPT settings
+2. Navigate to MCP servers configuration
+3. Add your server with the URL: `http://localhost:8000/mcp`
+
+Or if deploying to a cloud service (like Render.com):
+- Use the public URL provided by your hosting service
+- Example: `https://your-app-name.onrender.com/mcp`
+
+### 4. Deploy to Render.com (Optional)
+
+Your `render.yaml` is already configured. To deploy:
+
+1. **Push to GitHub:**
+   ```bash
+   git add .
+   git commit -m "Add pizza carousel with dual styling"
+   git push origin main
+   ```
+
+2. **Connect to Render:**
+   - Go to https://render.com
+   - Create new Web Service
+   - Connect your GitHub repository
+   - Render will automatically detect `render.yaml` and deploy
+
+3. **Get your public URL:**
+   - Render will provide a URL like: `https://pizzaz-mcp.onrender.com`
+   - Use this URL in ChatGPT: `https://pizzaz-mcp.onrender.com/mcp`
+
+## How Users Will Interact in ChatGPT
+
+Once deployed, users can interact with your pizza carousel in ChatGPT:
+
+### Example User Commands:
+
+**Show default styled carousel:**
+```
+Show me the pizza carousel with default styling
+```
+or
+```
+Use the pizza-carousel-default tool
+```
+
+**Show custom styled carousel:**
+```
+Show me the pizza carousel with custom branding
+```
+or
+```
+Use the pizza-carousel-custom tool
+```
+
+**Switch between styles:**
+```
+Now show it with custom styling instead
+```
+
+### What Happens:
+1. User types a command in ChatGPT
+2. ChatGPT calls your MCP server tool (`pizza-carousel-default` or `pizza-carousel-custom`)
+3. Server returns the HTML widget with the appropriate token file imported
+4. ChatGPT renders the carousel in the conversation
+5. User sees the styled carousel and can interact with it (hover, scroll)
+
+## Verification Checklist
+
+Before deploying, verify:
+
+- [x] Both HTML files exist in `assets/` directory
+- [x] Both token CSS files exist in `assets/tokens/` directory
+- [x] HTML files correctly reference token files with relative paths
+- [x] MCP server has both tools configured
+- [x] Server serves static assets from `/assets/` path
+- [ ] Server starts without errors (`npm start`)
+- [ ] Token files are accessible via HTTP
+- [ ] HTML files are accessible via HTTP
+- [ ] ChatGPT can connect to your MCP server
+- [ ] Both carousel tools work in ChatGPT
+
+## Testing in ChatGPT
+
+After deployment, test both tools:
+
+1. **Test default carousel:**
+   - Ask: "Show me the pizza carousel with default styling"
+   - Verify: Green buttons, 12px border radius
+   - Check: All 5 pizzas display correctly
+   - Test: Hover effects and scrolling work
+
+2. **Test custom carousel:**
+   - Ask: "Show me the pizza carousel with custom branding"
+   - Verify: Cyan buttons, 20px border radius
+   - Check: All 5 pizzas display correctly
+   - Test: Hover effects and scrolling work
+
+3. **Test switching:**
+   - Ask: "Now show the default version"
+   - Verify: Carousel switches to default styling
+   - Ask: "Now show the custom version"
+   - Verify: Carousel switches to custom styling
+
+## Troubleshooting
+
+### Token files not loading (404 errors)
+**Problem:** HTML shows unstyled content
+**Solution:** 
+- Verify token files exist in `assets/tokens/`
+- Check server logs for 404 errors
+- Ensure server is serving static assets from `/assets/` path
+
+### Styles not applying
+**Problem:** Carousel appears but with wrong colors
+**Solution:**
+- Open browser DevTools in ChatGPT
+- Check Network tab for CSS file loading
+- Verify CSS variables are defined in token files
+- Check that HTML uses `var(--variable-name)` syntax
+
+### Server won't start
+**Problem:** `npm start` fails
+**Solution:**
+- Check port 8000 is not already in use
+- Verify all dependencies are installed: `npm install`
+- Check for TypeScript errors in `src/server.ts`
+
+### ChatGPT can't connect
+**Problem:** MCP server not accessible from ChatGPT
+**Solution:**
+- Verify server is running and accessible
+- Check firewall settings
+- If using localhost, ensure ChatGPT can access local servers
+- If deployed, verify public URL is correct
+
+## Next Steps
+
+1. ✅ **Verification Complete** - All automated checks passed
+2. ⏳ **Local Testing** - Start server and test locally
+3. ⏳ **Deploy** - Push to GitHub and deploy to Render
+4. ⏳ **ChatGPT Integration** - Configure ChatGPT to use your MCP server
+5. ⏳ **User Testing** - Test both carousel variants in ChatGPT
+
+## Summary
+
+Your pizza carousel implementation is complete and ready for deployment! The MCP server is configured to serve both styling variants, and users will be able to switch between them using natural language commands in ChatGPT.
+
+**Key Features:**
+- ✅ Two distinct styling themes (default and custom)
+- ✅ Design token system for easy theming
+- ✅ All 5 pizzas with complete data
+- ✅ Interactive hover effects and smooth scrolling
+- ✅ MCP server tools configured and ready
+- ✅ Static asset serving for token CSS files
+
+**Ready to deploy!** 🚀

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pizzaz-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Pizzaz MCP server — themed pizza UI widgets for ChatGPT Apps SDK, deployed on Render",
+  "scripts": {
+    "dev": "vite --config vite.config.mts",
+    "build": "tsx ./build-all.mts",
+    "serve": "serve -s ./assets -p 4444 --cors",
+    "start": "tsx server/server.ts",
+    "tsc": "tsc -b"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@openai/apps-sdk-ui": "^0.2.1",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "clsx": "^2.1.1",
+    "embla-carousel": "^8.0.0",
+    "embla-carousel-react": "^8.0.0",
+    "framer-motion": "^12.23.12",
+    "lucide-react": "^0.536.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "react-router-dom": "^7.8.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.1.11",
+    "@types/node": "^24.3.0",
+    "@vitejs/plugin-react": "^4.5.2",
+    "autoprefixer": "10.4.21",
+    "fast-glob": "^3.3.3",
+    "postcss": "8.5.6",
+    "serve": "^14.2.4",
+    "tailwindcss": "4.1.11",
+    "tsx": "^4.20.4",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.1"
+  }
+}

package/render.yaml

@@ -0,0 +1,12 @@
+services:
+  - type: web
+    name: pizzaz-mcp
+    runtime: node
+    plan: free
+    buildCommand: npm install && BASE_URL=https://pizzaz-mcp.onrender.com npm run build
+    startCommand: npm start
+    envVars:
+      - key: NODE_ENV
+        value: production
+      - key: PORT
+        value: 10000