chatgpt-app-builder

ChatGPT App Builder

Build production-ready ChatGPT Apps from concept to App Store submission.

Quick Start

New app?           → Start at Phase 1 (Fit Evaluation)
Have app-spec.md?  → Start at Phase 3 (Implementation)
App built?         → Start at Phase 4 (Testing)
Ready to ship?     → Start at Phase 5 (Deployment)

Phase 1: Fit Evaluation

Goal: Determine if a ChatGPT App is right for this product.

Step 1: Gather Context

Ask the user:

1. What does your product do?
2. Who are your users?
3. What API/data does it expose?
4. What actions can users take?

Step 2: Apply Know/Do/Show Framework

Evaluate against three value pillars (see [fit_evaluation.md](references/fit_evaluation.md)):

| Pillar | Question | Strong Signal | |--------|----------|---------------| | Know | Does it provide data ChatGPT lacks? | Live prices, user-specific data, internal metrics | | Do | Can it take real actions? | Create, update, delete, send, schedule | | Show | Can it display better than text? | Lists, charts, maps, media galleries |

Minimum requirement: At least one pillar must be strong.

Step 3: Check Blockers

Review [fit_evaluation.md](references/fit_evaluation.md) for:

• Prohibited categories (gambling, adult, crypto speculation)
• Data restrictions (no PCI, PHI, SSN, API keys)
• Age requirements (13+ audience)

Step 4: Create Golden Prompt Set

Draft prompts for discovery testing:

• 5 direct prompts: Explicitly name your product ("Show my TaskFlow tasks")
• 5 indirect prompts: Describe intent without naming ("What should I work on?")
• 3 negative prompts: Similar but shouldn't trigger ("Create a reminder")

Step 5: Write app-spec.md

Create the specification file:

# [Product Name] ChatGPT App Spec

## Product Context
- Name: [Product name]
- API Base: [API URL]
- Auth: [Bearer token / OAuth / None]

## Value Proposition
- Know: [What data does it provide?]
- Do: [What actions can it take?]
- Show: [What UI is needed?]

## Golden Prompts
### Direct (should trigger)
1. ...

### Indirect (should trigger)
1. ...

### Negative (should NOT trigger)
1. ...

Output: app-spec.md in project directory

Phase 2: App Design

Goal: Define complete technical specification.

Step 1: Define Tools (2-5)

Follow one-job-per-tool principle. See [chatgpt_app_best_practices.md](references/chatgpt_app_best_practices.md).

For each tool, specify:

name: service_verb_noun  # e.g., taskflow_get_tasks
title: Human Readable Name
description: Use this when the user wants to... [be specific]
annotations:
  readOnlyHint: true/false
  destructiveHint: true/false
  openWorldHint: true/false
inputSchema:
  param1: type (required/optional)
  param2: enum["a", "b", "c"]
outputStructure:
  content: [text summary for model]
  structuredContent: {machine-readable data}
  _meta: {widget-only data}

Step 2: Decide Widget Needs

Does the app need custom UI?

| Use Case | Widget Needed? | Component Type | |----------|----------------|----------------| | Task list with checkboxes | Yes | List with actions | | Data display only | Maybe | Could use text | | Maps, charts, media | Yes | Specialized | | Multi-step workflow | Yes | Stateful widget |

See [widget_development.md](references/widget_development.md) for patterns.

Step 3: Plan Authentication

If accessing user-specific data or write operations, auth is required.

See [oauth_integration.md](references/oauth_integration.md) for:

• Well-known endpoint setup
• Provider-specific guides (Auth0, Stytch)
• Tool-level securitySchemes

Step 4: Update app-spec.md

Add technical specification:

## Tools

### 1. service_get_items
- **Annotations**: readOnlyHint: true
- **Input**: { status?: "active" | "completed", limit?: number }
- **Output**:
  - content: "Found N items"
  - structuredContent: { items: [...] }
  - _meta: { fullData: [...] }

### 2. service_create_item
- **Annotations**: openWorldHint: true
- **Input**: { title: string, description?: string }
- **Output**: { id, title, created_at }

## Widget
- Type: List with action buttons
- Display modes: inline, fullscreen
- State: { selectedId, filter }

## Authentication
- Required: Yes
- Provider: Auth0
- Scopes: read:items, write:items

Output: Updated app-spec.md with full technical spec

Phase 3: Implementation

Goal: Generate complete working project.

Step 1: Initialize Project

Copy from assets and customize:

# Project structure
myapp-chatgpt/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts          # MCP server entry
│   ├── tools/            # Tool handlers
│   ├── widget/           # Widget source
│   └── types/            # TypeScript types
└── scripts/
    └── build-widget.ts   # Widget bundler

See [node_chatgpt_app.md](references/node_chatgpt_app.md) for complete patterns.

Step 2: Implement MCP Server

Key components (from assets/server/):

1. HTTP server with SSE transport (required for ChatGPT Apps):

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";

// GET /mcp - SSE stream connection
// POST /mcp/messages - Message handling

1. Tool definitions with JSON Schema:

const tools: Tool[] = [{
  name: "service_get_items",
  title: "Get Items",
  description: "Use this when the user wants to see items...",
  inputSchema: { type: "object", properties: {...} },
  _meta: {
    "openai/outputTemplate": "ui://widget/app.html",
    "openai/widgetAccessible": true
  },
  annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
}];

1. Handler registration:

server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  // Handle tool calls...
  return {
    content: [{ type: "text", text: `Found ${items.length} items` }],
    structuredContent: { items: items.slice(0, 10) },
    _meta: { fullItems: items }
  };
});

Step 3: Implement Widget

Key patterns (from assets/widget/):

// Access data
const output = window.openai.toolOutput;
const meta = window.openai.toolResponseMetadata;

// Invoke tools
await window.openai.callTool("service_action", { id: "123" });

// Persist state
window.openai.setWidgetState({ selectedId: "123" });

// Layout control
window.openai.notifyIntrinsicHeight(400);
await window.openai.requestDisplayMode({ mode: "fullscreen" });

See [widget_development.md](references/widget_development.md) for React hooks and patterns.

Step 4: Build

npm install
npm run build  # Compiles server + bundles widget

Step 5: Implementation Checklist

Before moving to testing, verify:

Widget Requirements

• [ ] Uses Apps SDK UI design tokens (see [apps_sdk_ui_tokens.md](references/apps_sdk_ui_tokens.md))
• [ ] Implements dark mode with CSS variable architecture
• [ ] Uses LoadingDots pattern for loading states (see [widget_ui_patterns.md](references/widget_ui_patterns.md))
• [ ] Calls notifyIntrinsicHeight() after all DOM changes
• [ ] Includes copy button feedback for copyable content
• [ ] Has show more/less for long lists (>3 items)
• [ ] Works on mobile (test at 375px width)
• [ ] Loading UI guards against re-initialization (see [widget_loading_patterns.md](references/widget_loading_patterns.md))
• [ ] SVG animations use .style property, not setAttribute() (see [widget_development.md](references/widget_development.md#common-widget-gotchas))

Security Requirements

• [ ] All user input is validated (see [security_patterns.md](references/security_patterns.md))
• [ ] HTML output uses safe DOM methods (textContent, createElement)
• [ ] External image URLs are proxied with domain whitelist and size limits (200KB)
• [ ] Rate limiting is implem