sunpeak 0.15.4 → 0.16.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sunpeak",
-  "version": "0.15.4",
+  "version": "0.16.2",
   "description": "Local-first MCP Apps framework. Quickstart, build, test, and ship your Claude or ChatGPT App!",
   "type": "module",
   "main": "./dist/index.cjs",

package/template/.sunpeak/dev.tsx

@@ -4,8 +4,8 @@
  * This file bootstraps the multi-host simulator for development.
  *
  * Auto-discovers simulations and resources by file naming convention:
- * - tests/simulations/{resource}/{resource}-{scenario}-simulation.json
- * - src/resources/{resource}/{resource}-resource.tsx (component + resource metadata)
+ * - tests/simulations/*.json
+ * - src/resources/{resource}/{resource}.tsx (component + resource metadata)
  * - src/resources/{resource}/{Resource}Resource component (PascalCase)
  */
 import { StrictMode } from 'react';
@@ -18,9 +18,13 @@ const { Simulator, buildDevSimulations } = simulator;
 
 // Build simulations from discovered files
 const simulations = buildDevSimulations({
-  simulationModules: import.meta.glob('../tests/simulations/*/*-simulation.json', { eager: true }),
-  resourceModules: import.meta.glob('../src/resources/*/*-resource.tsx', { eager: true }),
+  simulationModules: import.meta.glob('../tests/simulations/*.json', { eager: true }),
   resourceComponents: resourceComponents as Record<string, React.ComponentType>,
+  toolModules: import.meta.glob('../src/tools/*.ts', { eager: true }),
+  resourceModules: import.meta.glob(
+    ['../src/resources/*/*.tsx', '!../src/resources/*/*.test.tsx'],
+    { eager: true }
+  ),
 });
 
 // Read app config from environment or use defaults

package/template/.sunpeak/resource-loader.tsx

@@ -17,6 +17,7 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 import { AppProvider } from 'sunpeak';
+import pkg from '../package.json';
 import '../src/styles/globals.css';
 import resourceComponents from '../src/resources';
 
@@ -39,7 +40,7 @@ if (!componentName) {
 
     root.render(
       <StrictMode>
-        <AppProvider appInfo={{ name: componentName, version: '1.0.0' }}>
+        <AppProvider appInfo={{ name: pkg.name || componentName, version: pkg.version || '1.0.0' }}>
           <Component />
         </AppProvider>
       </StrictMode>

package/template/README.md

@@ -18,7 +18,8 @@ That's it! Edit the resource files in [./src/resources/](./src/resources/) to bu
 pnpm test              # Run tests with Vitest.
 pnpm test:e2e          # Run end-to-end tests with Playwright.
 sunpeak dev            # Start dev server + MCP endpoint.
-sunpeak build          # Build all resources for production.
+sunpeak build          # Build resources and compile tools for production.
+sunpeak start          # Start the production MCP server.
 sunpeak upgrade        # Upgrade sunpeak to latest version.
 ```
 
@@ -32,11 +33,15 @@ Using a Review page as an example, sunpeak projects look like:
 my-app/
 ├── src/resources/
 │   └── review/
-│       └── review-resource.tsx # Review UI component + resource metadata.
+│       └── review.tsx            # Review UI component + resource metadata.
+├── src/tools/
+│   ├── review-diff.ts            # Tool: metadata, schema, handler.
+│   ├── review-post.ts
+│   └── review-purchase.ts
 ├── tests/simulations/
-│   └── review/
-│       ├── review-{scenario1}-simulation.json  # Mock state for testing.
-│       └── review-{scenario2}-simulation.json  # Mock state for testing.
+│   ├── review-diff.json          # Mock state for testing.
+│   ├── review-post.json
+│   └── review-purchase.json
 └── package.json
 ```
 
@@ -58,31 +63,31 @@ Once your app is connected, send the name of the app and a tool, like `/sunpeak
 
 ## Build & Deploy
 
-Build your app for production:
+Build and start your app for production:
 
 ```bash
-sunpeak build
+sunpeak build && sunpeak start
 ```
 
-This creates optimized builds in `dist/`, organized by resource:
+`sunpeak build` creates optimized builds in `dist/`:
 
 ```bash
 dist/
 ├── albums/
 │   ├── albums.html           # Built resource bundle.
 │   └── albums.json           # ResourceConfig (extracted from .tsx).
-├── review/
-│   ├── review.html
-│   └── review.json
+├── tools/
+│   ├── show-albums.js        # Compiled tool handler + schema.
+│   └── ...
+├── server.js                 # Compiled server entry (if src/server.ts exists).
 └── ...
 ```
 
-Each resource folder contains:
-
-- **`.html` file**: Self-contained bundle with JS and CSS inlined
-- **`.json` file**: Resource metadata (extracted from the `resource` export in your `.tsx` file) with a generated `uri` for cache-busting
+`sunpeak start` loads the compiled tools and resources, then starts a production MCP server with real handlers, Zod input validation, and optional auth.
 
-Host these files and reference them as resources in your production MCP server.
+```bash
+sunpeak start --port 3000     # Custom port (default: 8000)
+```
 
 ## Add a new UI (Resource)
 
@@ -90,14 +95,14 @@ To add a new UI (MCP Resource), create a new directory under `src/resources/` wi
 
 ```
 src/resources/NAME/
-├── NAME-resource.tsx              # React component + resource metadata (required)
-├── NAME-resource.test.tsx         # Unit tests (optional)
-└── components/                    # UI components (optional)
+├── NAME.tsx                      # React component + resource metadata (required)
+├── NAME.test.tsx                 # Unit tests (optional)
+└── components/                   # UI components (optional)
 ```
 
-Only the resource file (`.tsx`) is required to generate a production build and ship a UI. It must export a `resource` object (`ResourceConfig`) describing the resource metadata, and a React component that renders the UI.
+Only the resource file (`.tsx`) is required to generate a production build and ship a UI. It must export a `resource` object (`ResourceConfig`) describing the resource metadata, and a React component that renders the UI. The resource name is auto-derived from the directory name.
 
-Create the simulation file(s) in `tests/simulations/` if you want to preview your resource in `sunpeak dev`.
+Then create a tool file in `src/tools/` and simulation file(s) in `tests/simulations/` to preview your resource in `sunpeak dev`.
 
 ## Coding Agent Skill
 
@@ -110,6 +115,6 @@ npx skills add Sunpeak-AI/sunpeak@create-sunpeak-app
 ## Resources
 
 - [sunpeak](https://github.com/Sunpeak-AI/sunpeak)
+- [MCP Apps Documentation](https://sunpeak.ai/docs/mcp-apps/introduction)
 - [MCP Apps SDK](https://github.com/modelcontextprotocol/ext-apps)
 - [ChatGPT Apps SDK Design Guidelines](https://developers.openai.com/apps-sdk/concepts/design-guidelines)
-- [ChatGPT Apps SDK UI Documentation](https://developers.openai.com/apps-sdk/build/chatgpt-ui)

package/template/package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "dev": "sunpeak dev",
     "build": "sunpeak build",
+    "start": "sunpeak start",
     "test": "vitest run",
     "test:e2e": "playwright test"
   },
@@ -15,7 +16,8 @@
     "embla-carousel-wheel-gestures": "^8.1.0",
     "mapbox-gl": "^3.17.0",
     "sunpeak": "workspace:*",
-    "tailwind-merge": "^3.4.0"
+    "tailwind-merge": "^3.4.0",
+    "zod": "^3.25.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.57.0",

package/template/src/resources/albums/{albums-resource.test.tsx → albums.test.tsx}

@@ -1,6 +1,6 @@
 import { render, screen } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { AlbumsResource } from './albums-resource';
+import { AlbumsResource } from './albums';
 
 // Mock sunpeak — SafeArea renders as a plain div
 vi.mock('sunpeak', () => ({

package/template/src/resources/albums/{albums-resource.tsx → albums.tsx}

@@ -3,7 +3,6 @@ import type { ResourceConfig } from 'sunpeak';
 import { Albums } from './components/albums';
 
 export const resource: ResourceConfig = {
-  name: 'albums',
   title: 'Albums',
   description: 'Show photo albums widget',
   mimeType: 'text/html;profile=mcp-app',

package/template/src/resources/carousel/{carousel-resource.test.tsx → carousel.test.tsx}

@@ -1,6 +1,6 @@
 import { render, screen } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { CarouselResource } from './carousel-resource';
+import { CarouselResource } from './carousel';
 
 // Mock sunpeak hooks
 interface Place {

package/template/src/resources/carousel/{carousel-resource.tsx → carousel.tsx}

@@ -3,7 +3,6 @@ import type { ResourceConfig } from 'sunpeak';
 import { Carousel, Card } from './components';
 
 export const resource: ResourceConfig = {
-  name: 'carousel',
   title: 'Carousel',
   description: 'Show popular places to visit widget',
   mimeType: 'text/html;profile=mcp-app',

package/template/src/resources/index.ts

@@ -1,8 +1,8 @@
 /**
  * Auto-discovers and re-exports all resource components.
  *
- * Discovers all {resource}/{resource}-resource.tsx files and exports their component
- * with a PascalCase name (e.g., albums/albums-resource.tsx -> AlbumsResource).
+ * Discovers all {resource}/{resource}.tsx files and exports their component
+ * with a PascalCase name (e.g., albums/albums.tsx -> AlbumsResource).
  *
  * Supports both export styles:
  * - Default export: export default MyComponent
@@ -10,8 +10,8 @@
  */
 import { createResourceExports } from 'sunpeak';
 
-// Auto-discover all resource component files in subdirectories
-const resourceModules = import.meta.glob('./*/*-resource.tsx', { eager: true });
+// Auto-discover all resource component files in subdirectories (exclude test files)
+const resourceModules = import.meta.glob(['./*/*.tsx', '!./*/*.test.tsx'], { eager: true });
 
 // Build exports object from discovered files using library helper
 export default createResourceExports(resourceModules);

package/template/src/resources/map/{map-resource.test.tsx → map.test.tsx}

@@ -1,6 +1,6 @@
 import { render, screen } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { MapResource } from './map-resource';
+import { MapResource } from './map';
 
 // Mock sunpeak — SafeArea renders as a plain div
 vi.mock('sunpeak', () => ({

package/template/src/resources/map/{map-resource.tsx → map.tsx}

@@ -3,7 +3,6 @@ import type { ResourceConfig } from 'sunpeak';
 import { Map } from './components/map';
 
 export const resource: ResourceConfig = {
-  name: 'map',
   title: 'Map',
   description: 'Pizza restaurant finder widget',
   mimeType: 'text/html;profile=mcp-app',

package/template/src/resources/review/{review-resource.test.tsx → review.test.tsx}

@@ -1,6 +1,6 @@
 import { render, screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { ReviewResource } from './review-resource';
+import { ReviewResource } from './review';
 
 // Mock sunpeak hooks
 const mockSetState = vi.fn();

package/template/src/resources/review/{review-resource.tsx → review.tsx}

@@ -11,7 +11,6 @@ import { Button } from '../../components/button';
 import { ExpandLg } from '../../components/icon';
 
 export const resource: ResourceConfig = {
-  name: 'review',
   title: 'Review',
   description: 'Visualize and review a proposed set of changes or actions',
   mimeType: 'text/html;profile=mcp-app',
@@ -475,7 +474,7 @@ export function ReviewResource() {
       </div>
 
       {/* Footer with Actions */}
-      <div className="px-4 py-3 border-t border-[var(--color-border-tertiary)] bg-[var(--color-background-primary)]">
+      <div className="px-4 py-3 border-t border-[var(--color-border-tertiary)]">
         {decision === null ? (
           <div className="flex gap-3">
             <Button

package/template/src/server.ts

@@ -0,0 +1,17 @@
+import type { IncomingMessage } from 'node:http';
+import type { AuthInfo } from 'sunpeak/mcp';
+
+/**
+ * Optional server entry point.
+ *
+ * Called on every MCP request. Return AuthInfo to authenticate, null to reject (401).
+ * The returned AuthInfo is available as `extra.authInfo` in tool handlers.
+ */
+export async function auth(req: IncomingMessage): Promise<AuthInfo | null> {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  // Allow unauthenticated requests (no token = anonymous access).
+  // To require auth, return null here instead.
+  return { token: token ?? '', clientId: 'anonymous', scopes: [] };
+}
+
+export const server = { name: 'Sunpeak', version: '1.0.0' };

package/template/src/tools/review-diff.ts

@@ -0,0 +1,24 @@
+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'),
+  description: z.string().describe('Detailed description of what the changes accomplish'),
+  files: z.array(z.string()).describe('List of file paths affected by this change'),
+  runMigrations: z.boolean().describe('Whether to run database migrations as part of the change'),
+};
+
+export default async function (_args: Record<string, unknown>, _extra: ToolHandlerExtra) {
+  return { structuredContent: { title: 'Review', sections: [] } };
+}

package/template/src/tools/review-post.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import type { AppToolConfig, ToolHandlerExtra } from 'sunpeak/mcp';
+
+export const tool: AppToolConfig = {
+  resource: 'review',
+  title: 'Review Post',
+  description: 'Review a social media post before publishing',
+  annotations: { readOnlyHint: false },
+  _meta: {
+    ui: { visibility: ['model', 'app'] },
+  },
+};
+
+export const schema = {
+  content: z.string().describe('The text content of the post'),
+  platforms: z
+    .array(z.enum(['x', 'linkedin', 'facebook', 'instagram']))
+    .describe('Social media platforms to post to'),
+  schedule: z.enum(['now', 'scheduled']).describe('When to publish the post'),
+  scheduledTime: z.string().describe('ISO 8601 timestamp for scheduled posts'),
+  visibility: z.enum(['public', 'connections', 'private']).describe('Post visibility setting'),
+};
+
+export default async function (_args: Record<string, unknown>, _extra: ToolHandlerExtra) {
+  return { structuredContent: { title: 'Review Your Post', sections: [] } };
+}

package/template/src/tools/review-purchase.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { AppToolConfig, ToolHandlerExtra } from 'sunpeak/mcp';
+
+export const tool: AppToolConfig = {
+  resource: 'review',
+  title: 'Review Purchase',
+  description: 'Review a purchase before completing the transaction',
+  annotations: { readOnlyHint: false },
+  _meta: {
+    ui: { visibility: ['model', 'app'] },
+  },
+};
+
+export const schema = {
+  cartId: z.string().describe('Shopping cart identifier'),
+  items: z
+    .array(
+      z.object({
+        productId: z.string(),
+        quantity: z.number(),
+      })
+    )
+    .describe('List of items to purchase'),
+  shippingAddressId: z.string().describe('ID of the saved shipping address'),
+  shippingMethod: z.enum(['standard', 'express', 'overnight']).describe('Shipping speed'),
+  paymentMethodId: z.string().describe('ID of the saved payment method'),
+};
+
+export default async function (_args: Record<string, unknown>, _extra: ToolHandlerExtra) {
+  return { structuredContent: { title: 'Confirm Your Order', sections: [] } };
+}

package/template/src/tools/show-albums.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { AppToolConfig, ToolHandlerExtra } from 'sunpeak/mcp';
+
+export const tool: AppToolConfig = {
+  resource: 'albums',
+  title: 'Show Albums',
+  description: 'Show photo albums',
+  annotations: { readOnlyHint: true },
+  _meta: {
+    ui: { visibility: ['model', 'app'] },
+  },
+};
+
+export const schema = {
+  category: z.string().describe('Filter albums by category (e.g., travel, food, family)'),
+  search: z.string().describe('Search term to filter albums by title or description'),
+  limit: z.number().describe('Maximum number of albums to return'),
+};
+
+export default async function (_args: Record<string, unknown>, _extra: ToolHandlerExtra) {
+  return { structuredContent: { albums: [] } };
+}

package/template/src/tools/show-carousel.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import type { AppToolConfig, ToolHandlerExtra } from 'sunpeak/mcp';
+
+export const tool: AppToolConfig = {
+  resource: 'carousel',
+  title: 'Show Carousel',
+  description: 'Show popular places to visit',
+  annotations: { readOnlyHint: true },
+  _meta: {
+    ui: { visibility: ['model', 'app'] },
+  },
+};
+
+export const schema = {
+  city: z.string().describe('City name to search for places'),
+  state: z.string().describe('State or region'),
+  categories: z
+    .array(z.string())
+    .describe('Filter by categories (e.g., parks, restaurants, landmarks)'),
+  limit: z.number().describe('Maximum number of places to return'),
+};
+
+export default async function (_args: Record<string, unknown>, _extra: ToolHandlerExtra) {
+  return { structuredContent: { places: [] } };
+}

package/template/src/tools/show-map.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import type { AppToolConfig, ToolHandlerExtra } from 'sunpeak/mcp';
+
+export const tool: AppToolConfig = {
+  resource: 'map',
+  title: 'Show Map',
+  description: 'Show the map',
+  annotations: { readOnlyHint: true },
+  _meta: {
+    ui: { visibility: ['model', 'app'] },
+  },
+};
+
+export const schema = {
+  query: z.string().describe('Search query for places (e.g., pizza, coffee, restaurants)'),
+  location: z
+    .object({
+      lat: z.number(),
+      lng: z.number(),
+    })
+    .describe('Center location for the search'),
+  radius: z.number().describe('Search radius in miles'),
+  minRating: z.number().describe('Minimum rating filter (1-5)'),
+  priceRange: z.array(z.enum(['$', '$$', '$$$', '$$$$'])).describe('Price range filter'),
+};
+
+export default async function (_args: Record<string, unknown>, _extra: ToolHandlerExtra) {
+  return { structuredContent: { places: [] } };
+}

package/template/tests/e2e/albums.spec.ts

@@ -7,7 +7,7 @@ for (const host of hosts) {
   test.describe(`Albums Resource [${host}]`, () => {
     test.describe('Light Mode', () => {
       test('should render album cards with correct styles', async ({ page }) => {
-        await page.goto(createSimulatorUrl({ simulation: 'albums-show', theme: 'light', host }));
+        await page.goto(createSimulatorUrl({ simulation: 'show-albums', theme: 'light', host }));
 
         const iframe = page.frameLocator('iframe');
         const albumCard = iframe.locator('button:has-text("Summer Slice")');
@@ -27,7 +27,7 @@ for (const host of hosts) {
       });
 
       test('should have album image with correct aspect ratio', async ({ page }) => {
-        await page.goto(createSimulatorUrl({ simulation: 'albums-show', theme: 'light', host }));
+        await page.goto(createSimulatorUrl({ simulation: 'show-albums', theme: 'light', host }));
 
         const iframe = page.frameLocator('iframe');
         const albumImage = iframe.locator('button:has-text("Summer Slice") img').first();
@@ -54,7 +54,7 @@ for (const host of hosts) {
 
     test.describe('Dark Mode', () => {
       test('should render album cards with correct styles', async ({ page }) => {
-        await page.goto(createSimulatorUrl({ simulation: 'albums-show', theme: 'dark', host }));
+        await page.goto(createSimulatorUrl({ simulation: 'show-albums', theme: 'dark', host }));
 
         const iframe = page.frameLocator('iframe');
         const albumCard = iframe.locator('button:has-text("Summer Slice")');
@@ -73,7 +73,7 @@ for (const host of hosts) {
       });
 
       test('should have text with appropriate contrast', async ({ page }) => {
-        await page.goto(createSimulatorUrl({ simulation: 'albums-show', theme: 'dark', host }));
+        await page.goto(createSimulatorUrl({ simulation: 'show-albums', theme: 'dark', host }));
 
         const iframe = page.frameLocator('iframe');
         const albumTitle = iframe.locator('button:has-text("Summer Slice") div').first();
@@ -96,7 +96,7 @@ for (const host of hosts) {
       test('should render correctly in fullscreen displayMode', async ({ page }) => {
         await page.goto(
           createSimulatorUrl({
-            simulation: 'albums-show',
+            simulation: 'show-albums',
             theme: 'light',
             displayMode: 'fullscreen',
             host,
@@ -114,7 +114,7 @@ for (const host of hosts) {
       test('should maintain album card styles in fullscreen', async ({ page }) => {
         await page.goto(
           createSimulatorUrl({
-            simulation: 'albums-show',
+            simulation: 'show-albums',
             theme: 'dark',
             displayMode: 'fullscreen',
             host,

package/template/tests/e2e/carousel.spec.ts

@@ -7,7 +7,7 @@ for (const host of hosts) {
   test.describe(`Carousel Resource [${host}]`, () => {
     test.describe('Light Mode', () => {
       test('should render carousel cards with correct styles', async ({ page }) => {
-        await page.goto(createSimulatorUrl({ simulation: 'carousel-show', theme: 'light', host }));
+        await page.goto(createSimulatorUrl({ simulation: 'show-carousel', theme: 'light', host }));
 
         const iframe = page.frameLocator('iframe');
         const card = iframe.locator('.rounded-2xl').first();
@@ -26,7 +26,7 @@ for (const host of hosts) {
       });
 
       test('should have card with border styling', async ({ page }) => {
-        await page.goto(createSimulatorUrl({ simulation: 'carousel-show', theme: 'light', host }));
+        await page.goto(createSimulatorUrl({ simulation: 'show-carousel', theme: 'light', host }));
 
         const iframe = page.frameLocator('iframe');
         const card = iframe.locator('.rounded-2xl.border').first();
@@ -45,7 +45,7 @@ for (const host of hosts) {
       });
 
       test('should have interactive buttons', async ({ page }) => {
-        await page.goto(createSimulatorUrl({ simulation: 'carousel-show', theme: 'light', host }));
+        await page.goto(createSimulatorUrl({ simulation: 'show-carousel', theme: 'light', host }));
 
         const iframe = page.frameLocator('iframe');
         const visitButton = iframe.locator('button:has-text("Visit")').first();
@@ -64,7 +64,7 @@ for (const host of hosts) {
 
     test.describe('Dark Mode', () => {
       test('should render carousel cards with correct styles', async ({ page }) => {
-        await page.goto(createSimulatorUrl({ simulation: 'carousel-show', theme: 'dark', host }));
+        await page.goto(createSimulatorUrl({ simulation: 'show-carousel', theme: 'dark', host }));
 
         const iframe = page.frameLocator('iframe');
         const card = iframe.locator('.rounded-2xl').first();
@@ -83,7 +83,7 @@ for (const host of hosts) {
       });
 
       test('should have appropriate styling for dark mode', async ({ page }) => {
-        await page.goto(createSimulatorUrl({ simulation: 'carousel-show', theme: 'dark', host }));
+        await page.goto(createSimulatorUrl({ simulation: 'show-carousel', theme: 'dark', host }));
 
         const iframe = page.frameLocator('iframe');
         // Select card by its border + rounded combo
@@ -110,7 +110,7 @@ for (const host of hosts) {
           }
         });
 
-        await page.goto(createSimulatorUrl({ simulation: 'carousel-show', theme: 'dark', host }));
+        await page.goto(createSimulatorUrl({ simulation: 'show-carousel', theme: 'dark', host }));
 
         // Wait for iframe content to render
         const iframe = page.frameLocator('iframe');