Skip to main content

Overview

When you create a new project with sunpeak new, the sunpeak framework gives you a minimal, convention-based project structure with everything needed for MCP App development.
my-app/
├── src/resources/
   └── review/
       └── review-resource.tsx # Review UI component + resource metadata.
├── tests/simulations/
   └── review/
       ├── review-{scenario1}-simulation.json  # Mock state for testing.
       └── review-{scenario2}-simulation.json  # Mock state for testing.
└── package.json

Key Files & Directories

  • src/resources/ - Directory containing all your MCP Resources (MCP App UIs).
    • Each resource lives in its own folder: src/resources/{name}/
    • Each folder contains:
      • {name}-resource.tsx - React component + resource metadata (export const resource: ResourceConfig)
      • components/ - Optional subfolder for resource-specific components
  • tests/simulations/ - Directory containing simulation files for local development and testing.
    • Each resource’s simulations live in their own folder: tests/simulations/{name}/
    • Simulation files follow the naming convention: {name}-{scenario}-simulation.json
  • tests/e2e/ - Directory containing end-to-end Playwright tests for each resource. Uses the ChatGPTSimulator to test your resources render properly with any state (tool calls, saved state, dark mode, pip display mode, etc.).
No entry point files needed! The framework automatically discovers your simulations and resources using conventions.

Examples

Example sunpeak resource & simulation files for an MCP App called “Review”.

Resource

Each resource .tsx file exports both a ResourceConfig metadata object and the React component:
// src/resources/review/review-resource.tsx

import { useToolData } from 'sunpeak';
import type { ResourceConfig } from 'sunpeak';

export const resource: ResourceConfig = {
  name: 'review',
  description: 'Visualize and review a code change',
  _meta: { ui: { csp: { resourceDomains: ['https://cdn.openai.com'] } } },
};

export function ReviewResource() {
  const { output: data } = useToolData<unknown, { title: string }>();

  return <h1>Review: {data?.title}</h1>;
}

Simulation

Testing an MCP App requires setting a lot of state: state in your backend (accessed via MCP tool), the app runtime, and the host agent itself. Simulation files let you define key App states for development, automated testing, and demo purposes. Simulation files contain an official MCP Tool object and tool result data with structured content. Host state (like light/dark mode) is not set on the simulation, but rather on the sunpeak simulator itself via UI, props, or URL params.
// tests/simulations/review-diff-simulation.json

{
  // Official MCP tool object.
  "tool": {
    "name": "review-diff",
    "description": "Show a review dialog for a proposed code diff",
    "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
    "title": "Diff Review",
    "annotations": { "readOnlyHint": false },
    "_meta": {
      "ui": { "visibility": ["model", "app"] },
    },
  },
  // Tool input arguments (sent to CallTool).
  "toolInput": {
    "changesetId": "cs_789",
    "title": "Refactor Authentication Module",
  },
  // Tool result data (CallToolResult response).
  "toolResult": {
    "structuredContent": {
      "title": "Refactor Authentication Module",
      // ...
    },
  },
}

Included Tooling

The template includes minimal, essential tooling:

Vite

Fast build tool with hot-reload (HMR) for instant development feedback. The framework owns the dev server configuration - just run sunpeak dev.

Tailwind CSS 4

Utility-first CSS framework for rapid UI development. Pre-configured via Vite plugin.

TypeScript

Type safety with TypeScript 5. Configured via tsconfig.json.

Vitest (Unit Tests)

Vite-native testing framework for component testing. Run with pnpm test.

Playwright (E2E Tests)

End-to-end testing against the ChatGPT Simulator. Tests live in tests/e2e/. Run with pnpm test:e2e.

Add Your Own Tooling

The template is intentionally minimal. Add your preferred tools as needed:
  • Linting: ESLint
  • Formatting: Prettier
  • Type checking: Run tsc --noEmit as a script

sunpeak CLI API Reference

All sunpeak CLI commands and configurations.