Skip to main content

​
Overview

The sunpeak framework is a convention-over-configuration structure for building MCP Apps — like Next.js for AI host applications. It bundles the inspector and testing framework with a structured project layout, auto-discovery, and a CLI. 
sunpeak new my-app
cd my-app
sunpeak dev

sunpeak-app/
├── src/
│   ├── resources/
│   │   └── review/
│   │       └── review.tsx                   # Review UI component + resource metadata.
│   ├── tools/
│   │   ├── review-diff.ts                   # Tool with handler, schema, and optional resource link.
│   │   ├── review-post.ts                   # Multiple tools can share one resource.
│   │   └── review.ts                        # Backend-only tool (no resource, no UI).
│   └── server.ts                            # Optional: auth, server config.
├── tests/
│   ├── simulations/
│   │   ├── review-diff.json                 # Mock state for testing (includes serverTools).
│   │   ├── review-post.json                 # Mock state for testing (includes serverTools).
│   │   └── review-purchase.json             # Mock state for testing (includes serverTools).
│   ├── e2e/
│   │   └── review.spec.ts                   # Playwright tests against the inspector.
│   └── live/
│       └── review.spec.ts                   # Live tests against real ChatGPT (one per resource).
└── package.json

​
Convention Over Configuration

sunpeak discovers resources, tools, and simulations from your file system:
  • Resources from src/resources/{name}/{name}.tsx — each exports a React component and a resource config
  • Tools from src/tools/{name}.ts — each exports tool (metadata), schema (Zod), and a default handler. Tools with a resource field link to a resource UI.
  • Simulations from tests/simulations/{name}.json — JSON fixtures loaded by the inspector and used in E2E tests
  • Server config from src/server.ts (optional) — exports server for identity/icons and auth() for request authentication (see Authorization)

​
Runtime APIs

sunpeak provides multi-platform React hooks that wrap the MCP Apps protocol. Write your app logic once, deploy it across ChatGPT, Claude, and future hosts.

​
Data Hooks

HookDescription
useToolInput()Arguments passed to the tool by the model
useToolResult()Structured content returned by the tool handler
useAppState()Persistent state shared with the model via useUpdateModelContext()
useHostContext()Full host-provided context object

​
Environment Hooks

HookDescription
useTheme()'light' or 'dark' from the host
useDisplayMode()'inline', 'pip', or 'fullscreen'
usePlatform()'mobile', 'desktop', or 'web'
useLocale()BCP 47 language tag (e.g., 'en-US')
useTimeZone()IANA time zone (e.g., 'America/New_York')
useViewport()Container dimensions and constraints
useSafeArea()Device safe area insets
useDeviceCapabilities()Hover and touch support

​
Action Hooks

HookDescription
useCallServerTool()Call another tool on your MCP server
useOpenLink()Open a URL in the host browser
useDownloadFile()Trigger a file download
useRequestDisplayMode()Request inline/PiP/fullscreen switch
useSetAutoScroll()Control host auto-scroll behavior
See the Hooks API Reference for complete documentation.

​
Host Detection

Detect which host your app is running in — see Host Detection: 
import { detectHost, isChatGPT, isClaude } from 'sunpeak/host';

if (isChatGPT()) {
  // ChatGPT-specific behavior
}

​
MCP Server

The MCP server lets you serve your apps to AI hosts like ChatGPT and Claude. During development, sunpeak dev runs an MCP server that serves simulation fixture data. For production, use sunpeak build followed by sunpeak start. 
sunpeak dev        # Dev server with HMR + inspector + MCP endpoint
sunpeak build      # Build resources for production
sunpeak start      # Start the production MCP server
See the Deployment Guide for connecting to hosts, tunnels, and production setup.

​
UI Components

The framework includes pre-built components in src/resources/ and shared components in src/components/. These follow MCP App design guidelines using Tailwind CSS with MCP standard variables: 
<div className="text-[var(--color-text-primary)] bg-[var(--color-background-primary)]">
  Content that adapts to the host theme
</div>
See UI Components for the full list.

​
The sunpeak CLI

CommandDescription
sunpeak newCreate a new project
sunpeak devDev server with inspector and MCP endpoint
sunpeak inspectInspect any MCP server (standalone)
sunpeak buildBuild resources for production
sunpeak startStart the production MCP server
sunpeak upgradeUpgrade sunpeak to latest version
See the CLI Reference for all commands and options.

​
Dive Deeper

Inspector

Test MCP Apps in replicated ChatGPT and Claude runtimes.

Testing Framework

E2E tests against the inspector. Live tests against real hosts.

Project Scaffold

Detailed project structure and file conventions.

Deployment Guide

Deploy to production with tunnels and hosting.