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 + Cloudinary
• Widget: React 19 + TanStack Router + OpenAI App SDK

Before using the OpenCloset functionality, add these environment variables in Val Town:

• CLOUDINARY_CLOUD_NAME - Your Cloudinary cloud name
• CLOUDINARY_API_KEY - Your Cloudinary API key
• CLOUDINARY_API_SECRET - Your Cloudinary API secret
• CLOUDINARY_UPLOAD_PRESET - (Optional) Unsigned upload preset for easier setup

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"
   • "Show me an item card"
   • "Show me multiple wardrobe items"
   • "Show me an outfit"
   • Upload clothing photos and say "Add these to my closet as tops"
   • "Suggest an outfit from my closet"
   • "Show me all my closet items"

• 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

• show_item_card - Display a single wardrobe item card
• show_multi_item_card - Display multiple wardrobe items in a grid
• show_outfit_card - Display a complete outfit with top and bottom pieces

• opencloset.capture_items - Upload and categorize clothing photos to your closet
• opencloset.suggest_outfit - Get outfit suggestions from your saved items
• opencloset.list_items - View all items in your closet (with optional category filter)

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
• ItemCard - Individual wardrobe item display component
• MultiItemCard - Grid display for multiple wardrobe items
• OutfitCard - Complete outfit display with top and bottom pieces

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
{ kind: "item_card", item: {...} }             // → Individual ItemCard component
{ kind: "multi_item_card", items: [...] }      // → Individual MultiItemCard component
{ kind: "outfit_card", top: {...}, bottom: {...} } // → Individual OutfitCard component

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

For detailed information about the OpenCloset digital wardrobe functionality, see:

• OPENCLOSET.md - Complete implementation guide
• TESTING.md - Testing instructions for all widgets
• TROUBLESHOOTING.md - Fix common Cloudinary setup issues