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

Create New App

Add MCP Tool

Add Widget

Add Authentication

Add Database

Generate Golden Prompts

Validate App

Test App

Deploy App

Resume App

---

1. Create New App

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

Workflow

Phase 1: Conceptualization

Ask for the app idea

"What ChatGPT App would you like to build? Describe what it does and the problem it solves."

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?

Check for Anti-Patterns

- Static website content display
- Complex multi-step workflows requiring external tabs
- Duplicating ChatGPT's native capabilities
- Ads or upsells

Define Use Cases

Create 3-5 primary use cases with user stories.

Phase 2: Design

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)

Widget Design

For each widget:
- id - unique identifier (kebab-case)
- name - display name
- description - what it shows
- mockData - sample data for preview

Data Model

Design entities and relationships.

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: - 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: __CODE_BLOCK_1__ 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** __CODE_BLOCK_2__ 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 __CODE_BLOCK_3__ --- ## 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** __CODE_BLOCK_4__ 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** __CODE_BLOCK_5__ 6. **Apply Migrations** Run SQL in Supabase dashboard or via migration tool. ### Query Pattern Always filter by user_subject: __CODE_BLOCK_6__ --- ## 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: __CODE_BLOCK_7__ --- ## 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 | | 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** __CODE_BLOCK_8__ 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** __CODE_BLOCK_9__ ### 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** __CODE_BLOCK_10__ 3. **Generate Dockerfile** __CODE_BLOCK_11__ 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:

- MCP endpoint: - Tool discovery works - Widgets render 6. **Configure ChatGPT Connector** - URL:
- Test in ChatGPT

---

10. Resume App

Purpose: Resume building an in-progress ChatGPT App.

Workflow

Load State

Read .chatgpt-app/state.json:

{
     "appName": "My Task Manager",
     "phase": "Implementation",
     "tools": ["list-tasks", "create-task"],
     "widgets": ["task-list"],
     "auth": false,
     "database": true,
     "validated": false,
     "deployed": false
   }

Display Progress

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

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?"

Continue Work

Based on user's choice, invoke the appropriate workflow section.

---

Best Practices

Always save state after each major step

Validate before moving forward (especially before deployment)

Use agents for code generation (chatgpt-mcp-generator, chatgpt-auth-generator, etc.)

Test at every phase (preview widgets, test tools, run golden prompts)

Keep it conversational - guide the user naturally through the workflow

Explain trade-offs when offering choices (Auth0 vs Supabase, etc.)

Show examples when introducing new concepts

---

State Management

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

{
  "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

# 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 

# Deployment
git push origin main      # Trigger Render deploy

---

Getting Started

When the user invokes any chatgpt-app command:

Check if .chatgpt-app/state.json exists

If yes → use Resume App workflow

If no → use Create New App workflow

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