Universal Menu (Apps SDK)

An interactive decision menu for ChatGPT Apps SDK connectors.
Surface contextual choices on every assistant turn—at the start of a reply, at the end, or both.
If your agent returns proposedItems, the widget renders them; otherwise, the server falls back to defaults (no OpenAI autogen).

Features

• Encourages continuous choice-making by rendering a menu on every assistant message.

• Works with pre-computed menus (proposedItems) or a lightweight default set.

• Streamable HTTP transport compatible with Smithery and other MCP clients.

• React widget packaged as an iframe resource (ui://widget/menu.html).

Requirements

• Node.js 18+ (Node 20+ recommended)

• Smithery account & API key (for smithery dev/build)

• HTTPS endpoint when connecting from ChatGPT (ngrok, Cloudflare Tunnel, etc.)

Setup

Smithery Quickstart

The project mirrors the Smithery TypeScript quickstart so you can develop and deploy with the official CLI.

1. Run the single build pipeline once (bundles the widget, embeds it, compiles TS, and produces the Smithery artifact):

   npm run build

2. Start the widget watcher in a dedicated terminal whenever you iterate on web/src:

   npm run dev:web

   After iterating, re-run npm run build so the embedded bundle in src/generated stays in sync.

3. In another terminal, run the MCP server through Smithery (requires SMITHERY_API_KEY):

   export SMITHERY_API_KEY=... # or set via smithery login npm run dev # internally runs `smithery dev`

   This establishes an ngrok tunnel to the Smithery Playground. Prompt with “Use the Universal Menu connector and show next steps.”

4. When you are ready to ship, run the same production build:

   npm run build

   Push the repo to GitHub, open https://smithery.ai/, and press Deploy to ship the server.

Local HTTP Server (without Smithery)

If you need to self-host or tunnel manually:

Installing via Smithery

To install Universal Menu automatically via Smithery:

Widget Preview

Stop the preview server with pkill -f "http.server 3333".
Sample screenshot: docs/menu-preview.png.

Quick Check with MCP Inspector

ChatGPT Developer Mode Setup

1. Start a new chat → “+” near the composer → Developer mode.

2. Add the MCP server via HTTPS URL pointing to /mcp (e.g. ngrok http 2091).

3. Enable the connector and prompt the model to call get_menu at the start or end of each reply, e.g. “On every response, use the ‘Universal Menu’ connector to offer available next steps.”

Deployment Notes

• Works on Fly.io, Render, Railway, Cloud Run, Azure Container Apps, or Kubernetes ingresses that support streaming responses.

• For quick demos, ngrok http 2091 gives an HTTPS tunnel like https://<subdomain>.ngrok.app/mcp.

Architecture

• Tool returns supplied items (or defaults) and should be invoked on every turn to keep options fresh.

• Tool handles a chosen option, performs follow-up logic, and returns an updated menu.

• React widget (web/src/Menu.tsx) renders the actions, persists widget state, and uses MCP callbacks (callTool, sendFollowupMessage, etc.).

Environment Variables

• PORT — HTTP port for npm start (default 2091)

• DEFAULT_TITLE — fallback menu title when the caller does not specify one

Project Structure

License

MIT