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.

Definitions: An MCP App is an interactive UI embedded in an agent conversation.A ChatGPT App is an MCP App with optional ChatGPT-specific features.The UI of an MCP App is an MCP Resource.The API of an MCP App is an MCP Tool.More on MCP and the MCP Apps protocol.
This documentation is available via MCP at https://sunpeak.ai/docs/mcp, use it in your coding agent!
Install the sunpeak coding agent skills for built-in knowledge of patterns, hooks, simulations, and testing:
pnpm dlx skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server

​
sunpeak is three things

​
1. MCP App Framework

A convention-over-configuration framework for building MCP Apps with the inspector and testing built in. Like Next.js for AI chat apps. 
npx sunpeak new
Tools, resources, and simulations are auto-discovered from the file system. Multi-platform React hooks let you write your app logic once and deploy across ChatGPT, Claude, and future hosts. 
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
  • Runtime APIs: useToolData, useAppState, useTheme, useDisplayMode, and more
  • Project Scaffold: Complete dev setup with pre-configured tooling
  • Convention over configuration: resources, tools, and simulations are auto-discovered from src/ and tests/

App framework documentation

Project structure, runtime APIs, deployment, and CLI reference.

​
2. MCP Testing Framework

Automated tests for any MCP server, no sunpeak project required. Run against replicated ChatGPT and Claude runtimes. Works with Python, Go, TypeScript, Rust, or any language. 
npx sunpeak test init --server http://localhost:8000/mcp
npx sunpeak test
Playwright fixtures handle inspector startup, MCP connection, iframe traversal, and host switching. Four levels of testing: E2E, visual regression, live host tests, and multi-model evals. 
import { test, expect } from 'sunpeak/test';

test('search tool returns results', async ({ mcp }) => {
  const result = await mcp.callTool('search', { query: 'headphones' });
  expect(result.isError).toBeFalsy();
});

test('album cards render in dark mode', async ({ inspector }) => {
  const result = await inspector.renderTool('show-albums', {}, { theme: 'dark' });
  await expect(result.app().locator('button:has-text("Summer Slice")')).toBeVisible();
});

Testing documentation

Getting started, E2E, visual regression, live tests, and evals.

​
3. Inspector

See how your MCP server looks and behaves inside ChatGPT and Claude, without deploying to either. Works with any MCP server in any language. 
npx sunpeak inspect --server http://localhost:8000/mcp
The inspector replicates the ChatGPT and Claude app runtimes locally. Toggle between hosts, themes, display modes, and device types from the sidebar. Call real tool handlers or load simulation fixtures for deterministic mock data. Changes reflect instantly via HMR. No tunnel, no host account, no deployment. Just instant local feedback.

Inspector documentation

Full inspector guide, simulations, and sidebar controls.

​
The sunpeak CLI

​
Examples

Example sunpeak resource, tool, & 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.tsx

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

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

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

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

​
Tool

Each tool .ts file exports metadata (with a resource name), a Zod schema, and a handler: 
// src/tools/review-diff.ts

import { z } from 'zod';
import type { AppToolConfig, ToolHandlerExtra } from 'sunpeak/mcp';

export const tool: AppToolConfig = {
  resource: 'review',
  title: 'Diff Review',
  description: 'Show a review dialog for a proposed code diff',
  annotations: { readOnlyHint: false },
  _meta: { ui: { visibility: ['model', 'app'] } },
};

export const schema = {
  changesetId: z.string().describe('Unique identifier for the changeset'),
  title: z.string().describe('Title describing the changes'),
};

type Args = z.infer<z.ZodObject<typeof schema>>;

export default async function (args: Args, extra: ToolHandlerExtra) {
  return { structuredContent: { title: args.title, sections: [] } };
}

​
Simulation

Simulation files provide fixture data for testing. Each references a tool by filename and contains the mock input/output: 
// tests/simulations/review-diff.json

{
  "tool": "review-diff",                      // References src/tools/review-diff.ts
  "userMessage": "Refactor the auth module to use JWT tokens.",
  "toolInput": {
    "changesetId": "cs_789",
    "title": "Refactor Authentication Module"
  },
  "toolResult": {
    "structuredContent": {
      "title": "Refactor Authentication Module"
      // ...
    }
  }
}