vibe board - a chatgpt app prototype

This is a social based planner/todo ChatGPT App built on Cloudflare Workers and Durable Objects. It adapts the official examples from the OpenAI Apps SDK repository. If you don't know what ChatGPT Apps are, start here: App Developer Guidelines.

Social interaction coming inside ChatGPT!

Architecture

Codebase basically split into two primary parts which can be considered as backend and frontend:

1. mcp-server/ (backend) – A Cloudflare Worker that implements the Model Context Protocol (MCP) using the official MCP TypeScript library and the Cloudflare agents SDK. It registers the tools, coordinates tool execution, and persists state through a Durable Object defined in mcp-server/store.ts. Durable objects are "stateful serverless" magic utilising SQLite. If you don't know what a great thing Durable Objects are start here: Durable Objects or watch this if you want to nerdmaxing: https://www.youtube.com/watch?v=C5-741uQPVU&t=314s

2. src/ – The UI package rendered by ChatGPT. It is a React/Tailwind frontend that is compiled into hashed HTML/JS/CSS assets and served by the Worker.

┌────────────────────────────────────────────────────────┐
│              Cloudflare Worker (mcp-server)            │
│  • @modelcontextprotocol/sdk + @cloudflare/agents      │
│  • Durable Object store (state, history, logs)         │
│  • Serves the widget template and handles tool calls   │
└────────────────────────────────────────────────────────┘
                  │
                  │ (Structured content + widget HTML)
                  ▼
┌────────────────────────────────────────────────────────┐
│                    ChatGPT UI Package (src)            │
│  • React + Vite + Tailwind                             │
│  • Compiled template delivered via MCP widget metadata │
└────────────────────────────────────────────────────────┘

Requirements

Install and configure the following before working with the app:

• Node.js v20 or later (matches Wrangler's Node compatibility and the toolchain assumptions).
• pnpm (bundled with Node.js) or another package manager of your choice. The repo ships with an pnpm lockfile.
• Wrangler CLI v4.42 or later (npm install -g wrangler). You need a Cloudflare account to run or deploy the Worker but should be fine for local dev.
• Optional (local UI preview): Vite (npm run dev:widget) if you prefer to run the widget in a browser outside ChatGPT. Note that this apps local Vite server is not working very well right now - TODO.

Getting Started

1. Install dependencies

   pnpm install
   

2. Build the widget assets

   pnpm build:widget
   

   This compiles the React UI in src/ and regenerates mcp-server/widget-manifest.ts with hashed HTML/JS/CSS assets.

3. Run the Worker locally

   pnpm dev
   

   Wrangler serves the Worker, Durable Object, and widget assets on http://localhost:8787.

4. Testing in ChatGPT

   To add the app to ChatGPT, enable developer mode, and click Create.

   ChatGPT Connectors require a publicly reachable URL, so you cannot paste http://localhost:8787 (the default Workers port) directly into the configuration. You can use Cloudflare's cloudflared tunnel client to expose your local server or other alternatives.

   1. Install cloudflared for your platform from the cloudflare/cloudflared GitHub releases.

   2. Start your local MCP server so it is listening on http://localhost:8787.

   3. In a separate terminal, run:

      cloudflared tunnel --url http://localhost:8787
      

      The command creates a temporary Quick Tunnel and prints a https://<random>.trycloudflare.com URL that proxies requests to your local service.

   4. Copy that URL into ChatGPT > Settings > Connectors when adding your app.

   For longer-lived tunnels (so the URL stays stable), authenticate with Cloudflare (cloudflared tunnel login) and create a named tunnel before running cloudflared tunnel run <NAME>.

5. After a change in UI: run pnpm build:widget, delete the connector from your profile and reconnect. this is the only solution to caching as of now. see known limitations at the bottom.

6. After a change with registered tools: click refresh in settings after clicking the app you've registered which should fetch new tools

7. (Optional)Admin UI

   pnpm run dev:admin
   

   this is a simple admin dashboard attemp that runs at http://localhost:5174 for rapid UI iteration.

Deploying to Cloudflare

• This should be straightforward with wrangler deploy and figuring out the commands and I'll update here after I get to deploy this.

Deep Down

• mcp-server/index.ts – Main Worker entry. Routes requests to the MCP server, serves the widget template, and proxies Durable Object operations.
• mcp-server/types.ts – Shared types covering board columns, tasks, and durable state.
• mcp-server/store.ts – Durable Object implementation backing todo state, logs, and history.
• mcp-server/config.ts – Imports the latest widget manifest, exposes metadata consumed by MCP tooling, and defines tool strings.
• scripts/build-widget.mts – Vite-based build script (inspired by OpenAI’s build-all.mts) that produces the widget assets and manifest.
• src/todo/index.tsx – React component shown inside the ChatGPT widget. Handles board rendering, activity feeds, and UI interactions.

Development Notes

• The Worker sets nodejs_compat in Wrangler, so Node APIs (e.g., crypto, fs during build) are available.
• Durable Objects require migrations; wrangler.jsonc defines the initial migration tag v1 for the TodoStore class. Modify this file and wrangler migrations if you change the schema.
• MCP tool registration and structured content responses live in mcp-server/index.ts. Customize or add tools there if you expand beyond todo features. use mcp-server/config.ts for string literals.
• Widget metadata (BASE_WIDGET_META) automatically references the latest hashed template and version, so ChatGPT always receives the correct assets after pnpm run build:widget.

Contribution:

This repository more of an example and probably going to evolve with OpenAI's update to the official SDK. If you want to contribute feel free to open an issue and suggest your changes before opening a pull request.

Known limitations:

1. Cloudflare mcp server places JSON-RPC request payloads into the cf-mcp-message HTTP header when bridging WebSocket connections to Durable Objects with JSON stringtify. This causes failures when message includes emojis as LLM's tend to send. I've created a pull request in the agents library with the fix and will update agents library version when it's merged.

2. Caching makes constant development challenging. this is addressed here and openai team replied with plans to bring hot reloading. I'll update the repo once that's done, monkey patches i've tried didn't work.

3. Friend graph is a dummy data, I haven't tried setting up OAuth2 yet given others couldn't make it work yet and I'd like to focus on what I can do right now. Real social interaction inside chatgpt coming soon!