A starter template for building ChatGPT apps with interactive widgets using MCP (Model Context Protocol) on Val Town.

• Backend: Hono + MCP Lite + Drizzle ORM + SQLite
• Widget: React 19 + TanStack Router + OpenAI App SDK

1. Visit your deployment URL to get the MCP endpoint

2. Add to ChatGPT:

   • Open ChatGPT settings → Apps & Connectors -> Create (you will need developer mode enabled)
   • Add MCP server with your endpoint URL

3. Test in ChatGPT:

   • "List all messages"
   • "Add a message: Hello!"
   • "Show me message #1"
   • "Show me a counter widget"
   • "Show me a todo list"
   • "Show me the weather"

• list_messages - Shows all messages in an interactive widget
• add_message - Adds a new message and shows updated list
• get_message - Shows details for a specific message

• show_counter - Display an interactive counter with increment/decrement buttons
• increment_counter - Increment the counter by the step amount
• decrement_counter - Decrement the counter by the step amount
• reset_counter - Reset the counter to zero

• show_todos - Display an interactive todo list with progress tracking

• show_weather - Display current weather information for a location

The project includes several React widget components:

• CounterWidget (/counter) - Interactive counter with +/- buttons and reset
• TodoWidget (/todo) - Todo list with completion tracking and progress bar
• WeatherWidget (/weather) - Weather display with temperature, conditions, and stats
• DemoWidget (/demo) - Showcase page displaying all three widgets together

Tools return discriminated unions that drive widget navigation:

{ kind: "message_list", messages: [...] }      // → /list route
{ kind: "message_detail", id: 1, ... }         // → /detail/:id route
{ kind: "counter", count: 5, step: 1 }         // → /counter route
{ kind: "todo_list", todos: [...] }            // → /todo route
{ kind: "weather", location: "NYC", ... }      // → /weather route

The widget automatically navigates based on the kind field.

Messages are automatically scoped using the openai/subject field that ChatGPT includes in request metadata. This provides authless data isolation - each subject gets its own message board.

The scoping happens in tool handlers:

const subject = ctx.request.params._meta?.["openai/subject"];
const messages = await getMessages(subject);

The exact semantics of openai/subject are determined by ChatGPT.

1. Add tool in backend/mcp/server.ts
2. Define output schema in shared/types.ts
3. Create widget component in frontend/widgets/components/
4. Add route in frontend/widgets/routes.tsx
5. Update NavigationSync.tsx to handle new kind