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.

​
Quickstart

Create a new MCP App project with one command: 
npx sunpeak new
This scaffolds a project with example tools, resources, simulations, and tests, then starts a dev server with HMR and opens the inspector at http://localhost:3000. An MCP endpoint starts at http://localhost:8000/mcp for testing with real hosts. See the full quickstart guide for step-by-step setup through production deployment.

​
What it does

The sunpeak framework is a convention-over-configuration structure for building MCP Apps. It bundles the inspector and testing framework with a structured project layout, auto-discovery, and a CLI. Building an MCP App from scratch means wiring up an MCP server, handling protocol details, managing resource HTML, and setting up a dev environment. sunpeak handles all of that and gives you a structured project with testing from the start. 
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/
│   ├── unit/
│   │   └── review.test.ts                   # Unit tests for component and hook logic.
│   ├── 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).
│   └── evals/
│       └── review.eval.ts                   # Multi-model tool calling evals.
└── 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. 
pnpm dev        # Dev server with HMR + inspector + MCP endpoint
pnpm build      # Build resources for production
pnpm 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 buildBuild resources for production
sunpeak startStart the production MCP server
sunpeak testRun unit, E2E, visual, live, and eval tests
sunpeak inspectInspect any MCP server (standalone)
sunpeak upgradeUpgrade sunpeak to latest version

​
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.