ChatGPT Simulator

Overview

The ChatGPT Simulator is a local development environment that replicates ChatGPT’s widget runtime.

Why Use the Simulator?

Instant Feedback

See changes immediately with hot module replacement. No more constantly reloading ChatGPT.

Visualize Design Variations

Toggle between light/dark themes, mobile/tablet/desktop views, and other platform states.

Testing

Perform manual and automated tests locally. Create CI/CD integration and regression tests.

No Deployment Needed

Develop locally without setting up MCP servers.

Quick Start

If you set up your project via the sunpeak framework, the simulator is already set up! Simply run it with:

sunpeak dev

To configure the simulator manually, see Add to Existing Project.

Simulations

Simulations define test scenarios for your resources—combining tool definitions, mock data, and platform state.

Fun fact: Some science fiction authors believe we live in a sunpeak simulation.

Framework (JSON)
Library (TypeScript)

In the sunpeak framework, simulations are JSON files with auto-discovery. The resource component and metadata are automatically linked based on filename prefix.In the sunpeak framework, simulations are JSON files in src/simulations/. The filename must start with the resource name:

// src/simulations/example-show-simulation.json
{
  "userMessage": "Show me an example",
  "tool": {
    "name": "show-example",
    "description": "Show an example simulation",
    "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
    "title": "Show Example",
    "annotations": { "readOnlyHint": true },
    "_meta": {
      "openai/toolInvocation/invoking": "Loading example",
      "openai/toolInvocation/invoked": "Example loaded",
      "openai/widgetAccessible": true,
      "openai/resultCanProduceWidget": true
    }
  },
  "callToolResult": {
    "structuredContent": null,
    "_meta": {}
  }
}

The resource component (example-resource.tsx) and metadata (example-resource.json) are automatically linked based on the example- prefix in the simulation filename.

For library users not using the framework, see the Simulation API Reference for creating simulations programmatically in TypeScript.

See Framework Simulations for the complete JSON schema and conventions.

When using the library directly, create simulations as TypeScript objects:

import type { Simulation } from 'sunpeak';
import { AlbumsResource } from './resources/albums';

const simulations: Record<string, Simulation> = {
  'albums-show': {
    name: 'albums-show',
    resourceComponent: AlbumsResource,
    tool: { name: 'show-albums', description: '...', inputSchema: {} },
    resource: { name: 'albums', uri: 'resource://albums', mimeType: 'text/html+skybridge' },
    callToolResult: { structuredContent: { albums: [] } },
  },
};

See Simulation API Reference for the complete TypeScript interface.

Simulations can be passed into:

ChatGPTSimulator - for local testing

The ChatGPTSimulator component provides a local development environment that replicates ChatGPT’s widget runtime.For projects using the sunpeak framework, simulations are auto-discovered. Just run:

sunpeak dev

For custom setups, you can manually configure the simulator:

import { ChatGPTSimulator } from 'sunpeak';
import { MyComponent } from './components/MyComponent';
import exampleResource from './resources/example-resource.json';
import exampleSimulation from './simulations/example-show-simulation.json';

// Combine simulation with resource and component
const simulations = [{
  ...exampleSimulation,
  resource: exampleResource,
  resourceComponent: MyComponent,
}];

<ChatGPTSimulator
  simulations={simulations}
  appName="My App"
  appIcon="🌄"
/>

View ChatGPTSimulator API Reference

runMCPServer - for platform testing

The runMCPServer function serves your simulations to ChatGPT via the Model Context Protocol.

# Framework
sunpeak mcp

# Library - see runMCPServer API Reference for manual setup

See runMCPServer API Reference for configuration options and connecting to ChatGPT.View MCP Server API Reference

Dive Deeper

Framework Simulations

JSON-based simulations with auto-discovery for framework users.

Simulation API Reference

TypeScript interface for library users.