Skip to main content
sunpeak API

​
Overview

The Inspector component provides a local development environment that replicates the MCP App runtime used by hosts like ChatGPT and Claude. It renders your resources inside iframes, matching the production hosting behavior. The inspector supports multiple host shells — switch between ChatGPT and Claude conversation chrome, theming, and reported capabilities from the sidebar or via URL parameters.

​
Import

import 'sunpeak/style.css'; // Required to style the inspector.
import { Inspector } from 'sunpeak/inspector';

​
Basic Usage

For projects using the sunpeak framework, simulations are auto-discovered. Just run: 
sunpeak dev
For custom setups, you can manually configure the inspector: 
import { Inspector } from 'sunpeak/inspector';
import { resource } from './resources/example/example';
import exampleSimulation from './simulations/show-example.json';

// Combine simulation with resource
const simulations = [{
  ...exampleSimulation,
  resource,
  resourceUrl: 'http://localhost:3000/resources/example',
}];

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

​
Props

​
simulations
Record<string, Simulation>
Object mapping simulation names to their definitions. See Simulation API Reference for details.
​
appName
string
default:"Sunpeak App"
Name of the app displayed in the inspector UI.
​
appIcon
string
Optional icon (emoji) displayed in the inspector UI.
​
children
React.ReactNode
Optional children to render when no simulations are selected.
​
onCallTool
(params: { name: string; arguments?: Record<string, unknown> }) => Promise<CallToolResult> | CallToolResult
Handler for tool calls. When the user clicks Run, or when the app calls callServerTool, calls are forwarded to this callback. The sunpeak dev command wires this up automatically.
​
onCallToolDirect
(params: { name: string; arguments?: Record<string, unknown> }) => Promise<CallToolResult> | CallToolResult
Direct tool handler call, bypassing MCP server mock data. Used by the Run button to call real handlers. Falls back to onCallTool if not provided.
​
defaultProdResources
boolean
default:"false"
Initial state of the Prod Resources toggle. When true, the inspector loads resources from dist/ production builds instead of HMR. Set by the --prod-resources CLI flag.
​
hideInspectorModes
boolean
default:"false"
Hide the Prod Resources checkbox in the sidebar. Used in standalone inspect mode where Prod Resources is not applicable.

​
URL Parameters

The Inspector supports URL parameters for configuring the initial state. This is especially useful for automated testing and sharing specific configurations.

​
Supported Parameters

ParameterTypeDefaultDescription
toolstringFirst toolTool name to select. When specified without simulation, no mock data is loaded (“Press Run” state).
simulationstringFirst fixtureSimulation fixture name to load. Mock data renders immediately.
host'chatgpt' | 'claude''chatgpt'Host shell (conversation chrome, theming, capabilities)
theme'light' | 'dark''dark'Color theme
displayMode'inline' | 'pip' | 'fullscreen''inline'App display mode
localestring'en-US'Locale for i18n
maxHeightnumber600Max height in PiP mode
deviceType'mobile' | 'tablet' | 'desktop' | 'unknown''desktop'Device type
hover'true' | 'false''true'Hover capability
touch'true' | 'false''false'Touch capability
safeAreaTopnumber0Top safe area inset
safeAreaBottomnumber0Bottom safe area inset
safeAreaLeftnumber0Left safe area inset
safeAreaRightnumber0Right safe area inset
prodResources'true' | 'false''false'Enable Prod Resources mode (dist/ bundles)

​
Example URLs

# Load albums simulation with mock data
http://localhost:3000/?simulation=show-albums&theme=light

# Select a tool with no mock data (user clicks Run for real handler)
http://localhost:3000/?tool=show-albums&theme=dark

# Fullscreen dark mode
http://localhost:3000/?simulation=review-diff&theme=dark&displayMode=fullscreen

# Mobile simulation with touch
http://localhost:3000/?simulation=show-map&deviceType=mobile&touch=true&hover=false

# Claude host in light mode
http://localhost:3000/?simulation=show-albums&host=claude&theme=light

​
createInspectorUrl

For type-safe URL generation in tests, use the createInspectorUrl utility:

​
Import

import { createInspectorUrl } from 'sunpeak/inspector';

​
Usage

// Basic usage
createInspectorUrl({ simulation: 'show-albums', theme: 'light' })
// Returns: '/?simulation=show-albums&theme=light'

// With display mode
createInspectorUrl({
  simulation: 'review-diff',
  theme: 'dark',
  displayMode: 'fullscreen',
})
// Returns: '/?simulation=review-diff&theme=dark&displayMode=fullscreen'

// With device simulation
createInspectorUrl({
  simulation: 'show-map',
  deviceType: 'mobile',
  touch: true,
  hover: false,
})
// Returns: '/?simulation=show-map&deviceType=mobile&touch=true&hover=false'

// With safe area insets (for notch simulation)
createInspectorUrl({
  simulation: 'show-carousel',
  safeAreaTop: 44,
  safeAreaBottom: 34,
})
// Returns: '/?simulation=show-carousel&safeAreaTop=44&safeAreaBottom=34'

​
InspectorUrlParams Interface

interface InspectorUrlParams {
  tool?: string;
  simulation?: string;
  host?: string;
  theme?: 'light' | 'dark';
  displayMode?: 'inline' | 'pip' | 'fullscreen';
  locale?: string;
  maxHeight?: number;
  deviceType?: 'mobile' | 'tablet' | 'desktop' | 'unknown';
  hover?: boolean;
  touch?: boolean;
  safeAreaTop?: number;
  safeAreaBottom?: number;
  safeAreaLeft?: number;
  safeAreaRight?: number;
  prodResources?: boolean;
}

​
E2E Testing Example

import { test, expect } from '@playwright/test';
import { createInspectorUrl } from 'sunpeak/inspector';

test.describe('Albums Resource', () => {
  test('should render in light mode', async ({ page }) => {
    await page.goto(createInspectorUrl({
      simulation: 'show-albums',
      theme: 'light',
    }));

    const albumCard = page.locator('button:has-text("Summer Slice")');
    await expect(albumCard).toBeVisible();
  });

  test('should render in fullscreen dark mode', async ({ page }) => {
    await page.goto(createInspectorUrl({
      simulation: 'show-albums',
      theme: 'dark',
      displayMode: 'fullscreen',
    }));

    // Verify fullscreen behavior
    const expandButton = page.locator('button[aria-label="Enter fullscreen"]');
    await expect(expandButton).not.toBeVisible();
  });
});
The inspector sidebar provides interactive controls for:
  • Prod Tools: Toggle Prod Tools mode — calls real tool handlers instead of simulation mocks (requires onCallTool prop)
  • Prod Resources: Toggle Prod Resources mode — loads production-built HTML from dist/ instead of Vite HMR
  • Host: Switch between ChatGPT and Claude conversation shells
  • Simulation / Tool: Select which simulation (or tool, in Prod Tools mode) to display
  • Width: Toggle between mobile (375px, 425px), tablet (768px), and full width (1024px)
  • Theme: Toggle between light and dark themes
  • Display Mode: Switch between inline, PiP, and fullscreen modes
  • Locale: Set the locale string
  • Max Height: Configure PiP mode height
  • Device Type: Configure device type and capabilities (hover, touch)
  • Time Zone: Set the IANA time zone (e.g. America/New_York)
  • User Agent: Set the user agent string
  • Safe Area Insets: Configure safe area insets for notch simulation
  • JSON Editors: Edit tool input, tool result, and app context (model context) directly
  • Send as Partial (Streaming): Send the current tool input JSON as a tool-input-partial notification to test streaming input handling

​
ChatGPT Mock Runtime

When the ChatGPT host is selected, the inspector automatically injects a mock window.openai runtime into the resource iframe. This enables:
  • isChatGPT() returns true — host detection works correctly
  • ChatGPT-specific hooks (useUploadFile, useRequestModal, useRequestCheckout) work with stub implementations
  • All mock method calls are logged to the browser console with a [Inspector] prefix
When a different host (e.g. Claude) is selected, window.openai is not injected and ChatGPT hooks will throw if called. See ChatGPT Hooks for the full API reference.