Chatgpt App Todo
MCP server: Chatgpt App Todo
Installation
npx chatgpt-app-todoAsk AI about Chatgpt App Todo
Powered by Claude Β· Grounded in docs
I know everything about Chatgpt App Todo. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ChatGPT Todo App with MCP
Learn how to build a ChatGPT app with this step-by-step tutorial! This todo list application demonstrates how to integrate with ChatGPT using the Model Context Protocol (MCP). You'll discover how to create MCP tools that ChatGPT can call, build a React widget that appears in ChatGPT's interface, and implement real-time synchronization between ChatGPT conversations and your app's UI.
For the detailed step-by-step tutorial, you can read it here.
Architecture
MCP Server
The server implements the Model Context Protocol to expose task management capabilities to ChatGPT:
-
MCP Tools: Three tools are registered for ChatGPT to use:
createTask: Create a new todo taskgetTasks: Retrieve all taskscompleteTask: Mark a task as completed
-
Widget Resource: The server serves the React client as an embeddable widget (
ui://widget/chatgpt-app-todo.html) -
Tool Metadata: Each tool includes OpenAI-specific metadata:
openai/outputTemplate: Points to the UI widget for renderingopenai/widgetAccessible: Makes the widget accessible from tool outputsopenai/toolInvocation/*: Custom loading and success messages
Client with useOpenAiGlobal Hook
The React client uses the useOpenAiGlobal hook to integrate with ChatGPT's global state:
useOpenAiGlobal.js
This custom hook leverages React's useSyncExternalStore to:
- Subscribe to ChatGPT's global state changes via
openai:set_globalsevents - Access values from
window.openaiobject - Automatically re-render when ChatGPT updates tool outputs
Key Features:
const toolOutput = useOpenAiGlobal("toolOutput");
- When ChatGPT invokes an MCP tool, the
toolOutputvalue updates - The client automatically fetches and refreshes the task list
- Provides real-time synchronization between ChatGPT actions and the UI
How It Works
- Widget Rendering: When ChatGPT calls an MCP tool, the client app is rendered as a widget
- State Synchronization: The
useOpenAiGlobalhook detects tool outputs and refreshes the UI - Interactive UI: Users can interact with the widget directly (add, complete tasks)
- Natural Language: Users can also manage tasks through ChatGPT conversation
Setup
Prerequisites
- Node.js 18+
- npm or yarn
Installation
- Install dependencies:
# Install root dependencies
npm install
# Install server dependencies
cd server
npm install
# Install client dependencies
cd ../client
npm install
Build the Client
Build the React client before starting the server:
cd client
npm run build
This creates the client/dist directory that the server will serve.
Run the Server
Start the MCP server:
cd server
npm run dev
The server runs on http://localhost:3000.
Connect App with ChatGPT
To use this app with ChatGPT, you'll need to expose your local server and connect it to ChatGPT.
1. Expose Local Server with ngrok
Since ChatGPT needs to access your local server, use ngrok to create a public URL:
# Install ngrok (if not already installed)
# Visit https://ngrok.com/ to download
# Start ngrok tunnel to your local server
ngrok http 3000
This will generate a public URL like: https://xxxx-xx-xx-xx-xx.ngrok-free.app
Important: Make sure your server is running on http://localhost:3000 before starting ngrok.
2. Configure MCP in ChatGPT
- Open ChatGPT (use the desktop or web app)
- Go to Settings β Apps & Connectors
- Click Create
- Input your information and paste your ngrok URL with the
/mcpendpoint to MCP Server URL:https://your-ngrok-url.ngrok-free.app/mcp - Save
3. Start Using Natural Language
Once connected, you can use natural language commands in ChatGPT:
- Type "@ChatGPT App Todo" for including your app.
- "Create a new task: Buy groceries"
- "Show me all my tasks"
- "Complete task 1"
- "Mark the grocery shopping task as done"
4. Widget Interaction
When ChatGPT calls any task-related tool:
- The todo app widget appears in the ChatGPT interface
- The widget displays all tasks with a progress bar
- You can add tasks directly in the widget
- You can check off completed tasks by clicking checkboxes
Troubleshooting
- Connection fails: Verify your server is running and ngrok tunnel is active
- Widget not showing: Make sure you ran
npm run buildin the client directory - Tasks not syncing: Check browser console for CORS or network errors
Development
Project Structure
chatgpt-app-todo/
βββ server/ # MCP server with Express
β βββ index.js # MCP server, tools, and REST API
β βββ package.json
βββ client/ # React client app
β βββ src/
β β βββ App.jsx # Main UI component
β β βββ useOpenAiGlobal.js # ChatGPT integration hook
β β βββ main.jsx
β βββ package.json
βββ README.md
Technologies
Server:
- Express.js - Web server
- @modelcontextprotocol/sdk - MCP protocol implementation
- Zod - Schema validation
Client:
- React 19 - UI library
- Vite - Build tool
- Tailwind CSS - Styling
- useSyncExternalStore - React hook for external state management
Features
- β Create tasks via ChatGPT or UI
- β View all tasks with progress tracking
- β Complete tasks with a click or voice command
- β Real-time sync between ChatGPT and widget
- β Beautiful, modern UI with Tailwind CSS
- β Responsive design
How useOpenAiGlobal Works
The useOpenAiGlobal hook creates a bridge between ChatGPT and your React app:
- External Store Pattern: Uses React's
useSyncExternalStoreto manage state outside React - Event Listening: Listens for
openai:set_globalscustom events - Global Access: Reads values from
window.openai[key] - Automatic Updates: Triggers re-renders when ChatGPT updates tool outputs
This pattern enables the widget to respond instantly when ChatGPT executes MCP tools, creating a seamless interactive experience.
License
ISC
