sunpeak 0.15.4 → 0.16.2

package/README.md

@@ -61,21 +61,26 @@ Next.js for MCP Apps. Using an example App `my-app` with a `Review` UI (MCP reso
 
 ```bash
 my-app/
-├── src/resources/
-│   └── review/
-│       └── review-resource.tsx                 # Review UI component + resource metadata.
+├── src/
+│   ├── resources/
+│   │   └── review/
+│   │       └── review.tsx           # Review UI component + resource metadata.
+│   ├── tools/
+│   │   ├── review-diff.ts           # Tool with handler, schema, and resource reference.
+│   │   └── review-post.ts           # Multiple tools can share one resource.
+│   └── server.ts                    # Optional: auth, server config.
 ├── 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             # Mock state for testing.
 └── package.json
 ```
 
 1. Project scaffold: Complete development setup with the `sunpeak` library.
 2. UI components: Production-ready components following MCP App design guidelines.
 3. Convention over configuration:
-   1. Create a UI by creating a `-resource.tsx` file that exports a `ResourceConfig` and a React component ([example below](#resource-component)).
-   2. Create test state (`Simulation`s) for local dev, host dev, automated testing, and demos by creating a `-simulation.json` file. ([example below](#simulation))
+   1. Create a UI by creating a `.tsx` file in `src/resources/{name}/` that exports a `ResourceConfig` and a React component ([example below](#resource-component)).
+   2. Create a tool by creating a `.ts` file in `src/tools/` that exports `tool` (metadata with resource reference), `schema` (Zod), and a `default` handler ([example below](#tool-file)).
+   3. Create test state (`Simulation`s) by creating a `.json` file in `tests/simulations/` ([example below](#simulation)).
 
 ### The `sunpeak` CLI
 
@@ -83,7 +88,8 @@ Commands for managing MCP Apps:
 
 - `sunpeak new [name] [resources]` - Create a new project
 - `sunpeak dev` - Start dev server with MCP endpoint and live simulator
-- `sunpeak build` - Build resources for production
+- `sunpeak build` - Build resources and compile tools for production
+- `sunpeak start` - Start the production MCP server (real handlers, auth, Zod validation)
 - `sunpeak upgrade` - Upgrade sunpeak to latest version
 
 ## Example App
@@ -92,23 +98,15 @@ Example `Resource`, `Simulation`, and testing file (using the `Simulator`) for a
 
 ### `Resource` Component
 
-```bash
-my-app/
-├── src/resources/
-│   └── review/
-│       └── review-resource.tsx # This!
-```
-
 Each resource `.tsx` file exports both the React component and the MCP resource metadata:
 
 ```tsx
-// src/resources/review/review-resource.tsx
+// src/resources/review/review.tsx
 
 import { useToolData } from 'sunpeak';
 import type { ResourceConfig } from 'sunpeak';
 
 export const resource: ResourceConfig = {
-  name: 'review',
   description: 'Visualize and review a code change',
   _meta: { ui: { csp: { resourceDomains: ['https://cdn.example.com'] } } },
 };
@@ -120,48 +118,54 @@ export function ReviewResource() {
 }
 ```
 
-### `Simulation`
+### Tool File
 
-```bash
-├── tests/simulations/
-│   └── review/
-│       ├── review-{scenario1}-simulation.json  # These!
-│       └── review-{scenario2}-simulation.json  # These!
-```
+Each tool `.ts` file exports metadata (with a direct resource reference), a Zod schema, and a handler:
+
+```ts
+// src/tools/review-diff.ts
 
-`sunpeak` testing object (`.json`) defining key App-owned states.
+import { z } from 'zod';
+import type { AppToolConfig, ToolHandlerExtra } from 'sunpeak/mcp';
 
-Testing an MCP App requires setting a lot of state: state in your **backend**, **MCP tools**, and the **host runtime**.
+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'),
+};
+
+export default async function (args: Record<string, unknown>, extra: ToolHandlerExtra) {
+  return { structuredContent: { title: args.title, sections: [] } };
+}
+```
+
+### `Simulation`
 
-`Simulation` files contain an [official MCP tool object](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool), `toolInput` (the arguments sent to CallTool), and `toolResult` (the [CallToolResult](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#structured-content) response) so you can define **backend**, **tool**, and **runtime** states for testing.
+Simulation files provide fixture data for testing. Each references a tool by filename and contains the mock input/output:
 
 ```jsonc
-// tests/simulations/review-diff-simulation.json
+// tests/simulations/review-diff.json
 
 {
-  // Official MCP tool object.
-  "tool": {
-    "name": "review-diff",
-    "description": "Show a review dialog for a proposed code diff",
-    "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
-    "title": "Diff Review",
-    "annotations": { "readOnlyHint": false },
-    "_meta": {
-      "ui": { "visibility": ["model", "app"] },
-    },
-  },
-  // Tool input arguments (sent to CallTool).
+  "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",
+    "title": "Refactor Authentication Module"
   },
-  // Tool result data (CallToolResult response).
   "toolResult": {
     "structuredContent": {
       "title": "Refactor Authentication Module",
-      // ...
-    },
-  },
+      "sections": [...]
+    }
+  }
 }
 ```
 
@@ -217,6 +221,6 @@ npx skills add Sunpeak-AI/sunpeak@create-sunpeak-app
 
 ## Resources
 
-- [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
-- [MCP Apps SDK Design Guidelines](https://developers.openai.com/apps-sdk/concepts/design-guidelines)
-- [MCP Apps SDK Documentation - UI](https://developers.openai.com/apps-sdk/build/chatgpt-ui)
+- [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)

package/bin/commands/build.mjs

@@ -59,6 +59,11 @@ export async function build(projectRoot = process.cwd()) {
     process.exit(1);
   }
 
+  // Read project identity from package.json for appInfo
+  const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+  const appName = pkg.name || 'sunpeak-app';
+  const appVersion = pkg.version || '0.1.0';
+
   // Check if we're in the sunpeak workspace (directory is named "template")
   const isTemplate = path.basename(projectRoot) === 'template';
   const parentSrc = path.resolve(projectRoot, '../src');
@@ -153,7 +158,8 @@ export async function build(projectRoot = process.cwd()) {
     .filter(entry => entry.isDirectory())
     .map(entry => {
       const kebabName = entry.name;
-      const resourceFile = `${kebabName}-resource.tsx`;
+
+      const resourceFile = `${kebabName}.tsx`;
       const resourcePath = path.join(resourcesDir, kebabName, resourceFile);
 
       // Skip directories without a resource file
@@ -163,10 +169,11 @@ export async function build(projectRoot = process.cwd()) {
 
       // Convert kebab-case to PascalCase: 'review' -> 'Review', 'my-widget' -> 'MyWidget'
       const pascalName = toPascalCase(kebabName);
+      const componentFile = resourceFile.replace(/\.tsx$/, '');
 
       return {
         componentName: `${pascalName}Resource`,
-        componentFile: `${kebabName}-resource`,
+        componentFile,
         kebabName,
         resourceDir: path.join(resourcesDir, kebabName),
         entry: `.tmp/index-${kebabName}.tsx`,
@@ -180,7 +187,7 @@ export async function build(projectRoot = process.cwd()) {
 
   if (resourceFiles.length === 0) {
     console.error('Error: No resource directories found in src/resources/');
-    console.error('Each resource should be a directory like: src/resources/review/review-resource.tsx');
+    console.error('Each resource should be a directory like: src/resources/review/review.tsx');
     process.exit(1);
   }
 
@@ -218,7 +225,7 @@ export async function build(projectRoot = process.cwd()) {
       // Create entry file from template in temp directory
       const entryContent = template
         .replace('// RESOURCE_IMPORT', `import { ${componentName}, resource } from '../src/resources/${kebabName}/${componentFile}';`)
-        .replace('// RESOURCE_MOUNT', `createRoot(root).render(<AppProvider appInfo={{ name: resource.name, version: '1.0.0' }}><${componentName} /></AppProvider>);`);
+        .replace('// RESOURCE_MOUNT', `createRoot(root).render(<AppProvider appInfo={{ name: ${JSON.stringify(appName)}, version: ${JSON.stringify(appVersion)} }}><${componentName} /></AppProvider>);`);
 
       const entryPath = path.join(projectRoot, entry);
       writeFileSync(entryPath, entryContent);
@@ -283,6 +290,8 @@ export async function build(projectRoot = process.cwd()) {
     const destJson = path.join(distOutDir, `${kebabName}.json`);
 
     const meta = await extractResourceExport(srcTsx);
+    // Inject name from directory key if not explicitly set
+    meta.name = meta.name ?? kebabName;
     // Generate URI using resource name and build timestamp
     meta.uri = `ui://${meta.name}-${timestamp}`;
     writeFileSync(destJson, JSON.stringify(meta, null, 2));
@@ -331,10 +340,114 @@ ${jsContents}
 
   console.log('\n✓ All resources built successfully!');
   console.log('\nBuilt resources:');
-  for (const { kebabName, distOutDir } of resourceFiles) {
-    const files = readdirSync(distOutDir);
+  for (const { kebabName } of resourceFiles) {
     console.log(`  ${kebabName}`);
   }
+
+  // ========================================================================
+  // Compile server-side code (tools + server entry) for `sunpeak start`
+  // ========================================================================
+
+  const toolsDir = path.join(projectRoot, 'src/tools');
+  const serverEntryPath = path.join(projectRoot, 'src/server.ts');
+
+  // Find tool files
+  const toolFiles = existsSync(toolsDir)
+    ? readdirSync(toolsDir).filter(f => f.endsWith('.ts'))
+    : [];
+
+  const hasServerEntry = existsSync(serverEntryPath);
+
+  if (toolFiles.length > 0 || hasServerEntry) {
+    console.log('\nCompiling server-side code...');
+
+    let esbuild;
+    try {
+      const esbuildPath = resolveEsmEntry(require, 'esbuild');
+      esbuild = await import(esbuildPath);
+    } catch {
+      console.warn('Warning: esbuild not found — skipping tool/server compilation.');
+      console.warn('Install esbuild to enable `sunpeak start`: npm install -D esbuild');
+      esbuild = null;
+    }
+
+    if (esbuild) {
+      const toolsOutDir = path.join(distDir, 'tools');
+      if (toolFiles.length > 0) {
+        mkdirSync(toolsOutDir, { recursive: true });
+      }
+
+      // Compile each tool file
+      for (const toolFile of toolFiles) {
+        const toolName = toolFile.replace(/\.ts$/, '');
+        const toolPath = path.join(toolsDir, toolFile);
+
+        try {
+          await esbuild.build({
+            entryPoints: [toolPath],
+            bundle: true,
+            format: 'esm',
+            platform: 'node',
+            target: 'node18',
+            outfile: path.join(toolsOutDir, `${toolName}.js`),
+            // Externalize bare specifiers (node_modules) — resolve at runtime
+            plugins: [{
+              name: 'externalize-bare-specifiers',
+              setup(build) {
+                build.onResolve({ filter: /.*/ }, (args) => {
+                  if (args.kind !== 'import-statement') return;
+                  if (!args.path.startsWith('.') && !args.path.startsWith('/')) {
+                    return { external: true };
+                  }
+                  return undefined;
+                });
+              },
+            }],
+            loader: { '.tsx': 'tsx', '.ts': 'ts' },
+            logLevel: 'warning',
+          });
+          console.log(`✓ Compiled tools/${toolName}.js`);
+        } catch (err) {
+          console.error(`Failed to compile tool ${toolName}:`, err.message);
+          process.exit(1);
+        }
+      }
+
+      // Compile server entry if present
+      if (hasServerEntry) {
+        try {
+          await esbuild.build({
+            entryPoints: [serverEntryPath],
+            bundle: true,
+            format: 'esm',
+            platform: 'node',
+            target: 'node18',
+            outfile: path.join(distDir, 'server.js'),
+            plugins: [{
+              name: 'externalize-bare-specifiers',
+              setup(build) {
+                build.onResolve({ filter: /.*/ }, (args) => {
+                  if (args.kind !== 'import-statement') return;
+                  if (!args.path.startsWith('.') && !args.path.startsWith('/')) {
+                    return { external: true };
+                  }
+                  return undefined;
+                });
+              },
+            }],
+            loader: { '.tsx': 'tsx', '.ts': 'ts' },
+            logLevel: 'warning',
+          });
+          console.log(`✓ Compiled server.js`);
+        } catch (err) {
+          console.error(`Failed to compile server entry:`, err.message);
+          process.exit(1);
+        }
+      }
+    }
+  }
+
+  console.log('\n✓ Build complete!');
 }
 
 // Allow running directly

package/bin/commands/dev.mjs

@@ -178,8 +178,8 @@ export async function dev(projectRoot = process.cwd(), args = []) {
     sunpeakMcp = await import(pathToFileURL(join(sunpeakBase, 'dist/mcp/index.js')).href);
     sunpeakDiscovery = await import(pathToFileURL(join(sunpeakBase, 'dist/lib/discovery-cli.js')).href);
   }
-  const { FAVICON_BUFFER: faviconBuffer, runMCPServer } = sunpeakMcp;
-  const { findResourceDirs, findSimulationFiles, extractResourceExport } = sunpeakDiscovery;
+  const { FAVICON_BUFFER: faviconBuffer, runMCPServer, startProductionHttpServer } = sunpeakMcp;
+  const { findResourceDirs, findSimulationFilesFlat, findToolFiles, extractResourceExport, extractToolExport } = sunpeakDiscovery;
 
   // Vite plugin to serve the sunpeak favicon
   const sunpeakFaviconPlugin = () => ({
@@ -229,28 +229,73 @@ export async function dev(projectRoot = process.cwd(), args = []) {
   // Discover simulations using sunpeak's discovery utilities
   const resourcesDir = join(projectRoot, 'src/resources');
   const simulationsDir = join(projectRoot, 'tests/simulations');
-  const resourceDirs = findResourceDirs(resourcesDir, (key) => `${key}-resource.tsx`, fs);
+  const toolsDir = join(projectRoot, 'src/tools');
 
-  const simulations = [];
-  for (const { key: resourceKey, dir: resourceDir, resourcePath } of resourceDirs) {
+  const resourceDirs = findResourceDirs(resourcesDir, (key) => `${key}.tsx`, fs);
+
+  // Build resource metadata map
+  const resourceMap = new Map();
+  for (const { key, resourcePath } of resourceDirs) {
     const resource = await extractResourceExport(resourcePath);
-    const resourceSimDir = join(simulationsDir, resourceKey);
-    const simulationFiles = findSimulationFiles(resourceSimDir, resourceKey, fs);
-
-    for (const { filename, path: simPath } of simulationFiles) {
-      const simulationKey = filename.replace(/-simulation\.json$/, '');
-      const simulation = JSON.parse(readFileSync(simPath, 'utf-8'));
-
-      simulations.push({
-        ...simulation,
-        name: simulationKey,
-        distPath: join(projectRoot, `dist/${resourceKey}/${resourceKey}.html`),
-        srcPath: `/src/resources/${resourceKey}/${resourceKey}-resource.tsx`,
-        resource,
-      });
+    // Inject name from directory key if not explicitly set
+    resource.name = resource.name ?? key;
+    resourceMap.set(key, resource);
+  }
+
+  // Discover tool files and extract metadata
+  const toolFiles = findToolFiles(toolsDir, fs);
+  const toolMap = new Map();
+  for (const { name: toolName, path: toolPath } of toolFiles) {
+    try {
+      const { tool } = await extractToolExport(toolPath);
+      toolMap.set(toolName, tool);
+    } catch (err) {
+      console.warn(`Warning: Could not extract metadata from tool ${toolName}: ${err.message}`);
     }
   }
 
+  // Discover simulations from flat directory
+  const simulations = [];
+  const simFiles = findSimulationFilesFlat(simulationsDir, fs);
+
+  for (const { name: simName, path: simPath } of simFiles) {
+    const simulation = JSON.parse(readFileSync(simPath, 'utf-8'));
+    const toolName = typeof simulation.tool === 'string' ? simulation.tool : simName;
+
+    // Look up tool metadata
+    const tool = toolMap.get(toolName);
+    if (!tool) {
+      console.warn(`Warning: Tool "${toolName}" not found for simulation "${simName}". Skipping.`);
+      continue;
+    }
+
+    // tool.resource is the resource name string — find matching resource key
+    const resourceName = tool.resource;
+    const resourceKey = resourceName
+      ? Array.from(resourceMap.keys()).find((k) => resourceMap.get(k).name === resourceName)
+      : undefined;
+
+    if (!resourceKey) {
+      console.warn(`Warning: No resource found for tool "${toolName}" in simulation "${simName}". Skipping.`);
+      continue;
+    }
+
+    // Determine source path for the resource
+    const resourceDir = resourceDirs.find((d) => d.key === resourceKey);
+    const srcPath = resourceDir
+      ? `/src/resources/${resourceKey}/${basename(resourceDir.resourcePath)}`
+      : undefined;
+
+    simulations.push({
+      ...simulation,
+      ...(typeof simulation.tool === 'string' ? { tool: { name: toolName, ...tool } } : {}),
+      name: simName,
+      distPath: join(projectRoot, `dist/${resourceKey}/${resourceKey}.html`),
+      srcPath,
+      resource: resourceMap.get(resourceKey),
+    });
+  }
+
   // Start MCP server with its own Vite instance (unless --prod-mcp is set)
   if (simulations.length > 0) {
     const mcpMode = prodMcp ? 'production build' : 'Vite HMR';
@@ -294,7 +339,7 @@ const Component = ResourceModule.default || ResourceModule['${componentName}'];
 if (!Component) {
   document.getElementById('root').innerHTML = '<pre style="color:red;padding:16px">Component not found: ${componentName}\\nExports: ' + Object.keys(ResourceModule).join(', ') + '</pre>';
 } else {
-  const appInfo = { name: ResourceModule.resource?.name || '${componentName}', version: '1.0.0' };
+  const appInfo = { name: ${JSON.stringify(pkg.name || 'sunpeak-app')}, version: ${JSON.stringify(pkg.version || '0.1.0')} };
   root.render(
     createElement(AppProvider, { appInfo }, createElement(Component))
   );
@@ -344,13 +389,109 @@ if (import.meta.hot) {
     }
 
     const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
-    const mcpHandle = runMCPServer({
-      name: pkg.name || 'Sunpeak',
-      version: pkg.version || '0.1.0',
-      simulations,
-      port: 8000,
-      ...(mcpViteServer && { viteServer: mcpViteServer }),
-    });
+
+    let mcpHandle = null;
+
+    if (prodMcp) {
+      // --prod-mcp: Use real tool handlers via Vite SSR
+      // Load full tool modules (handler + schema + config) from TypeScript source
+      const ssrLoader = await createServer({
+        root: projectRoot,
+        server: { middlewareMode: true },
+        appType: 'custom',
+        logLevel: 'silent',
+        resolve: {
+          alias: {
+            ...(isTemplate && { sunpeak: parentSrc }),
+          },
+        },
+      });
+
+      const prodTools = [];
+      for (const { name: toolName, path: toolPath } of toolFiles) {
+        try {
+          const relativePath = './' + toolPath.replace(projectRoot + '/', '').replace(projectRoot + '\\', '');
+          const mod = await ssrLoader.ssrLoadModule(relativePath);
+          if (mod.tool && mod.default) {
+            prodTools.push({
+              name: toolName,
+              tool: mod.tool,
+              schema: mod.schema,
+              handler: mod.default,
+            });
+          }
+        } catch (err) {
+          console.warn(`Warning: Could not load tool handler ${toolName}: ${err.message}`);
+        }
+      }
+
+      // Load server entry if present
+      const serverEntryPath = join(projectRoot, 'src/server.ts');
+      let auth = undefined;
+      let serverConfig = {};
+      if (existsSync(serverEntryPath)) {
+        try {
+          const serverMod = await ssrLoader.ssrLoadModule('./src/server.ts');
+          if (typeof serverMod.auth === 'function') {
+            auth = serverMod.auth;
+            console.log('Loaded auth from src/server.ts');
+          }
+          if (serverMod.server) serverConfig = serverMod.server;
+        } catch (err) {
+          console.warn(`Warning: Could not load server entry: ${err.message}`);
+        }
+      }
+
+      await ssrLoader.close();
+
+      // Build production resources from dist/
+      const prodResources = [];
+      for (const { key } of resourceDirs) {
+        const meta = resourceMap.get(key);
+        if (!meta) continue;
+        const htmlPath = join(projectRoot, `dist/${key}/${key}.html`);
+        const jsonPath = join(projectRoot, `dist/${key}/${key}.json`);
+        if (!existsSync(htmlPath)) continue;
+
+        const html = readFileSync(htmlPath, 'utf-8');
+        let uri = `ui://${meta.name ?? key}`;
+        let _meta = meta._meta;
+
+        // Use URI from build JSON if available (has cache-bust timestamp)
+        if (existsSync(jsonPath)) {
+          try {
+            const buildMeta = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+            if (buildMeta.uri) uri = buildMeta.uri;
+          } catch {}
+        }
+
+        prodResources.push({
+          name: meta.name ?? key,
+          uri,
+          html,
+          description: meta.description,
+          _meta,
+        });
+      }
+
+      const name = serverConfig.name ?? pkg.name ?? 'Sunpeak';
+      const version = serverConfig.version ?? pkg.version ?? '0.1.0';
+
+      console.log(`Starting production MCP server with ${prodTools.length} tool(s)...`);
+      startProductionHttpServer(
+        { name, version, tools: prodTools, resources: prodResources, auth },
+        8000
+      );
+    } else {
+      // Default: simulation-based MCP server with fixture data
+      mcpHandle = runMCPServer({
+        name: pkg.name || 'Sunpeak',
+        version: pkg.version || '0.1.0',
+        simulations,
+        port: 8000,
+        ...(mcpViteServer && { viteServer: mcpViteServer }),
+      });
+    }
 
     // Build production bundles and watch for changes.
     // Tunnel clients (e.g. Claude via ngrok) get the pre-built HTML since they can't

package/bin/commands/new.mjs

@@ -153,9 +153,19 @@ export async function init(projectName, resourcesArg, deps = defaultDeps) {
         if (src.includes('/resources/') && name === resource) {
           return false;
         }
-        // Skip simulation directories for excluded resources: tests/simulations/{resource}/
-        if (src.includes('/tests/simulations/') && name === resource) {
-          return false;
+        // Skip flat simulation files for excluded resources: tests/simulations/*.json
+        if (src.includes('/tests/simulations/') && name.endsWith('.json')) {
+          const baseName = name.replace(/\.json$/, '');
+          if (baseName === resource || baseName.startsWith(resource + '-') || baseName.endsWith('-' + resource)) {
+            return false;
+          }
+        }
+        // Skip tool files for excluded resources: src/tools/*.ts
+        if (src.includes('/src/tools/') && name.endsWith('.ts')) {
+          const baseName = name.replace(/\.ts$/, '');
+          if (baseName === resource || baseName.startsWith(resource + '-') || baseName.endsWith('-' + resource)) {
+            return false;
+          }
         }
         // Skip e2e test files for excluded resources
         if (src.includes('/tests/e2e/') && name === `${resource}.spec.ts`) {