Create Sunpeak App

Sunpeak is a React framework built on

@modelcontextprotocol/ext-apps

sunpeak dev

sunpeak build

Getting Reference Code

Clone the sunpeak repo for working examples:

git clone --depth 1 https://github.com/Sunpeak-AI/sunpeak /tmp/sunpeak

Template app lives at

/tmp/sunpeak/packages/sunpeak/template/

Project Structure

my-sunpeak-app/
├── src/
│   ├── resources/
│   │   └── {name}/
│   │       └── {name}-resource.tsx   # Resource component + ResourceConfig export
│   └── styles/
│       └── globals.css               # Tailwind imports
├── tests/
│   ├── simulations/
│   │   └── {name}/
│   │       └── {name}-{scenario}-simulation.json  # Simulation fixture files
│   └── e2e/
│       └── {name}.spec.ts            # Playwright tests
├── package.json
└── (vite.config.ts, tsconfig.json, etc. managed by sunpeak CLI)

Discovery is convention-based:

• Resources:

  src/resources/{name}/{name}-resource.tsx

• Simulations:

  tests/simulations/{name}/{name}-{scenario}-simulation.json

Resource Component Pattern

Every resource file exports two things:

1. resource

   — A

   ResourceConfig

   object with MCP metadata
2. A named React component — The UI (

   {Name}Resource

   )

import { useToolData, useHostContext, useDisplayMode, SafeArea } from 'sunpeak';
import type { ResourceConfig } from 'sunpeak';

// MCP resource metadata
export const resource: ResourceConfig = {
  name: 'weather',
  title: 'Weather',
  description: 'Show current weather conditions',
  mimeType: 'text/html;profile=mcp-app',
  _meta: {
    ui: {
      csp: {
        resourceDomains: ['https://cdn.example.com'],
      },
    },
  },
};

// Type definitions
interface WeatherInput {
  city: string;
  units?: 'metric' | 'imperial';
}

interface WeatherOutput {
  temperature: number;
  condition: string;
  humidity: number;
}

// React component
export function WeatherResource() {
  // All hooks must be called before any early return
  const { input, output, isLoading } = useToolData<WeatherInput, WeatherOutput>();
  const context = useHostContext();
  const displayMode = useDisplayMode();

  if (isLoading) return <div className="p-4 text-[var(--color-text-secondary)]">Loading...</div>;

  const isFullscreen = displayMode === 'fullscreen';
  const hasTouch = context?.deviceCapabilities?.touch ?? false;

  return (
    <SafeArea className={isFullscreen ? 'flex flex-col h-screen' : undefined}>
      <div className="p-4">
        <h1 className="text-[var(--color-text-primary)] font-semibold">{input?.city}</h1>
        <p className={`${hasTouch ? 'text-base' : 'text-sm'} text-[var(--color-text-secondary)]`}>
          {output?.temperature}° — {output?.condition}
        </p>
      </div>
    </SafeArea>
  );
}

Rules:

• Always wrap in

  <SafeArea>

  to respect host insets
• Use MCP standard CSS variables via Tailwind arbitrary values:

  text-[var(--color-text-primary)]

  ,

  text-[var(--color-text-secondary)]

  ,

  bg-[var(--color-background-primary)]

  ,

  border-[var(--color-border-tertiary)]

• useToolData<TInput, TOutput>()

  — provide types for both input and output
• All hooks must be called before any early

  return

  (React rules of hooks)
• Do NOT mutate

  app

  directly inside hooks — use

  eslint-disable-next-line react-hooks/immutability

  for class setters

Simulation Files

Simulations are JSON fixtures that power the dev simulator and MCP server. Place them at:

tests/simulations/{name}/{name}-{scenario}-simulation.json

{
  "userMessage": "Show me the weather in Austin, TX.",
  "tool": {
    "name": "show-weather",
    "description": "Show current weather conditions",
    "inputSchema": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "units": { "type": "string", "enum": ["metric", "imperial"] }
      },
      "required": ["city"],
      "additionalProperties": false
    },
    "annotations": { "readOnlyHint": true },
    "_meta": {
      "ui": { "visibility": ["model", "app"] }
    }
  },
  "toolInput": {
    "city": "Austin",
    "units": "imperial"
  },
  "toolResult": {
    "structuredContent": {
      "temperature": 72,
      "condition": "Partly Cloudy",
      "humidity": 55
    }
  }
}

Key fields:

• userMessage

  — Decorative text shown in simulator (no functional purpose)

• tool

  — Full MCP Tool definition (used in

  tools/list

  )

• toolInput

  — Arguments sent to the tool (shown as input to

  useToolData

  )

• toolResult.structuredContent

  — The data rendered by

  useToolData().output

• toolResult.content[]

  — Text fallback for non-UI hosts

• hostContext

  — Optional overrides for

  McpUiHostContext

  (theme, locale, etc.)

Multiple simulations per resource are supported:

review-diff-simulation.json

review-post-simulation.json

Core Hooks Reference

All hooks are imported from

sunpeak

useToolData<TIn, TOut>()

{ input, inputPartial, output, isLoading, isError, isCancelled }

useHostContext()

McpUiHostContext | null

useTheme()

'light' | 'dark' | undefined

useDisplayMode()

'inline' | 'pip' | 'fullscreen'

'inline'

useSafeArea()

{ top, right, bottom, left }

useLocale()

string | undefined

'en-US'

useViewport()

{ width, height }

useIsMobile()

boolean

useApp()

App | null

useCallServerTool()

(params) => Promise<result>

useSendMessage()

(params) => Promise<void>

useOpenLink()

(params) => Promise<void>

useRequestDisplayMode()

{ requestDisplayMode, availableModes }

'inline'

'pip'

'fullscreen'

availableModes

useSendLog()

(params) => Promise<void>

useTeardown(fn)

void

useAppState(initial)

[state, setState]

updateModelContext()

useRequestDisplayMode

details

const { requestDisplayMode, availableModes } = useRequestDisplayMode();

// Always check availability before requesting
if (availableModes?.includes('fullscreen')) {
  await requestDisplayMode('fullscreen');
}
if (availableModes?.includes('pip')) {
  await requestDisplayMode('pip');
}

useCallServerTool

details

const callTool = useCallServerTool();

const result = await callTool({ name: 'get-weather', arguments: { city: 'Austin' } });
// result: { content?: [...], isError?: boolean }

useSendMessage

details

const sendMessage = useSendMessage();

await sendMessage({
  role: 'user',
  content: [{ type: 'text', text: 'Please refresh the data.' }],
});

useAppState

details

State is preserved in React and automatically sent to the host via

updateModelContext()

const [state, setState] = useAppState<{ decision: 'accepted' | 'rejected' | null }>({
  decision: null,
});
// setState triggers a re-render AND pushes state to the model context
setState({ decision: 'accepted' });

useToolData

details

const {
  input,         // TInput | null — final tool input arguments
  inputPartial,  // TInput | null — partial (streaming) input as it generates
  output,        // TOutput | null — tool result (structuredContent ?? content)
  isLoading,     // boolean — true until first toolResult arrives
  isError,       // boolean — true if tool returned an error
  isCancelled,   // boolean — true if tool was cancelled
  cancelReason,  // string | null
} = useToolData<MyInput, MyOutput>(defaultInput, defaultOutput);

Use

inputPartial

output

Commands

pnpm dev      # Start dev server (Vite + MCP server, port 3000 web / 8000 MCP)
pnpm build    # Build all resources to dist/
pnpm test     # Run unit tests (vitest)
pnpm test:e2e # Run Playwright e2e tests

The

sunpeak dev

http://localhost:3000

http://localhost:8000/mcp

Production Build Output

sunpeak build

dist/

dist/
├── weather/
│   ├── weather.html   # Self-contained bundle (JS + CSS inlined)
│   └── weather.json   # ResourceConfig with generated uri for cache-busting
├── review/
│   ├── review.html
│   └── review.json
└── ...

The

.json

ResourceConfig

.tsx

uri

ui://weather?v=abc123

.html

registerAppResource

Platform Detection

import { isChatGPT, isClaude, detectPlatform } from 'sunpeak/platform';

// In a resource component
function MyResource() {
  const platform = detectPlatform(); // 'chatgpt' | 'claude' | 'unknown'

  if (isChatGPT()) {
    // Safe to use ChatGPT-specific hooks
  }
}

ChatGPT-Specific Hooks

Import from

sunpeak/platform/chatgpt

import { useUploadFile, useRequestModal, useRequestCheckout } from 'sunpeak/platform/chatgpt';
import { isChatGPT } from 'sunpeak/platform';

function MyResource() {
  // Only call these when on ChatGPT
  const { upload } = useUploadFile();
  const { open } = useRequestModal();
  const { checkout } = useRequestCheckout();
}

useUploadFile()

useGetFileDownloadUrl(fileId)

useRequestModal(params)

useRequestCheckout(session)

SafeArea Component

Always wrap resource content in

<SafeArea>

import { SafeArea } from 'sunpeak';

export function MyResource() {
  return (
    <SafeArea>
      {/* your content */}
    </SafeArea>
  );
}

SafeArea

padding

useSafeArea()

Styling with MCP Standard Variables

Use MCP standard CSS variables via Tailwind arbitrary values instead of raw colors. These variables adapt automatically to each host's theme (ChatGPT, Claude):

text-[var(--color-text-primary)]

--color-text-primary

text-[var(--color-text-secondary)]

--color-text-secondary

bg-[var(--color-background-primary)]

--color-background-primary

bg-[var(--color-background-secondary)]

--color-background-secondary

bg-[var(--color-background-tertiary)]

--color-background-tertiary

bg-[var(--color-ring-primary)]

--color-ring-primary

border-[var(--color-border-tertiary)]

--color-border-tertiary

border-[var(--color-border-primary)]

--color-border-primary

dark:

[data-theme="dark"]

These variables use CSS

light-dark()

dark:

[data-theme="dark"]

E2E Tests with Playwright

Critical: all resource content renders inside an

<iframe>

page.frameLocator('iframe')

header

#root

page.locator()

import { test, expect } from '@playwright/test';
import { createSimulatorUrl } from 'sunpeak/chatgpt';

test('renders weather card', async ({ page }) => {
  await page.goto(createSimulatorUrl({ simulation: 'weather-show', theme: 'light' }));

  // Access elements INSIDE the resource iframe
  const iframe = page.frameLocator('iframe');
  await expect(iframe.locator('h1')).toHaveText('Austin');
});

test('loads without console errors', async ({ page }) => {
  const errors: string[] = [];
  page.on('console', (msg) => {
    if (msg.type() === 'error') errors.push(msg.text());
  });

  await page.goto(createSimulatorUrl({ simulation: 'weather-show', theme: 'dark' }));

  // Wait for content to render
  const iframe = page.frameLocator('iframe');
  await expect(iframe.locator('h1')).toBeVisible();

  // Filter expected MCP handshake noise
  const unexpectedErrors = errors.filter(
    (e) =>
      !e.includes('[IframeResource]') &&
      !e.includes('mcp') &&
      !e.includes('PostMessage') &&
      !e.includes('connect')
  );
  expect(unexpectedErrors).toHaveLength(0);
});

createSimulatorUrl(params)

simulation

string

-simulation.json

'carousel-show'

host

'chatgpt' | 'claude'

'chatgpt'

theme

'light' | 'dark'

'dark'

displayMode

'inline' | 'pip' | 'fullscreen'

'inline'

locale

string

'en-US'

deviceType

'mobile' | 'tablet' | 'desktop'

touch

boolean

hover

boolean

safeAreaTop/Bottom/Left/Right

number

ResourceConfig Fields

import type { ResourceConfig } from 'sunpeak';

export const resource: ResourceConfig = {
  name: 'my-resource',            // Unique resource name (kebab-case)
  title: 'My Resource',           // Human-readable title
  description: 'What it shows',   // Description for MCP hosts
  mimeType: 'text/html;profile=mcp-app',  // Required for MCP App resources
  _meta: {
    ui: {
      csp: {
        resourceDomains: ['https://cdn.example.com'],    // Image/script CDNs
        connectDomains: ['https://api.example.com'],     // API fetch targets
      },
    },
  },
};

AppProvider (Library Use)

When using sunpeak as a library (without the CLI framework), wrap your app in

AppProvider

import { AppProvider, useApp } from 'sunpeak';

// AppProvider handles App creation, PostMessageTransport, and connection
createRoot(document.getElementById('root')!).render(
  <AppProvider appInfo={{ name: 'MyApp', version: '1.0.0' }} capabilities={{}}>
    <MyApp />
  </AppProvider>
);

function MyApp() {
  const app = useApp(); // Reads from AppProvider context
  if (!app) return <div>Connecting...</div>;
  return <div>Connected!</div>;
}

When using the sunpeak CLI (

sunpeak dev

sunpeak build

AppProvider

Common Mistakes

1. Hooks before early returns — All hooks must run unconditionally. Move

   useMemo

   /

   useEffect

   above any

   if (...) return

   blocks.
2. Missing

   <SafeArea>

   — Always wrap content in

   <SafeArea>

   to respect host safe area insets.
3. Wrong Playwright locator — Use

   page.frameLocator('iframe').locator(...)

   for resource content, never

   page.locator(...)

   .
4. Hardcoded colors — Use MCP standard CSS variables via Tailwind arbitrary values (

   text-[var(--color-text-primary)]

   ,

   bg-[var(--color-background-primary)]

   ) not raw colors.
5. Simulation name mismatch — The simulation key is the filename without

   -simulation.json

   :

   carousel-show-simulation.json

   →

   carousel-show

   .
6. Mutating hook params — Use

   eslint-disable-next-line react-hooks/immutability

   for

   app.onteardown = ...

   (class setter, not a mutation).
7. Forgetting text fallback — Include

   toolResult.content[]

   in simulations for non-UI hosts.

References

• sunpeak Documentation
• MCP Apps Documentation
• MCP Apps SDK
• ChatGPT Apps SDK Design Guidelines