@nitrostack/widgets 1.0.3 → 1.0.5

package/README.md

@@ -1,89 +1,67 @@
-# @nitrostack/widgets ⚡
+# @nitrostack/widgets
 
-**The visual SDK for NitroStack — Build interactive, data-rich UI outputs for your MCP tools.**
+React SDK for building interactive widget UIs that render with NitroStack MCP
+tool outputs.
 
-[![Widgets SDK](https://img.shields.io/badge/NitroStack-Widgets-brightgreen?style=for-the-badge&logo=none)](https://nitrostack.ai)
-[![License](https://img.shields.io/badge/License-Apache%202.0-red?style=for-the-badge&logo=none)](https://opensource.org/licenses/Apache-2.0)
-[![Documentation](https://img.shields.io/badge/Docs-docs.nitrostack.ai-blue?style=for-the-badge&logo=none)](https://docs.nitrostack.ai)
+[![npm version](https://img.shields.io/npm/v/@nitrostack/widgets?style=flat-square)](https://www.npmjs.com/package/@nitrostack/widgets)
+[![npm downloads](https://img.shields.io/npm/dm/@nitrostack/widgets?style=flat-square)](https://www.npmjs.com/package/@nitrostack/widgets)
+[![license](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
 
-`@nitrostack/widgets` allows you to go beyond plain text tool outputs. Use the power of React to build beautiful, interactive components (Widgets) that render directly in supported MCP clients and NitroStudio.
-
----
-
-## ✨ Key Features
-
-- **⚛️ React Powered**: Build interactive UI logic using the React ecosystem you already know.
-- **📊 Rich Visualization**: Render charts, maps, and complex data tables instead of raw JSON.
-- **🎮 Interactive Elements**: Add buttons, forms, and triggers that call back to your MCP server.
-- **🔌 seamless Integration**: Attaches directly to tool results using the `@Widget()` decorator.
-- **🧪 Visual Preview**: Instantly preview and debug your widgets using NitroStudio.
-
----
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @nitrostack/widgets react react-dom
 ```
 
----
-
-## 🚀 Quick Start
-
-Define a widget in your NitroStack server:
+## What You Get
 
-```typescript
-// On the Server
-@Tool({ name: 'get_user_profile' })
-@Widget({ 
-  id: 'user-card', 
-  title: 'User Profile',
-  path: '/widgets/user-profile' 
-})
-async getUser() {
-  return { name: 'Alice', role: 'Admin' };
-}
-```
+- `useWidgetSDK()` for data and host interaction
+- Theme/display helpers for adaptive UI behavior
+- State helpers for interactive widget flows
+- Compatibility with NitroStudio widget previews
 
-Then create the React component:
+## Quick Example
 
 ```tsx
-// In your Widgets project
-import { useWidgetData } from '@nitrostack/widgets';
+'use client';
 
-export const UserCard = () => {
-  const { data, loading } = useWidgetData<UserData>();
+import { useWidgetSDK } from '@nitrostack/widgets';
 
-  if (loading) return <div>Loading...</div>;
+export default function ProductCard() {
+  const { isReady, getToolOutput } = useWidgetSDK();
+  const data = getToolOutput<{ name: string; price: number }>();
+
+  if (!isReady || !data) return <div>Loading...</div>;
 
   return (
-    <div className="p-4 border rounded">
+    <div>
       <h3>{data.name}</h3>
-      <p>{data.role}</p>
+      <p>${data.price}</p>
     </div>
   );
-};
+}
 ```
 
----
-
-## 🎨 NitroStudio
-
-NitroStudio is the best way to develop widgets. It automatically runs your server and providing a hot-reloading preview environment where you can see your widgets respond to real tool data in real-time.
-
-![NitroStudio](https://raw.githubusercontent.com/nitrocloudofficial/nitrostack/main/typescript/packages/widgets/assets/gif/nitrostudio-main.gif)
+## NitroStudio
 
-**[Download NitroStudio](https://nitrostack.ai/studio)**
+NitroStudio is the fastest way to test widget output and interaction behavior in
+real MCP workflows.
 
----
+- Download: <https://nitrostack.ai/studio>
+- Widgets guide: <https://docs.nitrostack.ai/sdk/typescript/ui/widgets>
 
-## 📖 Useful Links
+## Links
 
-- **[GitHub Repository](https://github.com/nitrocloudofficial/nitrostack)**
-- **[Documentation](https://docs.nitrostack.ai)**
-- **[Blog & Tutorials](https://blog.nitrostack.ai)**
-- **[NPM Package](https://www.npmjs.com/package/@nitrostack/widgets)**
+- Widgets docs: <https://docs.nitrostack.ai/sdk/typescript/ui/widgets>
+- Full docs: <https://docs.nitrostack.ai>
+- Source: <https://github.com/nitrocloudofficial/nitrostack>
+- npm: <https://www.npmjs.com/package/@nitrostack/widgets>
+- Blog: <https://blog.nitrostack.ai>
 
----
+## Community
 
-Built with ⚡ by the **NitroStack Team**.
+- Discord: <https://discord.gg/uVWey6UhuD>
+- X: <https://x.com/nitrostackai>
+- YouTube: <https://www.youtube.com/@nitrostackai>
+- LinkedIn: <https://linkedin.com/company/nitrostack-ai/>
+- GitHub: <https://github.com/nitrostackai>

package/dist/hooks/use-merged-tool-output.d.ts

@@ -0,0 +1,8 @@
+/**
+ * NitroStack CLI bundles pass tool output as a `data` prop (see bootstrap in `build.ts`).
+ * Hosts may also expose the same payload via `window.openai` / `__MCP_APP_CONTEXT__`.
+ * Prefer SDK output when present; otherwise use bootstrap `data` so widgets render in MCPJam
+ * and similar clients before the bridge is ready.
+ */
+export declare function useMergedToolOutput<T = unknown>(propData?: T | null): T | null;
+//# sourceMappingURL=use-merged-tool-output.d.ts.map

package/dist/hooks/use-merged-tool-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-merged-tool-output.d.ts","sourceRoot":"","sources":["../../src/hooks/use-merged-tool-output.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,CAY9E"}

package/dist/hooks/use-merged-tool-output.js

@@ -0,0 +1,26 @@
+import { useWidgetSDK } from './useWidgetSDK.js';
+import { normalizeToolOutputForWidget } from '../sdk.js';
+function hasNonEmptyRecord(v) {
+    return (v != null &&
+        typeof v === 'object' &&
+        !Array.isArray(v) &&
+        Object.keys(v).length > 0);
+}
+/**
+ * NitroStack CLI bundles pass tool output as a `data` prop (see bootstrap in `build.ts`).
+ * Hosts may also expose the same payload via `window.openai` / `__MCP_APP_CONTEXT__`.
+ * Prefer SDK output when present; otherwise use bootstrap `data` so widgets render in MCPJam
+ * and similar clients before the bridge is ready.
+ */
+export function useMergedToolOutput(propData) {
+    const { getToolOutput } = useWidgetSDK();
+    const sdk = getToolOutput();
+    const prop = propData != null ? normalizeToolOutputForWidget(propData) : null;
+    if (hasNonEmptyRecord(sdk)) {
+        return sdk;
+    }
+    if (hasNonEmptyRecord(prop)) {
+        return prop;
+    }
+    return (sdk ?? prop ?? null);
+}

package/dist/sdk.d.ts

@@ -84,8 +84,18 @@ export declare class WidgetSDK {
     getToolInput<T = unknown>(): T | null;
     /**
      * Get tool output data
+     * Handles both OpenAI (window.openai.toolOutput) and MCP Apps
+     * (unwrapping structuredContent or raw content arrays).
      */
     getToolOutput<T = unknown>(): T | null;
+    /**
+     * Robustly extract data from tool output.
+     * Supports:
+     * - OpenAI structuredContent wrapper
+     * - Standard MCP content array (text/json)
+     * - Standard MCP contents array (fallback)
+     */
+    private extractToolData;
     /**
      * Get tool response metadata
      */

package/dist/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../src/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEhE;;;GAGG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA0B;IAEjD,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,SAAS;IAO/B;;;OAGG;IACH,OAAO,IAAI,OAAO;IAKlB;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;;OAGG;IACG,YAAY,CAAC,OAAO,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBjD;;OAEG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7D;;OAEG;IACH,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAO1C;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAS3F;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAOpC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC;;OAEG;IACG,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC;IAO3E;;OAEG;IACH,YAAY,IAAI,IAAI;IASpB;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAO/B;;OAEG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASxD;;OAEG;IACH,YAAY,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;IAKrC;;OAEG;IACH,aAAa,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;IAKtC;;OAEG;IACH,uBAAuB,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;IAKhD;;OAEG;IACH,QAAQ,IAAI,OAAO,GAAG,MAAM;IAK5B;;OAEG;IACH,YAAY,IAAI,MAAM;IAKtB;;OAEG;IACH,cAAc,IAAI,WAAW;IAK7B;;OAEG;IACH,YAAY;IAKZ;;OAEG;IACH,SAAS,IAAI,MAAM;IAKnB;;OAEG;IACH,WAAW;IAKX;;OAEG;IACH,SAAS,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;IAIlC;;OAEG;IACH,UAAU,IAAI,OAAO;CAGxB;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAExC"}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../src/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEhE;;;GAGG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA0B;IAEjD,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,SAAS;IAO/B;;;OAGG;IACH,OAAO,IAAI,OAAO;IAKlB;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;;OAGG;IACG,YAAY,CAAC,OAAO,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBjD;;OAEG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7D;;OAEG;IACH,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAO1C;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAS3F;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAOpC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC;;OAEG;IACG,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC;IAO3E;;OAEG;IACH,YAAY,IAAI,IAAI;IASpB;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAO/B;;OAEG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASxD;;OAEG;IACH,YAAY,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;IAKrC;;;;OAIG;IACH,aAAa,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;IAStC;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAwCvB;;OAEG;IACH,uBAAuB,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;IAKhD;;OAEG;IACH,QAAQ,IAAI,OAAO,GAAG,MAAM;IAK5B;;OAEG;IACH,YAAY,IAAI,MAAM;IAKtB;;OAEG;IACH,cAAc,IAAI,WAAW;IAK7B;;OAEG;IACH,YAAY;IAKZ;;OAEG;IACH,SAAS,IAAI,MAAM;IAKnB;;OAEG;IACH,WAAW;IAKX;;OAEG;IACH,SAAS,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;IAIlC;;OAEG;IACH,UAAU,IAAI,OAAO;CAGxB;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAExC"}

package/dist/sdk.js

@@ -172,11 +172,61 @@ export class WidgetSDK {
     }
     /**
      * Get tool output data
+     * Handles both OpenAI (window.openai.toolOutput) and MCP Apps
+     * (unwrapping structuredContent or raw content arrays).
      */
     getToolOutput() {
         if (!this.isReady())
             return null;
-        return window.openai.toolOutput;
+        const rawOutput = window.openai.toolOutput;
+        if (!rawOutput)
+            return null;
+        return this.extractToolData(rawOutput);
+    }
+    /**
+     * Robustly extract data from tool output.
+     * Supports:
+     * - OpenAI structuredContent wrapper
+     * - Standard MCP content array (text/json)
+     * - Standard MCP contents array (fallback)
+     */
+    extractToolData(output) {
+        if (!output)
+            return null;
+        // 1. Check for structuredContent (OpenAI / NitroStack default)
+        if (output.structuredContent) {
+            return output.structuredContent;
+        }
+        // 2. Check for standard MCP content array
+        const contents = output.content || output.contents;
+        if (Array.isArray(contents)) {
+            // Look for JSON content first
+            const jsonContent = contents.find(c => c && typeof c === 'object' && (c.mimeType === 'application/json' || c.type === 'json'));
+            if (jsonContent) {
+                try {
+                    return (typeof jsonContent.text === 'string' ? JSON.parse(jsonContent.text) : jsonContent.text);
+                }
+                catch {
+                    // fall through
+                }
+            }
+            // Look for text content that might be JSON
+            const textContent = contents.find(c => c && typeof c === 'object' && (c.mimeType === 'text/plain' || c.type === 'text'));
+            if (textContent && typeof textContent.text === 'string') {
+                try {
+                    // Only try parsing if it looks like JSON
+                    if (textContent.text.trim().startsWith('{') || textContent.text.trim().startsWith('[')) {
+                        return JSON.parse(textContent.text);
+                    }
+                    return textContent.text;
+                }
+                catch {
+                    return textContent.text;
+                }
+            }
+        }
+        // 3. Fallback to raw output if it doesn't match standard patterns
+        return output;
     }
     /**
      * Get tool response metadata

package/dist/tool-output-normalize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Aligns with NitroStack server `appType`: only `mcp-app` needs unwrapping of MCP
+ * `tools/call` results. ChatGPT (`openai` / default) must leave `toolOutput` untouched.
+ */
+export type NitroStackWidgetAppType = 'openai' | 'mcp-app';
+/**
+ * MCP Apps mode for widgets. Uses **only** `nitrostackAppType` so we never collide with
+ * host fields named `appType` (e.g. display or product metadata on the same inject object).
+ */
+export declare function resolveWidgetAppType(data: Record<string, unknown>): NitroStackWidgetAppType;
+/**
+ * Many hosts set `toolOutput` to the MCP tool result `{ content, structuredContent }` while
+ * widgets read the flat JSON in `structuredContent`. If the root also carries real widget
+ * fields (e.g. `shops` alongside `content`), keep the root — that is the ChatGPT dual-shape.
+ */
+export declare function coalesceOpenAiToolOutput<T>(toolOutput: T | null | undefined): T | null | undefined;
+/**
+ * Nitro hosts disagree on shape: `data`, `openai`, `globals`, or `payload` may carry globals.
+ * Later keys win: `data` > `payload` > `globals` > `openai`.
+ */
+export declare function parseNitroInjectOpenaiPayload(message: unknown): Record<string, unknown> | null;
+/**
+ * MCP `tools/call` results use `content` blocks plus optional `structuredContent`.
+ * ChatGPT Apps SDK typically exposes the structured JSON as `toolOutput` directly.
+ *
+ * @param appType - When omitted or `openai`, returns `toolOutput` unchanged (required for ChatGPT).
+ */
+export declare function normalizeToolOutputForWidget<T>(toolOutput: T | null | undefined, options?: {
+    appType?: NitroStackWidgetAppType;
+}): T | null | undefined;
+//# sourceMappingURL=tool-output-normalize.d.ts.map

package/dist/tool-output-normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-output-normalize.d.ts","sourceRoot":"","sources":["../src/tool-output-normalize.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE3D;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,uBAAuB,CAE3F;AA6BD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,CAclG;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAc9F;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,EAC5C,UAAU,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAChC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,uBAAuB,CAAA;CAAE,GAC9C,CAAC,GAAG,IAAI,GAAG,SAAS,CAatB"}

package/dist/tool-output-normalize.js

@@ -0,0 +1,89 @@
+/**
+ * MCP Apps mode for widgets. Uses **only** `nitrostackAppType` so we never collide with
+ * host fields named `appType` (e.g. display or product metadata on the same inject object).
+ */
+export function resolveWidgetAppType(data) {
+    return data.nitrostackAppType === 'mcp-app' ? 'mcp-app' : 'openai';
+}
+/** Keys that belong to MCP `tools/call` / ChatGPT tool-result envelopes, not widget payloads */
+const MCP_TOOL_OUTPUT_ENVELOPE_KEYS = new Set([
+    'content',
+    'structuredContent',
+    'isError',
+    '_meta',
+]);
+/** JSON-RPC top-level keys when the client forwards the whole `tools/call` response */
+const JSONRPC_TOP_KEYS = new Set(['result', 'id', 'jsonrpc']);
+/**
+ * Some MCP clients pass the full JSON-RPC object `{ jsonrpc, id, result: { content, structuredContent } }`
+ * as `toolOutput`. Strip that shell when there are no other sibling payload fields.
+ */
+function peelJsonRpcToolResult(o) {
+    const keys = Object.keys(o);
+    const extra = keys.filter((k) => !JSONRPC_TOP_KEYS.has(k));
+    if (extra.length > 0) {
+        return o;
+    }
+    if (o.result != null && typeof o.result === 'object' && !Array.isArray(o.result)) {
+        return o.result;
+    }
+    return o;
+}
+/**
+ * Many hosts set `toolOutput` to the MCP tool result `{ content, structuredContent }` while
+ * widgets read the flat JSON in `structuredContent`. If the root also carries real widget
+ * fields (e.g. `shops` alongside `content`), keep the root — that is the ChatGPT dual-shape.
+ */
+export function coalesceOpenAiToolOutput(toolOutput) {
+    if (toolOutput == null || typeof toolOutput !== 'object' || Array.isArray(toolOutput)) {
+        return toolOutput;
+    }
+    const o = peelJsonRpcToolResult(toolOutput);
+    const sc = o.structuredContent;
+    if (sc == null || typeof sc !== 'object' || Array.isArray(sc) || !Array.isArray(o.content)) {
+        return o === toolOutput ? toolOutput : o;
+    }
+    const extraKeys = Object.keys(o).filter((k) => !MCP_TOOL_OUTPUT_ENVELOPE_KEYS.has(k));
+    if (extraKeys.length > 0) {
+        return o === toolOutput ? toolOutput : o;
+    }
+    return sc;
+}
+/**
+ * Nitro hosts disagree on shape: `data`, `openai`, `globals`, or `payload` may carry globals.
+ * Later keys win: `data` > `payload` > `globals` > `openai`.
+ */
+export function parseNitroInjectOpenaiPayload(message) {
+    if (!message || typeof message !== 'object') {
+        return null;
+    }
+    const m = message;
+    const pick = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+    const merged = {
+        ...pick(m.openai),
+        ...pick(m.globals),
+        ...pick(m.payload),
+        ...pick(m.data),
+    };
+    return Object.keys(merged).length > 0 ? merged : null;
+}
+/**
+ * MCP `tools/call` results use `content` blocks plus optional `structuredContent`.
+ * ChatGPT Apps SDK typically exposes the structured JSON as `toolOutput` directly.
+ *
+ * @param appType - When omitted or `openai`, returns `toolOutput` unchanged (required for ChatGPT).
+ */
+export function normalizeToolOutputForWidget(toolOutput, options) {
+    if ((options?.appType ?? 'openai') !== 'mcp-app') {
+        return toolOutput;
+    }
+    if (toolOutput == null || typeof toolOutput !== 'object') {
+        return toolOutput;
+    }
+    const o = peelJsonRpcToolResult(toolOutput);
+    const sc = o.structuredContent;
+    if (sc != null && typeof sc === 'object' && !Array.isArray(sc) && Array.isArray(o.content)) {
+        return sc;
+    }
+    return (o === toolOutput ? toolOutput : o);
+}

package/dist/withToolData.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withToolData.d.ts","sourceRoot":"","sources":["../src/withToolData.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA8B,MAAM,OAAO,CAAC;AAEnD;;;;;;;;GAQG;AAEH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,GAAG;IACxC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,GAAG,EAClC,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,iDAkNnD"}
+{"version":3,"file":"withToolData.d.ts","sourceRoot":"","sources":["../src/withToolData.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA8B,MAAM,OAAO,CAAC;AAEnD;;;;;;;;GAQG;AAEH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,GAAG;IACxC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,GAAG,EAClC,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,iDA+PnD"}

package/dist/withToolData.js

@@ -12,18 +12,60 @@ export function withToolData(WrappedComponent) {
         useEffect(() => {
             // Mark as mounted to prevent SSR/hydration issues
             setMounted(true);
+            // Robustly extract data from tool output
+            const extractToolData = (output) => {
+                if (!output)
+                    return null;
+                // 1. Check for structuredContent (OpenAI / NitroStack default)
+                if (output.structuredContent) {
+                    return output.structuredContent;
+                }
+                // 2. Check for standard MCP content array
+                const contents = output.content || output.contents;
+                if (Array.isArray(contents)) {
+                    // Look for JSON content first
+                    const jsonContent = contents.find((c) => c && typeof c === 'object' && (c.mimeType === 'application/json' || c.type === 'json'));
+                    if (jsonContent) {
+                        try {
+                            return (typeof jsonContent.text === 'string' ? JSON.parse(jsonContent.text) : jsonContent.text);
+                        }
+                        catch {
+                            // fall through
+                        }
+                    }
+                    // Look for text content that might be JSON
+                    const textContent = contents.find((c) => c && typeof c === 'object' && (c.mimeType === 'text/plain' || c.type === 'text'));
+                    if (textContent && typeof textContent.text === 'string') {
+                        try {
+                            // Only try parsing if it looks like JSON
+                            if (textContent.text.trim().startsWith('{') || textContent.text.trim().startsWith('[')) {
+                                return JSON.parse(textContent.text);
+                            }
+                            return textContent.text;
+                        }
+                        catch {
+                            return textContent.text;
+                        }
+                    }
+                }
+                // 3. Fallback to raw output
+                return output;
+            };
             // Function to check for data
             const checkForData = () => {
                 try {
                     if (typeof window !== 'undefined') {
                         const openai = window.openai;
-                        if (openai && openai.toolOutput) {
-                            setState({
-                                data: openai.toolOutput,
-                                loading: false,
-                                error: null,
-                            });
-                            return true;
+                        if (openai && (openai.toolOutput || openai.toolInput)) {
+                            const data = extractToolData(openai.toolOutput);
+                            if (data) {
+                                setState({
+                                    data: data,
+                                    loading: false,
+                                    error: null,
+                                });
+                                return true;
+                            }
                         }
                     }
                 }
@@ -47,8 +89,9 @@ export function withToolData(WrappedComponent) {
                 console.log('[Widget] Received postMessage:', event.data);
                 if (event.data && event.data.type === 'toolOutput') {
                     console.log('[Widget] Setting data:', event.data.data);
+                    const data = extractToolData(event.data.data);
                     setState({
-                        data: event.data.data,
+                        data: data,
                         loading: false,
                         error: null,
                     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitrostack/widgets",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Widget utilities for NitroStack - Build interactive UI widgets for MCP tools",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,8 @@
   "author": "Nitrostack Inc <hello@nitrostack.ai>",
   "license": "Apache-2.0",
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "@modelcontextprotocol/ext-apps": ">=0.1.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",