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 with hosts like ChatGPT.
Framework (JSON)
Library (TypeScript)
In the sunpeak framework, simulations are JSON files that live in the tests/simulations/ directory. The resource URL and metadata are automatically linked based on directory structure. File Naming Convention Simulation files live in tests/simulations/{name}/: tests/simulations/{name}/{name}-{scenario}-simulation.json
For example:
tests/simulations/albums/albums-show-simulation.jsontests/simulations/review/review-diff-simulation.jsontests/simulations/review/review-post-simulation.json Resource files live in src/resources/{name}/:
Component + Metadata : src/resources/{name}/{name}-resource.tsx (exports both the React component and export const resource: ResourceConfig) You can have multiple simulations per resource (e.g., albums-show-simulation.json and albums-empty-simulation.json in the same folder). JSON Schema Each simulation JSON file contains: // tests/simulations/example/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" : { "ui" : { "visibility" : true } } }, "toolResult" : { "structuredContent" : { "items" : [ "item1" , "item2" ] }, "_meta" : {} } }
Auto-Discovery The framework automatically discovers and links simulations:
Discovery : Scans tests/simulations/{name}/ folders for *-simulation.json filesLinking : Simulations are automatically linked to the corresponding resource in src/resources/{name}/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/resources/albums/ albums-resource.tsx # Component + resource metadata tests/simulations/albums/ albums-show-simulation.json # Default view albums-empty-simulation.json # Empty state albums-error-simulation.json # Error state
Each simulation can have different toolResult.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 ; // Dev mode: HTML page URL (with Vite HMR) resourceUrl ?: string ; // Prod mode: JS bundle URL resourceScript ?: string ; // Decorative message for simulator UI userMessage ?: string ; // MCP Tool definition (from @modelcontextprotocol/sdk) tool : Tool ; // MCP Resource definition (from @modelcontextprotocol/sdk) resource : Resource ; // Mock input parameters for the tool call toolInput ?: Record < string , unknown >; // Mock data for the tool response toolResult ?: { content ?: Array <{ type : string ; text : string }>; structuredContent ?: unknown ; isError ?: boolean ; }; // Initial host context hostContext ?: Partial < McpUiHostContext >; }
Usage with ChatGPTSimulator Pass simulations to the ChatGPTSimulator component: import 'sunpeak/style.css' ; import { ChatGPTSimulator } from 'sunpeak' ; import type { Simulation } from 'sunpeak' ; const simulations : Record < string , Simulation > = { 'albums-show' : { name: 'albums-show' , resourceUrl: '/resources/albums/index.html' , 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;profile=mcp-app' , }, toolResult: { 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 real MCP App hosts like ChatGPT. Properties Unique identifier for the simulation. Used to select simulations in the UI and URL parameters. (Library only - auto-generated from filename in framework)
URL to the resource HTML page for dev mode (with Vite HMR). (Library only - auto-linked in framework)
URL to the resource JS bundle for prod mode. (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 input parameters for the tool call. Accessible via useToolData().
Mock data for the tool response. The structuredContent property is passed to your component via useToolData(). { content ?: Array < { type : string ; text : string } > ; structuredContent ?: unknown ; isError ?: boolean ; }
hostContext
Partial<McpUiHostContext>
Initial host context for the simulation. Accessible via useHostContext().
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 >; }
See Also
ChatGPTSimulator Component API reference.
runMCPServer MCP server API reference.
