Editable MCP server URL, Tool/Simulation dropdowns, demo mode (#18)

Replace inspectMode/prodTools with a unified Tool + Simulation dropdown model.
The Tool dropdown is always visible and the Simulation dropdown shows available
fixtures with a "None (call server)" option. The MCP server URL is always
editable with connection status. Add demoMode prop for marketing embeds. The
--prod-tools flag now controls whether external MCP callers (Claude, ChatGPT)
get real handler results or simulation mocks.

Author: abewheel

docs/api-reference/cli/dev.mdx

@@ -56,32 +56,33 @@ No manual configuration or entry point files needed!
 | Option | Short | Description |
 |--------|-------|-------------|
 | `--port <number>` | `-p` | Port for the simulator (default: 3000, also respects `PORT` env var) |
-| `--prod-tools` | | Start with **Prod Tools** mode enabled (real tool handlers). Can also be toggled from the sidebar at runtime. |
 | `--prod-resources` | | Serve production-built HTML from `dist/` instead of Vite HMR |
 
-### `--prod-tools` and `--prod-resources` flags
+### Tool and Simulation selection
 
-These two orthogonal flags let you test different combinations of UI and tool behavior:
+The simulator sidebar has two primary selectors:
 
-| Flags | UI | Tools | Use case |
-|-------|-----|-------|----------|
-| *(none)* | HMR | Mocked | Day-to-day development |
-| `--prod-tools` | HMR | Real handlers | Integration testing with real backend logic |
-| `--prod-resources` | Production bundle | Mocked | Catch build regressions, CI/E2E testing |
-| `--prod-tools --prod-resources` | Production bundle | Real handlers | Final smoke test (simulator shell around production behavior) |
+- **Tool dropdown** — selects which tool to inspect. Always visible when tools exist.
+- **Simulation dropdown** — selects a simulation fixture with mock data. Shown when fixtures exist for the selected tool. Includes a "None (call server)" option to bypass mock data and call the real handler via the **Run** button.
 
-```bash
-# Integration test: real tool handlers with HMR UI
-sunpeak dev --prod-tools
+For programmatic testing, these map to URL parameters:
 
-# CI/E2E: production bundles with mock data
-sunpeak dev --prod-resources
+```bash
+# Mock data renders immediately (simulation fixture selected):
+http://localhost:3000/?simulation=show-albums&theme=dark
 
-# Full smoke test: production bundles with real handlers
-sunpeak dev --prod-tools --prod-resources
+# No mock data — user clicks Run for real handler:
+http://localhost:3000/?tool=show-albums&theme=dark
 ```
 
-When `--prod-resources` is used, `sunpeak build` runs automatically before the dev server starts. The built HTML is served from `dist/`.
+### `--prod-resources` flag
+
+When `--prod-resources` is used, `sunpeak build` runs automatically before the dev server starts. The built HTML is served from `dist/` instead of Vite HMR. Useful for catching build regressions in CI/E2E testing.
+
+```bash
+# CI/E2E: production bundles with simulation mock data
+sunpeak dev --prod-resources
+```
 
 ## Configuration
 

docs/api-reference/simulations/simulator.mdx

@@ -44,19 +44,19 @@ import { Simulator } from 'sunpeak/simulator';
 </ResponseField>
 
 <ResponseField name="onCallTool" type="(params: { name: string; arguments?: Record<string, unknown> }) => Promise<CallToolResult> | CallToolResult">
-  Override `callServerTool` resolution. When provided, enables the **Prod Tools** toggle in the sidebar. In Prod Tools mode, tool calls are forwarded to this callback instead of using simulation mock data. The `sunpeak dev` command wires this up automatically.
+  Handler for tool calls. When the user clicks **Run**, or when the app calls `callServerTool`, calls are forwarded to this callback. The `sunpeak dev` command wires this up automatically.
 </ResponseField>
 
-<ResponseField name="defaultProdTools" type="boolean" default="false">
-  Initial state of the Prod Tools toggle. When `true`, the simulator starts in Prod Tools mode. Set by the `--prod-tools` CLI flag.
+<ResponseField name="onCallToolDirect" type="(params: { name: string; arguments?: Record<string, unknown> }) => Promise<CallToolResult> | CallToolResult">
+  Direct tool handler call, bypassing MCP server mock data. Used by the **Run** button to call real handlers. Falls back to `onCallTool` if not provided.
 </ResponseField>
 
 <ResponseField name="defaultProdResources" type="boolean" default="false">
   Initial state of the Prod Resources toggle. When `true`, the simulator loads resources from `dist/` production builds instead of HMR. Set by the `--prod-resources` CLI flag.
 </ResponseField>
 
 <ResponseField name="hideSimulatorModes" type="boolean" default="false">
-  Hide the Prod Tools and Prod Resources checkboxes in the sidebar. Useful for embedded or marketing contexts where these modes are not applicable.
+  Hide the Prod Resources checkbox in the sidebar. Used in standalone inspect mode where Prod Resources is not applicable.
 </ResponseField>
 
 ## URL Parameters
@@ -67,7 +67,8 @@ The Simulator supports URL parameters for configuring the initial state. This is
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `simulation` | `string` | First simulation | Simulation name to load |
+| `tool` | `string` | First tool | Tool name to select. When specified without `simulation`, no mock data is loaded ("Press Run" state). |
+| `simulation` | `string` | First fixture | Simulation fixture name to load. Mock data renders immediately. |
 | `host` | `'chatgpt' \| 'claude'` | `'chatgpt'` | Host shell (conversation chrome, theming, capabilities) |
 | `theme` | `'light' \| 'dark'` | `'dark'` | Color theme |
 | `displayMode` | `'inline' \| 'pip' \| 'fullscreen'` | `'inline'` | App display mode |
@@ -80,15 +81,17 @@ The Simulator supports URL parameters for configuring the initial state. This is
 | `safeAreaBottom` | `number` | `0` | Bottom safe area inset |
 | `safeAreaLeft` | `number` | `0` | Left safe area inset |
 | `safeAreaRight` | `number` | `0` | Right safe area inset |
-| `prodTools` | `'true' \| 'false'` | `'false'` | Enable Prod Tools mode (real tool handlers) |
 | `prodResources` | `'true' \| 'false'` | `'false'` | Enable Prod Resources mode (dist/ bundles) |
 
 ### Example URLs
 
 ```
-# Load albums simulation in light mode
+# Load albums simulation with mock data
 http://localhost:3000/?simulation=show-albums&theme=light
 
+# Select a tool with no mock data (user clicks Run for real handler)
+http://localhost:3000/?tool=show-albums&theme=dark
+
 # Fullscreen dark mode
 http://localhost:3000/?simulation=review-diff&theme=dark&displayMode=fullscreen
 
@@ -147,6 +150,7 @@ createSimulatorUrl({
 
 ```typescript
 interface SimulatorUrlParams {
+  tool?: string;
   simulation?: string;
   host?: string;
   theme?: 'light' | 'dark';
@@ -160,7 +164,6 @@ interface SimulatorUrlParams {
   safeAreaBottom?: number;
   safeAreaLeft?: number;
   safeAreaRight?: number;
-  prodTools?: boolean;
   prodResources?: boolean;
 }
 ```

examples/albums-example/tests/e2e/albums.spec.ts

@@ -94,9 +94,7 @@ for (const host of hosts) {
 
     test.describe('Prod Tools Mode', () => {
       test('should show empty state with Run button', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'show-albums', theme: 'dark', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'show-albums', theme: 'dark', host }));
 
         // Should show the "Press Run to call the tool" empty state
         const emptyState = page.locator('text=Press Run to call the tool');
@@ -112,9 +110,7 @@ for (const host of hosts) {
       });
 
       test('should have themed empty state colors in light mode', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'show-albums', theme: 'light', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'show-albums', theme: 'light', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();
@@ -130,9 +126,7 @@ for (const host of hosts) {
       });
 
       test('should have themed empty state colors in dark mode', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'show-albums', theme: 'dark', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'show-albums', theme: 'dark', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();

examples/carousel-example/tests/e2e/carousel.spec.ts

@@ -64,9 +64,7 @@ for (const host of hosts) {
 
     test.describe('Prod Tools Mode', () => {
       test('should show empty state with Run button', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'show-carousel', theme: 'dark', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'show-carousel', theme: 'dark', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();
@@ -79,9 +77,7 @@ for (const host of hosts) {
       });
 
       test('should have themed empty state colors in light mode', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'show-carousel', theme: 'light', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'show-carousel', theme: 'light', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();
@@ -95,9 +91,7 @@ for (const host of hosts) {
       });
 
       test('should have themed empty state colors in dark mode', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'show-carousel', theme: 'dark', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'show-carousel', theme: 'dark', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();

examples/map-example/tests/e2e/map.spec.ts

@@ -103,9 +103,7 @@ for (const host of hosts) {
 
     test.describe('Prod Tools Mode', () => {
       test('should show empty state with Run button', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'show-map', theme: 'dark', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'show-map', theme: 'dark', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();
@@ -118,9 +116,7 @@ for (const host of hosts) {
       });
 
       test('should have themed empty state colors in light mode', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'show-map', theme: 'light', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'show-map', theme: 'light', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();
@@ -134,9 +130,7 @@ for (const host of hosts) {
       });
 
       test('should have themed empty state colors in dark mode', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'show-map', theme: 'dark', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'show-map', theme: 'dark', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();

examples/review-example/tests/e2e/review.spec.ts

@@ -101,9 +101,7 @@ for (const host of hosts) {
 
     test.describe('Prod Tools Mode', () => {
       test('should show empty state with Run button', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'review-diff', theme: 'dark', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'review-diff', theme: 'dark', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();
@@ -116,9 +114,7 @@ for (const host of hosts) {
       });
 
       test('should have themed empty state colors in light mode', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'review-diff', theme: 'light', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'review-diff', theme: 'light', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();
@@ -132,9 +128,7 @@ for (const host of hosts) {
       });
 
       test('should have themed empty state colors in dark mode', async ({ page }) => {
-        await page.goto(
-          createSimulatorUrl({ simulation: 'review-diff', theme: 'dark', host, prodTools: true })
-        );
+        await page.goto(createSimulatorUrl({ tool: 'review-diff', theme: 'dark', host }));
 
         const emptyState = page.locator('text=Press Run to call the tool');
         await expect(emptyState).toBeVisible();

packages/sunpeak/bin/commands/dev.mjs

@@ -159,11 +159,11 @@ export async function dev(projectRoot = process.cwd(), args = []) {
   // Parse --no-begging flag
   const noBegging = args.includes('--no-begging');
 
-  // Parse --prod-tools and --prod-resources flags
+  // Parse flags
   const isProdTools = args.includes('--prod-tools');
   const isProdResources = args.includes('--prod-resources');
 
-  if (isProdTools) console.log('Prod Tools enabled by default (toggle in simulator sidebar)');
+  if (isProdTools) console.log('Prod Tools: MCP tool calls will use real handlers instead of simulation mocks');
   if (isProdResources) console.log('Prod Resources: resources will use production-built HTML from dist/');
 
   console.log(`Starting dev server on port ${port}...`);
@@ -496,6 +496,8 @@ if (import.meta.hot) {
     // In --prod-resources mode, don't pass viteServer so the MCP server serves pre-built HTML.
     // Otherwise, pass it so ChatGPT gets Vite HMR.
     viteServer: isProdResources ? undefined : mcpViteServer,
+    // When --prod-tools is set, UI tool calls use real handlers instead of simulation mocks.
+    prodTools: isProdTools,
   });
 
   // Wait for the MCP server to be listening before starting the inspector
@@ -520,7 +522,6 @@ if (import.meta.hot) {
     name: serverDisplayName,
     sandboxUrl: sandbox.url,
     frameworkMode: true,
-    defaultProdTools: isProdTools,
     defaultProdResources: isProdResources,
     projectRoot,
     noBegging,