@miragon/mcp-toolkit-ui 0.10.1

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

@@ -0,0 +1,367 @@
+import { useState, useCallback } from "react"
+import { useWidget } 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 { LayoutBuilder } from "./layout-builder.js"
+import { WidgetRenderer, type WidgetComponent } from "./widget-renderer.js"
+
+export interface McpAppViewLabels {
+  loading?: string
+  refresh?: string
+  refreshing?: string
+  enterFullscreen?: string
+  exitFullscreen?: string
+  build?: string
+}
+
+const DEFAULT_LABELS: Required<McpAppViewLabels> = {
+  loading: "Waiting for pipeline result...",
+  refresh: "Refresh",
+  refreshing: "Loading...",
+  enterFullscreen: "Fullscreen",
+  exitFullscreen: "Collapse",
+  build: "Build",
+}
+
+interface RefreshParams {
+  keys?: Record<string, unknown>
+  steps?: PipelineStepRef[]
+  layout?: LayoutConfig
+  title?: string
+}
+
+interface ViewData {
+  _refreshParams?: RefreshParams
+  title?: string
+  context: {
+    keys: Record<string, unknown>
+    stepIds: string[]
+    stepData: Record<
+      string,
+      { data: unknown; keys: Record<string, unknown>; _app: string; _dataType: string }
+    >
+    errors: { stepId: string; reason: string }[]
+  }
+  layout?: LayoutConfig
+  /**
+   * Whether the server's in-iframe builder platform is usable (set by
+   * `render-view` from `createFrameworkApp`'s `app.builder`). The shell gates
+   * its Build affordance on this so the edit button never appears against a
+   * server whose `get-builder-catalogue` tool isn't registered.
+   */
+  builderAvailable?: boolean
+}
+
+/**
+ * A renderable view payload: the envelope `render-view`/`show_*` tools emit
+ * as `structuredContent`. Module-level so it is referentially stable as the
+ * recovery hook's `isValid` dependency.
+ */
+function isCompleteViewData(value: unknown): value is ViewData {
+  const v = value as ViewData | null | undefined
+  return Boolean(v?.context && v?.layout)
+}
+
+export interface McpAppViewProps {
+  /**
+   * Map of widget ID to React component. The consumer aggregates this from
+   * each module's widget exports and passes it in at the bundled `main.tsx`
+   * entry point. All widgets are host-bundled — the framework never fetches
+   * widget code at render time.
+   */
+  widgets: Record<string, WidgetComponent>
+  /**
+   * Name of the MCP tool that the refresh button invokes. Consumers typically
+   * register this tool as a thin wrapper around `renderView(...)` from
+   * `@miragon/mcp-toolkit-core`. Defaults to `"refresh-view"`.
+   */
+  refreshToolName?: string
+  /**
+   * Explicit override for the Build / edit (Pencil) affordance. Leave it
+   * `undefined` (the default) to let the shell follow the server's own
+   * signal — `render-view` reports `structuredContent.builderAvailable`,
+   * derived from `createFrameworkApp`'s `app.builder`, so the button appears
+   * only when the `get-builder-catalogue` tool is actually registered. Set it
+   * to `true` / `false` only to force the affordance on or off regardless of
+   * that signal (e.g. a custom server that registers the catalogue tool by
+   * hand). Even when forced on, the LayoutBuilder's catalogue fetch fails
+   * soft (no crash) if the tool is absent.
+   */
+  builderEnabled?: boolean
+  /**
+   * Override UI strings (loading, refresh, fullscreen, build).
+   * Defaults to English.
+   */
+  labels?: McpAppViewLabels
+}
+
+export function McpAppView({
+  widgets,
+  refreshToolName = "refresh-view",
+  builderEnabled,
+  labels,
+}: McpAppViewProps) {
+  const effectiveLabels = { ...DEFAULT_LABELS, ...labels }
+  const {
+    props: initialViewData,
+    isPending,
+    callTool,
+    displayMode: currentDisplayMode,
+    requestDisplayMode,
+    safeArea,
+    toolInput,
+    hostContext,
+  } = useWidget<ViewData>()
+
+  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
+  // catalogue, the user toggles into build by clicking the toolbar button.
+  const [buildMode, setBuildMode] = useState(false)
+
+  // Sync host-provided initialViewData → local viewData via render-phase
+  // setState (rather than an effect) so the React Compiler doesn't flag a
+  // cascading render. The guard against transient empty toolOutput stays:
+  // widgetProps may briefly drop `context`/`layout` when displayMode toggles,
+  // and we don't want that to clobber a valid viewData.
+  //
+  // `prev` MUST start as `null`, not `initialViewData`: hosts that expose the
+  // complete tool output before the app's first render (e.g. window.openai
+  // globals injected ahead of script execution) would otherwise never trip the
+  // identity check — initialViewData never changes again, the sync never runs,
+  // and the app idles on the loading skeleton forever.
+  const [prevInitialViewData, setPrevInitialViewData] = useState<typeof initialViewData | null>(
+    null,
+  )
+  if (initialViewData !== prevInitialViewData) {
+    setPrevInitialViewData(initialViewData)
+    if (!isPending && isCompleteViewData(initialViewData)) {
+      setViewData(initialViewData)
+    }
+  }
+
+  // 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.
+  const recovery = useToolResultRecovery<ViewData>({
+    resultReady: !isPending,
+    props: initialViewData,
+    isValid: isCompleteViewData,
+    toolInput,
+    hostContext,
+    callTool,
+  })
+  const [prevRecovered, setPrevRecovered] = useState<ViewData | null>(null)
+  if (recovery.data !== prevRecovered) {
+    setPrevRecovered(recovery.data)
+    // The host-delivered payload always wins; recovery only fills the gap.
+    if (recovery.data && !viewData) setViewData(recovery.data)
+  }
+
+  const toggleFullscreen = useCallback(async () => {
+    const newMode = displayMode === "fullscreen" ? "inline" : "fullscreen"
+    try {
+      const result = await requestDisplayMode(newMode)
+      setDisplayMode(result.mode)
+    } catch (e) {
+      console.error("Failed to toggle display mode:", e)
+    }
+  }, [displayMode, requestDisplayMode])
+
+  // Stable callTool callback (avoids a new object reference on every render)
+  const callToolFn = useCallback(
+    async (name: string, args: object) => {
+      return callTool(name, args as Record<string, unknown>)
+    },
+    [callTool],
+  )
+
+  const refreshView = useCallback(async () => {
+    if (!viewData?._refreshParams) return
+    setIsRefreshing(true)
+    try {
+      const result = await callTool(
+        refreshToolName,
+        viewData._refreshParams as unknown as Record<string, unknown>,
+      )
+      // Decode through the shared structured-first parser (one convention with
+      // `useToolQuery`); a refresh returns the view envelope as `structuredContent`.
+      const refreshed = parseToolResult<ViewData | null>(result)
+      if (refreshed?.context && refreshed?.layout) {
+        setViewData(refreshed)
+      }
+      void queryClient.invalidateQueries()
+    } catch (e) {
+      console.error("Failed to refresh view:", e)
+    } finally {
+      setIsRefreshing(false)
+    }
+  }, [callTool, refreshToolName, viewData])
+
+  // Called by LayoutBuilder when the user clicks Done. Commits the draft
+  // layout (and any keys/steps edits) into the parent viewData so the
+  // WidgetRenderer takes over showing the just-built layout.
+  const exitBuildMode = useCallback(
+    (commit?: {
+      layout: LayoutConfig
+      keys?: Record<string, unknown>
+      steps?: PipelineStepRef[]
+      title?: string
+      context?: ViewData["context"]
+    }) => {
+      if (commit) {
+        setViewData((prev) =>
+          prev
+            ? {
+                ...prev,
+                layout: commit.layout,
+                title: commit.title ?? prev.title,
+                context: commit.context ?? prev.context,
+                _refreshParams: {
+                  keys: commit.keys,
+                  steps: commit.steps,
+                  layout: commit.layout,
+                  title: commit.title ?? prev.title,
+                },
+              }
+            : prev,
+        )
+      }
+      setBuildMode(false)
+    },
+    [],
+  )
+
+  if (isPending || !viewData) {
+    return (
+      <div className="flex flex-col gap-4 p-4">
+        <Skeleton className="h-8 w-48" />
+        <Skeleton className="h-32 w-full" />
+        <p className="text-muted-foreground text-sm">{effectiveLabels.loading}</p>
+      </div>
+    )
+  }
+
+  const showHeader = !buildMode
+
+  // Follow the server's own signal by default: render-view reports
+  // `builderAvailable` (derived from `app.builder`), so the Build button only
+  // shows when the catalogue/dashboard tools are actually registered. An
+  // explicit `builderEnabled` prop forces the affordance on or off.
+  const builderAvailable = builderEnabled ?? viewData.builderAvailable ?? false
+
+  return (
+    <main
+      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).
+        ...(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,
+      }}
+    >
+      {showHeader && (
+        <div className="mb-4 flex items-center justify-between">
+          {viewData.title && <h2 className="text-xl font-bold">{viewData.title}</h2>}
+          <div className="ml-auto flex items-center gap-2">
+            {viewData._refreshParams && viewData.layout && (
+              <button
+                onClick={() => {
+                  void refreshView()
+                }}
+                disabled={isRefreshing}
+                className="hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm font-medium transition-colors disabled:opacity-50"
+              >
+                <RefreshCw
+                  aria-hidden="true"
+                  className={`h-4 w-4 ${isRefreshing ? "animate-spin" : ""}`}
+                />
+                {isRefreshing ? effectiveLabels.refreshing : effectiveLabels.refresh}
+              </button>
+            )}
+            {builderAvailable && viewData._refreshParams && (
+              <button
+                onClick={() => setBuildMode(true)}
+                className="hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm font-medium transition-colors"
+              >
+                <Pencil className="h-4 w-4" />
+                {effectiveLabels.build}
+              </button>
+            )}
+            <button
+              onClick={() => {
+                void toggleFullscreen()
+              }}
+              className="hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm font-medium transition-colors"
+            >
+              {displayMode === "fullscreen" ? (
+                <Minimize2 aria-hidden="true" className="h-4 w-4" />
+              ) : (
+                <Maximize2 aria-hidden="true" className="h-4 w-4" />
+              )}
+              {displayMode === "fullscreen"
+                ? effectiveLabels.exitFullscreen
+                : effectiveLabels.enterFullscreen}
+            </button>
+          </div>
+        </div>
+      )}
+
+      {!buildMode && viewData.context.errors.length > 0 && (
+        <div className="mb-4 flex flex-col gap-2">
+          {viewData.context.errors.map((err) => (
+            <div
+              key={err.stepId}
+              className="bg-destructive/10 text-destructive rounded-lg p-3 text-sm"
+            >
+              <strong>{err.stepId}:</strong> {err.reason}
+            </div>
+          ))}
+        </div>
+      )}
+
+      <AppQueryProvider callTool={callToolFn}>
+        {buildMode ? (
+          <LayoutBuilder
+            initialLayout={viewData.layout}
+            title={viewData.title}
+            initialKeys={viewData._refreshParams?.keys}
+            initialSteps={viewData._refreshParams?.steps}
+            widgets={widgets}
+            callTool={callToolFn}
+            onExit={exitBuildMode}
+          />
+        ) : viewData.layout ? (
+          <WidgetRenderer
+            layout={viewData.layout}
+            keys={viewData.context.keys}
+            stepData={viewData.context.stepData}
+            errors={viewData.context.errors}
+            widgets={widgets}
+          />
+        ) : null}
+      </AppQueryProvider>
+    </main>
+  )
+}

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

@@ -0,0 +1,25 @@
+import { McpUseProvider } from "mcp-use/react"
+import { McpAppView, type McpAppViewProps } from "./mcp-app-view.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.
+ *
+ * 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.
+ */
+export function McpToolkitApp(props: McpAppViewProps) {
+  return (
+    <McpUseProvider>
+      <McpAppView {...props} />
+    </McpUseProvider>
+  )
+}

package/src/app/use-host-actions.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest"
+import { buildShowWidgetIntent } from "./use-host-actions.js"
+
+describe("buildShowWidgetIntent", () => {
+  it("appends the tool-name hint in parentheses so the agent can disambiguate", () => {
+    expect(buildShowWidgetIntent("show_process_detail", "Show the process detail for `abc`")).toBe(
+      "Show the process detail for `abc` (use show_process_detail)",
+    )
+  })
+
+  it("keeps the description verbatim ahead of the hint", () => {
+    expect(buildShowWidgetIntent("analytics_show_kpis", "Open the analytics dashboard")).toBe(
+      "Open the analytics dashboard (use analytics_show_kpis)",
+    )
+  })
+})

package/src/app/use-host-actions.tsx

@@ -0,0 +1,88 @@
+import { useCallback } from "react"
+import { useHostBridge } from "./host-bridge.js"
+
+export interface HostActions {
+  /**
+   * Open an external URL in a new browser tab via the host bridge
+   * (`bridge.openLink` / `window.openai.openExternal`). Works inside the
+   * sandboxed iframe where raw `window.open` is blocked. Falls back to
+   * `window.open` only when no MCP host bridge is available (dev preview).
+   */
+  openLink: (url: string) => void
+  /**
+   * Ask the host to render another tool's widget by sending a follow-up
+   * user message into the conversation (`bridge.sendMessage` /
+   * `window.openai.sendFollowUpMessage`). The agent interprets the prompt
+   * and invokes the matching tool, whose widget then appears as the next
+   * chat turn — the proper MCP-Apps pattern for in-widget navigation.
+   *
+   * The prompt should be natural language and include enough hints
+   * (preferably the tool name in parentheses) for the agent to pick the
+   * right tool unambiguously.
+   */
+  showWidget: (prompt: string) => void
+  /**
+   * Hand an open-ended, judgment task to the agent in the conversation
+   * (`sendFollowUpMessage`) — root-cause analysis, "explain this", migration
+   * planning, ticket drafting. Same bridge as {@link HostActions.showWidget}
+   * but a distinct affordance: this crosses the UI→chat boundary deliberately,
+   * for things the deterministic UI cannot do. The prompt should be
+   * self-contained — inline the relevant IDs/keys rather than relying on
+   * ambient ModelContext alone.
+   */
+  askAi: (prompt: string) => void
+}
+
+/**
+ * Builds the natural-language intent string passed to {@link HostActions.showWidget}.
+ * The host agent reads the trailing `(use <toolName>)` hint to pick the right
+ * tool unambiguously. Centralised so every in-widget navigation handoff phrases
+ * the hint identically (and a tool rename only has to flow through the imported
+ * `*_SHOW_*` tool-name constant).
+ *
+ * @example host.showWidget(buildShowWidgetIntent(SHOW_PROCESS_DETAIL, `Show the process detail for \`${key}\``))
+ */
+export function buildShowWidgetIntent(toolName: string, description: string): string {
+  return `${description} (use ${toolName})`
+}
+
+/**
+ * Bridge-aware host actions for widgets. A thin, intent-named facade over
+ * {@link useHostBridge}: `openLink` → `bridge.openExternal`, and both
+ * `showWidget` and `askAi` → `bridge.sendFollowup` (kept as two affordances
+ * because they cross the UI→chat boundary for different reasons — see above).
+ *
+ * Relationship to {@link useHostBridge}: this hook resolves the active bridge
+ * through `useHostBridge()`, so it honours an explicit `HostBridgeProvider`
+ * (ChatGPT / standalone) when one is present, and otherwise falls back to the
+ * default `mcp-use` bridge — exactly the behaviour widgets had before the bridge
+ * abstraction existed, so no existing widget or test breaks. Prefer
+ * `useHostBridge` directly in new portable widgets; `useHostActions` stays for
+ * its named affordances and backward compatibility.
+ */
+export function useHostActions(): HostActions {
+  const bridge = useHostBridge()
+
+  const openLink = useCallback(
+    (url: string) => {
+      bridge.openExternal(url)
+    },
+    [bridge],
+  )
+
+  const showWidget = useCallback(
+    (prompt: string) => {
+      bridge.sendFollowup(prompt)
+    },
+    [bridge],
+  )
+
+  const askAi = useCallback(
+    (prompt: string) => {
+      bridge.sendFollowup(prompt)
+    },
+    [bridge],
+  )
+
+  return { openLink, showWidget, askAi }
+}

package/src/app/widget-fixture.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest"
+import { FixtureCallToolRegistry, buildFixtureWidgetProps } from "./widget-fixture.js"
+
+describe("FixtureCallToolRegistry", () => {
+  it("returns a static value entry wrapped under structuredContent", async () => {
+    const reg = new FixtureCallToolRegistry()
+    reg.register("get_thing", { id: "a", name: "Thing A" })
+
+    const res = await reg.call("get_thing", {})
+
+    expect(res.structuredContent).toEqual({ id: "a", name: "Thing A" })
+    // Mirrored into a text block so mcp-use's text-first decoder also sees it.
+    expect(res.content?.[0]?.text).toContain("Thing A")
+  })
+
+  it("passes a value entry through untouched when it already looks like a tool response", async () => {
+    const reg = new FixtureCallToolRegistry({
+      already_shaped: { structuredContent: { ok: true }, isError: false },
+    })
+
+    const res = await reg.call("already_shaped")
+
+    expect(res).toEqual({ structuredContent: { ok: true }, isError: false })
+  })
+
+  it("invokes a handler entry with the call args and wraps the return value", async () => {
+    const reg = new FixtureCallToolRegistry()
+    reg.register("search", (args: Record<string, unknown>) => ({
+      query: args.q,
+      hits: [String(args.q)],
+    }))
+
+    const res = await reg.call("search", { q: "leasing" })
+
+    expect(res.structuredContent).toEqual({ query: "leasing", hits: ["leasing"] })
+  })
+
+  it("awaits async handler entries", async () => {
+    const reg = new FixtureCallToolRegistry()
+    reg.register("slow", async (args: Record<string, unknown>) => {
+      await Promise.resolve()
+      return { echoed: args.value }
+    })
+
+    const res = await reg.call("slow", { value: 42 })
+
+    expect(res.structuredContent).toEqual({ echoed: 42 })
+  })
+
+  it("wraps a string entry into both structuredContent and a text block", async () => {
+    const reg = new FixtureCallToolRegistry({ greet: "hello" })
+
+    const res = await reg.call("greet")
+
+    expect(res.structuredContent).toBe("hello")
+    expect(res.content?.[0]?.text).toBe("hello")
+  })
+
+  it("rejects unknown tools with a descriptive, name-listing error", async () => {
+    const reg = new FixtureCallToolRegistry({ known: { ok: true } })
+
+    await expect(reg.call("missing")).rejects.toThrow(/No fixture registered for tool "missing"/)
+    await expect(reg.call("missing")).rejects.toThrow(/known/)
+  })
+
+  it("lists registered names and reports membership", () => {
+    const reg = new FixtureCallToolRegistry({ a: 1, b: 2 })
+    reg.register("c", 3)
+
+    expect(reg.has("a")).toBe(true)
+    expect(reg.has("z")).toBe(false)
+    expect(reg.names().sort()).toEqual(["a", "b", "c"])
+  })
+
+  it("overwrites an existing fixture on re-register", async () => {
+    const reg = new FixtureCallToolRegistry({ t: { v: 1 } })
+    reg.register("t", { v: 2 })
+
+    const res = await reg.call("t")
+
+    expect(res.structuredContent).toEqual({ v: 2 })
+  })
+})
+
+describe("buildFixtureWidgetProps", () => {
+  it("uses the fixture data as the keys map and an empty pipeline by default", () => {
+    const data = { "customers:customer": { name: "Acme" } }
+
+    const props = buildFixtureWidgetProps(data)
+
+    expect(props.keys).toBe(data)
+    expect(props.context.keys).toBe(data)
+    expect(props.context.steps).toEqual({})
+    expect(props.context.errors).toEqual([])
+  })
+
+  it("seeds a pipeline step keyed by dataType for adaptDataWidget components", () => {
+    const data = { value: 7 }
+
+    const props = buildFixtureWidgetProps(data, "demo:metric")
+
+    expect(props.context.steps.fixture?._dataType).toBe("demo:metric")
+    expect(props.context.steps.fixture?.data).toBe(data)
+    // The adapter scans steps by _dataType, so a matching step must exist.
+    const match = Object.values(props.context.steps).find((s) => s._dataType === "demo:metric")
+    expect(match?.data).toBe(data)
+  })
+})