Val Town ChatGPT App SDK Starter

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

\n\n

Setup Instructions

\n Copy your MCP endpoint URL:\n
\n
\n Add to ChatGPT:\n
- Open ChatGPT settings
- Navigate to \"Apps\" or \"Integrations\"
- Click \"Add MCP Server\"
- Paste your MCP endpoint URL
\n
\n Test the integration:\n
- Ask ChatGPT: \"List all messages\"
- The widget should appear with the message board interface
\n

\n\n

Available Tools

list_messages - Shows all messages in a widget
get_message - Shows details for a specific message
add_message - Adds a new message to the board

\n\n

Development

Edit the code in backend/ and frontend/widgets/ to customize your app. Changes deploy instantly to Val Town.

\n\n \n\n\n","0199ce87-fbda-7524-96e6-f67c6a1cd463",["D",1760106642287],"branchVersion","label",[166,67],"frontend","pulls","branches","forks","envVars",{"_174":26,"_176":26},"connections",{"_174":26,"_175":26},"count","unfilledCount","emptyCount",{"_32":408,"_13":348,"_65":342,"_42":-5,"_34":35,"_163":39,"_211":85,"_36":409,"_38":26,"_68":256,"_159":-5,"_69":24,"_164":-5,"_214":410,"_17":411},{"_32":404,"_13":376,"_65":371,"_42":342,"_34":35,"_163":39,"_211":85,"_36":405,"_38":26,"_68":256,"_159":-5,"_69":24,"_164":-5,"_214":406,"_17":407},{"_32":398,"_13":218,"_65":399,"_42":371,"_34":35,"_163":39,"_211":85,"_36":400,"_38":26,"_68":21,"_159":401,"_69":24,"_164":-5,"_214":402,"_17":403},{"_32":391,"_13":392,"_65":393,"_42":371,"_34":35,"_163":39,"_211":85,"_36":394,"_38":26,"_68":236,"_159":395,"_69":24,"_164":-5,"_214":396,"_17":397},{"_32":384,"_13":385,"_65":386,"_42":371,"_34":35,"_163":39,"_211":85,"_36":387,"_38":26,"_68":236,"_159":388,"_69":24,"_164":-5,"_214":389,"_17":390},{"_32":377,"_13":378,"_65":379,"_42":371,"_34":35,"_163":39,"_211":85,"_36":380,"_38":26,"_68":236,"_159":381,"_69":24,"_164":-5,"_214":382,"_17":383},{"_32":368,"_13":369,"_65":370,"_42":371,"_34":35,"_163":39,"_211":85,"_36":372,"_38":26,"_68":236,"_159":373,"_69":24,"_164":-5,"_214":374,"_17":375},{"_32":364,"_13":363,"_65":358,"_42":342,"_34":35,"_163":39,"_211":85,"_36":365,"_38":26,"_68":256,"_159":-5,"_69":24,"_164":-5,"_214":366,"_17":367},{"_32":355,"_13":356,"_65":357,"_42":358,"_34":35,"_163":39,"_211":85,"_36":359,"_38":26,"_68":236,"_159":360,"_69":24,"_164":-5,"_214":361,"_17":362},{"_32":349,"_13":218,"_65":350,"_42":342,"_34":35,"_163":39,"_211":85,"_36":351,"_38":26,"_68":21,"_159":352,"_69":24,"_164":-5,"_214":353,"_17":354},{"_32":340,"_13":341,"_65":83,"_42":342,"_34":35,"_163":39,"_211":85,"_36":343,"_38":26,"_68":344,"_159":345,"_69":24,"_164":-5,"_214":346,"_17":347},{"_32":336,"_13":166,"_65":161,"_42":-5,"_34":35,"_163":39,"_211":85,"_36":337,"_38":26,"_68":256,"_159":-5,"_69":24,"_164":-5,"_214":338,"_17":339},{"_32":332,"_13":270,"_65":265,"_42":161,"_34":35,"_163":39,"_211":85,"_36":333,"_38":26,"_68":256,"_159":-5,"_69":24,"_164":-5,"_214":334,"_17":335},{"_32":328,"_13":313,"_65":308,"_42":265,"_34":35,"_163":39,"_211":85,"_36":329,"_38":26,"_68":256,"_159":-5,"_69":24,"_164":-5,"_214":330,"_17":331},{"_32":321,"_13":322,"_65":323,"_42":308,"_34":35,"_163":39,"_211":85,"_36":324,"_38":26,"_68":236,"_159":325,"_69":24,"_164":-5,"_214":326,"_17":327},{"_32":314,"_13":315,"_65":316,"_42":308,"_34":35,"_163":39,"_211":85,"_36":317,"_38":26,"_68":236,"_159":318,"_69":24,"_164":-5,"_214":319,"_17":320},{"_32":305,"_13":306,"_65":307,"_42":308,"_34":35,"_163":39,"_211":85,"_36":309,"_38":26,"_68":236,"_159":310,"_69":24,"_164":-5,"_214":311,"_17":312},{"_32":298,"_13":299,"_65":300,"_42":265,"_34":35,"_163":39,"_211":85,"_36":301,"_38":26,"_68":236,"_159":302,"_69":24,"_164":-5,"_214":303,"_17":304},{"_32":291,"_13":292,"_65":293,"_42":265,"_34":35,"_163":39,"_211":85,"_36":294,"_38":26,"_68":236,"_159":295,"_69":24,"_164":-5,"_214":296,"_17":297},{"_32":285,"_13":67,"_65":286,"_42":265,"_34":35,"_163":39,"_211":85,"_36":287,"_38":26,"_68":21,"_159":288,"_69":24,"_164":-5,"_214":289,"_17":290},{"_32":278,"_13":279,"_65":280,"_42":265,"_34":35,"_163":39,"_211":85,"_36":281,"_38":26,"_68":236,"_159":282,"_69":24,"_164":-5,"_214":283,"_17":284},{"_32":271,"_13":272,"_65":273,"_42":265,"_34":35,"_163":39,"_211":85,"_36":274,"_38":26,"_68":236,"_159":275,"_69":24,"_164":-5,"_214":276,"_17":277},{"_32":262,"_13":263,"_65":264,"_42":265,"_34":35,"_163":39,"_211":85,"_36":266,"_38":26,"_68":236,"_159":267,"_69":24,"_164":-5,"_214":268,"_17":269},{"_32":158,"_13":67,"_65":66,"_42":161,"_34":35,"_163":39,"_211":85,"_36":259,"_38":26,"_68":21,"_159":160,"_69":24,"_164":-5,"_214":260,"_17":261},{"_32":254,"_13":240,"_65":234,"_42":-5,"_34":35,"_163":39,"_211":85,"_36":255,"_38":26,"_68":256,"_159":-5,"_69":24,"_164":-5,"_214":257,"_17":258},{"_32":248,"_13":218,"_65":249,"_42":234,"_34":35,"_163":39,"_211":85,"_36":250,"_38":26,"_68":21,"_159":251,"_69":24,"_164":-5,"_214":252,"_17":253},{"_32":241,"_13":242,"_65":243,"_42":234,"_34":35,"_163":39,"_211":85,"_36":244,"_38":26,"_68":236,"_159":245,"_69":24,"_164":-5,"_214":246,"_17":247},{"_32":231,"_13":232,"_65":233,"_42":234,"_34":35,"_163":39,"_211":85,"_36":235,"_38":26,"_68":236,"_159":237,"_69":24,"_164":-5,"_214":238,"_17":239},{"_32":224,"_13":225,"_65":226,"_42":-5,"_34":35,"_163":39,"_211":85,"_36":227,"_38":26,"_68":21,"_159":228,"_69":24,"_164":-5,"_214":229,"_17":230},{"_32":217,"_13":218,"_65":219,"_42":-5,"_34":35,"_163":39,"_211":85,"_36":220,"_38":26,"_68":21,"_159":221,"_69":24,"_164":-5,"_214":222,"_17":223},{"_32":208,"_13":209,"_65":210,"_42":-5,"_34":35,"_163":39,"_211":85,"_36":212,"_38":26,"_68":21,"_159":213,"_69":24,"_164":-5,"_214":215,"_17":216},"b3622754-a5e5-11f0-8f15-0224a6c84d84","deno.json","0199ce87-fbda-7524-96e7-12f8394e4ac2","latest",["D",1760106642287],"{\n \"$schema\": \"https://raw.githubusercontent.com/denoland/deno/348900b8b79f4a434cab4c74b3bc8d4d2fa8ee74/cli/schemas/config-file.v1.json\",\n \"lock\": false,\n \"compilerOptions\": {\n \"noImplicitAny\": false,\n \"strict\": false,\n \"types\": [\n \"https://www.val.town/types/valtown.d.ts\"\n ],\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ]\n },\n \"lint\": {\n \"files\": {\n \"include\": [\n \"deno:/https/esm.town/**/*\"\n ]\n },\n \"rules\": {\n \"exclude\": [\n \"no-explicit-any\"\n ]\n }\n },\n \"node_modules_dir\": false,\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true,\n \"unstable-sloppy-imports\": true\n }\n}","children",[],[209],"b3622542-a5e5-11f0-8f15-0224a6c84d84","README.md","0199ce87-fbda-7524-96e7-0d8a9db452b9",["D",1760106642287],"# Val Town ChatGPT App SDK Starter\n\nA starter template for building ChatGPT apps with interactive widgets using MCP (Model Context Protocol) on Val Town.\n\n## Tech Stack\n\n- **Backend**: Hono + MCP Lite + Drizzle ORM + SQLite\n- **Widget**: React 19 + TanStack Router + OpenAI App SDK\n\n## Quick Start\n\n\n1. Visit your deployment URL to get the MCP endpoint\n\n2. Add to ChatGPT:\n - Open ChatGPT settings → Apps & Connectors -> Create (you will need developer mode enabled)\n - Add MCP server with your endpoint URL\n\n4. Test in ChatGPT:\n - \"List all messages\"\n - \"Add a message: Hello!\"\n - \"Show me message #1\"\n\n## Available Tools\n\n- `list_messages` - Shows all messages in an interactive widget\n- `add_message` - Adds a new message and shows updated list\n- `get_message` - Shows details for a specific message\n\n## How It Works\n\nTools return discriminated unions that drive widget navigation:\n\n```typescript\n{ kind: \"message_list\", messages: [...] } // → /list route\n{ kind: \"message_detail\", id: 1, ... } // → /detail/:id route\n```\n\nThe widget automatically navigates based on the `kind` field.\n\n## Where do I go from here?\n\n1. Add tool in `backend/mcp/server.ts`\n2. Define output schema in `shared/types.ts`\n3. Create widget route in `frontend/widgets/routes.tsx`\n4. Update `NavigationSync.tsx` to handle new `kind`\n\n",[],[218],"b362240c-a5e5-11f0-8f15-0224a6c84d84",".vtignore","0199ce87-fbda-7524-96e7-0b44073fa6ec",["D",1760106642287],".git\n.vscode\n.cursorrules\n.DS_Store\nnode_modules\nvendor",[],[225],"b3622132-a5e5-11f0-8f15-0224a6c84d84","utils.ts","0199ce87-fbda-7524-96e7-014910ff08e4","0199ce87-fbda-7524-96e7-05b707581d2d",["D",1760106642287],"script","export type { Message } from \"./types.ts\";\n\nexport const MESSAGE_LIMIT = 5;",[],[240,232],"shared","b3621f70-a5e5-11f0-8f15-0224a6c84d84","types.ts","0199ce87-fbda-7524-96e6-fc05b44f77ed",["D",1760106642287],"import { z } from \"https://esm.sh/zod@4\";\n\n// Message schema\nexport const MessageSchema = z.object({\n id: z.number(),\n content: z.string(),\n timestamp: z.string(),\n});\n\n// Widget output schemas with discriminators\nexport const MessageListOutputSchema = z.object({\n kind: z.literal(\"message_list\"),\n messages: z.array(MessageSchema),\n});\n\nexport const MessageDetailOutputSchema = MessageSchema.extend({\n kind: z.literal(\"message_detail\"),\n});\n\n// Inferred TypeScript types\nexport type Message = z.infer;\nexport type MessageListOutput = z.infer;\nexport type MessageDetailOutput = z.infer;\n\n// Discriminated union for all widget states\nexport type WidgetState = MessageListOutput | MessageDetailOutput;\n",[],[240,242],"b3621dc2-a5e5-11f0-8f15-0224a6c84d84","0199ce87-fbda-7524-96e6-fa92d0d62dc7",["D",1760106642287],"# Shared\n\nIt's common to have code and types that are needed on both the frontend and the backend. It's important that you write this code in a particularly defensive way because it's limited by what both environments support:\n\n![shapes at 25-02-25 11.57.13.png](https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/75db1d51-d9b3-45e0-d178-25d886c10700/public)\n\nFor example, you *cannot* use the `Deno` keyword. For imports, you can't use `npm:` specifiers, so we reccomend `https://esm.sh` because it works on the server & client. You *can* use TypeScript because that is transpiled in `/backend/index.ts` for the frontend. Most code that works on the frontend tends to work in Deno, because Deno is designed to support \"web-standards\", but there are definitely edge cases to look out for.",[],[240,218],"b36222fe-a5e5-11f0-8f15-0224a6c84d84",["D",1760106642287],"directory",[202,203,204],[240],["D",1760106642287],[],[166,67],"b36217d2-a5e5-11f0-8f15-0224a6c84d84","widget.tsx","0199ce87-fbda-7524-96e6-e96b6839065a","0199ce87-fbda-7524-96e6-ee0ed769666d",["D",1760106642287],"/** @jsxImportSource https://esm.sh/react@19 */\nimport { createRoot } from \"https://esm.sh/react-dom@19/client?deps=react@19\";\nimport { RouterProvider } from \"https://esm.sh/@tanstack/react-router@1?deps=react@19\";\nimport { router } from \"./routes.tsx\";\n\nconst appElement = document.getElementById(\"app\");\nif (!appElement) {\n throw new Error(\"App element not found\");\n}\n\nconst root = createRoot(appElement);\nroot.render();\n",[],[166,270,263],"widgets","b36215ca-a5e5-11f0-8f15-0224a6c84d84","routes.tsx","0199ce87-fbda-7524-96e6-e6ef2e2f2b95",["D",1760106642287],"/** @jsxImportSource https://esm.sh/react@19 */\nimport {\n createRootRoute,\n createRoute,\n createRouter,\n Outlet,\n} from \"https://esm.sh/@tanstack/react-router@1?deps=react@19\";\nimport { LoadingWidget } from \"./components/LoadingWidget.tsx\";\nimport { MessageListWidget } from \"./components/MessageListWidget.tsx\";\nimport { MessageDetailWidget } from \"./components/MessageDetailWidget.tsx\";\nimport { NavigationSync } from \"./NavigationSync.tsx\";\n\nfunction RootComponent() {\n return (\n <>\n \n \n \n );\n}\n\nconst rootRoute = createRootRoute({\n component: RootComponent,\n});\n\nconst loadingRoute = createRoute({\n getParentRoute: () => rootRoute,\n path: \"/\",\n component: LoadingWidget,\n});\n\nconst listRoute = createRoute({\n getParentRoute: () => rootRoute,\n path: \"/list\",\n component: MessageListWidget,\n});\n\nconst detailRoute = createRoute({\n getParentRoute: () => rootRoute,\n path: \"/detail/$messageId\",\n component: MessageDetailWidget,\n});\n\nconst routeTree = rootRoute.addChildren([\n loadingRoute,\n listRoute,\n detailRoute,\n]);\n\nexport const router = createRouter({ routeTree });\n\ndeclare module \"https://esm.sh/@tanstack/react-router@1?deps=react@19\" {\n interface Register {\n router: typeof router;\n }\n}\n",[],[166,270,272],"b3620fb2-a5e5-11f0-8f15-0224a6c84d84","openai-types.ts","0199ce87-fbda-7524-96e6-e271439a3c20",["D",1760106642287],"type UnknownObject = Record;\n\nexport interface OpenAiGlobals<\n ToolInput extends UnknownObject = UnknownObject,\n ToolOutput extends UnknownObject = UnknownObject,\n ToolResponseMetadata extends UnknownObject = UnknownObject,\n WidgetState extends UnknownObject = UnknownObject,\n> {\n theme: \"light\" | \"dark\";\n userAgent: {\n device: { type: \"mobile\" | \"tablet\" | \"desktop\" | \"unknown\" };\n capabilities: {\n hover: boolean;\n touch: boolean;\n };\n };\n locale: string;\n maxHeight: number;\n displayMode: \"pip\" | \"inline\" | \"fullscreen\";\n safeArea: {\n insets: {\n top: number;\n bottom: number;\n left: number;\n right: number;\n };\n };\n toolInput: ToolInput;\n toolOutput: ToolOutput | null;\n toolResponseMetadata: ToolResponseMetadata | null;\n widgetState: WidgetState | null;\n}\n\nexport interface OpenAIWidgetAPI<\n ToolInput extends UnknownObject = UnknownObject,\n ToolOutput extends UnknownObject = UnknownObject,\n ToolResponseMetadata extends UnknownObject = UnknownObject,\n WidgetState extends UnknownObject = UnknownObject,\n> extends OpenAiGlobals<\n ToolInput,\n ToolOutput,\n ToolResponseMetadata,\n WidgetState\n > {\n setWidgetState: (state: WidgetState) => Promise;\n callTool: (name: string, args: unknown) => Promise;\n sendFollowUpMessage: (params: { prompt: string }) => Promise;\n requestDisplayMode: (mode: \"pip\" | \"inline\" | \"fullscreen\") => Promise;\n}\n\nexport const SET_GLOBALS_EVENT_TYPE = \"openai:set_globals\";\n\nexport interface SetGlobalsEvent\n extends CustomEvent<{ globals: Partial }> {\n type: typeof SET_GLOBALS_EVENT_TYPE;\n}\n\ndeclare global {\n interface Window {\n openai: OpenAIWidgetAPI;\n }\n\n interface WindowEventMap {\n [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent;\n }\n}\n\nexport function getOpenAI(): OpenAIWidgetAPI | undefined {\n return window.openai;\n}\n",[],[166,270,279],"b3620e2c-a5e5-11f0-8f15-0224a6c84d84","0199ce87-fbda-7524-96e6-dc9bc3ae9175",["D",1760106642287],"\n\n \n \n \n Widget\n \n \n \n \n

\n \n \n\n",[],[166,270,67],"b3620b34-a5e5-11f0-8f15-0224a6c84d84","hooks.ts","0199ce87-fbda-7524-96e6-d968a01fcb12",["D",1760106642287],"/** @jsxImportSource https://esm.sh/react@19 */\nimport { useCallback, useEffect, useState, useSyncExternalStore } from \"https://esm.sh/react@19\";\nimport type { OpenAiGlobals, SetGlobalsEvent } from \"./openai-types.ts\";\nimport { getOpenAI, SET_GLOBALS_EVENT_TYPE } from \"./openai-types.ts\";\n\ntype UnknownObject = Record;\n\nexport function useOpenAiGlobal(\n key: K,\n): OpenAiGlobals[K] {\n return useSyncExternalStore(\n (onChange) => {\n function handleSetGlobal(event: Event) {\n const setGlobalsEvent = event as SetGlobalsEvent;\n const value = setGlobalsEvent.detail?.globals[key];\n\n if (value === undefined) return;\n onChange();\n }\n\n window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {\n passive: true,\n });\n\n return () => {\n window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);\n };\n },\n () => window.openai[key],\n );\n}\n\nexport function useToolOutput(): T | null {\n return useOpenAiGlobal(\"toolOutput\") as T | null;\n}\n\nexport function useTheme(): \"light\" | \"dark\" {\n return useOpenAiGlobal(\"theme\");\n}\n\nexport function useWidgetState(\n defaultState: T | (() => T),\n): readonly [T, (state: React.SetStateAction) => void] {\n const widgetStateFromWindow = useOpenAiGlobal(\"widgetState\") as T | null;\n\n const [widgetState, _setWidgetState] = useState(() => {\n return (\n widgetStateFromWindow ??\n (typeof defaultState === \"function\" ? defaultState() : defaultState)\n );\n });\n\n useEffect(() => {\n if (widgetStateFromWindow) {\n _setWidgetState(widgetStateFromWindow);\n }\n }, [widgetStateFromWindow]);\n\n const setWidgetState = useCallback(\n (stateOrUpdater: React.SetStateAction) => {\n _setWidgetState((prevState) => {\n const newState =\n typeof stateOrUpdater === \"function\"\n ? (stateOrUpdater as (prev: T) => T)(prevState)\n : stateOrUpdater;\n\n getOpenAI()?.setWidgetState(newState);\n return newState;\n });\n },\n [],\n );\n\n return [widgetState, setWidgetState] as const;\n}\n",[],[166,270,292],"b3620a1c-a5e5-11f0-8f15-0224a6c84d84","NavigationSync.tsx","0199ce87-fbda-7524-96e6-d537a3c73e32",["D",1760106642287],"/** @jsxImportSource https://esm.sh/react@19 */\nimport { useEffect } from \"https://esm.sh/react@19\";\nimport { useNavigate } from \"https://esm.sh/@tanstack/react-router@1?deps=react@19\";\nimport { useToolOutput } from \"./hooks.ts\";\nimport type { WidgetState } from \"../../shared/types.ts\";\n\nexport function NavigationSync() {\n const data = useToolOutput();\n const navigate = useNavigate();\n\n useEffect(() => {\n if (!data) {\n navigate({ to: \"/\" });\n return;\n }\n\n switch (data.kind) {\n case \"message_list\":\n navigate({ to: \"/list\" });\n break;\n\n case \"message_detail\":\n navigate({\n to: \"/detail/$messageId\",\n params: { messageId: String(data.id) },\n });\n break;\n }\n }, [data, navigate]);\n\n return null;\n}\n",[],[166,270,299],"b36203d2-a5e5-11f0-8f15-0224a6c84d84","MessageListWidget.tsx","0199ce87-fbda-7524-96e6-cc527981c238","0199ce87-fbda-7524-96e6-d2efb46d2afe",["D",1760106642287],"/** @jsxImportSource https://esm.sh/react@19 */\nimport type { MessageListOutput } from \"../../../shared/types.ts\";\nimport { useTheme, useToolOutput } from \"../hooks.ts\";\nimport { getOpenAI } from \"../openai-types.ts\";\n\nexport function MessageListWidget() {\n const data = useToolOutput();\n const theme = useTheme();\n const isDark = theme === \"dark\";\n\n if (!data || data.kind !== \"message_list\") {\n return (\n \n

\n \n \n Loading messages...\n

\n \n );\n }\n\n const { messages } = data;\n\n async function handleAddMessage() {\n await getOpenAI()?.sendFollowUpMessage({\n prompt: \"Add a new message\",\n });\n }\n\n return (\n \n

Messages

\n \n + Add Message\n \n

\n\n {messages.length === 0 ? (\n \n

No messages yet

Click \"Add Message\" to create one

\n \n ) : (\n

\n {messages.map((message) => (\n \n ))}\n

\n )}\n \n );\n}\n\nfunction MessageCard({ message, isDark }) {\n return (\n \n

{message.content}

\n \n {new Date(message.timestamp).toLocaleString()}\n \n \n #{message.id}\n \n

\n \n );\n}\n",[],[166,270,313,306],"components","b3620166-a5e5-11f0-8f15-0224a6c84d84","MessageDetailWidget.tsx","0199ce87-fbda-7524-96e6-c966a47f993e",["D",1760106642287],"/** @jsxImportSource https://esm.sh/react@19 */\nimport type { MessageDetailOutput } from \"../../../shared/types.ts\";\nimport { useTheme, useToolOutput } from \"../hooks.ts\";\nimport { getOpenAI } from \"../openai-types.ts\";\n\nexport function MessageDetailWidget() {\n const data = useToolOutput();\n const theme = useTheme();\n const isDark = theme === \"dark\";\n\n async function handleBackToList() {\n await getOpenAI()?.sendFollowUpMessage({\n prompt: \"Show me all messages\",\n });\n }\n\n if (!data || data.kind !== \"message_detail\") {\n return (\n \n

\n \n \n Loading message...\n

\n \n );\n }\n\n return (\n \n

Message Details

\n\n \n

{data.content}

\n \n\n

\n \n ID\n

{data.id}

\n\n

\n \n CREATED\n

\n {new Date(data.timestamp).toLocaleString()}\n

\n \n \n\n \n ← Back to List\n \n \n );\n}\n",[],[166,270,313,315],"b361ffae-a5e5-11f0-8f15-0224a6c84d84","LoadingWidget.tsx","0199ce87-fbda-7524-96e6-c6ef23c8b0ba",["D",1760106642287],"/** @jsxImportSource https://esm.sh/react@19 */\nimport { useTheme } from \"../hooks.ts\";\n\nexport function LoadingWidget() {\n const theme = useTheme();\n const isDark = theme === \"dark\";\n\n return (\n \n

\n \n \n Loading...\n

\n \n );\n}\n",[],[166,270,313,322],"b36208fa-a5e5-11f0-8f15-0224a6c84d84",["D",1760106642287],[191,192,193],[166,270,313],"b36218ea-a5e5-11f0-8f15-0224a6c84d84",["D",1760106642287],[190,194,195,196,197,198,199],[166,270],"b3621cb4-a5e5-11f0-8f15-0224a6c84d84",["D",1760106642287],[189,200],[166],"b361faae-a5e5-11f0-8f15-0224a6c84d84","index.ts","0199ce87-fbda-7524-96e6-c16fe0a60fe5",["D",1760106642287],"http","import { parseProject, readFile, serveFile } from \"https://esm.town/v/std/utils/index.ts\";\nimport { Hono } from \"npm:hono\";\nimport { cors } from \"npm:hono/cors\";\nimport { mcpHandler, setBaseUrl } from \"./mcp/server.ts\";\n\nconst app = new Hono();\n\n// Enable CORS for widget assets (ChatGPT iframe needs this)\napp.use(\"/widget-assets/*\", cors({\n origin: \"*\",\n allowMethods: [\"GET\", \"HEAD\", \"OPTIONS\"],\n}));\n\n// Serve setup instructions at the root /\napp.get(\"/\", async c => {\n let html = await readFile(\"/frontend/index.html\", import.meta.url);\n\n // Get this project's URL, in a way that works across forks and branches\n const projectVal = parseProject(import.meta.url);\n const thisProjectURL = projectVal.links.self.project;\n\n // Inject the project URL for the setup instructions\n const dataScript = ``;\n\n // Insert the script right before the closing tag\n html = html.replace(\"\", `${dataScript}`);\n\n return c.html(html);\n});\n\n// MCP endpoint for ChatGPT\napp.all(\"/mcp\", async (c) => {\n // Set base URL before handling MCP request\n const url = new URL(c.req.url);\n setBaseUrl(`${url.protocol}//${url.host}`);\n\n const response = await mcpHandler(c.req.raw);\n return response;\n});\n\n// Serve widget assets with automatic transpilation\napp.get(\"/widget-assets/**/*\", (c) => {\n return serveFile(c.req.path.replace(\"/widget-assets\", \"/frontend/widgets\"), import.meta.url);\n});\n\n// Unwrap and rethrow Hono errors as the original error\n// If you delete this, all errors will be \"Internal Server Error\"\napp.onError((err, c) => {\n throw err;\n});\n\n// HTTP vals expect an exported \"fetch handler\"\n// This is how you \"run the server\" in Val Town with Hono\nexport default app.fetch;",[],[348,341],"backend","b361f0b8-a5e5-11f0-8f15-0224a6c84d84","0199ce87-fbda-7524-96e6-bb409d6b5bb4",["D",1760106642287],"# Backend\n\nThis folder contains all backend code for the MCP server and widget serving.\n\n## Structure\n\n* `index.ts` - Main Hono application entrypoint\n* `database/` - SQLite database schema and queries\n* `mcp/` - MCP server with ChatGPT tools and widget resources\n\n## Hono\n\nThis app uses [Hono](https://hono.dev/) as the web framework. Hono is designed for serverless environments like Val Town and Cloudflare Workers. If you're familiar with Express, Flask, or Sinatra, Hono follows similar patterns.\n\n## Routes\n\nThe backend serves three types of content:\n\n### 1. Root Route (`GET /`)\nServes the setup instructions page with the dynamically injected MCP endpoint URL.\n\n### 2. MCP Endpoint (`ALL /mcp`)\nThe Model Context Protocol server endpoint that ChatGPT connects to. This handles:\n- Tool discovery and execution\n- Widget resource serving\n- Streaming HTTP transport for MCP messages\n\n### 3. Widget Assets (`GET /widget-assets/**`)\nServes the React widget files with automatic TypeScript/TSX transpilation. The backend maps requests from `/widget-assets/*` to `/frontend/widgets/*` and uses Val Town's `serveFile` utility to:\n- Read project files across branches and forks\n- Automatically transpile TSX → JS\n- Set correct content-types\n\nExample: `GET /widget-assets/widget.tsx` → serves transpiled JS from `/frontend/widgets/widget.tsx`\n\n## MCP Server\n\nThe MCP server (`backend/mcp/server.ts`) defines:\n\n1. **Widget Resource** - The HTML template that ChatGPT loads in an iframe\n2. **Tools** - Functions that ChatGPT can call (list_messages, add_message, get_message)\n3. **Widget Metadata** - Configuration for widget behavior, CSP, loading states\n\nEach tool returns structured data with a `kind` discriminator that the widget router uses for navigation.\n\n## Serving Widget HTML\n\nThe widget HTML template (`frontend/widgets/index.html`) contains `__VAL_TOWN_URL__` placeholders that get replaced with the actual deployment URL when the widget resource is requested. This ensures widget assets load from the correct domain across forks and branches.\n\n## Error Handling\n\nBy default, Hono swallows errors and returns \"Internal Server Error\". We override this behavior to see full stack traces:\n\n```typescript\napp.onError((err, c) => {\n throw err;\n});\n```\n\nThis makes debugging easier during development. You can customize this for production.\n",[],[348,218],"b361e7ee-a5e5-11f0-8f15-0224a6c84d84","server.ts","0199ce87-fbda-7524-96e6-b20af7dad923","0199ce87-fbda-7524-96e6-b6c1f1ce7b23",["D",1760106642287],"import { McpServer, StreamableHttpTransport } from \"https://esm.sh/mcp-lite@0.8.1\";\nimport { readFile } from \"https://esm.town/v/std/utils/index.ts\";\nimport { z } from \"https://esm.sh/zod@4\";\nimport { getMessages, insertMessage } from \"../database/queries.ts\";\nimport {\n MessageListOutputSchema,\n MessageDetailOutputSchema,\n} from \"../../shared/types.ts\";\n\nconst WIDGET_URI = \"ui://widget/index.html\";\n\n// Store current base URL (set per request)\nlet currentBaseUrl = \"\";\n\nexport function setBaseUrl(url: string) {\n currentBaseUrl = url;\n}\n\nfunction getBaseUrl(): string {\n if (!currentBaseUrl) {\n throw new Error(\"Base URL not set - must call setBaseUrl before handling MCP requests\");\n }\n return currentBaseUrl;\n}\n\nfunction widgetMeta(invoking?: string, invoked?: string) {\n return {\n \"openai/outputTemplate\": WIDGET_URI,\n \"openai/toolInvocation/invoking\": invoking,\n \"openai/toolInvocation/invoked\": invoked,\n \"openai/widgetAccessible\": true,\n \"openai/resultCanProduceWidget\": true,\n } as const;\n}\n\nconst mcp = new McpServer({\n name: \"valtown-message-board\",\n version: \"1.0.0\",\n schemaAdapter: (schema) => z.toJSONSchema(schema as z.ZodType),\n});\n\nasync function loadWidgetHtml(baseUrl: string): Promise {\n let html = await readFile(\"/frontend/widgets/index.html\", import.meta.url);\n html = html.replaceAll(\"__VAL_TOWN_URL__\", baseUrl);\n return html;\n}\n\nmcp.resource(\n WIDGET_URI,\n {\n name: \"Message Board Widget\",\n description: \"Interactive message board widget\",\n mimeType: \"text/html+skybridge\",\n },\n async (uri) => {\n const baseUrl = getBaseUrl();\n const html = await loadWidgetHtml(baseUrl);\n\n return {\n contents: [\n {\n uri: uri.href,\n type: \"text\",\n text: html,\n mimeType: \"text/html+skybridge\",\n _meta: {\n ...widgetMeta(),\n \"openai/widgetCSP\": {\n connect_domains: [baseUrl, \"https://esm.sh\", \"https://cdn.jsdelivr.net\"],\n resource_domains: [baseUrl, \"https://esm.sh\", \"https://cdn.jsdelivr.net\"],\n },\n },\n },\n ],\n };\n },\n);\n\nmcp.tool(\"list_messages\", {\n description: \"List all messages from the message board\",\n inputSchema: z.object({}),\n outputSchema: MessageListOutputSchema,\n _meta: widgetMeta(\"Loading messages...\", \"Messages loaded\"),\n handler: async () => {\n const messages = await getMessages();\n\n return {\n structuredContent: {\n kind: \"message_list\",\n messages,\n },\n content: [\n {\n type: \"text\",\n text: `Found ${messages.length} message${messages.length === 1 ? \"\" : \"s\"}`,\n },\n ],\n _meta: widgetMeta(),\n };\n },\n});\n\nmcp.tool(\"get_message\", {\n description: \"Get a specific message by ID\",\n inputSchema: z.object({\n id: z.number().describe(\"Message ID\"),\n }),\n outputSchema: MessageDetailOutputSchema,\n _meta: widgetMeta(\"Loading message...\", \"Message loaded\"),\n handler: async ({ id }) => {\n const messages = await getMessages();\n const message = messages.find((m) => m.id === id);\n\n if (!message) {\n throw new Error(`Message with ID ${id} not found`);\n }\n\n return {\n structuredContent: {\n kind: \"message_detail\",\n ...message,\n },\n content: [\n {\n type: \"text\",\n text: `Message #${id}: ${message.content}`,\n },\n ],\n _meta: widgetMeta(),\n };\n },\n});\n\nmcp.tool(\"add_message\", {\n description: \"Add a new message to the message board\",\n inputSchema: z.object({\n content: z.string().describe(\"The message content\"),\n }),\n outputSchema: MessageListOutputSchema,\n _meta: widgetMeta(\"Adding message...\", \"Message added\"),\n handler: async ({ content }) => {\n if (!content || content.trim() === \"\") {\n throw new Error(\"Message content cannot be empty\");\n }\n\n await insertMessage(content);\n\n // Return updated message list\n const messages = await getMessages();\n\n return {\n structuredContent: {\n kind: \"message_list\",\n messages,\n },\n content: [\n {\n type: \"text\",\n text: `Added message: \"${content}\"`,\n },\n ],\n _meta: widgetMeta(),\n };\n },\n});\n\nconst transport = new StreamableHttpTransport();\nexport const mcpHandler = transport.bind(mcp);\n",[],[348,363,356],"mcp","b361eee2-a5e5-11f0-8f15-0224a6c84d84",["D",1760106642287],[185],[348,363],"b361e3fc-a5e5-11f0-8f15-0224a6c84d84","schema.ts","0199ce87-fbda-7524-96e6-ab4d7e3f4c83","0199ce87-fbda-7524-96e6-ad2e6c99ea27",["D",1760106642287],"import { sqliteTable, text, integer } from \"npm:drizzle-orm/sqlite-core\";\n\n// Messages table\nexport const messages = sqliteTable(\"messages\", {\n id: integer(\"id\").primaryKey({ autoIncrement: true }),\n content: text(\"content\").notNull(),\n timestamp: text(\"timestamp\").notNull().default(new Date().toISOString()),\n});\n\n// Type exports\nexport type Message = typeof messages.$inferSelect;",[],[348,376,369],"database","b361e2bc-a5e5-11f0-8f15-0224a6c84d84","queries.ts","0199ce87-fbda-7524-96e6-a70a239e6683",["D",1760106642287],"import { desc } from \"npm:drizzle-orm\";\nimport { db, schema } from \"./db.ts\";\nimport { createTables } from \"./migrations.ts\";\nimport { MESSAGE_LIMIT } from \"../../shared/utils.ts\";\n\n// This will create the database table if it doesn't exist.\n// This will run every time the app starts up. You can\n// comment out this line for a modest (30ms) performance improvement\n// on cold starts. It's left in to ensure the database tables are\n// automatically set up correctly for users who fork this app.\nawait createTables();\n\nexport async function getMessages(limit = MESSAGE_LIMIT) {\n const messages = await db\n .select()\n .from(schema.messages)\n .orderBy(desc(schema.messages.timestamp))\n .limit(limit)\n .all();\n \n return messages;\n}\n\nexport async function insertMessage(content: string) {\n await db\n .insert(schema.messages)\n .values({\n content,\n timestamp: new Date().toISOString(),\n })\n .run();\n}",[],[348,376,378],"b361e172-a5e5-11f0-8f15-0224a6c84d84","migrations.ts","0199ce87-fbda-7524-96e6-a01c85e80bd1",["D",1760106642287],"import { sql } from \"npm:drizzle-orm\";\nimport { db } from \"./db.ts\";\n\nexport async function createTables() {\n // Uncomment to reset database\n await db.run(sql`DROP TABLE IF EXISTS messages`);\n // Create messages table\n await db.run(sql`\n CREATE TABLE IF NOT EXISTS messages (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n content TEXT NOT NULL,\n timestamp TEXT NOT NULL DEFAULT (datetime('now'))\n )\n `);\n}",[],[348,376,385],"b361de48-a5e5-11f0-8f15-0224a6c84d84","db.ts","0199ce87-fbda-7524-96e6-9de157aeec5d",["D",1760106642287],"import { sqlite } from \"https://esm.town/v/std/sqlite\";\nimport { drizzle } from \"npm:drizzle-orm/libsql\";\nimport * as schema from \"./schema.ts\";\n\n// Create Drizzle instance with Val Town's sqlite\nexport const db = drizzle(sqlite as any);\n\n// Export schema for convenience\nexport { schema };",[],[348,376,392],"b361d48e-a5e5-11f0-8f15-0224a6c84d84","0199ce87-fbda-7524-96e6-9b65d6f0ebb5",["D",1760106642287],"# Database\n\nThis app uses [Val Town SQLite](https://docs.val.town/std/sqlite/) to manage data. Every Val Town account comes with a free SQLite database, hosted on [Turso](https://turso.tech/).\n\n## Structure\n\n* `schema.ts` - Drizzle ORM schema definitions (tables, columns, types)\n* `migrations.ts` - Database table creation logic\n* `queries.ts` - Query functions used by MCP tools\n* `db.ts` - Database connection configuration\n\n## Tables\n\nThe starter includes a `messages` table for storing message board data:\n\n```typescript\nexport const messages = sqliteTable(\"messages\", {\n id: integer(\"id\").primaryKey({ autoIncrement: true }),\n content: text(\"content\").notNull(),\n timestamp: text(\"timestamp\").notNull().default(new Date().toISOString()),\n});\n```\n\n## Migrations\n\nMigrations run automatically on startup via `createTables()` in `migrations.ts`, which is imported in `queries.ts`.\n\nThe migration logic uses `CREATE TABLE IF NOT EXISTS`, so it's safe to run on every startup. You can comment out the import in `queries.ts` for a slight (30ms) performance improvement on cold starts, but it's left in by default so forks work out of the box.\n\n## Queries\n\nThe `queries.ts` file exports typed functions for database operations:\n\n- `getMessages(limit?)` - Fetch messages with optional limit\n- `insertMessage(content)` - Insert a new message\n\nThese functions are imported and used by MCP tools in `backend/mcp/server.ts`.\n\n## Schema Changes\n\nSQLite has limited support for altering existing tables. When you need to modify a table schema:\n\n1. Create a new table with the updated schema\n2. Copy data from the old table to the new table\n3. Drop the old table\n4. Rename the new table\n\nAlternatively, you can just change the table name (e.g., `messages_v2`) to start fresh.\n\nFor help with database operations, reach out in the [Val Town Discord](https://discord.com/invite/dHv45uN5RY).\n",[],[348,376,218],"b361e50a-a5e5-11f0-8f15-0224a6c84d84",["D",1760106642287],[179,180,181,182,183],[348,376],"b361fe6e-a5e5-11f0-8f15-0224a6c84d84",["D",1760106642287],[178,184,186,187],[348],["D",1760106642287],{"_11":12,"_123":72},{"_11":12,"_119":-5,"_71":72,"_30":70,"_120":121,"_122":24},{"_38":39,"_13":16,"_32":35,"_108":74,"_109":62,"_110":111,"_112":78,"_113":114,"_115":116,"_117":14,"_118":12},"ctx",{"_51":-5,"_144":449,"_450":451,"_452":453,"_454":24,"_455":24,"_456":24,"_457":85,"_458":-5,"_459":-7,"_460":-7,"_461":26,"_462":24,"_463":24,"_464":-5,"_465":24,"_466":24,"_467":24,"_468":-5},"ENV",{"_420":421,"_422":423,"_424":16,"_425":426,"_427":428,"_429":430,"_431":432,"_433":434,"_435":436,"_437":438,"_439":440,"_441":442,"_443":444,"_445":446,"_447":448},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

History · index.html