@miragon/mcp-toolkit-ui 0.10.1 → 1.0.1

package/src/app/host-bridge.test.ts

@@ -2,6 +2,8 @@ import { afterEach, describe, expect, it, vi } from "vitest"
 import {
   createChatGptHostBridge,
   createStandaloneHostBridge,
+  toHostBridge,
+  type McpUseWidgetSurface,
   type OpenAiAppsSdk,
 } from "./host-bridge.js"
 
@@ -9,6 +11,111 @@ afterEach(() => {
   vi.restoreAllMocks()
 })
 
+/** A widget surface whose verbs all succeed; override per test. */
+function surface(overrides: Partial<McpUseWidgetSurface> = {}): McpUseWidgetSurface {
+  return {
+    callTool: vi.fn().mockResolvedValue({ structuredContent: { ok: true } }),
+    sendFollowUpMessage: vi.fn().mockResolvedValue(undefined),
+    openExternal: vi.fn(),
+    setState: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  }
+}
+
+/**
+ * The `mcp-use` adapter is the one bridge whose upstream shape is not ours, so
+ * these pin the mapping itself: every verb's fail-soft promise, and the exact
+ * wire shape of the model-context write. A widget renders through this — none
+ * of it may start throwing, and `__model_context` is what the host reads.
+ */
+describe("toHostBridge — mcp-use widget surface mapping", () => {
+  it("passes callTool through untouched and resolves with the raw tool response", async () => {
+    const callTool = vi.fn().mockResolvedValue({ structuredContent: { rows: 3 } })
+    const bridge = toHostBridge(surface({ callTool }))
+
+    await expect(bridge.callTool("list_tasks", { limit: 10 })).resolves.toEqual({
+      structuredContent: { rows: 3 },
+    })
+    expect(callTool).toHaveBeenCalledWith("list_tasks", { limit: 10 })
+  })
+
+  it("swallows a rejected sendFollowUpMessage with a warning instead of an unhandled rejection", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    const sendFollowUpMessage = vi.fn().mockRejectedValue(new Error("no conversation"))
+    const bridge = toHostBridge(surface({ sendFollowUpMessage }))
+
+    expect(() => bridge.sendFollowup("show me more")).not.toThrow()
+    await vi.waitFor(() => {
+      expect(warn).toHaveBeenCalledWith(
+        "[host-bridge] sendFollowUpMessage failed:",
+        expect.any(Error),
+      )
+    })
+  })
+
+  it("falls back to window.open when the host's openExternal throws", () => {
+    const openExternal = vi.fn(() => {
+      throw new Error("no host bridge")
+    })
+    const open = vi.fn()
+    vi.stubGlobal("window", { open })
+
+    const bridge = toHostBridge(surface({ openExternal }))
+    expect(() => bridge.openExternal("https://example.test")).not.toThrow()
+    expect(open).toHaveBeenCalledWith("https://example.test", "_blank", "noopener")
+
+    vi.unstubAllGlobals()
+  })
+
+  it("does not reach for window.open when the host handles the link", () => {
+    const open = vi.fn()
+    vi.stubGlobal("window", { open })
+
+    const bridge = toHostBridge(surface())
+    bridge.openExternal("https://example.test")
+    expect(open).not.toHaveBeenCalled()
+
+    vi.unstubAllGlobals()
+  })
+
+  it("returns the host-pushed output from getWidgetData, and null when there is none", () => {
+    expect(toHostBridge(surface({ output: { total: 7 } })).getWidgetData()).toEqual({ total: 7 })
+    expect(toHostBridge(surface({ output: undefined })).getWidgetData()).toBeNull()
+    // A host that pushes an explicit null must not surface as undefined.
+    expect(toHostBridge(surface({ output: null })).getWidgetData()).toBeNull()
+  })
+
+  it("writes model context as setState({ __model_context }) — the key the host reads", () => {
+    const setState = vi.fn().mockResolvedValue(undefined)
+    const bridge = toHostBridge(surface({ setState }))
+
+    bridge.setModelContext?.("selected invoice 42")
+    expect(setState).toHaveBeenCalledWith({ __model_context: "selected invoice 42" })
+  })
+
+  it("swallows a rejected setState with a warning", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    const setState = vi.fn().mockRejectedValue(new Error("state unavailable"))
+    const bridge = toHostBridge(surface({ setState }))
+
+    expect(() => bridge.setModelContext?.("x")).not.toThrow()
+    await vi.waitFor(() => {
+      expect(warn).toHaveBeenCalledWith(
+        "[host-bridge] setState (model context) failed:",
+        expect.any(Error),
+      )
+    })
+  })
+
+  it("normalizes the theme: only an exact 'dark' is dark, everything else is light", () => {
+    expect(toHostBridge(surface({ theme: "dark" })).theme).toBe("dark")
+    expect(toHostBridge(surface({ theme: "light" })).theme).toBe("light")
+    // Unknown or absent host spellings must not leak through as-is.
+    expect(toHostBridge(surface({ theme: undefined })).theme).toBe("light")
+    expect(toHostBridge(surface({ theme: "Dark" })).theme).toBe("light")
+  })
+})
+
 describe("createChatGptHostBridge — no window.openai (defensive guards)", () => {
   // Passing `null` exercises the fully-absent SDK path without touching window.
   it("rejects callTool with a clear error instead of throwing synchronously", async () => {

package/src/app/host-bridge.tsx

@@ -1,5 +1,4 @@
-import { createContext, useContext, useMemo, type ReactNode } from "react"
-import { useWidget } from "mcp-use/react"
+import { createContext, useContext, type ReactNode } from "react"
 
 /**
  * The host capabilities a hand-built widget needs, abstracted away from any one
@@ -20,31 +19,31 @@ export interface HostBridge {
    * with `parseToolResult`. Rejects if the call fails so a widget's own error
    * state (TanStack Query, try/catch) can surface it.
    */
-  callTool(name: string, args: Record<string, unknown>): Promise<unknown>
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>
   /**
    * Hand a natural-language prompt back to the conversation to drive a new model
    * turn (navigate to another widget, ask the agent to analyse something). In
    * hosts without a conversation (standalone web app) this is a no-op unless an
    * `onFollowup` handler is supplied.
    */
-  sendFollowup(prompt: string): void
+  sendFollowup: (prompt: string) => void
   /**
    * Ask the host to open a URL outside the (often sandboxed) widget frame.
    * Falls back to `window.open` only where no host bridge mediates links.
    */
-  openExternal(url: string): void
+  openExternal: (url: string) => void
   /**
    * The structured data this widget was rendered with, if the host pushed any
    * (the tool result's `structuredContent` / `toolOutput`). Returns `null` when
    * the host delivers data another way (e.g. props) or has none.
    */
-  getWidgetData<T>(): T | null
+  getWidgetData: <T>() => T | null
   /**
    * Persist a short text the model should see on the next turn (selection,
    * filter, current view). Optional: not every host exposes model context, and
    * a standalone web app has no model at all — callers must guard its absence.
    */
-  setModelContext?(text: string): void
+  setModelContext?: (text: string) => void
   /** The host's colour-scheme preference, when it reports one. */
   theme?: "light" | "dark"
 }
@@ -54,12 +53,9 @@ const HostBridgeContext = createContext<HostBridge | null>(null)
 /**
  * Provide an explicit {@link HostBridge} to a subtree. Wrap a portable widget in
  * the adapter for the host it is running in — {@link createChatGptHostBridge},
- * {@link createStandaloneHostBridge}, or {@link createMcpUseHostBridge} — and
- * every `useHostBridge()` below resolves to it.
- *
- * Omitting the provider is supported: {@link useHostBridge} (and, for backward
- * compatibility, `useHostActions`) then fall back to the `mcp-use`/react default
- * bridge so existing widgets keep working without any wrapping.
+ * {@link createStandaloneHostBridge}, or (inside the toolkit's own mcp-use
+ * view) the `McpUseHostBridgeProvider` — and every `useHostBridge()` below
+ * resolves to it.
  */
 export function HostBridgeProvider({
   bridge,
@@ -82,86 +78,93 @@ export function useHostBridgeOrNull(): HostBridge | null {
 }
 
 /**
- * The {@link HostBridge} for the current subtree. Resolution order:
+ * The {@link HostBridge} for the current subtree — the nearest
+ * {@link HostBridgeProvider}'s bridge.
  *
- * 1. An explicit bridge from the nearest {@link HostBridgeProvider}.
- * 2. The default `mcp-use`/react bridge ({@link createMcpUseHostBridge}), so a
- *    widget mounted in our own host needs no provider.
+ * A provider is always present in the supported mounts: the toolkit shell
+ * (`McpToolkitApp` via `McpUseHostBridgeProvider`) installs the `mcp-use`
+ * bridge for every widget it renders, the `WidgetFixtureHost` harness installs
+ * a standalone bridge, and ChatGPT / standalone apps wrap their root in
+ * {@link createChatGptHostBridge} / {@link createStandaloneHostBridge}.
  *
- * The `mcp-use` hooks the default bridge wraps must run under an `mcp-use`
- * provider/host context; outside one (e.g. a bare unit test render) wrap the
- * widget in a `HostBridgeProvider` with a {@link createStandaloneHostBridge}
- * instead. This hook never returns `null`: a portable widget can always assume a
- * bridge exists.
+ * Since mcp-use 2.x there is no provider-less fallback: the `mcp-use` hooks
+ * only work inside a `bootstrapView`-mounted view, so a bare render without a
+ * provider cannot silently degrade — this hook throws with a pointer to the
+ * adapters instead.
  */
 export function useHostBridge(): HostBridge {
   const explicit = useContext(HostBridgeContext)
-  // Always call the default-bridge hook (Rules of Hooks): it's cheap and only
-  // *used* when no explicit bridge is provided. The mcp-use hooks underneath are
-  // host-context readers, safe to call even when their result goes unused.
-  const fallback = useMcpUseHostBridge()
-  return explicit ?? fallback
+  if (!explicit) {
+    throw new Error(
+      "[host-bridge] useHostBridge() found no HostBridgeProvider. Wrap the widget in " +
+        "McpToolkitApp / McpUseHostBridgeProvider (toolkit host), WidgetFixtureHost (dev), " +
+        "or a HostBridgeProvider with createChatGptHostBridge / createStandaloneHostBridge.",
+    )
+  }
+  return explicit
 }
 
 /**
- * Build a {@link HostBridge} backed by `mcp-use`/react — the default for widgets
- * running in the toolkit's own host. Wraps `useWidget()` (host actions,
- * `toolOutput`, `theme`) and `useCallTool` so it preserves exactly the behaviour
- * widgets had before the bridge abstraction:
- *
- * - `openExternal` routes through the host's `openExternal` and falls back to
- *   `window.open` when no host bridge is wired (local dev preview) — mirroring
- *   the original `useHostActions.openLink`.
- * - `sendFollowup` routes through `sendFollowUpMessage` and swallows rejections
- *   with a `console.warn`, as `useHostActions` did.
+ * Exactly the slice of `mcp-use`'s widget surface {@link toHostBridge} reads —
+ * declared structurally rather than imported from `mcp-use/react`.
  *
- * Must be called inside an `mcp-use` host context (it calls `mcp-use` hooks).
- * Use {@link createMcpUseHostBridge} for the standalone factory variant.
+ * That indirection is the point: the mapping below is the behaviour widgets
+ * depend on, and pinning it against a local interface keeps it testable without
+ * a host, a DOM, or a React renderer. It also localises upstream churn — when
+ * the shape moves, this interface and the `McpUseHostBridgeProvider` (which
+ * composes the mcp-use 2.x view hooks into this surface) are what change, and
+ * {@link toHostBridge}'s tests still prove the bridge contract widgets see is
+ * unchanged. The 1.x `useWidget()` satisfied it directly; the 2.x composition
+ * lives in `mcp-use-host-bridge.tsx`.
  */
-export function useMcpUseHostBridge(): HostBridge {
-  const widget = useWidget()
-  const { callTool, sendFollowUpMessage, openExternal, output, theme, setState } = widget
-
-  return useMemo<HostBridge>(
-    () => ({
-      callTool: (name, args) => callTool(name, args),
-      sendFollowup: (prompt) => {
-        void sendFollowUpMessage(prompt).catch((err: unknown) => {
-          console.warn("[host-bridge] sendFollowUpMessage failed:", err)
-        })
-      },
-      openExternal: (url) => {
-        try {
-          openExternal(url)
-        } catch {
-          // No host bridge (local dev preview) — fall back to window.open.
-          if (typeof window !== "undefined") window.open(url, "_blank", "noopener")
-        }
-      },
-      getWidgetData: <T,>() => (output as T | null) ?? null,
-      setModelContext: (text) => {
-        void setState({ __model_context: text }).catch((err: unknown) => {
-          console.warn("[host-bridge] setState (model context) failed:", err)
-        })
-      },
-      theme: theme === "dark" ? "dark" : "light",
-    }),
-    [callTool, sendFollowUpMessage, openExternal, output, theme, setState],
-  )
+export interface McpUseWidgetSurface {
+  /** Invoke a tool on the connected server. */
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>
+  /** Hand a prompt back to the conversation. Rejects are swallowed by the mapping. */
+  sendFollowUpMessage: (prompt: string) => Promise<unknown>
+  /** Open a URL outside the widget frame. Throws when no host mediates links. */
+  openExternal: (url: string) => void
+  /** The tool output the host rendered this widget with, when it pushed one. */
+  output?: unknown
+  /** The host's reported colour scheme, in whatever spelling it uses. */
+  theme?: unknown
+  /** Persist widget state; the model-context write rides on this. */
+  setState: (state: Record<string, unknown>) => Promise<unknown>
 }
 
 /**
- * Factory form of {@link useMcpUseHostBridge} for symmetry with the other
- * adapters. Because the `mcp-use` bridge is hook-driven (it reads live host
- * context), the "factory" is really the hook itself — call it from a component.
+ * Map `mcp-use`'s widget surface onto the host-agnostic {@link HostBridge}.
  *
- * @example
- * function MyWidget() {
- *   const bridge = createMcpUseHostBridge() // === useMcpUseHostBridge()
- *   // …or rely on useHostBridge()'s default and skip the provider entirely.
- * }
+ * Pure and separately exported so the fail-soft behaviour is pinned by tests:
+ * every verb here has a documented failure mode that widgets rely on, and none
+ * of them may start throwing into widget render paths.
  */
-export const createMcpUseHostBridge = useMcpUseHostBridge
+export function toHostBridge(widget: McpUseWidgetSurface): HostBridge {
+  const { callTool, sendFollowUpMessage, openExternal, output, theme, setState } = widget
+  return {
+    callTool: (name, args) => callTool(name, args),
+    sendFollowup: (prompt) => {
+      void sendFollowUpMessage(prompt).catch((err: unknown) => {
+        console.warn("[host-bridge] sendFollowUpMessage failed:", err)
+      })
+    },
+    openExternal: (url) => {
+      try {
+        openExternal(url)
+      } catch {
+        // No host bridge (local dev preview) — fall back to window.open.
+        if (typeof window !== "undefined") window.open(url, "_blank", "noopener")
+      }
+    },
+    getWidgetData: <T,>() => (output as T | null) ?? null,
+    setModelContext: (text) => {
+      void setState({ __model_context: text }).catch((err: unknown) => {
+        console.warn("[host-bridge] setState (model context) failed:", err)
+      })
+    },
+    theme: theme === "dark" ? "dark" : "light",
+  }
+}
 
 /**
  * Minimal structural view of the OpenAI Apps SDK `window.openai` object this

package/src/app/index.ts

@@ -1,6 +1,6 @@
 export { McpAppView } from "./mcp-app-view.js"
 export type { McpAppViewProps, McpAppViewLabels } from "./mcp-app-view.js"
-export { McpToolkitApp } from "./mcp-toolkit-app.js"
+export { McpToolkitApp, mountMcpToolkitApp } from "./mcp-toolkit-app.js"
 export {
   WidgetRenderer,
   WidgetErrorBoundary,
@@ -11,31 +11,36 @@ export type { WidgetRendererProps, WidgetComponent } from "./widget-renderer.js"
 export { LayoutBuilder } from "./layout-builder.js"
 export type { LayoutBuilderProps, LayoutBuilderLabels } from "./layout-builder.js"
 
-// App-level value modules that import `mcp-use/react` (ModelContext, useWidget)
-// — exported from this subpath only, never the root barrel.
-export { adaptDataWidget } from "./adapt-data-widget.js"
+// App-level value modules that import `mcp-use/react` (ModelContext, the 2.x
+// view hooks) — exported from this subpath only, never the root barrel.
+export { adaptDataWidget, HostModelContext } from "./adapt-data-widget.js"
 export type { DescribeForModel } from "./adapt-data-widget.js"
 export { useHostActions, buildShowWidgetIntent } from "./use-host-actions.js"
 export type { HostActions } from "./use-host-actions.js"
 
 // Host-portability bridge: the seam that lets the same hand-built widget run in
 // our mcp-use host, ChatGPT (Apps SDK), or a standalone web app against an
-// existing MCP server. Lives under ./app because the default adapter imports
+// existing MCP server. Lives under ./app because the mcp-use adapter imports
 // `mcp-use/react` — never the root barrel.
 export {
   HostBridgeProvider,
   useHostBridge,
   useHostBridgeOrNull,
-  useMcpUseHostBridge,
-  createMcpUseHostBridge,
+  toHostBridge,
   createChatGptHostBridge,
   createStandaloneHostBridge,
 } from "./host-bridge.js"
-export type { HostBridge, OpenAiAppsSdk, StandaloneHostBridgeOptions } from "./host-bridge.js"
+export type {
+  HostBridge,
+  McpUseWidgetSurface,
+  OpenAiAppsSdk,
+  StandaloneHostBridgeOptions,
+} from "./host-bridge.js"
+export { McpUseHostBridgeProvider, useIsInsideMcpUseView } from "./mcp-use-host-bridge.js"
 
 // Storybook-style harness for developing widgets in isolation with fixture
-// data and a mocked host. Lives under ./app because it mocks the
-// `mcp-use/react` host bridge (window.openai) — never the root barrel.
+// data and a simulated HostBridge. Lives under ./app to keep every host-facing
+// surface on one subpath — never the root barrel.
 export {
   WidgetFixtureHost,
   FixtureCallToolRegistry,

package/src/app/mcp-app-view.tsx

@@ -1,11 +1,12 @@
 import { useState, useCallback } from "react"
-import { useWidget } from "mcp-use/react"
+import { useDisplayMode, useHostContext, useToolContext } from "mcp-use/react"
 import { Maximize2, Minimize2, Pencil, RefreshCw } from "lucide-react"
 import type { LayoutConfig, PipelineStepRef } from "@miragon/mcp-toolkit-core"
 import { Skeleton } from "../primitives/skeleton.js"
 import { AppQueryProvider, queryClient } from "../providers/query-provider.js"
 import { useToolResultRecovery } from "../hooks/use-tool-result-recovery.js"
 import { parseToolResult } from "../lib/parse-tool-result.js"
+import { useHostBridge } from "./host-bridge.js"
 import { LayoutBuilder } from "./layout-builder.js"
 import { WidgetRenderer, type WidgetComponent } from "./widget-renderer.js"
 
@@ -106,24 +107,24 @@ export function McpAppView({
   labels,
 }: McpAppViewProps) {
   const effectiveLabels = { ...DEFAULT_LABELS, ...labels }
-  const {
-    props: initialViewData,
-    isPending,
-    callTool,
-    displayMode: currentDisplayMode,
-    requestDisplayMode,
-    safeArea,
-    toolInput,
-    hostContext,
-  } = useWidget<ViewData>()
+  // Since mcp-use 2.x the shell reads the view channels through the dedicated
+  // hooks (all require the surrounding `bootstrapView` mount that
+  // `mountMcpToolkitApp` provides) and calls tools through the HostBridge that
+  // `McpUseHostBridgeProvider` installs.
+  const tool = useToolContext()
+  const { displayMode, requestDisplayMode } = useDisplayMode()
+  const { safeArea, hostContext } = useHostContext()
+  const bridge = useHostBridge()
+  const callTool = useCallback(
+    (name: string, args: Record<string, unknown>) => bridge.callTool(name, args),
+    [bridge],
+  )
+
+  const isPending = tool.status === "pending"
+  const initialViewData = tool.status === "ready" ? (tool.toolOutput as ViewData) : undefined
+  const toolInput = tool.toolInput
 
   const [viewData, setViewData] = useState<ViewData | null>(null)
-  const [displayMode, setDisplayMode] = useState<string>(currentDisplayMode ?? "inline")
-  const [prevCurrentDisplayMode, setPrevCurrentDisplayMode] = useState(currentDisplayMode)
-  if (currentDisplayMode !== prevCurrentDisplayMode) {
-    setPrevCurrentDisplayMode(currentDisplayMode)
-    if (currentDisplayMode) setDisplayMode(currentDisplayMode)
-  }
   const [isRefreshing, setIsRefreshing] = useState(false)
 
   // In-iframe build mode is purely a UI state — the LLM never sees the
@@ -152,10 +153,13 @@ export function McpAppView({
   }
 
   // Hosts that strip `structuredContent` from the tool-result notification
-  // (claude.ai / Claude Desktop) leave `initialViewData` empty forever; the
-  // recovery re-executes the originating tool once via `callTool` (responses
-  // carry `structuredContent` intact) and fills the gap. Conforming hosts
-  // deliver a valid payload up front, so this never fires there.
+  // (claude.ai / Claude Desktop) never latch a result under mcp-use 2.x — the
+  // `useToolContext` latch ignores content-only results, so `isPending` stays
+  // true forever. The recovery therefore also arms itself on a grace timer
+  // once the originating tool is known, re-executes it via `callTool`
+  // (responses carry `structuredContent` intact), and fills the gap.
+  // Conforming hosts deliver a valid payload up front, so it never fires
+  // there.
   const recovery = useToolResultRecovery<ViewData>({
     resultReady: !isPending,
     props: initialViewData,
@@ -174,8 +178,10 @@ export function McpAppView({
   const toggleFullscreen = useCallback(async () => {
     const newMode = displayMode === "fullscreen" ? "inline" : "fullscreen"
     try {
-      const result = await requestDisplayMode(newMode)
-      setDisplayMode(result.mode)
+      // Advisory since 2.x: the promise only confirms the host processed the
+      // request. `displayMode` from `useDisplayMode` updates reactively when
+      // (and only when) the host actually applies the change.
+      await requestDisplayMode({ mode: newMode })
     } catch (e) {
       console.error("Failed to toggle display mode:", e)
     }
@@ -245,7 +251,10 @@ export function McpAppView({
     [],
   )
 
-  if (isPending || !viewData) {
+  // `isPending` must not gate the render: on hosts that strip
+  // `structuredContent` the 2.x latch stays "pending" forever, and recovered
+  // viewData still has to replace the skeleton.
+  if (!viewData) {
     return (
       <div className="flex flex-col gap-4 p-4">
         <Skeleton className="h-8 w-48" />
@@ -268,17 +277,17 @@ export function McpAppView({
       style={{
         // Fullscreen: the widget owns the viewport, so we take the full window
         // and handle our own scrolling. Inline: the host (Claude, ChatGPT) owns
-        // sizing + scrolling and is notified of our intrinsic height via
-        // `McpUseProvider`, so we let content dictate height and avoid setting
-        // overflowY (which would clip our own content inside a host that's
-        // already auto-sized to us).
+        // sizing + scrolling and observes our intrinsic height via
+        // `bootstrapView`'s auto-resize, so we let content dictate height and
+        // avoid setting overflowY (which would clip our own content inside a
+        // host that's already auto-sized to us).
         ...(displayMode === "fullscreen"
           ? { minHeight: "100vh", overflowY: "auto" as const }
           : null),
-        paddingTop: safeArea?.insets?.top,
-        paddingRight: safeArea?.insets?.right,
-        paddingBottom: safeArea?.insets?.bottom,
-        paddingLeft: safeArea?.insets?.left,
+        paddingTop: safeArea.top,
+        paddingRight: safeArea.right,
+        paddingBottom: safeArea.bottom,
+        paddingLeft: safeArea.left,
       }}
     >
       {showHeader && (

package/src/app/mcp-toolkit-app.tsx

@@ -1,25 +1,42 @@
-import { McpUseProvider } from "mcp-use/react"
+import { ThemeProvider, bootstrapView } from "mcp-use/react"
 import { McpAppView, type McpAppViewProps } from "./mcp-app-view.js"
+import { McpUseHostBridgeProvider } from "./mcp-use-host-bridge.js"
 
 /**
- * Consumer-facing root for a toolkit-rendered MCP App. Wraps `McpAppView`
- * in `McpUseProvider` so the host (Claude, ChatGPT Apps SDK) receives
- * intrinsic-height notifications and the widget auto-sizes inside the
- * host's inline container.
+ * Consumer-facing root for a toolkit-rendered MCP App. Composes the mcp-use
+ * 2.x view plumbing around `McpAppView`: `ThemeProvider` applies the host's
+ * theme/style variables to the document, and `McpUseHostBridgeProvider`
+ * installs the `HostBridge` (and view-scope flag) every toolkit widget below
+ * resolves through `useHostBridge()`.
  *
- * Usage at the bundle entry point:
- *
- * ```tsx
- * createRoot(root).render(<McpToolkitApp widgets={widgets} />)
- * ```
- *
- * `McpUseProvider` also installs StrictMode, a default ErrorBoundary, and
- * the theme plumbing used by the toolkit primitives.
+ * Must render inside a `bootstrapView`-mounted tree — the mcp-use view hooks
+ * throw outside one. Use {@link mountMcpToolkitApp} at the bundle entry point,
+ * which wires exactly that; render `McpToolkitApp` directly only when
+ * composing a custom view under your own `bootstrapView` call.
  */
 export function McpToolkitApp(props: McpAppViewProps) {
   return (
-    <McpUseProvider>
-      <McpAppView {...props} />
-    </McpUseProvider>
+    <ThemeProvider>
+      <McpUseHostBridgeProvider>
+        <McpAppView {...props} />
+      </McpUseHostBridgeProvider>
+    </ThemeProvider>
   )
 }
+
+/**
+ * Mount the toolkit app as the document's MCP App view — the bundle entry
+ * point since mcp-use 2.x.
+ *
+ * `bootstrapView` owns the mount: it connects the ext-apps postMessage bridge
+ * to the host, installs an error boundary, and auto-reports size changes
+ * (replacing 1.x's `createRoot` + `McpUseProvider` pair).
+ *
+ * ```tsx
+ * // main.tsx of the widget bundle
+ * mountMcpToolkitApp({ widgets })
+ * ```
+ */
+export function mountMcpToolkitApp(props: McpAppViewProps): void {
+  bootstrapView({ default: () => <McpToolkitApp {...props} /> })
+}