mcp-app-studio 0.5.1 → 0.6.0

package/README.md

@@ -1,14 +1,16 @@
 # MCP App Studio
 
-**Build interactive apps for AI assistants (ChatGPT, Claude, MCP hosts).**
+**Build interactive apps for MCP Apps hosts (ChatGPT, Claude Desktop, etc.).**
 
-Create widgets that work across multiple platforms with a single codebase. The SDK auto-detects whether you're running in ChatGPT, Claude Desktop, or another MCP-compatible host.
+ChatGPT is an **MCP Apps host**. This SDK is MCP-first: it uses the standard
+`ui/*` bridge everywhere, and treats `window.openai` as **optional ChatGPT-only
+extensions** layered on top.
 
 ## What You Get
 
 - **Local workbench** — Preview widgets without deploying
-- **Universal SDK** — Single API works on ChatGPT and MCP hosts
-- **Platform detection** — Auto-adapts to the host environment
+- **Universal SDK** — Single API works across MCP Apps hosts
+- **Optional ChatGPT extensions** — Feature-detected `window.openai` helpers
 - **One-command export** — Generate production bundle + MCP server
 
 ## Quick Start
@@ -33,18 +35,19 @@ import {
   useToolInput,
   useCallTool,
   useTheme,
-  useFeature
+  useFeature,
+  hasChatGPTExtensions,
 } from "mcp-app-studio";
 
 function MyWidget() {
-  const platform = usePlatform(); // "chatgpt" | "mcp" | "unknown"
+  const platform = usePlatform(); // "mcp" | "unknown"
   const input = useToolInput<{ query: string }>();
   const callTool = useCallTool();
   const theme = useTheme();
 
-  // Platform-specific features
-  const hasWidgetState = useFeature('widgetState'); // ChatGPT only
-  const hasModelContext = useFeature('modelContext'); // MCP only
+  // Optional ChatGPT extensions (window.openai)
+  const hasWidgetState = useFeature("widgetState");
+  const canUseOpenAIExtensions = hasChatGPTExtensions();
 
   return (
     <div className={theme === 'dark' ? 'bg-gray-900' : 'bg-white'}>
@@ -63,17 +66,56 @@ function App() {
 }
 ```
 
+## Migrating from 0.5.x
+
+### Platform detection
+
+`detectPlatform()` now reports host family (`"mcp"` or `"unknown"`). It no
+longer returns `"chatgpt"` directly.
+
+```tsx
+// Before (0.5.x)
+import { detectPlatform } from "mcp-app-studio";
+
+if (detectPlatform() === "chatgpt") {
+  // ChatGPT-specific behavior
+}
+
+// After (MCP-first)
+import { hasChatGPTExtensions, useFeature } from "mcp-app-studio";
+
+if (hasChatGPTExtensions()) {
+  // ChatGPT extension layer is available (window.openai)
+}
+
+const hasWidgetState = useFeature("widgetState");
+```
+
+### Provider imports
+
+Use `UniversalProvider` from the main package export. The
+`mcp-app-studio/chatgpt` entrypoint is removed.
+
+```tsx
+// Before (0.5.x)
+import { ChatGPTProvider } from "mcp-app-studio/chatgpt";
+
+// After (MCP-first)
+import { UniversalProvider } from "mcp-app-studio";
+```
+
 ## Platform Capabilities
 
-| Feature | ChatGPT | MCP |
-|---------|---------|-----|
-| `callTool` | ✅ | ✅ |
-| `openLink` | ✅ | ✅ |
-| `sendMessage` | ✅ | ✅ |
-| `widgetState` (persistence) | ✅ | ❌ |
-| `modelContext` (dynamic context) | ❌ | ✅ |
-| `fileUpload` / `fileDownload` | ✅ | ❌ |
-| `partialToolInput` (streaming) | ❌ | ✅ |
+| Feature | MCP Apps bridge | ChatGPT extensions (`window.openai`) |
+|---------|----------------|-------------------------------------|
+| `callTool` | ✅ | ✅ (`callTool`) |
+| `openLink` | ✅ | ✅ (`openExternal`) |
+| `sendMessage` | ✅ | ✅ (`sendFollowUpMessage`) |
+| `modelContext` (`ui/update-model-context`) | ✅ | — |
+| `widgetState` (persistence) | — | ✅ |
+| `fileUpload` / `fileDownload` | — | ✅ |
+| `requestModal` | — | ✅ |
+| `partialToolInput` (streaming) | Host-dependent | — |
 
 ## Workflow
 
@@ -130,6 +172,12 @@ console.log('Detected by:', result.detectedBy);
 console.log('Checks:', result.checks);
 ```
 
+## Tool metadata (`_meta.ui.resourceUri`)
+
+For tools that render UI, OpenAI recommends using `_meta.ui.resourceUri` (with
+legacy support for `_meta["openai/outputTemplate"]`). See the starter template
+and MCP server generator for a working example.
+
 ## MCP Server
 
 If you selected "Include MCP server" during setup:

package/dist/{bridge-BXW_-p2R.d.ts → bridge-BKLezf-H.d.ts}

@@ -17,6 +17,18 @@ interface AppCapabilities {
 }
 interface MCPBridgeOptions {
     autoResize?: boolean;
+    /**
+     * Guard against hanging forever when rendered outside a host.
+     *
+     * `@modelcontextprotocol/ext-apps` connects via `postMessage` to the parent
+     * host. In a plain browser environment (no host), that handshake may never
+     * complete unless we time out.
+     *
+     * Set to `0` or a negative value to disable.
+     *
+     * @default 1500
+     */
+    connectTimeoutMs?: number;
 }
 type CallToolHandler = (name: string, args: Record<string, unknown>, extra: unknown) => Promise<ToolResult>;
 type ListToolsHandler = (cursor?: string) => Promise<string[]>;
@@ -24,6 +36,7 @@ declare class MCPBridge implements ExtendedBridge {
     readonly platform: "mcp";
     readonly capabilities: HostCapabilities;
     private app;
+    private connectTimeoutMs;
     private toolInputCallbacks;
     private toolInputPartialCallbacks;
     private toolResultCallbacks;

package/dist/{chunk-2OPSDEPI.js → chunk-IEZAKOIG.js}

@@ -1,6 +1,6 @@
 import {
   MCP_CAPABILITIES
-} from "./chunk-4LAH4JH6.js";
+} from "./chunk-QNH5NSRH.js";
 
 // src/platforms/mcp/bridge.ts
 import { App } from "@modelcontextprotocol/ext-apps";
@@ -8,6 +8,7 @@ var MCPBridge = class {
   platform = "mcp";
   capabilities = MCP_CAPABILITIES;
   app;
+  connectTimeoutMs;
   toolInputCallbacks = /* @__PURE__ */ new Set();
   toolInputPartialCallbacks = /* @__PURE__ */ new Set();
   toolResultCallbacks = /* @__PURE__ */ new Set();
@@ -16,6 +17,7 @@ var MCPBridge = class {
   teardownCallbacks = /* @__PURE__ */ new Set();
   constructor(appInfo, appCapabilities, options) {
     const autoResize = options?.autoResize ?? true;
+    this.connectTimeoutMs = options?.connectTimeoutMs ?? 1500;
     this.app = new App(
       appInfo ?? { name: "MCP App", version: "1.0.0" },
       appCapabilities ?? {},
@@ -60,7 +62,37 @@ var MCPBridge = class {
     };
   }
   async connect() {
-    await this.app.connect();
+    const timeoutMs = this.connectTimeoutMs;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      await this.app.connect();
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const timeoutId = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        reject(
+          new Error(
+            `MCP bridge connect timed out after ${timeoutMs}ms (no host responded).`
+          )
+        );
+      }, timeoutMs);
+      this.app.connect().then(
+        () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeoutId);
+          resolve();
+        },
+        (error) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeoutId);
+          reject(error);
+        }
+      );
+    });
   }
   getHostContext() {
     const ctx = this.app.getHostContext();

package/dist/{chunk-4LAH4JH6.js → chunk-QNH5NSRH.js}

@@ -1,22 +1,4 @@
 // src/core/capabilities.ts
-var CHATGPT_CAPABILITIES = {
-  platform: "chatgpt",
-  callTool: true,
-  openLink: true,
-  displayModes: ["pip", "inline", "fullscreen"],
-  sizeReporting: true,
-  closeWidget: true,
-  sendMessage: true,
-  modal: true,
-  fileUpload: true,
-  fileDownload: true,
-  widgetState: true,
-  modelContext: false,
-  logging: false,
-  partialToolInput: false,
-  toolCancellation: false,
-  teardown: false
-};
 var MCP_CAPABILITIES = {
   platform: "mcp",
   callTool: true,
@@ -41,7 +23,6 @@ function hasFeature(capabilities, feature) {
 }
 
 export {
-  CHATGPT_CAPABILITIES,
   MCP_CAPABILITIES,
   hasFeature
 };