open-mcp-app 0.0.5 → 0.0.6

package/README.md

@@ -0,0 +1,158 @@
+# open-mcp-app
+
+SDK for building MCP Apps that work on any MCP App host (Creature, ChatGPT, Claude Desktop).
+
+## Installation
+
+```bash
+npm install open-mcp-app
+```
+
+## Quick Start
+
+### Server-side (Express)
+
+```typescript
+import { createApp } from "open-mcp-app/server";
+import { z } from "zod";
+
+const app = createApp({ name: "My App", version: "1.0.0" })
+  .tool("greet", {
+    description: "Greet a user",
+    parameters: z.object({ name: z.string() }),
+    execute: async ({ name }) => ({
+      content: [{ type: "text", text: `Hello, ${name}!` }],
+    }),
+  })
+  .build();
+
+app.listen(3000);
+```
+
+### Client-side (React)
+
+```tsx
+import { HostProvider, useHost } from "open-mcp-app/react";
+
+function App() {
+  return (
+    <HostProvider name="My App">
+      <MyWidget />
+    </HostProvider>
+  );
+}
+
+function MyWidget() {
+  const host = useHost();
+  
+  const handleClick = async () => {
+    const result = await host.callTool("greet", { name: "World" });
+    console.log(result);
+  };
+  
+  return <button onClick={handleClick}>Greet</button>;
+}
+```
+
+## Host Compatibility
+
+| Feature | Creature | ChatGPT | Claude Desktop |
+|---------|----------|---------|----------------|
+| Tool Calls | ✅ | ✅ | ✅ |
+| Display Modes | ✅ | ✅ | ❌ |
+| Widget State | ✅ | ✅ | ✅ |
+| Update Model Context | ✅ | ✅ | ✅ |
+| Multi-Instance | ✅ | ❌ | ❌ |
+| Theme Sync | ✅ | ❌ | ✅ |
+
+## Core Concepts
+
+### Widget State
+
+Persist UI state across sessions using `widgetState`. Supports two segments:
+
+- **modelContent**: Visible to the AI model in future turns
+- **privateContent**: UI-only, hidden from the model
+
+```tsx
+const host = useHost();
+
+// Set widget state
+host.exp.setWidgetState({
+  modelContent: "User is on the settings page",
+  privateContent: { theme: "dark", collapsed: false },
+});
+
+// Read current state
+const state = host.widgetState;
+```
+
+### Update Model Context
+
+Explicitly inform the AI model about user actions without triggering an immediate response. Use this when the UI needs the model to know about important interactions (file selections, preferences, etc.) for future turns.
+
+```tsx
+const { updateModelContext } = useHost();
+
+// Inform the model about a user action
+await updateModelContext([
+  { type: "text", text: "User selected file: /src/App.tsx" },
+]);
+```
+
+**Host Behavior:**
+- **Creature**: Sends `ui/update-model-context` notification per MCP Apps spec
+- **ChatGPT**: Maps to `setWidgetState` per their MCP Apps compatibility layer
+- **Claude Desktop**: Supported via MCP Apps protocol
+
+### Tool Visibility
+
+Control whether tools are available to the model, UI, or both:
+
+```typescript
+.tool("search_internal", {
+  description: "Search internal data",
+  parameters: z.object({ query: z.string() }),
+  execute: async ({ query }) => ({ ... }),
+  visibility: "app",  // UI-only tool, hidden from AI
+})
+```
+
+Visibility options:
+- `"model"` (default): AI can call the tool
+- `"app"`: UI-only, hidden from AI
+- `["model", "app"]`: Available to both
+
+## Entry Points
+
+Import from specific subpaths:
+
+```typescript
+import { createApp } from "open-mcp-app/server";  // Server-side
+import { createHost } from "open-mcp-app/core";   // Vanilla JS client
+import { useHost } from "open-mcp-app/react";     // React hooks
+import { mcpAppPlugin } from "open-mcp-app/vite"; // Vite plugin
+import "open-mcp-app/styles/tailwind.css";        // Base styles
+```
+
+## Development
+
+### With Vite
+
+```typescript
+// vite.config.ts
+import { mcpAppPlugin } from "open-mcp-app/vite";
+
+export default {
+  plugins: [mcpAppPlugin()],
+};
+```
+
+The Vite plugin provides:
+- Hot Module Replacement in the Creature iframe
+- Automatic port discovery between UI and server
+- Development proxy configuration
+
+## License
+
+MIT

package/dist/core/index.d.ts

@@ -198,17 +198,6 @@ interface ExpHostApi {
      * Creature only - no-op on ChatGPT and generic MCP Apps hosts.
      */
     setTitle(title: string): void;
-    /**
-     * Update the model context for future turns.
-     *
-     * In MCP Apps spec as `ui/update-model-context`. Context is available
-     * to the model in future turns without triggering immediate response.
-     * Each call overwrites previous context.
-     *
-     * - MCP Apps hosts: Supported (if host declares capability)
-     * - ChatGPT: No-op
-     */
-    updateModelContext(content: ContentBlock[]): Promise<void>;
     /**
      * Send a raw notification to the host.
      *
@@ -322,6 +311,20 @@ interface UnifiedHostClient {
      * Falls back to browser console on ChatGPT.
      */
     log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Update the model context for future turns.
+     *
+     * In MCP Apps spec as `ui/update-model-context`. Context is available
+     * to the model in future turns without triggering immediate response.
+     * Each call overwrites previous context.
+     *
+     * Use this for ephemeral notifications that don't need persistence.
+     * For persistent context, use widgetState.modelContent instead.
+     *
+     * - MCP Apps hosts: Sends `ui/update-model-context` notification
+     * - ChatGPT: Maps to setWidgetState per MCP Apps compatibility
+     */
+    updateModelContext(content: ContentBlock[]): Promise<void>;
     /**
      * Register an event handler. Returns unsubscribe function.
      */
@@ -521,6 +524,14 @@ declare class CreatureDesktopHostClient extends Subscribable implements UnifiedH
      * Send a log message to the host's DevConsole.
      */
     log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Update the model context for future turns.
+     *
+     * Sends `ui/update-model-context` notification per MCP Apps spec.
+     * Context is available to the model in future turns without
+     * triggering immediate response.
+     */
+    updateModelContext(content: ContentBlock[]): Promise<void>;
     on<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
     /**
      * Experimental APIs (shared across all hosts).
@@ -661,6 +672,14 @@ declare class ClaudeDesktopHostClient extends Subscribable implements UnifiedHos
      * Send a log message to the host's DevConsole.
      */
     log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Update the model context for future turns.
+     *
+     * Sends `ui/update-model-context` notification per MCP Apps spec.
+     * Context is available to the model in future turns without
+     * triggering immediate response.
+     */
+    updateModelContext(content: ContentBlock[]): Promise<void>;
     on<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
     /**
      * Experimental APIs (shared across all hosts).
@@ -811,6 +830,13 @@ declare class ChatGptWebHostClient extends Subscribable implements UnifiedHostCl
      * ChatGPT doesn't have a DevConsole, so logs go to browser console only.
      */
     log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Update model context for future turns.
+     *
+     * On ChatGPT, this maps to setWidgetState per their MCP Apps compatibility.
+     * The content blocks are converted to a string and stored as modelContent.
+     */
+    updateModelContext(content: ContentBlock[]): Promise<void>;
     on<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
     /**
      * Experimental APIs (shared across all hosts).
@@ -890,6 +916,10 @@ declare class StandaloneHostClient extends Subscribable implements UnifiedHostCl
      * Log a message to the console.
      */
     log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Update model context - logs in standalone mode.
+     */
+    updateModelContext(content: ContentBlock[]): Promise<void>;
     on<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
     /**
      * Experimental APIs for non-standard features.
@@ -903,28 +933,11 @@ declare class StandaloneHostClient extends Subscribable implements UnifiedHostCl
 }
 
 /**
- * SDK Layout Variables
- *
- * This module provides SDK-only CSS variables for spacing, containers, and component sizing.
- * These are NOT part of the MCP Apps spec - they are convenient defaults for clean layouts.
+ * Style Application Utilities
  *
  * Host-provided spec variables (colors, typography, etc.) are applied automatically
- * when the app initializes via hostContext.styles.variables. Apps are not shown until
- * initialization is complete, so there's no need for pre-host defaults.
- *
- * Usage:
- * 1. Import base.css which uses these variables
- * 2. Or apply them manually via applyLayoutDefaults()
- */
-/**
- * SDK-only layout variables for spacing, containers, and component sizing.
- * These are NOT part of the MCP Apps spec but provide sensible defaults
- * for clean layouts.
- *
- * Based on a 4px (0.25rem) base unit, similar to Tailwind's spacing scale.
- * Component sizing follows patterns from @openai/apps-sdk-ui for consistency.
+ * when the app initializes via hostContext.styles.variables.
  */
-declare const LAYOUT_DEFAULTS: Record<string, string>;
 /**
  * Apply CSS variables to an element (defaults to document root).
  *
@@ -935,17 +948,6 @@ declare const applyStyles: ({ styles, root, }: {
     styles: Record<string, string>;
     root?: HTMLElement;
 }) => void;
-/**
- * Apply SDK layout defaults to the document.
- * This applies spacing, container, and control variables.
- *
- * Note: If you import base.css, these variables are already defined via :root.
- * Only call this manually if you need to apply them programmatically or
- * to a specific element other than document root.
- *
- * @param root - Element to apply styles to (defaults to document.documentElement)
- */
-declare const applyLayoutDefaults: (root?: HTMLElement) => void;
 
 /**
  * Create a WebSocket client with automatic reconnection.
@@ -1023,4 +1025,4 @@ declare const createHost: (config: HostClientConfig) => UnifiedHostClient;
  */
 declare const createHostAsync: (config: HostClientConfig) => Promise<UnifiedHostClient>;
 
-export { ChatGptWebHostClient, ClaudeDesktopHostClient, type ContentBlock, CreatureDesktopHostClient, type DisplayMode, type Environment, type ExpHostApi, type HostClientConfig, type HostClientEvents, type HostClientState, type HostContext, type ImageContentBlock, LAYOUT_DEFAULTS, type LogLevel, type OpenContext, StandaloneHostClient, type StateListener, type StructuredWidgetState, type TextContentBlock, type ToolResult, type UnifiedHostClient, type WebSocketClient, type WebSocketClientConfig, type WebSocketStatus, type WidgetState, applyLayoutDefaults, applyStyles, createHost, createHostAsync, createWebSocket, detectEnvironment };
+export { ChatGptWebHostClient, ClaudeDesktopHostClient, type ContentBlock, CreatureDesktopHostClient, type DisplayMode, type Environment, type ExpHostApi, type HostClientConfig, type HostClientEvents, type HostClientState, type HostContext, type ImageContentBlock, type LogLevel, type OpenContext, StandaloneHostClient, type StateListener, type StructuredWidgetState, type TextContentBlock, type ToolResult, type UnifiedHostClient, type WebSocketClient, type WebSocketClientConfig, type WebSocketStatus, type WidgetState, applyStyles, createHost, createHostAsync, createWebSocket, detectEnvironment };

package/dist/core/index.js

@@ -210,6 +210,27 @@ var ChatGptWebHostClient = class _ChatGptWebHostClient extends Subscribable {
     const consoleMethod = level === "error" ? "error" : level === "warning" ? "warn" : "log";
     console[consoleMethod](`[${this.config.name}]`, message, data ?? "");
   }
+  /**
+   * Update model context for future turns.
+   *
+   * On ChatGPT, this maps to setWidgetState per their MCP Apps compatibility.
+   * The content blocks are converted to a string and stored as modelContent.
+   */
+  async updateModelContext(content) {
+    if (!window.openai?.setWidgetState) return;
+    const textContent = content.filter(
+      (block) => block.type === "text" && typeof block.text === "string"
+    ).map((block) => block.text).join("\n");
+    if (!textContent) return;
+    const existingState = this.state.widgetState || {};
+    const newState = {
+      ...existingState,
+      modelContent: textContent
+    };
+    this.setState({ widgetState: newState });
+    window.openai.setWidgetState(newState);
+    this.emit("widget-state-change", newState);
+  }
   on(event, handler) {
     if (event === "theme-change" || event === "teardown") {
       return () => {
@@ -240,9 +261,6 @@ var ChatGptWebHostClient = class _ChatGptWebHostClient extends Subscribable {
       setTitle: (_title) => {
       },
       // MCP Apps-only (no-op on ChatGPT)
-      updateModelContext: async (_content) => {
-      },
-      // MCP Apps-only (no-op on ChatGPT)
       sendNotification: (_method, _params) => {
       },
       getInstanceId: () => {
@@ -9764,6 +9782,21 @@ var CreatureDesktopHostClient = class _CreatureDesktopHostClient extends Subscri
       data: data ? { message, ...data } : message
     });
   }
+  /**
+   * Update the model context for future turns.
+   *
+   * Sends `ui/update-model-context` notification per MCP Apps spec.
+   * Context is available to the model in future turns without
+   * triggering immediate response.
+   */
+  async updateModelContext(content) {
+    if (!this.app) return;
+    this.app.notification({
+      method: "ui/update-model-context",
+      params: { content }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+  }
   on(event, handler) {
     if (event === "theme-change" || event === "teardown") {
       return this.onMcpEvent(
@@ -9805,14 +9838,6 @@ var CreatureDesktopHostClient = class _CreatureDesktopHostClient extends Subscri
       setTitle: (title) => {
         this.sendNotification("ui/notifications/title-changed", { title });
       },
-      updateModelContext: async (content) => {
-        if (!this.app) return;
-        this.app.notification({
-          method: "ui/update-model-context",
-          params: { content }
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        });
-      },
       sendNotification: (method, params) => {
         this.sendNotification(method, params);
       },
@@ -10135,6 +10160,21 @@ var ClaudeDesktopHostClient = class _ClaudeDesktopHostClient extends Subscribabl
       data: data ? { message, ...data } : message
     });
   }
+  /**
+   * Update the model context for future turns.
+   *
+   * Sends `ui/update-model-context` notification per MCP Apps spec.
+   * Context is available to the model in future turns without
+   * triggering immediate response.
+   */
+  async updateModelContext(content) {
+    if (!this.app) return;
+    this.app.notification({
+      method: "ui/update-model-context",
+      params: { content }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+  }
   on(event, handler) {
     if (event === "theme-change" || event === "teardown") {
       return this.onMcpEvent(
@@ -10176,14 +10216,6 @@ var ClaudeDesktopHostClient = class _ClaudeDesktopHostClient extends Subscribabl
       // Not supported on Claude Desktop
       setTitle: (_title) => {
       },
-      updateModelContext: async (content) => {
-        if (!this.app) return;
-        this.app.notification({
-          method: "ui/update-model-context",
-          params: { content }
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        });
-      },
       sendNotification: (method, params) => {
         this.sendNotification(method, params);
       },
@@ -10453,6 +10485,12 @@ var StandaloneHostClient = class _StandaloneHostClient extends Subscribable {
     const consoleMethod = level === "error" ? "error" : level === "warning" ? "warn" : "log";
     console[consoleMethod](`[${this.config.name}]`, message, data ?? "");
   }
+  /**
+   * Update model context - logs in standalone mode.
+   */
+  async updateModelContext(content) {
+    console.debug(`[Standalone] updateModelContext(${content.length} blocks)`);
+  }
   on(event, handler) {
     if (event === "theme-change" || event === "teardown") {
       return () => {
@@ -10479,9 +10517,6 @@ var StandaloneHostClient = class _StandaloneHostClient extends Subscribable {
       setTitle: (title) => {
         console.debug(`[Standalone] exp.setTitle("${title}")`);
       },
-      updateModelContext: async (content) => {
-        console.debug(`[Standalone] exp.updateModelContext(${content.length} blocks)`);
-      },
       sendNotification: (method, params) => {
         console.debug(`[Standalone] exp.sendNotification("${method}")`, params);
       },
@@ -10518,121 +10553,6 @@ var StandaloneHostClient = class _StandaloneHostClient extends Subscribable {
 };
 
 // src/core/styles.ts
-var LAYOUT_DEFAULTS = {
-  // Spacing scale (4px base)
-  "--spacing-0": "0",
-  "--spacing-px": "1px",
-  "--spacing-0-5": "0.125rem",
-  // 2px
-  "--spacing-1": "0.25rem",
-  // 4px
-  "--spacing-1-5": "0.375rem",
-  // 6px
-  "--spacing-2": "0.5rem",
-  // 8px
-  "--spacing-2-5": "0.625rem",
-  // 10px
-  "--spacing-3": "0.75rem",
-  // 12px
-  "--spacing-3-5": "0.875rem",
-  // 14px
-  "--spacing-4": "1rem",
-  // 16px
-  "--spacing-5": "1.25rem",
-  // 20px
-  "--spacing-6": "1.5rem",
-  // 24px
-  "--spacing-7": "1.75rem",
-  // 28px
-  "--spacing-8": "2rem",
-  // 32px
-  "--spacing-9": "2.25rem",
-  // 36px
-  "--spacing-10": "2.5rem",
-  // 40px
-  "--spacing-12": "3rem",
-  // 48px
-  "--spacing-14": "3.5rem",
-  // 56px
-  "--spacing-16": "4rem",
-  // 64px
-  "--spacing-20": "5rem",
-  // 80px
-  "--spacing-24": "6rem",
-  // 96px
-  // Container max-widths
-  "--container-xs": "20rem",
-  // 320px
-  "--container-sm": "24rem",
-  // 384px
-  "--container-md": "28rem",
-  // 448px
-  "--container-lg": "32rem",
-  // 512px
-  "--container-xl": "36rem",
-  // 576px
-  "--container-2xl": "42rem",
-  // 672px
-  "--container-3xl": "48rem",
-  // 768px
-  "--container-4xl": "56rem",
-  // 896px
-  "--container-5xl": "64rem",
-  // 1024px
-  "--container-6xl": "72rem",
-  // 1152px
-  "--container-7xl": "80rem",
-  // 1280px
-  "--container-prose": "65ch",
-  // Optimal reading width
-  // Control heights (buttons, inputs)
-  "--control-height-xs": "1.5rem",
-  // 24px
-  "--control-height-sm": "1.75rem",
-  // 28px
-  "--control-height-md": "2rem",
-  // 32px
-  "--control-height-lg": "2.25rem",
-  // 36px
-  "--control-height-xl": "2.5rem",
-  // 40px
-  "--control-height-2xl": "2.75rem",
-  // 44px
-  "--control-height-3xl": "3rem",
-  // 48px
-  // Control padding (internal horizontal padding)
-  "--control-padding-xs": "0.5rem",
-  // 8px
-  "--control-padding-sm": "0.625rem",
-  // 10px
-  "--control-padding-md": "0.75rem",
-  // 12px
-  "--control-padding-lg": "0.875rem",
-  // 14px
-  "--control-padding-xl": "1rem",
-  // 16px
-  // Icon sizes (for use in buttons/inputs)
-  "--icon-size-xs": "0.75rem",
-  // 12px
-  "--icon-size-sm": "0.875rem",
-  // 14px
-  "--icon-size-md": "1rem",
-  // 16px
-  "--icon-size-lg": "1.125rem",
-  // 18px
-  "--icon-size-xl": "1.25rem",
-  // 20px
-  "--icon-size-2xl": "1.5rem",
-  // 24px
-  // Focus ring
-  "--ring-width": "2px",
-  "--ring-offset": "2px",
-  // Transitions
-  "--transition-fast": "100ms ease",
-  "--transition-normal": "150ms ease",
-  "--transition-slow": "200ms ease",
-  "--transition-slower": "300ms ease"
-};
 var applyStyles = ({
   styles,
   root
@@ -10645,9 +10565,6 @@ var applyStyles = ({
     element.style.setProperty(key, value);
   }
 };
-var applyLayoutDefaults = (root) => {
-  applyStyles({ styles: LAYOUT_DEFAULTS, root });
-};
 
 // src/core/websocket.ts
 function createWebSocket(url, config = {}) {
@@ -10821,12 +10738,10 @@ export {
   ChatGptWebHostClient,
   ClaudeDesktopHostClient,
   CreatureDesktopHostClient,
-  LAYOUT_DEFAULTS,
   StandaloneHostClient,
   YU as applyDocumentTheme,
   qU as applyHostFonts,
   QU as applyHostStyleVariables,
-  applyLayoutDefaults,
   applyStyles,
   createHost,
   createHostAsync,