@r0hitsharma/webmcp 0.12.0 → 0.13.0-rohit-charting-cursor-fixes.1

package/README.md

@@ -1,9 +1,16 @@
 # @r0hitsharma/webmcp
 
-A stable React wrapper over [WebMCP](https://github.com/webmcp-org) (`@mcp-b/global`) for registering UI tools that a connected agent harness can call. It exposes a fixed interface so the fast-moving `@mcp-b/*` packages can churn behind a single seam.
+A stable React wrapper for registering UI tools that an AI agent can call, over [WebMCP](https://webmachinelearning.github.io/webmcp/) and the [MCP-B](https://docs.mcp-b.ai) polyfill (`@mcp-b/global`). It exposes a fixed interface so the fast-moving `@mcp-b/*` packages can churn behind a single seam.
 
 Tools are registered into `document.modelContext`. A tool registered here runs in the consumer's own authenticated browser session, so it reuses the app's existing auth and APIs rather than requiring separate server credentials.
 
+## Spec and browser status
+
+- **WebMCP** is a draft of the W3C Web Machine Learning Community Group ([spec](https://webmachinelearning.github.io/webmcp/), [repository](https://github.com/webmachinelearning/webmcp)). It defines `document.modelContext.registerTool()`, tool annotations, and an `execute(input, { signal })` callback whose result the browser serializes as JSON. It is not a standard yet and still changes.
+- **Chrome** exposes a native `document.modelContext` through an origin trial (Chrome 149 to 156 at the time of writing). Other browsers do not implement it.
+- **MCP-B** ([docs](https://docs.mcp-b.ai), [source](https://github.com/WebMCP-org/npm-packages)) polyfills `document.modelContext` where it is missing and bridges the registered tools to MCP clients such as the MCP-B browser extension. `WebMCPProvider` installs it.
+- A harness that cannot reach the page directly can call the same tools through the relay back-channel (`useRelaySession`, [`@r0hitsharma/mcp-relay`](../mcp-relay/README.md)).
+
 ## Installation
 
 ```bash
@@ -14,9 +21,12 @@ npm install @r0hitsharma/webmcp react
 
 ## Features
 
-- Schema-first tool definitions (`defineTool`)
+- Schema-first tool definitions (`defineTool`), validated against WebMCP's naming rules
+- WebMCP annotations derived from `mutation`, with per-field overrides
+- Human confirmation for every `mutation: true` call, on every invocation path
+- An abort `signal` for every handler call, fired when the tool unregisters mid-call or the relay disconnects
 - StrictMode-safe registration that mounts/unmounts cleanly
-- A React provider that initializes the WebMCP polyfill and a tool registry
+- A React provider that initializes the polyfill with an explicit, same-origin transport
 - Hooks to register tools, observe the registry, and contribute view state
 - Wire-protocol types shared with the relay back-channel
 
@@ -66,17 +76,98 @@ function IdentityView({ onSelect }: { onSelect: (id: string) => void }) {
 }
 ```
 
+### Tool fields
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `name` | yes | 1-128 characters of `A-Z a-z 0-9 _ . -`; `defineTool` throws otherwise. Chrome suggests 30 or fewer. |
+| `description` | yes | What the tool does, for the agent. `defineTool` warns (once per tool) above 500 characters, Chrome's guidance; keep parameter descriptions under about 150 and results around 1.5K characters. |
+| `schema` | yes | JSON Schema of the input object. |
+| `handler` | yes | `(args, { signal }) => result`. Return plain data and throw on failure (see below). |
+| `title` | no | Human-readable display name. |
+| `annotations` | no | `readOnlyHint`, `consequentialHint`, `untrustedContentHint`. See below. |
+| `outputSchema` | no | JSON Schema of the result object. Forwarded to MCP clients (MCP-B, relay); WebMCP has no output schema. |
+| `mutation` | no | `true` for a tool that changes state: requires confirmation. |
+| `confirmationSummary` | with `mutation` | `(args) => string` shown in the confirmation dialog. |
+
+### Results, errors and cancellation
+
+Return the result as plain data. On `document.modelContext` the browser serializes it as JSON for the agent; the MCP-B bridge and the relay turn it into an MCP result, with an object passed as `structuredContent`. Throw to report a failure: it reaches native agents as a failed call and MCP clients as `isError: true`.
+
+The second handler argument carries an `AbortSignal`. It aborts when the tool is unregistered mid-call (its component unmounts, or the provider re-initializes) and, on the relay path, when the back-channel closes. An agent's own cancellation reaches it only on a browser whose `document.modelContext` passes a per-call signal: the MCP-B polyfill does not (as of 5.1.0), and the relay protocol has no cancel frame. Pass it to `fetch()` and other cancellable work. Handlers that take one argument keep working.
+
+```ts
+defineTool({
+  name: 'orders.search',
+  description: 'Search orders by customer name.',
+  schema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
+  annotations: { untrustedContentHint: true }, // results contain customer-entered text
+  handler: async ({ q }: { q: string }, context) => {
+    const res = await fetch(`/api/orders?q=${encodeURIComponent(q)}`, {
+      signal: context?.signal,
+    });
+    if (!res.ok) throw new Error(`Search failed (HTTP ${res.status}).`);
+    return { orders: await res.json() };
+  },
+});
+```
+
+### Annotations
+
+Tools are registered with WebMCP's hints. `readOnlyHint` and `consequentialHint` come from `mutation` unless set explicitly: a mutation is `consequentialHint: true, readOnlyHint: false`; anything else is `readOnlyHint: true`. `untrustedContentHint` (default `false`) tells the agent the result may contain content the page does not control, so it should not follow instructions in it. WebMCP has no `destructiveHint`; MCP clients see a non-read-only tool as destructive (the relay sets `destructiveHint` from `consequentialHint`).
+
+### Confirming mutations
+
+Every call to a `mutation: true` tool waits for the user's approval, whether it came from a native agent, an MCP-B client, or the relay. The provider owns one queue for all of them. Render a dialog from `useToolConfirmation()` (or from `useRelaySession()`, which returns the same queue):
+
+```tsx
+import { ConfirmToolCallDialog } from '@r0hitsharma/mcp-connect';
+import { useToolConfirmation } from '@r0hitsharma/webmcp';
+
+function Confirmations() {
+  const { pendingConfirmation: p, pendingQueueLength, approve, deny } = useToolConfirmation();
+  return (
+    <ConfirmToolCallDialog
+      pendingCall={p && { callId: p.callId, sessionId: '', toolName: p.toolName, toolArgs: p.argsPreview,
+        summary: p.summary, createdAt: p.createdAt, expiresAt: p.expiresAt, status: 'pending' }}
+      queueLength={pendingQueueLength}
+      onApprove={approve}
+      onDeny={deny}
+    />
+  );
+}
+```
+
+A denied call, or one nobody answers before the window closes (`confirmationWindowSeconds` on the provider, default 50 s, under the MCP SDK's 60 s request timeout; `useRelaySession` uses its own, default 25 s, under the relay's 30 s timeout), fails without running the handler: the agent gets an error (MCP `isError: true`) saying the user declined or did not answer. It is an error rather than a result so it never has to match the tool's `outputSchema`. With no dialog mounted, a mutation call therefore waits out the whole window and is then denied.
+
+### Transport
+
+`@mcp-b/global` starts itself on import and, unconfigured, accepts MCP connections from any origin. This package opts out of that and has `WebMCPProvider` initialize it with an explicit transport: by default the tab transport (used by the MCP-B extension) accepts the page's own origin only, and the iframe transport is off. Configure both with the `transport` prop:
+
+```tsx
+<WebMCPProvider
+  transport={{
+    tabServer: { allowedOrigins: [window.location.origin] },
+    // When the page is embedded, name the embedding origins:
+    iframeServer: { allowedOrigins: ['https://host.example'] },
+  }}
+>
+```
+
+`false` disables a transport. The prop governs the MCP-B bridge only, not a browser's native `document.modelContext`. A host page can still set `window.__webModelContextOptions` before loading this package: the provider applies its `installTestingShim`, and its `transport` when the prop is not set. Only an explicit `autoInitialize: true` keeps @mcp-b/global's import-time start; the host then owns that instance, and the provider neither re-configures nor tears it down (its `transport` prop has no effect).
+
 ## Public surface
 
 - `defineTool` — schema-first tool factory
-- `WebMCPProvider` — provider that initializes the polyfill and registry
+- `WebMCPProvider` — provider that initializes the polyfill (props: `transport`, `confirmationWindowSeconds`, `initPolyfill`) and the registry
 - `useRegisterTool` — register a tool while a component is mounted
 - `useTool` — observe a single tool's spec by name
 - `useToolRegistry` / `useToolRegistryRef` — read the full registry
 - `useContributeViewState` — contribute a partial view-state slice
+- `useToolConfirmation` — drive a mutation-confirmation dialog from the provider's queue
 - `listTools` / `getViewState` — imperative helpers for non-React callers
-- `useRelaySession` — drive the relay back-channel from the registry: mint/reuse a session, advertise the registered tools, run incoming `invoke`s, and gate any `mutation: true` tool behind a local confirmation
-- Tool types (`ToolSpec`, `ToolHandler`, `PendingCallPrompt`, `ViewState`, ...) and the wire-protocol types re-exported from [`@r0hitsharma/mcp-relay`](../mcp-relay/README.md), the single source of truth shared with the Python relay
+- `useRelaySession` — drive the relay back-channel from the registry: mint/reuse a session, advertise the registered tools, run incoming `invoke`s, and gate any `mutation: true` tool behind the shared confirmation queue
+- Tool types (`ToolSpec`, `ToolHandler`, `ToolHandlerContext`, `ToolAnnotations`, `ToolOutputSchema`, `PendingCallPrompt`, `ViewState`, `WebMCPTransportOptions`, ...) and the wire-protocol types re-exported from [`@r0hitsharma/mcp-relay`](../mcp-relay/README.md), their single source of truth
 
 ## Related
 

package/dist/__tests__/fake-context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A minimal spec-shaped `document.modelContext` for unit tests: registerTool
+ * returns a Promise, rejects duplicates, and unregisters on signal abort.
+ */
+export type FakeTool = Record<string, unknown> & {
+    name: string;
+    execute: (input: unknown, options?: {
+        signal?: AbortSignal;
+    }) => unknown;
+};
+export type FakeContext = {
+    tools: Map<string, FakeTool>;
+    calls: FakeTool[];
+    registerTool: (tool: FakeTool, options?: {
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    /** When set, the next registerTool waits for this before settling. */
+    gate?: Promise<void>;
+    /** When set, registerTool rejects with this error. */
+    failWith?: unknown;
+};
+export declare function installFakeContext(): FakeContext;
+export declare function removeFakeContext(): void;
+export declare function flushMicrotasks(): Promise<void>;

package/dist/__tests__/fake-context.js

@@ -0,0 +1,35 @@
+export function installFakeContext() {
+    const ctx = {
+        tools: new Map(),
+        calls: [],
+        async registerTool(tool, options) {
+            ctx.calls.push(tool);
+            if (ctx.gate)
+                await ctx.gate;
+            if (ctx.failWith)
+                throw ctx.failWith;
+            options?.signal?.throwIfAborted();
+            if (ctx.tools.has(tool.name)) {
+                throw new DOMException(`Tool already registered: ${tool.name}`, 'InvalidStateError');
+            }
+            ctx.tools.set(tool.name, tool);
+            options?.signal?.addEventListener('abort', () => {
+                if (ctx.tools.get(tool.name) === tool)
+                    ctx.tools.delete(tool.name);
+            });
+        },
+    };
+    Object.defineProperty(document, 'modelContext', {
+        configurable: true,
+        value: ctx,
+    });
+    return ctx;
+}
+export function removeFakeContext() {
+    Reflect.deleteProperty(document, 'modelContext');
+}
+export async function flushMicrotasks() {
+    for (let i = 0; i < 5; i++)
+        await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 0));
+}

package/dist/__tests__/helpers.d.ts

@@ -0,0 +1,7 @@
+/** Tool names on the bridged `document.modelContext` (MCP-B's `listTools()`). */
+export declare function modelContextToolNames(): string[];
+/** Let deferred unregisters, polyfill syncs and timers settle. */
+export declare function settle(ms?: number): Promise<void>;
+export declare function ReadTool({ name }: {
+    name: string;
+}): null;

package/dist/__tests__/helpers.js

@@ -0,0 +1,24 @@
+import { act } from '@testing-library/react';
+import { useRegisterTool } from '../hooks.js';
+import { defineTool } from '../types.js';
+/** Tool names on the bridged `document.modelContext` (MCP-B's `listTools()`). */
+export function modelContextToolNames() {
+    const ctx = document
+        .modelContext;
+    return ctx?.listTools?.().map((t) => t.name) ?? [];
+}
+/** Let deferred unregisters, polyfill syncs and timers settle. */
+export async function settle(ms = 20) {
+    await act(async () => {
+        await new Promise((r) => setTimeout(r, ms));
+    });
+}
+export function ReadTool({ name }) {
+    useRegisterTool(defineTool({
+        name,
+        description: `Test tool ${name}.`,
+        schema: { type: 'object', properties: {} },
+        handler: () => ({ ok: true }),
+    }));
+    return null;
+}

package/dist/__tests__/relay-harness.d.ts

@@ -0,0 +1,26 @@
+export declare class FakeWebSocket {
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    static instances: FakeWebSocket[];
+    readonly url: string;
+    readyState: number;
+    readonly sent: Array<Record<string, unknown>>;
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: string;
+    }) => void) | null;
+    onerror: (() => void) | null;
+    onclose: (() => void) | null;
+    constructor(url: string);
+    send(data: string): void;
+    close(): void;
+    serverOpen(): Promise<void>;
+    serverSend(frame: Record<string, unknown>): Promise<void>;
+    /** Frames of `type` the browser sent. */
+    framesOf(type: string): Array<Record<string, unknown>>;
+}
+export declare function installRelayFakes(): void;
+/** The socket the hook opened, once it has. */
+export declare function openedSocket(): Promise<FakeWebSocket>;

package/dist/__tests__/relay-harness.js

@@ -0,0 +1,73 @@
+/**
+ * Fakes for driving useRelaySession without a network: a scripted WebSocket
+ * the test plays the relay's side of, and a fetch that mints a session.
+ */
+import { act } from '@testing-library/react';
+import { vi } from 'vitest';
+export class FakeWebSocket {
+    static CONNECTING = 0;
+    static OPEN = 1;
+    static CLOSING = 2;
+    static CLOSED = 3;
+    static instances = [];
+    url;
+    readyState = FakeWebSocket.CONNECTING;
+    sent = [];
+    onopen = null;
+    onmessage = null;
+    onerror = null;
+    onclose = null;
+    constructor(url) {
+        this.url = url;
+        FakeWebSocket.instances.push(this);
+    }
+    send(data) {
+        this.sent.push(JSON.parse(data));
+    }
+    close() {
+        if (this.readyState === FakeWebSocket.CLOSED)
+            return;
+        this.readyState = FakeWebSocket.CLOSED;
+        this.onclose?.();
+    }
+    // --- the relay's side -----------------------------------------------------
+    async serverOpen() {
+        await act(async () => {
+            this.readyState = FakeWebSocket.OPEN;
+            this.onopen?.();
+            this.onmessage?.({
+                data: JSON.stringify({ type: 'hello/accepted', session_id: 's-1' }),
+            });
+        });
+    }
+    async serverSend(frame) {
+        await act(async () => {
+            this.onmessage?.({ data: JSON.stringify(frame) });
+        });
+    }
+    /** Frames of `type` the browser sent. */
+    framesOf(type) {
+        return this.sent.filter((f) => f['type'] === type);
+    }
+}
+export function installRelayFakes() {
+    FakeWebSocket.instances = [];
+    localStorage.clear();
+    vi.stubGlobal('WebSocket', FakeWebSocket);
+    vi.stubGlobal('fetch', vi.fn(async () => ({
+        ok: true,
+        status: 201,
+        json: async () => ({
+            connection_token: 'token-1',
+            ws_url: 'ws://relay.test/ws/sessions/s-1',
+        }),
+    })));
+}
+/** The socket the hook opened, once it has. */
+export async function openedSocket() {
+    await vi.waitFor(() => {
+        if (FakeWebSocket.instances.length === 0)
+            throw new Error('no socket yet');
+    });
+    return FakeWebSocket.instances.at(-1);
+}

package/dist/confirmation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Human-in-the-loop confirmation for `mutation: true` tools.
+ *
+ * One queue per <WebMCPProvider>, shared by every path a tool can be invoked
+ * on (document.modelContext, the MCP-B bridge, the relay back-channel), so a
+ * mutation never runs without the user's approval whichever agent called it,
+ * and one dialog serves them all. Framework-free: React reads it through
+ * useSyncExternalStore.
+ */
+import type { PendingCallPrompt, ToolSpec } from './types.js';
+/**
+ * How a confirmation ended. `cancelled` means the caller went away (its
+ * signal aborted, or the provider unmounted) before the user answered.
+ */
+export type ConfirmationDecision = 'approved' | 'denied' | 'expired' | 'cancelled';
+export interface ConfirmationOptions {
+    /** Seconds before an unanswered prompt expires (and the call is denied). */
+    windowSeconds: number;
+    /** Reuse the caller's id (the relay's call_id); generated when omitted. */
+    callId?: string;
+    /** Aborting it withdraws the prompt with a `cancelled` decision. */
+    signal?: AbortSignal;
+}
+export declare class ConfirmationQueue {
+    private held;
+    private snapshot;
+    private readonly listeners;
+    private counter;
+    /** Queue a prompt for `spec` and resolve once the user (or the clock) decides. */
+    request(spec: Pick<ToolSpec, 'name' | 'confirmationSummary'>, args: Record<string, unknown>, { windowSeconds, callId, signal }: ConfirmationOptions): Promise<ConfirmationDecision>;
+    /** Answer the prompt at the head of the queue. */
+    resolveHead(decision: 'approved' | 'denied'): void;
+    /** Withdraw every prompt (e.g. the provider unmounted). */
+    cancelAll(): void;
+    getSnapshot: () => readonly PendingCallPrompt[];
+    subscribe: (listener: () => void) => (() => void);
+    private publish;
+}
+/**
+ * The error message an agent receives when a mutation was not approved.
+ *
+ * A denial is reported as a failed call (a rejected execute, an MCP
+ * `isError` result), not as a result object: a tool that declares an
+ * `outputSchema` would otherwise hand the agent an object that fails its own
+ * schema, and MCP servers and clients reject that as a broken tool. The
+ * message says the user declined, so an agent can tell it from a bug and does
+ * not retry blindly.
+ */
+export declare function denialMessage(decision: 'denied' | 'expired'): string;
+/** Signature the registration layer uses to ask for approval. */
+export type RequestConfirmation = (spec: Pick<ToolSpec, 'name' | 'confirmationSummary'>, args: Record<string, unknown>, options?: Partial<ConfirmationOptions>) => Promise<ConfirmationDecision>;

package/dist/confirmation.js

@@ -0,0 +1,104 @@
+// setTimeout fires at once for any delay above 2^31 - 1 ms (about 24.8 days).
+const MAX_WINDOW_SECONDS = Math.floor((2 ** 31 - 1) / 1000);
+function isValidWindow(seconds) {
+    return (typeof seconds === 'number' &&
+        Number.isFinite(seconds) &&
+        seconds > 0 &&
+        seconds <= MAX_WINDOW_SECONDS);
+}
+export class ConfirmationQueue {
+    held = [];
+    snapshot = [];
+    listeners = new Set();
+    counter = 0;
+    /** Queue a prompt for `spec` and resolve once the user (or the clock) decides. */
+    request(spec, args, { windowSeconds, callId, signal }) {
+        if (signal?.aborted)
+            return Promise.resolve('cancelled');
+        if (!isValidWindow(windowSeconds)) {
+            // A bad window must not open a prompt that can never expire (or that
+            // expires at once): fail the call and tell the developer why.
+            const error = new RangeError(`[webmcp] confirmationWindowSeconds must be a number of seconds above 0 and at most ${MAX_WINDOW_SECONDS}; got ${String(windowSeconds)}.`);
+            console.error(error.message);
+            return Promise.reject(error);
+        }
+        const id = callId ?? `local-${(this.counter += 1)}`;
+        // A re-delivered call is already on screen; the original prompt answers it.
+        if (this.held.some((h) => h.prompt.callId === id)) {
+            return Promise.resolve('cancelled');
+        }
+        return new Promise((resolve) => {
+            const now = new Date();
+            const prompt = {
+                callId: id,
+                toolName: spec.name,
+                summary: summarize(spec, args),
+                argsPreview: args,
+                createdAt: now.toISOString(),
+                expiresAt: new Date(now.getTime() + windowSeconds * 1000).toISOString(),
+            };
+            let done = false;
+            const onAbort = () => settle('cancelled');
+            const timer = setTimeout(() => settle('expired'), windowSeconds * 1000);
+            const settle = (decision) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                this.held = this.held.filter((h) => h.prompt !== prompt);
+                this.publish();
+                resolve(decision);
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            this.held.push({ prompt, settle });
+            this.publish();
+        });
+    }
+    /** Answer the prompt at the head of the queue. */
+    resolveHead(decision) {
+        this.held[0]?.settle(decision);
+    }
+    /** Withdraw every prompt (e.g. the provider unmounted). */
+    cancelAll() {
+        for (const h of [...this.held])
+            h.settle('cancelled');
+    }
+    getSnapshot = () => this.snapshot;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    publish() {
+        this.snapshot = this.held.map((h) => h.prompt);
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+function summarize(spec, args) {
+    try {
+        return spec.confirmationSummary?.(args) ?? spec.name;
+    }
+    catch {
+        // A throwing summary must not bypass or wedge the gate: fall back to the
+        // tool name so the user can still decide.
+        return spec.name;
+    }
+}
+/**
+ * The error message an agent receives when a mutation was not approved.
+ *
+ * A denial is reported as a failed call (a rejected execute, an MCP
+ * `isError` result), not as a result object: a tool that declares an
+ * `outputSchema` would otherwise hand the agent an object that fails its own
+ * schema, and MCP servers and clients reject that as a broken tool. The
+ * message says the user declined, so an agent can tell it from a bug and does
+ * not retry blindly.
+ */
+export function denialMessage(decision) {
+    return decision === 'expired'
+        ? 'The user did not approve this call before the confirmation request expired; it was not run.'
+        : 'The user denied this call; it was not run.';
+}

package/dist/hooks.d.ts

@@ -5,7 +5,7 @@
  * None of them import @mcp-b/* directly, that coupling lives in provider.tsx.
  */
 import { type DependencyList } from 'react';
-import type { ToolSpec, ViewState } from './types.js';
+import type { PendingCallPrompt, ToolSpec, ViewState } from './types.js';
 /**
  * Register a tool while the calling component is mounted.
  *
@@ -52,6 +52,27 @@ export declare function useRegisterTool<TArgs = Record<string, unknown>, TResult
  * the registration themselves.
  */
 export declare function useTool(toolName: string): ToolSpec | null;
+/** The mutation-confirmation queue, as a confirmation dialog needs it. */
+export interface ToolConfirmation {
+    /** The mutation awaiting approval (head of the queue), or null. */
+    pendingConfirmation: PendingCallPrompt | null;
+    /** Number of mutations waiting (including the active one). */
+    pendingQueueLength: number;
+    /** Approve the active mutation: its handler runs and returns the result. */
+    approve: () => void;
+    /** Deny the active mutation: the agent receives a denial result. */
+    deny: () => void;
+}
+/**
+ * Drive a confirmation dialog (e.g. `ConfirmToolCallDialog` from
+ * `@r0hitsharma/mcp-connect`) from the provider's queue.
+ *
+ * Every call to a `mutation: true` tool waits here for approval, whether it
+ * came through document.modelContext or the relay. Mount a dialog wired to
+ * this hook in any app that registers mutations: with nothing to answer
+ * them, calls are denied when the confirmation window expires.
+ */
+export declare function useToolConfirmation(): ToolConfirmation;
 /**
  * Read-only view of the whole tool registry.
  *

package/dist/hooks.js

@@ -5,7 +5,7 @@
  * All hooks require <WebMCPProvider> in the component tree.
  * None of them import @mcp-b/* directly, that coupling lives in provider.tsx.
  */
-import { useEffect, useMemo, useRef } from 'react';
+import { useEffect, useMemo, useRef, useSyncExternalStore, } from 'react';
 import { useToolRegistryContext } from './provider.js';
 import { acquireToolRegistration } from './registration.js';
 // ---------------------------------------------------------------------------
@@ -73,19 +73,28 @@ export function useRegisterTool(spec, deps) {
         get name() {
             return specRef.current.name;
         },
+        get title() {
+            return specRef.current.title;
+        },
         get description() {
             return specRef.current.description;
         },
         get schema() {
             return specRef.current.schema;
         },
+        get outputSchema() {
+            return specRef.current.outputSchema;
+        },
+        get annotations() {
+            return specRef.current.annotations;
+        },
         get mutation() {
             return specRef.current.mutation;
         },
         get confirmationSummary() {
             return specRef.current.confirmationSummary;
         },
-        handler: (args) => specRef.current.handler(args),
+        handler: (args, context) => specRef.current.handler(args, context),
     }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [spec.name]);
@@ -100,8 +109,11 @@ export function useRegisterTool(spec, deps) {
     // microtask-synced McpServer and throws "Tool <name> is already registered".
     // The manager registers each name once, refcounted, with AbortSignal-based
     // unregister.
+    // Mutations are gated on the provider's confirmation queue (the same one the
+    // relay path uses), so every invocation path needs the user's approval.
+    const requestConfirmation = registry._requestConfirmation;
     useEffect(() => {
-        return acquireToolRegistration(stableSpec);
+        return acquireToolRegistration(stableSpec, { requestConfirmation });
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [spec.name]);
 }
@@ -121,6 +133,25 @@ export function useTool(toolName) {
     const registry = useToolRegistryContext();
     return registry.tools.find((t) => t.name === toolName) ?? null;
 }
+/**
+ * Drive a confirmation dialog (e.g. `ConfirmToolCallDialog` from
+ * `@r0hitsharma/mcp-connect`) from the provider's queue.
+ *
+ * Every call to a `mutation: true` tool waits here for approval, whether it
+ * came through document.modelContext or the relay. Mount a dialog wired to
+ * this hook in any app that registers mutations: with nothing to answer
+ * them, calls are denied when the confirmation window expires.
+ */
+export function useToolConfirmation() {
+    const queue = useToolRegistryContext()._confirmationQueue;
+    const pending = useSyncExternalStore(queue.subscribe, queue.getSnapshot, queue.getSnapshot);
+    return useMemo(() => ({
+        pendingConfirmation: pending[0] ?? null,
+        pendingQueueLength: pending.length,
+        approve: () => queue.resolveHead('approved'),
+        deny: () => queue.resolveHead('denied'),
+    }), [pending, queue]);
+}
 // ---------------------------------------------------------------------------
 // useToolRegistry
 // ---------------------------------------------------------------------------

package/dist/index.d.ts

@@ -11,17 +11,18 @@
  *   - useTool                      observe a single tool's spec by name
  *   - useToolRegistry              read the full registry (listTools / getViewState)
  *   - useContributeViewState       contribute a partial view-state slice
+ *   - useToolConfirmation          drive a mutation-confirmation dialog
  *   - useRelaySession              drive a relay back-channel from the registry
  *   - listTools / getViewState     imperative helpers for non-React callers
  *   - ToolSpec / ViewState / etc.  shared types
  *   - wire-protocol types          re-exported from @r0hitsharma/mcp-relay
  */
 export { defineTool } from './types.js';
-export type { PendingCallPrompt, ToolHandler, ToolRegistry, ToolSpec, ViewState, } from './types.js';
+export type { PendingCallPrompt, ToolAnnotations, ToolHandler, ToolHandlerContext, ToolOutputSchema, ToolRegistry, ToolSpec, ViewState, } from './types.js';
 export { WebMCPProvider } from './provider.js';
-export type { WebMCPProviderProps, ToolRegistryContextValue, } from './provider.js';
-export { useRegisterTool, useTool, useToolRegistry, useContributeViewState, listTools, getViewState, useToolRegistryRef, } from './hooks.js';
-export type { ToolRegistryRef } from './hooks.js';
+export type { WebMCPProviderProps, WebMCPTransportEndpoint, WebMCPTransportOptions, ToolRegistryContextValue, } from './provider.js';
+export { useRegisterTool, useTool, useToolRegistry, useContributeViewState, useToolConfirmation, listTools, getViewState, useToolRegistryRef, } from './hooks.js';
+export type { ToolConfirmation, ToolRegistryRef } from './hooks.js';
 export { useRelaySession } from './useRelaySession.js';
 export type { RelaySessionStatus, UseRelaySessionOptions, UseRelaySessionResult, } from './useRelaySession.js';
 export type { BrowserToServerMessage, ConnectionTokenClaims, CreateSessionResponse, HarnessStatusMessage, HelloAcceptedMessage, HelloMessage, HelloRejectedMessage, InvokeMessage, PingMessage, PongMessage, ResultMessage, ServerToBrowserMessage, ToolActivityMessage, ToolDefinition, ToolInputSchema, ToolsChangedMessage, ToolsListMessage, } from './protocol.js';

package/dist/index.js

@@ -11,6 +11,7 @@
  *   - useTool                      observe a single tool's spec by name
  *   - useToolRegistry              read the full registry (listTools / getViewState)
  *   - useContributeViewState       contribute a partial view-state slice
+ *   - useToolConfirmation          drive a mutation-confirmation dialog
  *   - useRelaySession              drive a relay back-channel from the registry
  *   - listTools / getViewState     imperative helpers for non-React callers
  *   - ToolSpec / ViewState / etc.  shared types
@@ -21,6 +22,6 @@ export { defineTool } from './types.js';
 // Provider
 export { WebMCPProvider } from './provider.js';
 // Hooks
-export { useRegisterTool, useTool, useToolRegistry, useContributeViewState, listTools, getViewState, useToolRegistryRef, } from './hooks.js';
+export { useRegisterTool, useTool, useToolRegistry, useContributeViewState, useToolConfirmation, listTools, getViewState, useToolRegistryRef, } from './hooks.js';
 // Relay session: connects the registry to a relay back-channel.
 export { useRelaySession } from './useRelaySession.js';

package/dist/mcp-b-optout.d.ts

@@ -0,0 +1 @@
+export {};