--- name: chatgpt-apps description: Complete ChatGPT Apps builder - Create, design, implement, test, and deploy ChatGPT Apps with MCP servers, widgets, auth, database integration, and automated deployment homepage: https://github.com/hollaugo/prompt-circle-claude-plugins user-invocable: true ---

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
2. Add MCP Tool
3. Add Widget
4. Add Authentication
5. Add Database
6. Generate Golden Prompts
7. Validate App
8. Test App
9. Deploy 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."

1. 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?

1. Check for Anti-Patterns

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

1. 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)

1. Widget Design

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

1. Data Model

Design entities and relationships.

1. 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?

1. 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

1. Design Input Schema

Create Zod schema with appropriate types and descriptions.

1. Generate Tool Handler

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

1. 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 } } ```

1. 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

1. Define Data Shape

Document expected structure with TypeScript interface.

1. 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 / }, }, ]; ```

1. 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)

1. Create/Update Tool

Link tool to widget via widgetId.

1. Test Widget

Preview at /preview/{widget-id} with mock data.

Widget HTML Structure

(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.

1. Guide Setup

- Auth0: Create application, configure callback URLs, get credentials - Supabase: Already configured with database setup

1. Generate Auth Code

Use chatgpt-auth-generator agent to create: - Session management middleware - User subject extraction - Token validation

1. Update Server

Add auth middleware to protect routes.

...