Overview Simulations define test scenarios for your resources—combining tool definitions, mock data, and platform state. They can be used with the ChatGPTSimulator for local development or runMCPServer for platform testing.
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. File Naming Convention Simulation files follow the pattern: src/simulations/{resource}-{scenario}-simulation.json
For example:
albums-show-simulation.json - linked to albums-resource.tsxreview-diff-simulation.json - linked to review-resource.tsxreview-post-simulation.json - linked to review-resource.tsx The {resource} prefix determines which resource files are automatically linked:
Component : src/resources/{resource}-resource.tsxMetadata : src/resources/{resource}-resource.json You can have multiple simulations per resource (e.g., albums-show-simulation.json and albums-empty-simulation.json). JSON Schema Each simulation JSON file contains: // src/simulations/example-show-simulation.json { "userMessage" : "Show me an example" , "tool" : { "name" : "show-example" , "description" : "Show an example" , "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" : { "items" : [ "item1" , "item2" ] }, "_meta" : {} } }
Auto-Discovery The framework automatically discovers and links simulations:
Discovery : Glob pattern src/simulations/*-simulation.jsonMatching : Longest prefix match links to resources (e.g., albums-show matches albums-resource.tsx)No imports needed : Everything is wired automatically This means you never need to:
Import resource metadata into simulations
Specify resource in the simulation JSON
Maintain an index file of simulations
Multiple Scenarios Create multiple simulations per resource to test different scenarios: src/simulations/ albums-show-simulation.json # Default view albums-empty-simulation.json # Empty state albums-error-simulation.json # Error state
Each simulation can have different callToolResult.structuredContent to test various data scenarios. When using the library directly, create simulations as TypeScript objects. Import import type { Simulation } from 'sunpeak' ;
Interface interface Simulation { // Unique identifier for the simulation name : string ; // React component to render resourceComponent : React . ComponentType ; // Decorative message for simulator UI userMessage ?: string ; // MCP Tool definition (from @modelcontextprotocol/sdk) tool : Tool ; // MCP Resource definition (from @modelcontextprotocol/sdk) resource : Resource ; // Mock data for the CallTool response callToolResult ?: CallToolResult ; // Mock input parameters for the tool call callToolRequestParams ?: CallToolRequestParams ; // Initial widget state widgetState ?: Record < string , unknown > | null ; }
Usage with ChatGPTSimulator Pass simulations to the ChatGPTSimulator component: import 'sunpeak/style.css' ; import { ChatGPTSimulator } from 'sunpeak' ; import type { Simulation } from 'sunpeak' ; import { AlbumsResource } from './resources/albums' ; const simulations : Record < string , Simulation > = { 'albums-show' : { name: 'albums-show' , resourceComponent: AlbumsResource , userMessage: 'Show me some albums' , tool: { name: 'show-albums' , description: 'Display photo albums' , inputSchema: { type: 'object' , properties: {}, additionalProperties: false }, annotations: { readOnlyHint: true }, }, resource: { name: 'albums' , uri: 'resource://albums' , mimeType: 'text/html+skybridge' , }, callToolResult: { structuredContent: { albums: [{ id: '1' , title: 'Summer' , cover: '/cover.jpg' }], }, }, }, }; function App () { return < ChatGPTSimulator simulations = { simulations } appName = "My App" /> ; }
Simulations can also be passed to runMCPServer for testing against the real ChatGPT platform. Properties Unique identifier for the simulation. Used to select simulations in the UI and URL parameters. (Library only - auto-generated from filename in framework)
resourceComponent
React.ComponentType
required
The React component to render for this simulation. (Library only - auto-linked in framework)
A decorative message shown in the simulator interface. Has no functional purpose.
MCP Tool definition from @modelcontextprotocol/sdk. Defines the tool’s name, description, input schema, and metadata. import type { Tool } from '@modelcontextprotocol/sdk/types.js' ;
MCP Resource definition from @modelcontextprotocol/sdk. Defines the resource’s name, URI, MIME type, and metadata. (Library only - auto-linked in framework) import type { Resource } from '@modelcontextprotocol/sdk/types.js' ;
Mock data for the MCP CallTool response. The structuredContent property is passed to your component via useWidgetProps(). import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js' ;
Mock input parameters for the tool call. The arguments property is accessible via useToolInput(). import type { CallToolRequest } from '@modelcontextprotocol/sdk/types.js' ; type CallToolRequestParams = CallToolRequest [ 'params' ];
widgetState
Record<string, unknown> | null
Initial widget state for the simulation. Accessible via useWidgetState().
MCP SDK Types The simulation interface uses official types from @modelcontextprotocol/sdk:
interface Tool { name : string ; description ?: string ; inputSchema : JSONSchema ; title ?: string ; annotations ?: { readOnlyHint ?: boolean ; destructiveHint ?: boolean ; idempotentHint ?: boolean ; openWorldHint ?: boolean ; }; _meta ?: Record < string , unknown >; }
Resource interface Resource { name : string ; uri : string ; title ?: string ; description ?: string ; mimeType ?: string ; _meta ?: Record < string , unknown >; }
interface CallToolResult { content ?: Array < TextContent | ImageContent | AudioContent | EmbeddedResource >; structuredContent ?: Record < string , unknown >; isError ?: boolean ; _meta ?: Record < string , unknown >; }
When targeting ChatGPT, include OpenAI-specific metadata in the _meta fields:
{ _meta : { 'openai/toolInvocation/invoking' : 'Loading albums...' , 'openai/toolInvocation/invoked' : 'Albums loaded' , 'openai/widgetAccessible' : true , 'openai/resultCanProduceWidget' : true , } }
{ _meta : { 'openai/widgetDomain' : 'https://example.com' , 'openai/widgetCSP' : { connect_domains: [], resource_domains: [ 'https://*.oaistatic.com' ], }, } }
See Also
ChatGPTSimulator Component API reference.
runMCPServer MCP server API reference.
