@r0hitsharma/webmcp 0.12.0-rohit-fork-ci.1

package/dist/registration.d.ts

@@ -0,0 +1,24 @@
+/**
+ * StrictMode-safe tool registration against the WebMCP polyfill.
+ *
+ * Why this exists: the pinned `@mcp-b` polyfill bridges `document.modelContext`
+ * (a Map with AbortSignal-based unregister) to an underlying McpServer whose
+ * `_registeredTools` is synced via `queueMicrotask`. React StrictMode mounts
+ * effects mount -> unmount -> mount synchronously, which races that microtask
+ * sync and makes the McpServer throw `Tool <name> is already registered`,
+ * crashing the app in dev. (This is the kind of @mcp-b churn the wrapper is
+ * meant to absorb; see decision 8 / the plan's section 8.)
+ *
+ * The fix: register each tool name exactly once, refcounted. A transient
+ * unmount/remount in the same tick re-acquires the existing registration
+ * instead of abort+re-add, so the polyfill never sees a duplicate. The real
+ * unregister (signal abort) only fires once the last holder is gone, deferred
+ * to a microtask so a StrictMode remount can cancel it.
+ */
+import type { ToolSpec } from './types.js';
+/**
+ * Acquire a registration for `spec`. Returns a release function to call on
+ * unmount. Idempotent per tool name: concurrent holders share one underlying
+ * polyfill registration.
+ */
+export declare function acquireToolRegistration(spec: ToolSpec): () => void;

package/dist/registration.js

@@ -0,0 +1,92 @@
+const REGISTRY = new Map();
+/** Resolve the polyfilled model context, preferring the current draft location. */
+function getModelContext() {
+    if (typeof window === 'undefined')
+        return undefined;
+    const doc = window.document;
+    const nav = window.navigator;
+    return doc?.modelContext ?? nav?.modelContext;
+}
+function stringify(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+}
+/**
+ * Acquire a registration for `spec`. Returns a release function to call on
+ * unmount. Idempotent per tool name: concurrent holders share one underlying
+ * polyfill registration.
+ */
+export function acquireToolRegistration(spec) {
+    const existing = REGISTRY.get(spec.name);
+    if (existing) {
+        existing.count += 1;
+        existing.spec = spec; // keep the freshest handler/description
+        return makeRelease(spec.name);
+    }
+    const controller = new AbortController();
+    const entry = { count: 1, controller, spec };
+    REGISTRY.set(spec.name, entry);
+    const modelContext = getModelContext();
+    if (!modelContext) {
+        // No polyfill (SSR / unsupported browser): keep the refcount bookkeeping so
+        // listTools()-style local state still balances, but skip the global call.
+        return makeRelease(spec.name);
+    }
+    const execute = async (args) => {
+        try {
+            // Read the latest spec so deps-driven handler updates take effect without
+            // re-registering against the polyfill.
+            const current = REGISTRY.get(spec.name)?.spec ?? spec;
+            const result = await current.handler(args);
+            return { content: [{ type: 'text', text: stringify(result) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    };
+    try {
+        modelContext.registerTool({
+            name: spec.name,
+            description: spec.description,
+            inputSchema: spec.schema,
+            ...(spec.mutation ? { annotations: { destructiveHint: true } } : {}),
+            execute,
+        }, { signal: controller.signal });
+    }
+    catch (error) {
+        // Defensive: if the polyfill still reports a duplicate (e.g. a stale
+        // registration from a prior race), treat it as already-present rather than
+        // crashing the app. The existing registration stays usable.
+        if (!/already registered/i.test(String(error))) {
+            REGISTRY.delete(spec.name);
+            throw error;
+        }
+    }
+    return makeRelease(spec.name);
+}
+function makeRelease(name) {
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        const entry = REGISTRY.get(name);
+        if (!entry)
+            return;
+        entry.count -= 1;
+        if (entry.count > 0)
+            return;
+        // Defer the abort so a StrictMode remount in the same tick can re-acquire
+        // (bumping count back above zero) and cancel the teardown.
+        queueMicrotask(() => {
+            const current = REGISTRY.get(name);
+            if (current && current.count === 0) {
+                current.controller.abort();
+                REGISTRY.delete(name);
+            }
+        });
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Tool-definition contract for @r0hitsharma/webmcp.
+ *
+ * Mirrors the Python ToolSpec / define_tool idiom in the relay core
+ * (schema-first authoring shape).
+ *
+ * Usage:
+ *
+ *   import { defineTool } from '@r0hitsharma/webmcp';
+ *
+ *   const selectIdentity = defineTool({
+ *     name: 'explorer.selectIdentity',
+ *     description: 'Select and focus an identity node in the Explorer.',
+ *     schema: {
+ *       type: 'object',
+ *       properties: { identityId: { type: 'string' } },
+ *       required: ['identityId'],
+ *     },
+ *     handler: async ({ identityId }) => { ... },
+ *   });
+ */
+import type { ToolInputSchema } from './protocol.js';
+export type ToolHandler<TArgs = Record<string, unknown>, TResult = unknown> = (args: TArgs) => Promise<TResult> | TResult;
+export interface ToolSpec<TArgs = Record<string, unknown>, TResult = unknown> {
+    /** Namespaced tool name, e.g. "explorer.selectIdentity". */
+    name: string;
+    description: string;
+    schema: ToolInputSchema;
+    handler: ToolHandler<TArgs, TResult>;
+    /** True for any tool that mutates state. Triggers human-in-the-loop confirmation. */
+    mutation?: boolean;
+    /**
+     * Returns a one-sentence plain-English summary shown in the confirmation dialog.
+     * Required when mutation is true.
+     */
+    confirmationSummary?: (args: TArgs) => string;
+}
+/**
+ * Define a tool using the schema-first idiom.
+ *
+ * This is a pass-through factory; the returned value is the same object.
+ * It exists to provide type inference on the handler args and to make tool
+ * definitions self-documenting at the call site.
+ */
+export declare function defineTool<TArgs = Record<string, unknown>, TResult = unknown>(spec: ToolSpec<TArgs, TResult>): ToolSpec<TArgs, TResult>;
+export interface ViewState {
+    selectedIdentityId?: string;
+    selectedContentUuid?: string;
+    selectedBranch?: string;
+    mode?: string;
+    [key: string]: unknown;
+}
+export interface ToolRegistry {
+    registerTool: <TArgs = Record<string, unknown>, TResult = unknown>(spec: ToolSpec<TArgs, TResult>) => () => void;
+    listTools: () => ToolSpec[];
+    getViewState: () => ViewState;
+}
+/**
+ * A mutation awaiting approval, as the browser-side UI needs to render it.
+ *
+ * Named `PendingCallPrompt` (not `PendingCall`) to avoid colliding with
+ * `@r0hitsharma/mcp-connect`'s richer `PendingCallRecord`, which carries
+ * lifecycle status. This shape is the minimal prompt: what the dialog displays.
+ */
+export interface PendingCallPrompt {
+    callId: string;
+    toolName: string;
+    summary: string;
+    argsPreview: Record<string, unknown>;
+    /** ISO-8601 timestamp when the prompt was raised (for the countdown bar). */
+    createdAt: string;
+    expiresAt: string;
+}

package/dist/types.js

@@ -0,0 +1,37 @@
+/**
+ * Tool-definition contract for @r0hitsharma/webmcp.
+ *
+ * Mirrors the Python ToolSpec / define_tool idiom in the relay core
+ * (schema-first authoring shape).
+ *
+ * Usage:
+ *
+ *   import { defineTool } from '@r0hitsharma/webmcp';
+ *
+ *   const selectIdentity = defineTool({
+ *     name: 'explorer.selectIdentity',
+ *     description: 'Select and focus an identity node in the Explorer.',
+ *     schema: {
+ *       type: 'object',
+ *       properties: { identityId: { type: 'string' } },
+ *       required: ['identityId'],
+ *     },
+ *     handler: async ({ identityId }) => { ... },
+ *   });
+ */
+/**
+ * Define a tool using the schema-first idiom.
+ *
+ * This is a pass-through factory; the returned value is the same object.
+ * It exists to provide type inference on the handler args and to make tool
+ * definitions self-documenting at the call site.
+ */
+export function defineTool(spec) {
+    // Enforce the cross-field invariant the type system can't express cleanly:
+    // a mutation must carry a confirmationSummary, otherwise the human-in-the-loop
+    // dialog would have nothing to show. Fail loudly at authoring time.
+    if (spec.mutation && !spec.confirmationSummary) {
+        throw new Error(`defineTool("${spec.name}"): a tool with mutation:true must provide a confirmationSummary.`);
+    }
+    return spec;
+}

package/dist/useRelaySession.d.ts

@@ -0,0 +1,30 @@
+import type { PendingCallPrompt } from './types.js';
+/** Connection state surfaced to the connect UI (mirrors the indicator states). */
+export type RelaySessionStatus = 'disconnected' | 'ready' | 'connected' | 'reconnecting';
+export interface UseRelaySessionOptions {
+    /** Base URL of the relay Worker, e.g. https://mcp-relay.example.workers.dev */
+    relayBaseUrl: string;
+    /** localStorage key for persisting the session across reloads. */
+    storageKey: string;
+    /** Human-readable title sent in the `hello` frame. */
+    title?: string;
+    /** Seconds a mutation confirmation stays open before it self-expires.
+     *  Kept under the relay's invoke timeout so a late approval is not wasted. */
+    confirmationWindowSeconds?: number;
+}
+export interface UseRelaySessionResult {
+    status: RelaySessionStatus;
+    /** Durable token the user pastes into their harness config; null until minted. */
+    connectionToken: string | null;
+    /** Most-recent-first activity log lines, capped. */
+    activity: string[];
+    /** 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: run its handler and return the result. */
+    approve: () => void;
+    /** Deny the active mutation: return a denial result to the harness. */
+    deny: () => void;
+}
+export declare function useRelaySession({ relayBaseUrl, storageKey, title, confirmationWindowSeconds, }: UseRelaySessionOptions): UseRelaySessionResult;

package/dist/useRelaySession.js

@@ -0,0 +1,317 @@
+/**
+ * useRelaySession
+ *
+ * Drives a relay back-channel from the browser using the tools registered via
+ * `useRegisterTool`. This is the piece that lets a connected harness actually
+ * call the page's tools:
+ *
+ *   - mints (or reuses) a session against the relay Worker and keeps the
+ *     WebSocket open, reconnecting with exponential backoff;
+ *   - advertises the registered tools (`tools/list`) and re-advertises when the
+ *     registry changes;
+ *   - on `invoke`, runs the registered tool's handler and returns a `result`;
+ *   - gates any tool declared `mutation: true` behind a local confirmation: the
+ *     invoke is held until the user approves (handler runs, result returned) or
+ *     denies (a denial result is returned). The relay stays a dumb pipe — no
+ *     confirmation frames cross the wire.
+ *
+ * Must be called inside <WebMCPProvider>.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useToolRegistryContext } from './provider.js';
+function toWireTool(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        input_schema: spec.schema,
+        ...(spec.mutation ? { mutation: true } : {}),
+    };
+}
+export function useRelaySession({ relayBaseUrl, storageKey, title = 'webmcp relay session', confirmationWindowSeconds = 25, }) {
+    const registry = useToolRegistryContext();
+    const [status, setStatus] = useState('disconnected');
+    const [connectionToken, setConnectionToken] = useState(null);
+    const [activity, setActivity] = useState([]);
+    const [pendingQueue, setPendingQueue] = useState([]);
+    const wsRef = useRef(null);
+    const acceptedRef = useRef(false);
+    // Invokes held awaiting a confirmation decision, keyed by call_id.
+    const heldRef = useRef(new Map());
+    // Always read the freshest registry accessor from the WS handler. Synced
+    // in an effect, not during render: refs are read-only during render.
+    const listToolsRef = useRef(registry.listTools);
+    useEffect(() => {
+        listToolsRef.current = registry.listTools;
+    });
+    const log = useCallback((line) => {
+        setActivity((prev) => [`${new Date().toLocaleTimeString()}  ${line}`, ...prev].slice(0, 50));
+    }, []);
+    const send = useCallback((frame) => {
+        const ws = wsRef.current;
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(frame));
+        }
+    }, []);
+    const advertiseTools = useCallback(() => {
+        send({
+            type: 'tools/list',
+            tools: listToolsRef.current().map(toWireTool),
+        });
+    }, [send]);
+    // Run a (non-mutation, or already-approved) tool and return its result frame.
+    const runAndRespond = useCallback(async (callId, spec, args) => {
+        let result;
+        try {
+            result = await spec.handler(args);
+        }
+        catch (err) {
+            result = { error: err.message };
+        }
+        send({ type: 'result', call_id: callId, result });
+        log(`-> ${JSON.stringify(result).slice(0, 160)}`);
+    }, [send, log]);
+    const resolveHead = useCallback((decision) => {
+        setPendingQueue((prev) => {
+            const head = prev[0];
+            if (!head)
+                return prev;
+            const held = heldRef.current.get(head.callId);
+            heldRef.current.delete(head.callId);
+            if (held) {
+                if (decision === 'approved') {
+                    log(`approved ${held.spec.name}`);
+                    void runAndRespond(head.callId, held.spec, held.args);
+                }
+                else {
+                    log(`denied ${held.spec.name}`);
+                    send({
+                        type: 'result',
+                        call_id: head.callId,
+                        result: { denied: true, message: 'The user denied this call.' },
+                    });
+                }
+            }
+            return prev.slice(1);
+        });
+    }, [log, runAndRespond, send]);
+    const approve = useCallback(() => resolveHead('approved'), [resolveHead]);
+    const deny = useCallback(() => resolveHead('denied'), [resolveHead]);
+    // Connect + keep the back-channel open, reconnecting with backoff.
+    useEffect(() => {
+        let closed = false;
+        let attempt = 0;
+        let reconnectTimer;
+        function loadStored() {
+            try {
+                const raw = localStorage.getItem(storageKey);
+                if (!raw)
+                    return null;
+                const s = JSON.parse(raw);
+                if (!s.connection_token || !s.ws_url)
+                    return null;
+                if (s.expires && Date.now() > s.expires)
+                    return null;
+                return s;
+            }
+            catch {
+                return null;
+            }
+        }
+        async function mintSession() {
+            const res = await fetch(`${relayBaseUrl}/api/sessions`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: '{}',
+            });
+            // A 4xx/5xx body is the Worker's { error } shape, not a session: surface
+            // it instead of connecting to ws_url=undefined.
+            if (!res.ok) {
+                log(`Session mint failed (HTTP ${res.status}); will retry.`);
+                return null;
+            }
+            const minted = (await res.json());
+            if (!minted.connection_token || !minted.ws_url) {
+                log('Session mint returned an unexpected response; will retry.');
+                return null;
+            }
+            // Re-mint shortly before the 12h connection-token TTL.
+            const stored = {
+                connection_token: minted.connection_token,
+                ws_url: minted.ws_url,
+                expires: Date.now() + 11 * 60 * 60 * 1000,
+            };
+            try {
+                localStorage.setItem(storageKey, JSON.stringify(stored));
+            }
+            catch {
+                /* storage disabled/full: fall back to an in-memory session */
+            }
+            log('Minted a new session (saved for reuse across reloads).');
+            return stored;
+        }
+        function scheduleReconnect() {
+            if (closed)
+                return;
+            attempt += 1;
+            const delay = Math.min(30_000, 1000 * 2 ** (attempt - 1));
+            setStatus('reconnecting');
+            log(`Reconnecting in ${Math.round(delay / 1000)}s (attempt ${attempt}).`);
+            reconnectTimer = setTimeout(() => void connect(), delay);
+        }
+        function handleInvoke(callId, toolName, args) {
+            log(`invoke ${toolName}(${JSON.stringify(args)})`);
+            const spec = listToolsRef.current().find((t) => t.name === toolName);
+            if (!spec) {
+                send({
+                    type: 'result',
+                    call_id: callId,
+                    result: { error: `Unknown tool: ${toolName}` },
+                });
+                return;
+            }
+            if (!spec.mutation) {
+                void runAndRespond(callId, spec, args);
+                return;
+            }
+            // Mutation: hold the invoke and surface a confirmation prompt.
+            const now = new Date();
+            const prompt = {
+                callId,
+                toolName,
+                summary: spec.confirmationSummary?.(args) ?? toolName,
+                argsPreview: args,
+                createdAt: now.toISOString(),
+                expiresAt: new Date(now.getTime() + confirmationWindowSeconds * 1000).toISOString(),
+            };
+            heldRef.current.set(callId, { prompt, spec, args });
+            setPendingQueue((prev) => prev.some((p) => p.callId === callId) ? prev : [...prev, prompt]);
+            log(`awaiting confirmation for ${toolName}`);
+            // Self-expire so a never-answered prompt does not wedge the dialog.
+            setTimeout(() => {
+                if (!heldRef.current.has(callId))
+                    return;
+                heldRef.current.delete(callId);
+                setPendingQueue((prev) => prev.filter((p) => p.callId !== callId));
+                log(`confirmation for ${toolName} expired`);
+            }, confirmationWindowSeconds * 1000);
+        }
+        async function connect() {
+            try {
+                acceptedRef.current = false;
+                let stored = loadStored();
+                if (stored) {
+                    log('Reusing the saved session (token is stable across reloads).');
+                }
+                else {
+                    stored = await mintSession();
+                    if (!stored) {
+                        scheduleReconnect();
+                        return;
+                    }
+                }
+                if (closed)
+                    return;
+                setConnectionToken(stored.connection_token);
+                setStatus('ready');
+                const session = stored;
+                const ws = new WebSocket(session.ws_url);
+                wsRef.current = ws;
+                ws.onopen = () => {
+                    ws.send(JSON.stringify({
+                        type: 'hello',
+                        tab_id: crypto.randomUUID(),
+                        origin: location.origin,
+                        url: location.href,
+                        title,
+                        connection_token: session.connection_token,
+                    }));
+                };
+                ws.onmessage = (event) => {
+                    let msg;
+                    try {
+                        msg = JSON.parse(event.data);
+                    }
+                    catch {
+                        log('Ignored a malformed frame from the relay.');
+                        return;
+                    }
+                    switch (msg['type']) {
+                        case 'hello/accepted':
+                            attempt = 0; // back-channel established: reset backoff
+                            acceptedRef.current = true;
+                            log('Back-channel connected; advertising tools.');
+                            advertiseTools();
+                            break;
+                        case 'hello/rejected':
+                            // Stale/invalid token: drop the saved session so the next
+                            // reconnect mints a fresh one rather than looping on a bad token.
+                            log('Session rejected by relay; clearing it and re-pairing.');
+                            try {
+                                localStorage.removeItem(storageKey);
+                            }
+                            catch {
+                                /* storage disabled: nothing to clear */
+                            }
+                            break;
+                        case 'harness_status':
+                            setStatus(msg['attached'] ? 'connected' : 'ready');
+                            break;
+                        case 'invoke':
+                            handleInvoke(msg['call_id'], msg['tool_name'] ?? '', msg['args'] ?? {});
+                            break;
+                        case 'ping':
+                            send({ type: 'pong' });
+                            break;
+                        default:
+                            break;
+                    }
+                };
+                ws.onerror = () => {
+                    log('WebSocket error; the connection will be retried.');
+                };
+                ws.onclose = () => {
+                    acceptedRef.current = false;
+                    if (!closed)
+                        scheduleReconnect();
+                };
+            }
+            catch (err) {
+                log(`Error: ${err.message}`);
+                scheduleReconnect();
+            }
+        }
+        void connect();
+        return () => {
+            closed = true;
+            if (reconnectTimer)
+                clearTimeout(reconnectTimer);
+            wsRef.current?.close();
+        };
+    }, [
+        relayBaseUrl,
+        storageKey,
+        title,
+        confirmationWindowSeconds,
+        log,
+        send,
+        advertiseTools,
+        runAndRespond,
+    ]);
+    // Re-advertise when the registered tool set changes mid-connection.
+    const toolSignature = registry.tools.map((t) => t.name).join(',');
+    useEffect(() => {
+        if (acceptedRef.current) {
+            advertiseTools();
+        }
+        // oxlint-disable-next-line react/exhaustive-effect-dependencies -- `toolSignature` is a deliberate trigger-only dep; see the PR description.
+    }, [toolSignature, advertiseTools]);
+    return {
+        status,
+        connectionToken,
+        activity,
+        pendingConfirmation: pendingQueue[0] ?? null,
+        pendingQueueLength: pendingQueue.length,
+        approve,
+        deny,
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@r0hitsharma/webmcp",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "prepare": "npm run build",
+    "type:check": "tsc -p tsconfig.json --noEmit",
+    "lint": "oxlint -c oxlint.config.ts --max-warnings=0 src",
+    "lint:fix": "oxlint -c oxlint.config.ts --fix src",
+    "format": "oxfmt -c oxfmt.config.ts --write src",
+    "format:check": "oxfmt -c oxfmt.config.ts --check src"
+  },
+  "dependencies": {
+    "@mcp-b/global": "5.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@r0hitsharma/mcp-relay": "*",
+    "@r0hitsharma/oxfmt-config": "*",
+    "@r0hitsharma/oxlint-config": "*",
+    "@r0hitsharma/tsconfig": "*",
+    "@types/react": "^19.0.0",
+    "oxfmt": "0.67.0",
+    "oxlint": "1.82.0"
+  },
+  "version": "0.12.0-rohit-fork-ci.1",
+  "repository": {
+    "url": "https://github.com/r0hitsharma/uikit"
+  }
+}