Skip to main content

Documentation Index

Fetch the complete documentation index at: https://sunpeak.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The sunpeak dev command starts a local development server with a built-in inspector and MCP server, allowing you to develop and test your MCP Resources both locally and with hosts like ChatGPT. 
sunpeak dev

​
Features

​
Hot Module Reload (HMR)

The dev server uses Vite’s hot reload technology for instant feedback:
  • Component changes reflect immediately without full page refresh
  • State is preserved across updates when possible
  • CSS updates apply instantly
  • MCP server also supports HMR - no more cache issues or manual refreshes in ChatGPT

​
Inspector

Access the inspector at http://localhost:3000 to:
  • Test your MCP Resources in a ChatGPT-like environment
  • Simulate tool calls and responses
  • Preview your UI components with realistic styling
  • Iterate quickly without needing a tunnel or ChatGPT connection

​
MCP Server

The dev server also runs an MCP server on port 8000 for testing with hosts like ChatGPT:
  • Serves your apps to ChatGPT via MCP
  • Automatically rebuilds when you make changes
  • Uses unique URIs to cache-bust ChatGPT’s aggressive caching

​
Automatic Discovery

The dev server automatically discovers and loads:
  • All resource folders from src/resources/{name}/
  • All tool files from src/tools/*.ts
  • All simulations from tests/simulations/*.json
No manual configuration or entry point files needed!

​
Options

OptionShortDescription
--port <number>-pPort for the inspector (default: 3000, also respects PORT env var)
--prod-toolsCall real tool handlers instead of simulation mock data
--prod-resourcesServe production-built HTML from dist/ instead of Vite HMR
--no-beggingSuppress the GitHub star message on startup

​
Tool and Simulation selection

The inspector sidebar has two primary selectors:
  • Tool dropdown — selects which tool to inspect, including backend-only tools without UI resources. Selecting a backend-only tool shows Tool does not render a UI, but you can still edit Tool Input, click Run, and inspect Tool Result.
  • Simulation dropdown — selects a simulation fixture with mock data. Shown when fixtures exist for the selected tool. Includes a “None (call server)” option to bypass mock data and call the real handler via the Run button.
For programmatic testing, these map to URL parameters: 
# Mock data renders immediately (simulation fixture selected):
http://localhost:3000/?simulation=show-albums&theme=dark

# No mock data — user clicks Run for real handler:
http://localhost:3000/?tool=show-albums&theme=dark

# Hide the sidebars (app viewer only):
http://localhost:3000/?simulation=show-albums&sidebar=false

# Hide the dev overlay (for e2e tests):
http://localhost:3000/?simulation=show-albums&devOverlay=false

​
Dev Overlay

During development, a small overlay appears in the bottom-right corner of each resource showing:
  • Resource: the timestamp when the resource HTML was served (helps detect stale cached resources in ChatGPT)
  • Tool: the duration of the most recent tool call in milliseconds
The overlay is only present in development, never in production builds. To hide it:
  • Inspector URL param: devOverlay=false (used by e2e tests via the tests/e2e/helpers.ts wrapper)
  • Environment variable: SUNPEAK_DEV_OVERLAY=false disables it server-wide (used by the live test config’s devOverlay option)
  • Live test config: defineLiveConfig({ devOverlay: false }) passes the env var to the dev server

​
--prod-tools flag

When --prod-tools is used, tool calls execute your real handlers in src/tools/ instead of returning simulation mock data. The sidebar’s “Prod Tools” checkbox starts enabled (and can be toggled at runtime). 
# Integration testing: real handlers with HMR UI
sunpeak dev --prod-tools

​
--prod-resources flag

When --prod-resources is used, sunpeak build runs automatically before the dev server starts. The built HTML is served from dist/ instead of Vite HMR. Useful for catching build regressions in CI/E2E testing. 
# CI/E2E: production bundles with simulation mock data
sunpeak dev --prod-resources

​
Combining flags

The two flags are orthogonal and can be combined:
FlagsUIToolsUse case
(none)HMRMockedDay-to-day development
--prod-toolsHMRReal handlersIntegration testing
--prod-resourcesBuiltMockedCI/E2E, catch build regressions
--prod-tools --prod-resourcesBuiltReal handlersFinal smoke test before shipping

​
Configuration

​
Ports

The dev server runs multiple services on different ports:
PortServicePurposeConfigurable
3000Inspector UIMain dev server with HMR--port flag or PORT env
8000MCP serverTool execution endpoint (tunnel this for ChatGPT/Claude)SUNPEAK_MCP_PORT env
24679HMR WebSocketVite HMR for MCP resource bundlesSUNPEAK_HMR_PORT env
24680Sandbox proxyCross-origin iframe isolation (local only, not tunneled)SUNPEAK_SANDBOX_PORT env
Set SUNPEAK_DEV_OVERLAY=false to disable the dev overlay across all resources served by this server. Only port 8000 needs to be tunneled (e.g., via ngrok) for ChatGPT/Claude connections. The sandbox proxy server provides real cross-origin isolation for the inspector’s iframe architecture, matching how production hosts run apps on a separate sandbox origin.

​
Usage

sunpeak dev
Or with a custom port: 
sunpeak dev --port 3000

​
When to Use

Use sunpeak dev for:
  • Local component development with the inspector
  • Testing with real ChatGPT via the integrated MCP server
  • Rapid iteration with hot reload in either context
The dev server is for development only. For production, use sunpeak build followed by sunpeak start.

​
Connecting to ChatGPT

To test with the real ChatGPT, expose the MCP server with a tunnel: 
# In another terminal, run a tunnel
ngrok http 8000
Then connect the tunnel URL at the /mcp path (e.g., https://your-subdomain.ngrok.io/mcp) from ChatGPT in developer mode: User > Settings > Apps & Connectors > Create.

sunpeak build

Build resources and compile tools.

sunpeak start

Start the production MCP server.