@miragon/mcp-toolkit-ui 0.10.1

package/src/components/GroupCard.tsx

@@ -0,0 +1,52 @@
+import type { KeyboardEvent, MouseEvent, ReactNode } from "react"
+
+export interface GroupCardProps {
+  /** Whether the body is expanded. */
+  expanded: boolean
+  /** Toggle handler for the summary bar. */
+  onToggle: () => void
+  /** Always-visible summary bar (may contain its own buttons/links). */
+  summary: ReactNode
+  /** Collapsible body, rendered only when `expanded`. */
+  children?: ReactNode
+}
+
+/**
+ * Bordered card with a clickable summary bar and a collapsible body. Use to
+ * group related rows behind an expandable header (e.g. items grouped by a key).
+ *
+ * The summary uses `role="button"` rather than a `<button>` element so it can
+ * contain its own controls (drill buttons, links) without producing invalid
+ * nested-interactive HTML; clicks landing on those controls do not toggle.
+ */
+export function GroupCard({ expanded, onToggle, summary, children }: GroupCardProps) {
+  function handleKeyDown(e: KeyboardEvent<HTMLDivElement>) {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault()
+      onToggle()
+    }
+  }
+
+  function handleClick(e: MouseEvent<HTMLDivElement>) {
+    if ((e.target as HTMLElement).closest("button, a, input, select, textarea, label")) return
+    onToggle()
+  }
+
+  return (
+    <div className="border-border mb-2 overflow-hidden rounded-lg border">
+      <div
+        role="button"
+        tabIndex={0}
+        aria-expanded={expanded}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        className={`bg-card hover:bg-muted focus-visible:ring-ring/50 cursor-pointer transition-colors focus:outline-none focus-visible:ring-2 ${
+          expanded ? "border-border border-b" : ""
+        }`}
+      >
+        {summary}
+      </div>
+      {expanded && children && <div>{children}</div>}
+    </div>
+  )
+}

package/src/components/KpiGrid.tsx

@@ -0,0 +1,134 @@
+import type { ReactNode } from "react"
+import { TONE_TEXT, type ToneVariant } from "../lib/tone-utils.js"
+
+/** Trend direction → tone for the small trend line under a value. */
+const TREND_TONE: Record<"up" | "down" | "flat", string> = {
+  up: "text-danger",
+  down: "text-success",
+  flat: "text-muted-foreground",
+}
+
+export interface KpiCell {
+  /** Caption shown above the value. */
+  label: ReactNode
+  /** The headline figure. Pre-format numbers for locale/currency. */
+  value: ReactNode
+  /** Small fraction shown next to the value, e.g. ` /14`. */
+  fraction?: ReactNode
+  /** Optional trend line under the value (e.g. `"+12% vs last week"`). */
+  trend?: ReactNode
+  /** Colours the trend line. `up` reads as bad (danger), `down` as good (success). */
+  trendDirection?: "up" | "down" | "flat"
+  /** Tone applied to the value text (e.g. `"danger"` for a breached metric). */
+  tone?: ToneVariant
+  /** When set, the cell renders as a button — turns a metric into a nav entry point. */
+  onClick?: () => void
+  /** Accessible label for the clickable cell (recommended when `onClick` is set). */
+  ariaLabel?: string
+}
+
+const COL_CLASS: Record<number, string> = {
+  1: "grid-cols-1",
+  2: "grid-cols-2",
+  3: "grid-cols-3",
+  4: "grid-cols-4",
+  5: "grid-cols-5",
+  6: "grid-cols-6",
+}
+
+export interface KpiGridHeader {
+  /** Group label, rendered uppercase in the strip header. */
+  label: ReactNode
+  /** Optional muted badge to the right of the label. */
+  badge?: ReactNode
+}
+
+export interface KpiGridProps {
+  /** The metric cells, flowed as columns (1–6, clamped). */
+  cells: KpiCell[]
+  /** Wrap the strip in a bordered card with an optional group `header`. Default `false`. */
+  boxed?: boolean
+  /** Group header shown above the strip when `boxed`. */
+  header?: KpiGridHeader
+}
+
+/**
+ * Bordered strip of KPI cells — the canonical way to show a row of headline
+ * metrics in a widget (replaces the single-metric KPICard). Cells flow as
+ * columns (1–6) and can be made clickable to drill into a detail view. Use
+ * `boxed` + `header` for a labelled metric block; unboxed (default) renders the
+ * lighter `border-y` strip.
+ */
+export function KpiGrid({ cells, boxed = false, header }: KpiGridProps) {
+  const cols = Math.min(Math.max(cells.length, 1), 6)
+  const colClass = COL_CLASS[cols] ?? "grid-cols-4"
+  const wrapperClass = boxed ? "border-border overflow-hidden rounded-lg border" : ""
+  const stripClass = boxed ? "" : "border-border border-y"
+  return (
+    <div className={wrapperClass}>
+      {header && (
+        <div className="border-border bg-muted text-muted-foreground flex items-center gap-2 border-b px-4 py-2 text-[11px] font-semibold tracking-wide uppercase">
+          <span>{header.label}</span>
+          {header.badge && (
+            <span className="border-border bg-card text-muted-foreground rounded border px-1.5 py-0 text-[10px] font-medium normal-case">
+              {header.badge}
+            </span>
+          )}
+        </div>
+      )}
+      <div className={`grid ${colClass} ${stripClass}`}>
+        {cells.map((cell, idx) => {
+          const borderClass = idx < cells.length - 1 ? "border-border border-r" : ""
+          const content = (
+            <>
+              <div className="text-muted-foreground flex items-center justify-between gap-2 text-xs font-medium">
+                <span>{cell.label}</span>
+                {cell.onClick && (
+                  <span aria-hidden="true" className="text-sm leading-none">
+                    ›
+                  </span>
+                )}
+              </div>
+              <div
+                className={`mt-1.5 text-2xl leading-none font-bold tracking-tight tabular-nums ${
+                  (cell.tone && TONE_TEXT[cell.tone]) || "text-foreground"
+                }`}
+              >
+                {cell.value}
+                {cell.fraction && (
+                  <span className="text-muted-foreground ml-0.5 text-sm font-normal">
+                    {cell.fraction}
+                  </span>
+                )}
+              </div>
+              {cell.trend && (
+                <div
+                  className={`mt-1.5 text-xs ${
+                    cell.trendDirection ? TREND_TONE[cell.trendDirection] : "text-muted-foreground"
+                  }`}
+                >
+                  {cell.trend}
+                </div>
+              )}
+            </>
+          )
+          return cell.onClick ? (
+            <button
+              key={idx}
+              type="button"
+              onClick={cell.onClick}
+              aria-label={cell.ariaLabel}
+              className={`hover:bg-muted focus-visible:ring-ring cursor-pointer px-5 py-4 text-left transition-colors outline-none focus-visible:ring-2 focus-visible:ring-inset ${borderClass}`}
+            >
+              {content}
+            </button>
+          ) : (
+            <div key={idx} className={`px-5 py-4 ${borderClass}`}>
+              {content}
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}

package/src/components/ListFooter.tsx

@@ -0,0 +1,48 @@
+export interface ListFooterProps {
+  /** How many rows are currently rendered. */
+  shown: number
+  /** The total number of rows available. */
+  total: number
+  /** Whether more rows can be loaded. */
+  hasMore: boolean
+  /** Disables the button and shows a loading label while a fetch is in flight. */
+  loadingMore?: boolean
+  /** Called when the user asks for the next page. */
+  onLoadMore: () => void
+  /** Plural noun for the count, e.g. `"instances"`. Default `"rows"`. */
+  noun?: string
+}
+
+/**
+ * Footer for a paginated list: an honest "Showing X of Y" total plus an
+ * explicit "Load more" control. Deliberately not infinite scroll — the user
+ * gets the total, a reachable footer, and control over fetching. Renders
+ * nothing when `total` is 0.
+ */
+export function ListFooter({
+  shown,
+  total,
+  hasMore,
+  loadingMore = false,
+  onLoadMore,
+  noun = "rows",
+}: ListFooterProps) {
+  if (total <= 0) return null
+  return (
+    <div className="text-muted-foreground flex items-center justify-between gap-3 px-1 py-2 text-xs">
+      <span>
+        Showing {shown.toLocaleString()} of {total.toLocaleString()} {noun}
+      </span>
+      {hasMore && (
+        <button
+          type="button"
+          onClick={onLoadMore}
+          disabled={loadingMore}
+          className="border-border text-foreground hover:bg-muted focus-visible:ring-ring inline-flex items-center gap-1 rounded-md border px-3 py-1.5 font-medium outline-none focus-visible:ring-2 disabled:opacity-50"
+        >
+          {loadingMore ? "Loading…" : "Load more"}
+        </button>
+      )}
+    </div>
+  )
+}

package/src/components/Pills.tsx

@@ -0,0 +1,45 @@
+import type { ReactNode } from "react"
+import { TONE_DOT, TONE_SOFT, type ToneVariant } from "../lib/tone-utils.js"
+
+export interface LivePillProps {
+  /** Status tone driving the dot + tint. Default `"info"`. */
+  tone?: ToneVariant
+  /** Pill label. Defaults to `"Live"`. */
+  children?: ReactNode
+}
+
+/**
+ * Small tinted pill with a pulsing dot. Use in a widget header to signal that
+ * the data is live/real-time. Tone-based, so it inherits the active theme.
+ */
+export function LivePill({ tone = "info", children }: LivePillProps) {
+  return (
+    <span
+      className={`inline-flex items-center gap-1.5 rounded-md px-2 py-0.5 text-xs font-semibold ${TONE_SOFT[tone]}`}
+    >
+      <span className={`size-1.5 animate-pulse rounded-full ${TONE_DOT[tone]}`} />
+      {children ?? "Live"}
+    </span>
+  )
+}
+
+export interface CountPillProps {
+  /** Status tone driving the tint. Default `"neutral"`. */
+  tone?: ToneVariant
+  /** The count/value to display (tabular numbers). */
+  children: ReactNode
+}
+
+/**
+ * Compact count badge — tabular numbers on a tinted background. Use as the
+ * right-aligned indicator on a list/group row (e.g. a per-group item count).
+ */
+export function CountPill({ tone = "neutral", children }: CountPillProps) {
+  return (
+    <span
+      className={`inline-flex min-w-[2.5rem] items-center justify-center rounded-md px-2.5 py-0.5 text-sm font-semibold tabular-nums ${TONE_SOFT[tone]}`}
+    >
+      {children}
+    </span>
+  )
+}

package/src/components/SectionHeading.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react"
+
+export interface SectionHeadingProps {
+  /** The section title. */
+  title: ReactNode
+  /** Optional muted hint shown on the right (e.g. a count or last-updated note). */
+  hint?: ReactNode
+  /** Right-aligned slot that overrides `hint` when set (e.g. a control). */
+  trailing?: ReactNode
+}
+
+/**
+ * Section title row — a small semibold heading with an optional muted hint or
+ * control on the right. Use to label a block inside a widget body (e.g. a list
+ * or sub-table) without the visual weight of a full card header.
+ */
+export function SectionHeading({ title, hint, trailing }: SectionHeadingProps) {
+  return (
+    <div className="text-muted-foreground mb-3 flex items-center justify-between text-sm font-semibold">
+      <span>{title}</span>
+      {(hint || trailing) && (
+        <span className="text-muted-foreground text-xs font-medium">{trailing ?? hint}</span>
+      )}
+    </div>
+  )
+}

package/src/components/WidgetHeader.tsx

@@ -0,0 +1,51 @@
+import type { ReactNode } from "react"
+import { TONE_SOFT, type ToneVariant } from "../lib/tone-utils.js"
+
+export interface WidgetHeaderProps {
+  /** Optional icon/glyph rendered in a tinted tile above the title. */
+  icon?: ReactNode
+  /** Tone for the icon tile. Default `"neutral"`. */
+  iconTone?: ToneVariant
+  /** The widget title. */
+  title: ReactNode
+  /** Subtitle/meta row under the title (e.g. a live pill + counts). */
+  sub?: ReactNode
+  /** Right-aligned actions slot (buttons, drill controls). */
+  actions?: ReactNode
+}
+
+/**
+ * Page-level header for the top of a dashboard widget: an optional tinted icon
+ * tile, a large title, a subtitle/meta row, and a right-aligned actions slot.
+ * Use once per widget surface to anchor it.
+ */
+export function WidgetHeader({
+  icon,
+  iconTone = "neutral",
+  title,
+  sub,
+  actions,
+}: WidgetHeaderProps) {
+  return (
+    <header className="flex flex-wrap items-start justify-between gap-4">
+      <div className="min-w-0">
+        {icon && (
+          <div
+            className={`mb-3.5 grid size-11 place-items-center rounded-xl text-xl ${TONE_SOFT[iconTone]}`}
+          >
+            {icon}
+          </div>
+        )}
+        <h1 className="text-foreground mb-1.5 text-3xl leading-tight font-bold tracking-tight">
+          {title}
+        </h1>
+        {sub && (
+          <div className="text-muted-foreground flex flex-wrap items-center gap-2 text-sm">
+            {sub}
+          </div>
+        )}
+      </div>
+      {actions && <div className="flex flex-wrap items-center gap-2">{actions}</div>}
+    </header>
+  )
+}

package/src/globals.css

@@ -0,0 +1,168 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@fontsource-variable/geist";
+
+@source "../**/*.{ts,tsx}";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --font-heading: var(--font-sans);
+  --font-sans: "Geist Variable", sans-serif;
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --color-foreground: var(--foreground);
+  --color-background: var(--background);
+  /* Semantic status tones — the token surface behind ToneVariant/TONE_* maps.
+     Each tone exposes a readable foreground (`text-danger`) and a tinted
+     surface (`bg-danger-soft`); both carry light + dark values so tone-based
+     components (Pills, KpiGrid, WidgetHeader, FilterBar) re-theme automatically. */
+  --color-danger: var(--danger);
+  --color-danger-soft: var(--danger-soft);
+  --color-warning: var(--warning);
+  --color-warning-soft: var(--warning-soft);
+  --color-success: var(--success);
+  --color-success-soft: var(--success-soft);
+  --color-info: var(--info);
+  --color-info-soft: var(--info-soft);
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.87 0 0);
+  --chart-2: oklch(0.556 0 0);
+  --chart-3: oklch(0.439 0 0);
+  --chart-4: oklch(0.371 0 0);
+  --chart-5: oklch(0.269 0 0);
+  --radius: 0.625rem;
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+  /* Semantic status tones (light). Foreground = readable on a card; *-soft =
+     a tinted surface for badges/dots/icon tiles. Neutral tone reuses the
+     muted ramp and needs no dedicated token. */
+  --danger: oklch(0.55 0.21 27.3);
+  --danger-soft: oklch(0.95 0.04 27.3);
+  --warning: oklch(0.62 0.16 70);
+  --warning-soft: oklch(0.95 0.05 80);
+  --success: oklch(0.58 0.15 152);
+  --success-soft: oklch(0.95 0.05 152);
+  --info: oklch(0.55 0.2 255);
+  --info-soft: oklch(0.95 0.04 255);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.87 0 0);
+  --chart-2: oklch(0.556 0 0);
+  --chart-3: oklch(0.439 0 0);
+  --chart-4: oklch(0.371 0 0);
+  --chart-5: oklch(0.269 0 0);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+  /* Semantic status tones (dark). Brighter foregrounds for contrast on the
+     dark surface; *-soft is a low-alpha tint of the same hue. */
+  --danger: oklch(0.7 0.19 22.2);
+  --danger-soft: oklch(0.7 0.19 22.2 / 18%);
+  --warning: oklch(0.78 0.15 75);
+  --warning-soft: oklch(0.78 0.15 75 / 18%);
+  --success: oklch(0.72 0.17 152);
+  --success-soft: oklch(0.72 0.17 152 / 18%);
+  --info: oklch(0.7 0.16 255);
+  --info-soft: oklch(0.7 0.16 255 / 18%);
+}
+
+* {
+  font-family: "Geist Variable", ui-sans-serif, system-ui, sans-serif !important;
+}
+
+@layer base {
+  *,
+  *::before,
+  *::after {
+    @apply border-border outline-ring/50;
+  }
+  html,
+  body {
+    @apply bg-background text-foreground;
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,17 @@
+export { useIsMobile } from "./use-mobile.js"
+export { useDebouncedValue } from "./use-debounced-value.js"
+export { useToolQuery, useToolMutation } from "./use-tool-query.js"
+export type { UseToolQueryOptions } from "./use-tool-query.js"
+export { useViewToolQuery } from "./use-view-tool-query.js"
+export type { UseViewToolQueryOptions } from "./use-view-tool-query.js"
+export { useViewData } from "./use-view-data.js"
+export type { ViewDataResult } from "./use-view-data.js"
+export {
+  useToolResultRecovery,
+  resolveRecoveryToolName,
+  decodeRecoveredResult,
+} from "./use-tool-result-recovery.js"
+export type {
+  ToolResultRecoveryOptions,
+  ToolResultRecoveryState,
+} from "./use-tool-result-recovery.js"

package/src/hooks/use-debounced-value.ts

@@ -0,0 +1,15 @@
+import { useEffect, useState } from "react"
+
+/**
+ * Returns `value` delayed by `delayMs`, resetting the timer on every change.
+ * Use to debounce a search box so a server-side filter only re-queries once the
+ * user pauses typing (not on every keystroke). Pure React — no host dependency.
+ */
+export function useDebouncedValue<T>(value: T, delayMs = 300): T {
+  const [debounced, setDebounced] = useState(value)
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delayMs)
+    return () => clearTimeout(id)
+  }, [value, delayMs])
+  return debounced
+}

package/src/hooks/use-mobile.ts

@@ -0,0 +1,24 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+/**
+ * Tracks whether the viewport is below the mobile breakpoint (768px), updating
+ * on resize. Use to switch a widget between a compact and a wide layout.
+ */
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(() =>
+    typeof window === "undefined" ? undefined : window.innerWidth < MOBILE_BREAKPOINT,
+  )
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}

package/src/hooks/use-tool-query.ts

@@ -0,0 +1,63 @@
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
+import { useCallTool } from "../providers/query-provider.js"
+import { parseToolResult } from "../lib/parse-tool-result.js"
+
+export interface UseToolQueryOptions<TData = unknown, TSelected = TData> {
+  enabled?: boolean
+  select?: (data: TData) => TSelected
+}
+
+/**
+ * Loads data from a widget tool via TanStack Query.
+ *
+ * `args` is appended to the effective query key so two callers that share
+ * the supplied `queryKey` but pass different `args` get separate cache
+ * entries (otherwise the second caller silently reads stale data from the
+ * first — the classic queryKey-vs-args trap). `select` transforms data on
+ * each read without mutating the cache.
+ */
+export function useToolQuery<TData = unknown, TSelected = TData>(
+  queryKey: unknown[],
+  toolName: string,
+  args: object,
+  opts?: UseToolQueryOptions<TData, TSelected>,
+) {
+  const callTool = useCallTool()
+
+  return useQuery<TData, Error, TSelected>({
+    queryKey: [...queryKey, args],
+    queryFn: async () => {
+      if (!callTool) throw new Error("callTool not available")
+      const result = await callTool(toolName, args)
+      return parseToolResult<TData>(result)
+    },
+    select: opts?.select,
+    enabled: !!callTool && (opts?.enabled ?? true),
+  })
+}
+
+/**
+ * Executes a mutation via a widget tool and invalidates configured query keys.
+ */
+export function useToolMutation<TData = unknown>(
+  toolName: string,
+  opts?: { invalidateKeys?: unknown[][] },
+) {
+  const callTool = useCallTool()
+  const queryClient = useQueryClient()
+
+  return useMutation<TData, Error, Record<string, unknown>>({
+    mutationFn: async (args: Record<string, unknown>) => {
+      if (!callTool) throw new Error("callTool not available")
+      const result = await callTool(toolName, args)
+      return parseToolResult<TData>(result)
+    },
+    onSuccess: async () => {
+      if (opts?.invalidateKeys) {
+        await Promise.all(
+          opts.invalidateKeys.map((key) => queryClient.refetchQueries({ queryKey: key })),
+        )
+      }
+    },
+  })
+}