{"id":12102,"library":"sunpeak","title":"Sunpeak AI App Framework and Testing","description":"Sunpeak (current version 0.20.7) is an AI application framework, testing framework, and inspector specifically designed for building and debugging Multi-Platform (MCP) Apps, such as those for ChatGPT and Claude. It provides a convention-over-configuration approach to simplify wiring MCP servers, handling protocol messages, managing resource HTML bundles, and setting up dev environments with hot module replacement (HMR). Its key differentiators include a robust testing framework that simulates host runtimes and provides simulation fixtures for reproducible testing across various hosts, themes, and data states without relying on external accounts or API credits. It also offers a visual inspector for debugging. Sunpeak releases are frequent, primarily focusing on bug fixes, performance improvements, and feature enhancements within the 0.x.x minor version range, indicating active development.","status":"active","version":"0.20.7","language":"javascript","source_language":"en","source_url":"https://github.com/Sunpeak-AI/sunpeak","tags":["javascript","openai-app","chatgpt-apps-sdk","chatgpt-app","mcp-ui","mcp","chatgpt-inspector","claude","claude-inspector","typescript"],"install":[{"cmd":"npm install sunpeak","lang":"bash","label":"npm"},{"cmd":"yarn add sunpeak","lang":"bash","label":"yarn"},{"cmd":"pnpm add sunpeak","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for building UIs with Sunpeak's App Framework and inspector rendering.","package":"react","optional":false},{"reason":"DOM rendering for React components within Sunpeak apps.","package":"react-dom","optional":false},{"reason":"Core AI SDK for interacting with various language models.","package":"ai","optional":false},{"reason":"OpenAI provider for the AI SDK.","package":"@ai-sdk/openai","optional":true},{"reason":"Anthropic provider for the AI SDK.","package":"@ai-sdk/anthropic","optional":true},{"reason":"Google AI provider for the AI SDK.","package":"@ai-sdk/google","optional":true}],"imports":[{"note":"The testing utilities are designed for ESM. Use named imports. CommonJS `require` will fail in modern setups.","wrong":"const { test, expect } = require('sunpeak/test');","symbol":"test","correct":"import { test, expect } from 'sunpeak/test';"},{"note":"These React hooks are essential for building interactive MCP Apps within the Sunpeak framework.","symbol":"useToolData","correct":"import { useToolData, useAppState } from 'sunpeak/react';"},{"note":"Used for Playwright test configurations. The path changed in v0.19.1; `sunpeak/test/live/config` is deprecated.","wrong":"import { defineConfig } from 'sunpeak/test/live/config';","symbol":"defineConfig","correct":"import { defineConfig } from 'sunpeak/test/config';"}],"quickstart":{"code":"import { test, expect } from 'sunpeak/test';\nimport { createOpenAI } from '@ai-sdk/openai';\n\n// To initialize a new Sunpeak project:\n// npx sunpeak new\n\n// Then, add a test file (e.g., tests/e2e/my-app.test.ts)\n\n// Mock your AI model for consistent testing\nconst mockOpenAI = createOpenAI({ apiKey: process.env.OPENAI_API_KEY ?? 'mock-key' });\n\ntest('My MCP App loads and renders a tool', async ({ page, inspector, mcp }) => {\n  // Render a specific tool within the Sunpeak inspector\n  await inspector.renderTool({ name: 'my-awesome-tool', params: { query: 'test' } });\n\n  // Wait for the tool's UI to appear and interact with it\n  await expect(page.locator('text=Welcome to My Awesome Tool')).toBeVisible();\n\n  // You can also mock tool calls to the MCP server\n  mcp.useTool(async ({ name, params }) => {\n    if (name === 'my-awesome-tool') {\n      const result = await mockOpenAI.chat({\n        model: 'gpt-4o',\n        messages: [{ role: 'user', content: params.query as string }],\n      });\n      return { result: result.text };\n    }\n    return { result: 'Unknown tool' };\n  });\n\n  // Simulate an interaction or assert on UI changes\n  await page.locator('button', { hasText: 'Execute' }).click();\n  await expect(page.locator('text=Execution complete')).toBeVisible();\n});\n\n// To run the tests:\n// npx sunpeak test --e2e","lang":"typescript","description":"This quickstart demonstrates how to initialize a Sunpeak project and write an end-to-end test for an MCP App using the `sunpeak/test` framework, including mocking AI model interactions."},"warnings":[{"fix":"Update test files to use the new `inspector` fixture for rendering and hosting methods. For example, change `mcp.renderTool(...)` to `inspector.renderTool(...)`.","message":"The test fixture API was redesigned, splitting the single `mcp` fixture into two: `mcp` (for MCP protocol methods) and `inspector` (for Sunpeak inspector rendering methods like `renderTool` and `host`). Code using `mcp.renderTool` will now fail.","severity":"breaking","affected_versions":">=0.20.1"},{"fix":"Review and update all test file imports. Change `import { mcp } from 'sunpeak/test/live'` to `import { mcp } from 'sunpeak/test'`. Update Playwright config imports from `sunpeak/test/live/config` to `sunpeak/test/config`.","message":"Significant changes to the testing framework import paths and default fixtures. `sunpeak/test` became the primary module for the `mcp` fixture, replacing older `live` imports. `defineConfig()` moved from `sunpeak/test/live/config` to `sunpeak/test/config`.","severity":"breaking","affected_versions":">=0.19.1"},{"fix":"Ensure your `vitest` or testing configuration is set up for ESM, especially if you encounter `require is not defined` errors. This might involve updating `package.json` to `\"type\": \"module\"` or configuring loaders.","message":"Unit tests were updated for ESM compatibility in v0.20.7, which might cause issues with older CommonJS-style test setups or specific module resolvers.","severity":"gotcha","affected_versions":">=0.20.7"},{"fix":"Update your `package.json` scripts to use `\"test\": \"sunpeak test\"`, `\"test:unit\": \"sunpeak test --unit\"`, etc., to leverage the `sunpeak` CLI's managed test environment.","message":"While direct `vitest run` or `playwright test` commands still function, the recommended way to run tests is via `npx sunpeak test`. Bypassing the CLI might lead to missing environment setups, configurations, or features managed by the `sunpeak` CLI.","severity":"gotcha","affected_versions":">=0.19.2"},{"fix":"Ensure that `react` and `react-dom` (v18 or v19) are installed alongside `sunpeak`. Additionally, install the specific `@ai-sdk` packages (e.g., `@ai-sdk/openai`) you intend to use with compatible versions.","message":"Sunpeak has several peer dependencies, including `react`, `react-dom`, and the `@ai-sdk/*` packages. Incorrect versions or missing peer dependencies will lead to runtime errors or build failures.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Convert `require()` statements to ES module `import` syntax. Ensure your project's `package.json` has `\"type\": \"module\"` or configure your build tools for ESM.","cause":"Attempting to use CommonJS `require()` syntax in a modern Sunpeak project, which primarily uses ESM.","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Replace `mcp.renderTool(...)` with `inspector.renderTool(...)` in your test files. The `inspector` fixture needs to be destructured from the `test` parameters (e.g., `async ({ page, inspector }) => { ... }`).","cause":"Using the deprecated `mcp.renderTool` method after the v0.20.1 breaking change, which moved rendering capabilities to the `inspector` fixture.","error":"TypeError: mcp.renderTool is not a function"},{"fix":"Update import paths: `sunpeak/test/live` is now `sunpeak/test` (for fixtures like `mcp`), and `sunpeak/test/live/config` is now `sunpeak/test/config` (for Playwright's `defineConfig`).","cause":"Attempting to import from old testing module paths that were deprecated and moved in v0.19.1.","error":"Error: Cannot find module 'sunpeak/test/live' or 'sunpeak/test/live/config'"},{"fix":"Install `react` and `react-dom` (versions ^18.0.0 || ^19.0.0) in your project: `npm install react react-dom` or `yarn add react react-dom`. Verify versions are compatible.","cause":"The `react` or `react-dom` peer dependency is not installed, or its version is incompatible with Sunpeak.","error":"Error: Missing peer dependency \"react\""}],"ecosystem":"npm"}