chatgpt-apps

CLI tool to generate ChatGPT Apps from OpenAPI specs using agentic AI workflows.

Overview

chatgpt-apps is a developer tool that transforms your existing REST APIs (via OpenAPI specs) into fully functional ChatGPT Apps. It uses Claude AI in an agentic workflow to:

1. Analyze your OpenAPI spec and propose an optimal app structure
2. Generate MCP (Model Context Protocol) server code
3. Test the generated app for correctness
4. Refine the UX through natural language feedback

Output Modes

The CLI supports two output modes:

| Mode | Transport | Use Case | |------|-----------|----------| | Claude Desktop (default) | stdio | Local MCP server for Claude Desktop | | ChatGPT Apps SDK | HTTP | Web-based MCP server with widgets for ChatGPT |

Installation

npm install -g openapi-chatgpt-apps

Quick Start

For Claude Desktop (stdio MCP)

# Create an MCP server for Claude Desktop
chatgpt-apps create -s ./api-spec.yaml -o ./my-app

For ChatGPT Apps SDK (HTTP MCP + Widgets)

# Create a ChatGPT App with HTTP server and web widgets
chatgpt-apps create -s ./api-spec.yaml -o ./my-chatgpt-app --chatgpt-app

# Build and run the server
cd my-chatgpt-app
npm install && npm run build
npm start  # Server runs at http://localhost:3000/mcp

# Expose via ngrok for ChatGPT
ngrok http 3000

Filtering Large APIs

For APIs with many endpoints, you can filter to include only specific paths or limit the number of tools. This helps avoid ChatGPT's 2MB connector size limit.

# Include only specific paths (supports wildcards)
chatgpt-apps create -s ./api-spec.yaml -o ./my-app --chatgpt-app \
  --include-paths "/api/v2/auth/*,/api/v2/surveys/"

# Limit to 10 tools maximum
chatgpt-apps create -s ./api-spec.yaml -o ./my-app --chatgpt-app \
  --max-tools 10

# Combine both options
chatgpt-apps create -s ./api-spec.yaml -o ./my-app --chatgpt-app \
  --include-paths "/users,/surveys/*" --max-tools 15

Individual Commands

chatgpt-apps analyze -s ./api-spec.yaml
chatgpt-apps generate ./my-chatgpt-app
chatgpt-apps test ./my-chatgpt-app

Commands

| Command | Description | |---------|-------------| | create | Full workflow: analyze, generate, test | | analyze | Analyze OpenAPI spec and propose app structure | | generate | Generate MCP server from approved proposal | | test | Test a generated ChatGPT app | | ux | Refine app UX with AI-powered feedback | | serve | Start development server for testing | | config | Manage CLI configuration |

Configuration

Set your Anthropic API key:

chatgpt-apps config --set ANTHROPIC_API_KEY=your-key-here

Or use environment variable:

export ANTHROPIC_API_KEY=your-key-here

How It Works

Architecture

The CLI uses an agentic architecture with specialized AI agents:

1. Analyzer Agent - Parses OpenAPI specs and proposes optimal ChatGPT app structure
2. Generator Agent - Produces TypeScript MCP server code (stdio transport)
3. ChatGPT App Generator - Produces HTTP MCP server with web widgets
4. Tester Agent - Validates generated code and tests tool functionality
5. UX Agent - Iteratively improves widgets and user experience

ChatGPT Apps SDK Integration

When using --chatgpt-app, the generator creates:

• HTTP Server with /mcp endpoint using StreamableHTTPServerTransport
• Web Widgets (HTML/JS) for rendering tool outputs in ChatGPT iframes
• OpenAI Metadata on tools (openai/outputTemplate, openai/widgetAccessible)

To connect your app to ChatGPT:

1. Enable Developer Mode: Settings → Apps & Connectors → Advanced settings
2. Create a Connector: Settings → Connectors → Create
3. Enter your ngrok URL (e.g., https://abc123.ngrok.app/mcp)
4. Use in chat: Click + → More → Select your connector

See OpenAI Apps SDK Documentation for more details.

OpenAPI to MCP Mapping

| OpenAPI | MCP | |---------|-----| | Path + Method | Tool | | Parameters | Tool input schema | | Request body | Tool input properties | | Response | Tool output | | Tags | Resource groups |

Requirements

• Node.js >= 18
• Anthropic API key (Claude 4.5)
• OpenAPI 3.x spec

Development

# Clone the repo
git clone https://github.com/alinaqi/chatgpt-apps.git
cd chatgpt-apps

# Install dependencies
npm install

# Run in development mode
npm run dev -- create -s ./example.yaml

# Run tests
npm test

License

MIT