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

# MCP App Framework

> Convention-over-configuration framework for building MCP Apps with the inspector and testing built in.

## Quickstart

Create a new MCP App project with one command:

```bash theme={null}
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](/docs/quickstart) 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](/docs/mcp-apps-inspector) and [testing framework](/docs/mcp-testing) 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.

```bash 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
```

## 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](/docs/testing/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](/docs/app-framework/guides/authorization))

## Runtime APIs

sunpeak provides multi-platform React hooks that wrap the [MCP Apps protocol](/docs/mcp-apps/introduction). Write your app logic once, deploy it across ChatGPT, Claude, and future hosts.

### Data Hooks

| Hook                                                        | Description                                                                                                           |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [`useToolData()`](/docs/app-framework/hooks/use-tool-data)       | Tool input arguments, structured output, streaming partials, error and cancellation state                             |
| [`useToolInfo()`](/docs/app-framework/hooks/use-tool-info)       | The active tool's definition (name, description, schemas)                                                             |
| [`useAppState()`](/docs/app-framework/hooks/use-app-state)       | Persistent state shared with the model via [`useUpdateModelContext()`](/docs/app-framework/hooks/use-update-model-context) |
| [`useHostContext()`](/docs/app-framework/hooks/use-host-context) | Full host-provided context object                                                                                     |
| [`useHostInfo()`](/docs/app-framework/hooks/use-host-info)       | Host name, version, and reported capabilities                                                                         |

### Environment Hooks

| Hook                                                                      | Description                                 |
| ------------------------------------------------------------------------- | ------------------------------------------- |
| [`useTheme()`](/docs/app-framework/hooks/use-theme)                            | `'light'` or `'dark'` from the host         |
| [`useDisplayMode()`](/docs/app-framework/hooks/use-display-mode)               | `'inline'`, `'pip'`, or `'fullscreen'`      |
| [`usePlatform()`](/docs/app-framework/hooks/use-platform)                      | `'mobile'`, `'desktop'`, or `'web'`         |
| [`useLocale()`](/docs/app-framework/hooks/use-locale)                          | BCP 47 language tag (e.g., `'en-US'`)       |
| [`useTimeZone()`](/docs/app-framework/hooks/use-time-zone)                     | IANA time zone (e.g., `'America/New_York'`) |
| [`useViewport()`](/docs/app-framework/hooks/use-viewport)                      | Container dimensions and constraints        |
| [`useSafeArea()`](/docs/app-framework/hooks/use-safe-area)                     | Device safe area insets                     |
| [`useDeviceCapabilities()`](/docs/app-framework/hooks/use-device-capabilities) | Hover and touch support                     |

### Action Hooks

| Hook                                                                             | Description                                                       |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [`useCallServerTool()`](/docs/app-framework/hooks/use-call-server-tool)               | Call another tool on your MCP server                              |
| [`useReadServerResource()`](/docs/app-framework/hooks/use-read-server-resource)       | Read a resource from your MCP server                              |
| [`useListServerResources()`](/docs/app-framework/hooks/use-list-server-resources)     | List resources on your MCP server                                 |
| [`useSendMessage()`](/docs/app-framework/hooks/use-send-message)                      | Send a user message into the chat                                 |
| [`useUpdateModelContext()`](/docs/app-framework/hooks/use-update-model-context)       | Push structured data to the model's context                       |
| [`useCreateSamplingMessage()`](/docs/app-framework/hooks/use-create-sampling-message) | Request an LLM completion via the host                            |
| [`useOpenLink()`](/docs/app-framework/hooks/use-open-link)                            | Open a URL in the host browser                                    |
| [`useDownloadFile()`](/docs/app-framework/hooks/use-download-file)                    | Trigger a file download                                           |
| [`useRequestDisplayMode()`](/docs/app-framework/hooks/use-request-display-mode)       | Request inline/PiP/fullscreen switch                              |
| [`useRequestTeardown()`](/docs/app-framework/hooks/use-request-teardown)              | Ask the host to unmount the View                                  |
| [`useSendLog()`](/docs/app-framework/hooks/use-send-log)                              | Send a diagnostic log to the host                                 |
| [`useRegisterTool()`](/docs/app-framework/hooks/use-register-tool)                    | Register a single app-side tool the host can call                 |
| [`useAppTools()`](/docs/app-framework/hooks/use-app-tools)                            | Declare a static set of app-side tools with a single `onCallTool` |
| [`useSendToolListChanged()`](/docs/app-framework/hooks/use-send-tool-list-changed)    | Notify the host that app-side tools changed                       |
| [`useTeardown()`](/docs/app-framework/hooks/use-teardown)                             | Reactive flag set when the host requests teardown                 |

See the [Hooks API Reference](/docs/app-framework/hooks/use-tool-data) for complete documentation.

### Host Detection

Detect which host your app is running in — see [Host Detection](/docs/app-framework/functions/host-detection):

```typescript theme={null}
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`](/docs/app-framework/cli/dev) runs an MCP server that serves simulation fixture data. For production, use [`sunpeak build`](/docs/app-framework/cli/build) followed by [`sunpeak start`](/docs/app-framework/cli/start).

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    pnpm dev        # Dev server with HMR + inspector + MCP endpoint
    pnpm build      # Build resources for production
    pnpm start      # Start the production MCP server
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm run dev        # Dev server with HMR + inspector + MCP endpoint
    npm run build      # Build resources for production
    npm run start      # Start the production MCP server
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn dev        # Dev server with HMR + inspector + MCP endpoint
    yarn build      # Build resources for production
    yarn start      # Start the production MCP server
    ```
  </Tab>
</Tabs>

See the [Deployment Guide](/docs/app-framework/guides/deployment) 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:

```tsx theme={null}
<div className="text-[var(--color-text-primary)] bg-[var(--color-background-primary)]">
  Content that adapts to the host theme
</div>
```

See [UI Components](/docs/app-framework/ui-components) for the full list.

## The sunpeak CLI

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

## Dive Deeper

<Card horizontal title="Inspector" icon="desktop" href="/docs/mcp-apps-inspector">
  Test MCP Apps in replicated ChatGPT and Claude runtimes.
</Card>

<Card horizontal title="Testing Framework" icon="flask" href="/docs/testing/overview">
  E2E tests against the inspector. Live tests against real hosts.
</Card>

<Card horizontal title="Project Scaffold" icon="folder" href="/docs/app-framework/project-scaffold">
  Detailed project structure and file conventions.
</Card>

<Card horizontal title="Deployment Guide" icon="rocket" href="/docs/app-framework/guides/deployment">
  Deploy to production with tunnels and hosting.
</Card>