Chatgpt Apps

# ChatGPT Apps Builder

Complete workflow for building, testing, and deploying ChatGPT Apps from concept to production.

## Commands

- `/chatgpt-apps new` - Create a new ChatGPT App - `/chatgpt-apps add-tool` - Add an MCP tool to your app - `/chatgpt-apps add-widget` - Add a widget to your app - `/chatgpt-apps add-auth` - Configure authentication - `/chatgpt-apps add-database` - Set up database - `/chatgpt-apps validate` - Validate your app - `/chatgpt-apps test` - Run tests - `/chatgpt-apps deploy` - Deploy to production - `/chatgpt-apps resume` - Resume working on an app

---

## Table of Contents

1. [Create New App](#1-create-new-app) 2. [Add MCP Tool](#2-add-mcp-tool) 3. [Add Widget](#3-add-widget) 4. [Add Authentication](#4-add-authentication) 5. [Add Database](#5-add-database) 6. [Generate Golden Prompts](#6-generate-golden-prompts) 7. [Validate App](#7-validate-app) 8. [Test App](#8-test-app) 9. [Deploy App](#9-deploy-app) 10. [Resume App](#10-resume-app)

---

## 1. Create New App

**Purpose:** Create a new ChatGPT App from concept to working code.

### Workflow

#### Phase 1: Conceptualization

1. **Ask for the app idea** "What ChatGPT App would you like to build? Describe what it does and the problem it solves."

2. **Analyze against UX Principles** - **Conversational Leverage**: What can users accomplish through natural language? - **Native Fit**: How does this integrate with ChatGPT's conversational flow? - **Composability**: Can tools work independently and combine with other apps?

3. **Check for Anti-Patterns** - Static website content display - Complex multi-step workflows requiring external tabs - Duplicating ChatGPT's native capabilities - Ads or upsells

4. **Define Use Cases** Create 3-5 primary use cases with user stories.

#### Phase 2: Design

1. **Tool Topology** - Query tools (readOnlyHint: true) - Mutation tools (destructiveHint: false) - Destructive tools (destructiveHint: true) - Widget tools (return UI with _meta) - External API tools (openWorldHint: true)

2. **Widget Design** For each widget: - `id` - unique identifier (kebab-case) - `name` - display name - `description` - what it shows - `mockData` - sample data for preview

3. **Data Model** Design entities and relationships.

4. **Auth Requirements** - Single-user (no auth needed) - Multi-user (Auth0 or Supabase Auth)

#### Phase 3: Implementation

Generate complete application with this structure:

``` {app-name}/ ├── package.json ├── tsconfig.server.json ├── setup.sh ├── START.sh ├── .env.example ├── .gitignore └── server/ └── index.ts ```

**Critical Requirements:** - `Server` class from `@modelcontextprotocol/sdk/server/index.js` - `StreamableHTTPServerTransport` for session management - Widget URIs: `ui://widget/{widget-id}.html` - Widget MIME type: `text/html+skybridge` - `structuredContent` in tool responses - `_meta` with `openai/outputTemplate` on tools

#### Phase 4: Testing - Run setup: `./setup.sh` - Start dev: `./START.sh --dev` - Preview widgets: `http://localhost:3000/preview` - Test MCP connection

#### Phase 5: Deployment - Generate Dockerfile and render.yaml - Deploy to Render - Configure ChatGPT connector

---

## 2. Add MCP Tool

**Purpose:** Add a new MCP tool to your ChatGPT App.

### Workflow

1. **Gather Information** - What does this tool do? - What inputs does it need? - What does it return?

2. **Classify Tool Type** - **Query** (readOnlyHint: true) - Fetches data - **Mutation** (destructiveHint: false) - Creates/updates data - **Destructive** (destructiveHint: true) - Deletes data - **Widget** - Returns UI content - **External** (openWorldHint: true) - Calls external APIs

3. **Design Input Schema** Create Zod schema with appropriate types and descriptions.

4. **Generate Tool Handler** Use `chatgpt-mcp-generator` agent to create: - Tool handler in `server/tools/` - Zod schema export - Type exports - Database queries (if needed)

5. **Register Tool** Update `server/index.ts` with metadata: ```typescript { name: "my-tool", _meta: { "openai/toolInvocation/invoking": "Loading...", "openai/toolInvocation/invoked": "Done", "openai/outputTemplate": "ui://widget/my-widget.html", // if widget } } ```

6. **Update State** Add tool to `.chatgpt-app/state.json`.

### Tool Naming Use kebab-case: `list-items`, `create-task`, `show-recipe-detail`

### Annotations Guide

| Scenario | readOnlyHint | destructiveHint | openWorldHint | |----------|--------------|-----------------|---------------| | List/Get | true | false | false | | Create/Update | false | false | false | | Delete | false | true | false | | External API | varies | varies | true |

---

## 3. Add Widget

**Purpose:** Add inline HTML widgets with HTML/CSS/JS and Apps SDK integration.

### 5 Widget Patterns

1. **Card Grid** - Multiple items in grid 2. **Stats Dashboard** - Key metrics display 3. **Table** - Tabular data 4. **Bar Chart** - Simple visualizations 5. **Detail Widget** - Single item details

### Workflow

1. **Gather Information** - Widget purpose and data - Visual design (cards, table, chart, etc.) - Interactivity needs

2. **Define Data Shape** Document expected structure with TypeScript interface.

3. **Add Widget Config** ```typescript const widgets: WidgetConfig[] = [ { id: "my-widget", name: "My Widget", description: "Displays data", templateUri: "ui://widget/my-widget.html", invoking: "Loading...", invoked: "Ready", mockData: { /* sample */ }, }, ]; ```

4. **Add Widget HTML** Generate HTML with: - Preview mode support (`window.PREVIEW_DATA`) - OpenAI Apps SDK integration (`window.openai.toolOutput`) - Event listeners (`openai:set_globals`) - Polling fallback (100ms, 10s timeout)

5. **Create/Update Tool** Link tool to widget via `widgetId`.

6. **Test Widget** Preview at `/preview/{widget-id}` with mock data.

### Widget HTML Structure

```javascript (function() { let rendered = false;

function render(data) { if (rendered || !data) return; rendered = true; // Render logic }

function tryRender() { if (window.PREVIEW_DATA) { render(window.PREVIEW_DATA); return; } if (window.openai?.toolOutput) { render(window.openai.toolOutput); } }

window.addEventListener('openai:set_globals', tryRender);

const poll = setInterval(() => { if (window.openai?.toolOutput || window.PREVIEW_DATA) { tryRender(); clearInterval(poll); } }, 100); setTimeout(() => clearInterval(poll), 10000);

tryRender(); })(); ```

---

## 4. Add Authentication

**Purpose:** Configure authentication using Auth0 or Supabase Auth.

### When to Add - Multiple users - Persistent private data per user - User-specific API credentials

### Providers

**Auth0:** - Enterprise-grade - OAuth 2.1, PKCE flow - Social logins (Google, GitHub, etc.)

**Supabase Auth:** - Simpler setup - Email/password default - Integrates with Supabase database

### Workflow

1. **Choose Provider** Ask user preference based on needs.

2. **Guide Setup** - **Auth0:** Create application, configure callback URLs, get credentials - **Supabase:** Already configured with database setup

3. **Generate Auth Code** Use `chatgpt-auth-generator` agent to create: - Session management middleware - User subject extraction - Token validation

4. **Update Server** Add auth middleware to protect routes.

5. **Update Environment** ```bash # Auth0 AUTH0_DOMAIN=your-tenant.auth0.com AUTH0_CLIENT_ID=... AUTH0_CLIENT_SECRET=... # Supabase (from database setup) SUPABASE_URL=... SUPABASE_ANON_KEY=... ```

6. **Test** Verify login flow and user isolation.

---

## 5. Add Database

**Purpose:** Configure PostgreSQL database using Supabase.

### When to Add - Persistent user data - Multi-entity relationships - Query/filter capabilities

### Workflow

1. **Check Supabase Setup** Verify account and project exist.

2. **Gather Credentials** - Project URL - Anon key (public) - Service role key (server-side)

3. **Define Entities** For each entity, specify: - Fields and types - Relationships - Indexes

4. **Generate Schema** Use `chatgpt-database-generator` agent to create SQL with: - `id` (UUID primary key) - `user_subject` (varchar, indexed) - `created_at` (timestamptz) - `updated_at` (timestamptz) - RLS policies for user isolation

5. **Setup Connection Pool** ```typescript import { createClient } from '@supabase/supabase-js'; const supabase = createClient( process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_ROLE_KEY! ); ```

6. **Apply Migrations** Run SQL in Supabase dashboard or via migration tool.

### Query Pattern

Always filter by `user_subject`:

```typescript const { data } = await supabase .from('tasks') .select('*') .eq('user_subject', userSubject); ```

---

## 6. Generate Golden Prompts

**Purpose:** Generate test prompts to validate ChatGPT correctly invokes tools.

### Why Important - Measure precision/recall - Enable iteration - Post-launch monitoring

### 3 Categories

1. **Direct Prompts** - Explicit tool invocation - "Show me my task list" - "Create a new task called..."

2. **Indirect Prompts** - Outcome-based, ChatGPT should infer tool - "What do I need to do today?" - "Help me organize my work"

3. **Negative Prompts** - Should NOT trigger tool - "What is a task?" - "Tell me about project management"

### Workflow

1. **Analyze Tools** Review each tool's purpose and inputs.

2. **Generate Prompts** For each tool, create: - 5+ direct prompts - 5+ indirect prompts - 3+ negative prompts - 2+ edge case prompts

3. **Best Practices** - Tool descriptions start with "Use this when..." - State limitations clearly - Include examples in descriptions

4. **Save Output** Write to `.chatgpt-app/golden-prompts.json`: ```json { "toolName": { "direct": ["prompt1", "prompt2"], "indirect": ["prompt1", "prompt2"], "negative": ["prompt1", "prompt2"], "edge": ["prompt1", "prompt2"] } } ```

---

## 7. Validate App

**Purpose:** Validation suite before deployment.

### 10 Validation Checks

1. **Required Files** - package.json - tsconfig.server.json - setup.sh (executable) - START.sh (executable) - server/index.ts - .env.example

2. **Server Implementation** - Uses `Server` from MCP SDK - Has `StreamableHTTPServerTransport` - Session management with Map - Correct request handlers

3. **Widget Configuration** - `widgets` array exists - Each has id, name, description, templateUri, mockData - URIs match pattern `ui://widget/{id}.html`

4. **Tool Response Format** - Returns `structuredContent` (not just `content`) - Widget tools have `_meta` with `openai/outputTemplate`

5. **Resource Handler Format** - MIME type: `text/html+skybridge` - Returns `_meta` with serialization and CSP

6. **Widget HTML Structure** - Preview mode support - Event listeners for Apps SDK - Polling fallback - Render guard

7. **Endpoint Existence** - `/health` - Health check - `/preview` - Widget index - `/preview/:widgetId` - Widget preview - `/mcp` - MCP endpoint

8. **Package.json Scripts** - Has `build:server` - Has `start` with HTTP_MODE=true - Has `dev` with watch mode - NO web build scripts (web/, ui/, client/)

9. **Annotation Validation** - readOnlyHint set correctly - destructiveHint for delete operations - openWorldHint for external APIs

10. **Database Validation** (if enabled) - Tables have required fields - user_subject indexed - RLS policies enabled

### Common Errors

| Error | Fix | |-------|-----| | Missing structuredContent | Add to tool response | | Wrong widget URI | Use ui://widget/{id}.html | | No session management | Add Map<string, Transport> | | Missing _meta | Add to tool definition and response | | Wrong MIME type | Use text/html+skybridge |

**Critical:** Check file existence FIRST before other validations!

---

## 8. Test App

**Purpose:** Run automated tests using MCP Inspector and golden prompts.

### 4 Test Categories

1. **MCP Protocol** - Server starts without errors - Handles initialize - Lists tools correctly - Lists resources correctly

2. **Schema Validation** - Tool schemas are valid Zod - Required fields marked - Types match implementation

3. **Widget Tests** - All widgets render in preview mode - Mock data loads correctly - No console errors

4. **Golden Prompt Tests** - Direct prompts trigger correct tools - Indirect prompts work as expected - Negative prompts don't trigger tools

### Workflow

1. **Start Server in Test Mode** ```bash HTTP_MODE=true NODE_ENV=test npm run dev ```

2. **Run MCP Inspector** Test protocol compliance: - Initialize connection - List tools - Call each tool with valid inputs - Check responses

3. **Schema Validation** Verify schemas compile and match implementation.

4. **Golden Prompt Tests** Use ChatGPT to test prompts: - Record which tool was called - Compare to expected tool - Calculate precision/recall

5. **Generate Report** ```json { "passed": 42, "failed": 3, "categories": { "mcp": "✅", "schema": "✅", "widgets": "✅", "prompts": "⚠️ 3 failures" }, "timing": "2.3s" } ```

### Fixing Failures

For each failure, explain: - What failed - Why it failed - How to fix (with code example)

---

## 9. Deploy App

**Purpose:** Deploy ChatGPT App to Render with PostgreSQL and health checks.

### Prerequisites

- ✅ Validation passed - ✅ Tests passed - ✅ Git repository clean - ✅ Environment variables ready

### Workflow

1. **Pre-flight Check** - Run validation - Run tests - Check database connection (if enabled)

2. **Generate render.yaml** ```yaml services: - type: web name: {app-name} runtime: docker plan: free healthCheckPath: /health envVars: - key: PORT value: 3000 - key: HTTP_MODE value: true - key: NODE_ENV value: production - key: WIDGET_DOMAIN generateValue: true # Add auth/database vars if needed ```

3. **Generate Dockerfile** ```dockerfile FROM node:20-slim WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY dist ./dist EXPOSE 3000 CMD ["node", "dist/server/index.js"] ```

4. **Deploy** **Option A: Automated (if Render MCP available)** Use Render MCP agent to deploy. **Option B: Manual** - Push to GitHub - Connect repo in Render dashboard - Set environment variables - Deploy

5. **Verify Deployment** - Health check: `https://{app}.onrender.com/health` - MCP endpoint: `https://{app}.onrender.com/mcp` - Tool discovery works - Widgets render

6. **Configure ChatGPT Connector** - URL: `https://{app}.onrender.com/mcp` - Test in ChatGPT

---

## 10. Resume App

**Purpose:** Resume building an in-progress ChatGPT App.

### Workflow

1. **Load State** Read `.chatgpt-app/state.json`: ```json { "appName": "My Task Manager", "phase": "Implementation", "tools": ["list-tasks", "create-task"], "widgets": ["task-list"], "auth": false, "database": true, "validated": false, "deployed": false } ```

2. **Display Progress** Show current status: - App name - Current phase - Completed items (tools, widgets) - Pending items (auth, validation, deployment)

3. **Offer Next Steps** Based on phase: **Concept Phase:** - "Let's design the tools and widgets" - "Shall we start implementation?" **Implementation Phase:** - "Add another tool?" - "Add a widget?" - "Set up authentication?" - "Set up database?" **Testing Phase:** - "Generate golden prompts?" - "Run validation?" - "Run tests?" **Deployment Phase:** - "Deploy to Render?" - "Configure ChatGPT connector?"

4. **Continue Work** Based on user's choice, invoke the appropriate workflow section.

---

## Best Practices

1. **Always save state** after each major step 2. **Validate before moving forward** (especially before deployment) 3. **Use agents for code generation** (chatgpt-mcp-generator, chatgpt-auth-generator, etc.) 4. **Test at every phase** (preview widgets, test tools, run golden prompts) 5. **Keep it conversational** - guide the user naturally through the workflow 6. **Explain trade-offs** when offering choices (Auth0 vs Supabase, etc.) 7. **Show examples** when introducing new concepts

---

## State Management

The `.chatgpt-app/state.json` file tracks progress:

```json { "appName": "string", "description": "string", "phase": "Concept" | "Implementation" | "Testing" | "Deployment", "tools": ["tool-name"], "widgets": ["widget-id"], "auth": { "enabled": boolean, "provider": "auth0" | "supabase" | null }, "database": { "enabled": boolean, "entities": ["entity-name"] }, "validated": boolean, "tested": boolean, "deployed": boolean, "deploymentUrl": "string | null", "goldenPromptsGenerated": boolean, "lastUpdated": "ISO timestamp" } ```

---

## Command Reference

```bash # Setup ./setup.sh

# Development ./START.sh --dev # Dev mode with watch ./START.sh --preview # Open preview in browser ./START.sh --stdio # STDIO mode (testing) ./START.sh # Production mode

# Testing npm run validate # Type checking curl http://localhost:3000/health

# Deployment git push origin main # Trigger Render deploy ```

---

## Getting Started

When the user invokes any chatgpt-app command:

1. Check if `.chatgpt-app/state.json` exists 2. If yes → use **Resume App** workflow 3. If no → use **Create New App** workflow

Always guide users through the natural progression: **Concept → Implementation → Testing → Deployment**