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

# Overview

> Server-agnostic MCP testing framework and full-stack MCP App framework.

<Info>
  **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.

  ChatGPT apps are now submitted and published as **plugins**. An app can be the MCP-backed part of an app-only plugin or an app-plus-skills plugin. This packaging does not change the MCP Apps protocol or the app you build with sunpeak.

  The UI of an MCP App is an **[MCP Resource](/mcp-apps/mcp/resources)**.

  The API of an MCP App is an **[MCP Tool](/mcp-apps/mcp/tools)**.

  More on [MCP](/mcp-apps/mcp/overview) and the [MCP Apps protocol](/mcp-apps/introduction).
</Info>

<Tip>
  This documentation is available via MCP at [https://sunpeak.ai/docs/mcp](https://sunpeak.ai/docs/mcp), use it in your coding agent!
</Tip>

<Tip>
  Install the sunpeak coding agent skills for built-in knowledge of patterns, hooks, simulations, and testing:

  <Tabs>
    <Tab title="pnpm">
      ```bash theme={null}
      pnpm dlx skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server
      ```
    </Tab>

    <Tab title="npm">
      ```bash theme={null}
      npx skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server
      ```
    </Tab>

    <Tab title="yarn">
      ```bash theme={null}
      yarn dlx skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server
      ```
    </Tab>
  </Tabs>
</Tip>

<video src="https://cdn.sunpeak.ai/sunpeak-demo-prod.mp4" autoPlay muted loop playsInline controls className="w-full aspect-video rounded-xl" />

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

```bash theme={null}
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.

```bash theme={null} theme={null}
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](/app-framework/runtime-apis)**: `useToolData`, `useAppState`, `useTheme`, `useDisplayMode`, and more
* **[Project Scaffold](/app-framework/project-scaffold)**: Complete dev setup with pre-configured tooling
* **Convention over configuration**: resources, tools, and [simulations](/testing/simulations) are auto-discovered from `src/` and `tests/`

<Card horizontal title="App framework documentation" icon="hammer" href="/mcp-apps-framework">
  Project structure, runtime APIs, deployment, and CLI reference.
</Card>

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

```bash theme={null}
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.

```typescript theme={null}
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();
});
```

<Card horizontal title="Testing documentation" icon="flask" href="/mcp-testing">
  Getting started, E2E, visual regression, live tests, and evals.
</Card>

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

```bash theme={null}
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.

<Card horizontal title="Inspector documentation" icon="desktop" href="/mcp-apps-inspector">
  Full inspector guide, simulations, and sidebar controls.
</Card>

### The sunpeak CLI

* [`sunpeak new`](/app-framework/cli/new) - Create a new project
* [`sunpeak dev`](/app-framework/cli/dev) - Start dev server with inspector and MCP endpoint
* [`sunpeak build`](/app-framework/cli/build) - Build resources for production
* [`sunpeak start`](/app-framework/cli/start) - Start the production MCP server
* [`sunpeak test`](/testing/cli/test) - Run unit, E2E, visual, live, and eval tests
* [`sunpeak inspect`](/testing/cli/inspect) - Inspect any MCP server (standalone)
* [`sunpeak upgrade`](/testing/cli/upgrade) - Upgrade sunpeak to latest version

## 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:

```tsx theme={null} theme={null}
// 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:

```ts theme={null} theme={null}
// 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:

```jsonc theme={null} theme={null}
// 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"
      // ...
    }
  }
}
```