Val Town ChatGPT App SDK Starter

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"

• 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

Tools return discriminated unions that drive widget navigation:

{ kind: "message_list", messages: [...] }      // → /list route
{ kind: "message_detail", id: 1, ... }         // → /detail/:id 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 route in frontend/widgets/routes.tsx
4. Update NavigationSync.tsx to handle new kind