[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-73896":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":15,"starSnapshotCount":15,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},73896,"openai-apps-sdk-examples","openai\u002Fopenai-apps-sdk-examples","openai","Example apps for the Apps SDK",null,"TypeScript",2251,506,43,105,0,18,61.92,"MIT License",false,"main",true,[],"2026-06-12 04:01:12","# Apps SDK Examples Gallery\n\n[![MIT License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-green.svg)](LICENSE)\n\nThis repository showcases example UI components to be used with the [Apps SDK](https:\u002F\u002Fdevelopers.openai.com\u002Fapps-sdk), as well as example MCP servers that expose a collection of components as tools.\nIt is meant to be used as a starting point and source of inspiration to build your own apps for ChatGPT.\n\nNote: If you are on Chrome and have recently updated to version 142, you will need to disable the [`local-network-access` flag](https:\u002F\u002Fdeveloper.chrome.com\u002Frelease-notes\u002F142#local_network_access_restrictions) to see the widget UI.\n\nHow to disable it:\n\n1. Go to chrome:\u002F\u002Fflags\u002F\n2. Find #local-network-access-check\n3. Set it to Disabled\n\n⚠️ **Note 🚨 Make sure to restart Chrome after changing this flag for the update to take effect.**\n\n## MCP + Apps SDK overview\n\nThe 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.\n\nWithin 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:\n\n1. **List tools** – Your server advertises the tools it supports, including their JSON Schema input\u002Foutput contracts and optional annotations (for example, `readOnlyHint`).\n2. **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.\n3. **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).\n\nBecause the protocol is transport agnostic, you can host the server over Server-Sent Events or streaming HTTP—Apps SDK supports both.\n\nThe MCP servers in this demo highlight how each tool can light up widgets by combining structured payloads with `_meta.ui.resourceUri` metadata returned from the MCP servers.\n\n## Repository structure\n\n- `src\u002F` – Source for each widget example.\n- `assets\u002F` – Generated HTML, JS, and CSS bundles after running the build step.\n- `shopping_cart_python\u002F` – Python MCP server that demonstrates how `_meta[\"widgetSessionId\"]` keeps `widgetState` in sync across turns for a shopping-cart widget.\n- `pizzaz_server_node\u002F` – MCP server implemented with the official TypeScript SDK.\n- `pizzaz_server_python\u002F` – Python MCP server that returns the Pizzaz widgets.\n- `solar-system_server_python\u002F` – Python MCP server for the 3D solar system widget.\n- `kitchen_sink_server_node\u002F` – Node MCP server for the kitchen-sink-lite widget.\n- `kitchen_sink_server_python\u002F` – Python MCP server for the kitchen-sink-lite widget.\n- `authenticated_server_python\u002F` – Python MCP server that demonstrates authenticated tool calls.\n- `build-all.mts` – Vite build orchestrator that produces hashed bundles for every widget entrypoint.\n\n### Pizzaz overview\n\nThis example contains multiple components showing multiple types of views and interactions: a list view, a carousel view, a map view. It also contains a \"pizzaz shop\" showing interactive flows and a checkout page.\n\nThis example uses the [Apps SDK UI library](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fapps-sdk-ui) for simple components such as images, buttons, and badges.\n\n### Kitchen sink lite overview\n\nThe kitchen sink lite sample shows the full `window.openai` surface working together:\n\n- Reads host state (`toolInput`, `toolOutput`, `displayMode`, `theme`, `widgetState`).\n- Writes host state with `setWidgetState`.\n- Calls another MCP tool from the widget with `callTool`.\n- Uses host helpers like `requestDisplayMode`, `openExternal`, and `sendFollowUpMessage`.\n\nUse it as a reference for how to wire UI to MCP tool responses and host APIs with the Apps SDK UI components.\n\n## Prerequisites\n\n- Node.js 18+\n- pnpm (recommended) or npm\u002Fyarn\n- Python 3.10+ (for the Python MCP server)\n- pre-commit for formatting\n\n## Install dependencies\n\nClone the repository and install the workspace dependencies:\n\n```bash\npnpm install\npre-commit install\n```\n\n> Using npm or yarn? Install the root dependencies with your preferred client and adjust the commands below accordingly.\n\n## Build the components gallery\n\nThe components are bundled into standalone assets that the MCP servers serve as reusable UI resources.\n\n```bash\npnpm run build\n```\n\nThis command runs `build-all.mts`, producing versioned `.html`, `.js`, and `.css` files inside `assets\u002F`. Each widget is wrapped with the CSS it needs so you can host the bundles directly or ship them with your own server.\n\nTo iterate on your components locally, you can also launch the Vite dev server:\n\n```bash\npnpm run dev\n```\n\n## Serve the static assets\n\nAll of the MCP servers expect the bundled HTML, JS, and CSS to be served from the local static file server. After every build, start the server before launching any MCP processes:\n\n```bash\npnpm run serve\n```\n\nThe assets are exposed at [`http:\u002F\u002Flocalhost:4444`](http:\u002F\u002Flocalhost:4444) with CORS enabled so that local tooling (including MCP inspectors) can fetch them.\n\n> **Note:** The Python Pizzaz server caches widget HTML with `functools.lru_cache`. If you rebuild or manually edit files in `assets\u002F`, restart the MCP server so it picks up the updated markup.\n\n## Run the MCP servers\n\nThe repository ships several demo MCP servers that highlight different widget bundles:\n\n- **Pizzaz (Node & Python)** – pizza-inspired collection of tools and components\n- **Solar system (Python)** – 3D solar system viewer\n- **Authenticated (Python)** – set of tools that require different levels of OAuth\n- **Kitchen sink lite (Node & Python)** – minimal widget + server pairing that demonstrates tool output, widget state, `callTool`, and host helpers\n- **Shopping cart (Python)** – simple shopping cart widget that demonstrates how to use `widgetSessionId` to keep state between tool calls\n\n### Pizzaz Node server\n\n```bash\ncd pizzaz_server_node\npnpm start\n```\n\n### Pizzaz Python server\n\n```bash\npython -m venv .venv\nsource .venv\u002Fbin\u002Factivate\npip install -r pizzaz_server_python\u002Frequirements.txt\nuvicorn pizzaz_server_python.main:app --port 8000\n```\n\n### Authenticated Python server\n\n```bash\npython -m venv .venv\nsource .venv\u002Fbin\u002Factivate\npip install -r authenticated_server_python\u002Frequirements.txt\nuvicorn authenticated_python_server.main:app --port 8000\n```\n\n### Solar system Python server\n\n```bash\npython -m venv .venv\nsource .venv\u002Fbin\u002Factivate\npip install -r solar-system_server_python\u002Frequirements.txt\nuvicorn solar-system_server_python.main:app --port 8000\n```\n\n### Kitchen sink lite Node server\n\n```bash\npnpm --filter kitchen-sink-mcp-node start\n```\n\n### Kitchen sink lite Python server\n\n```bash\npython -m venv .venv\nsource .venv\u002Fbin\u002Factivate\npip install -r kitchen_sink_server_python\u002Frequirements.txt\nuvicorn kitchen_sink_server_python.main:app --port 8000\n```\n\n### Shopping cart Python server\n\nUse this example to learn how `_meta[\"widgetSessionId\"]` can carry `widgetState` between tool calls so the model and widget share the same shopping cart. The widget merges tool responses with prior `widgetState`, and UI actions (like incrementing quantities) feed back into that shared state so the assistant always sees the latest cart.\n\n```bash\npython -m venv .venv\nsource .venv\u002Fbin\u002Factivate\npip install -r shopping_cart_python\u002Frequirements.txt\nuvicorn shopping_cart_python.main:app --port 8000\n```\n\n> [!NOTE]\n> In production you should persist the cart server-side (see [shopping_cart_python\u002FREADME.md](shopping_cart_python\u002FREADME.md)), but this demo shows the mechanics of keeping state through `widgetSessionId`.\n\n---\n\nYou can reuse the same virtual environment for all Python servers—install the dependencies once and run whichever entry point you need.\n\n## Testing in ChatGPT\n\nTo add these apps to ChatGPT, enable [developer mode](https:\u002F\u002Fplatform.openai.com\u002Fdocs\u002Fguides\u002Fdeveloper-mode), and add your apps in Settings > Connectors.\n\nTo add your local server without deploying it, you can use a tool like [ngrok](https:\u002F\u002Fngrok.com\u002F) to expose your local server to the internet.\n\nFor example, once your mcp servers are running, you can run:\n\n```bash\nngrok http 8000\n```\n\nYou will get a public URL that you can use to add your local server to ChatGPT in Settings > Connectors.\n\nFor example: `https:\u002F\u002F\u003Ccustom_endpoint>.ngrok-free.app\u002Fmcp`\n\n> [!IMPORTANT]\n> The Python MCP SDK enforces DNS rebinding protection. When tunneling (for example via ngrok), allow your tunnel host before starting any Python server:\n>\n> ```bash\n> export MCP_ALLOWED_HOSTS=\"\u003Ccustom_endpoint>.ngrok-free.app\"\n> export MCP_ALLOWED_ORIGINS=\"https:\u002F\u002F\u003Ccustom_endpoint>.ngrok-free.app\"\n> ```\n\nOnce you add a connector, you can use it in ChatGPT conversations.\n\nYou can add your app to the conversation context by selecting it in the \"More\" options.\n\n![more-chatgpt](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F26852b36-7f9e-4f48-a515-aebd87173399)\n\nYou can then invoke tools by asking something related. For example, for the Pizzaz app, you can ask \"What are the best pizzas in town?\".\n\n## Next steps\n\n- Customize the widget data: edit the handlers in `pizzaz_server_node\u002Fsrc`, `pizzaz_server_python\u002Fmain.py`, or the solar system server to fetch data from your systems.\n- Create your own components and add them to the gallery: drop new entries into `src\u002F` and they will be picked up automatically by the build script.\n\n### Deploy your MCP server\n\nYou can use the cloud environment of your choice to deploy your MCP server.\n\nInclude this in the environment variables:\n\n```\nBASE_URL=https:\u002F\u002Fyour-server.com\nAPI_BASE_URL=https:\u002F\u002Fyour-api.example.com\n```\n\nThis will be used to generate the HTML for the widgets so that they can serve static assets from this hosted url. `API_BASE_URL` is used by client widgets to build fully-qualified API URLs (for example, the Cards Against AI game event stream).\n\n## Contributing\n\nYou are welcome to open issues or submit PRs to improve this app, however, please note that we may not review all suggestions.\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](.\u002FLICENSE) for details.\n","该项目提供了与OpenAI Apps SDK配套使用的示例应用程序，旨在帮助开发者构建ChatGPT插件。核心功能包括通过Model Context Protocol (MCP)协议定义的工具列表、工具调用及返回嵌入式资源以支持丰富用户界面组件的渲染。技术特点上，项目采用TypeScript编写，并且展示了如何使用MCP服务器（支持Node.js和Python实现）来增强聊天机器人的交互体验，允许其访问外部工具或数据。适合希望为ChatGPT创建自定义扩展功能的应用场景，如集成特定领域的知识库、在线服务接口等。",2,"2026-06-11 03:47:49","high_star"]