@machfivetechchicago/machvive-webmcp-ai 5.5.6 → 5.6.0

package/README.md

@@ -25,6 +25,8 @@ elements with Shadow DOM that work anywhere `customElements` does.
 | Component | Tag | What it does |
 | --- | --- | --- |
 | WebMCP polyfill | `<machvive-webmcp-polyfill>` | Shims `navigator.modelContext` so a page can expose tools to AI agents |
+| WebMCP inspector | `<machvive-webmcp-inspect>` | Lists registered tools, builds a form from each schema, runs them |
+| WebMCP analytics | `<machvive-webmcp-analytics>` | Captures every tool call for listing, editing, export, replay, and dataLayer |
 | Lorum Ipsum | `<machvive-lorum-ipsum>` | Placeholder copy that projects slotted content |
 
 ## ⚡ Integration with Vite (Vanilla JS)
@@ -127,6 +129,83 @@ const result = await navigator.modelContext.callTool('add_to_cart', { sku: 'M5T-
 `callTool` never throws: a handler that rejects comes back as
 `{ content: [...], isError: true }`.
 
+## 🔎 Inspector
+
+`machvive-webmcp-inspect` lists every registered tool, renders a form from its
+`inputSchema`, and executes it with what you type. Values are coerced to the types
+the schema declares — an `integer` field sends `3`, not `"3"` — required fields are
+enforced before anything runs, and `object`/`array` fields accept JSON.
+
+```html
+<!-- inline: renders where you place it -->
+<machvive-webmcp-inspect></machvive-webmcp-inspect>
+
+<!-- floating: docks as an overlay panel with a toggle, no layout impact -->
+<machvive-webmcp-inspect floating></machvive-webmcp-inspect>
+
+<!-- floating and expanded on load -->
+<machvive-webmcp-inspect floating open></machvive-webmcp-inspect>
+```
+
+`show()` and `hide()` drive the panel from script. The list refreshes automatically
+as tools are registered or removed.
+
+## 📊 Analytics
+
+`machvive-webmcp-analytics` captures every WebMCP invocation — params, result,
+duration, and errors — then lets you list, edit, export, replay, or forward them.
+
+```javascript
+import '@machfivetechchicago/machvive-webmcp-ai/webmcp-analytics';
+```
+
+```html
+<machvive-webmcp-analytics></machvive-webmcp-analytics>
+```
+
+**Import it before you register tools.** Capture works by wrapping each tool's
+handler at registration time, so anything registered earlier is invisible to it —
+the component warns in the console when it detects this. Wrapping the handler rather
+than the caller is deliberate: it records invocations from *any* caller, including a
+native `navigator.modelContext` and real agents, neither of which route through this
+library.
+
+Captured calls persist to **IndexedDB**, so a log survives reloads and is not bound
+by the ~5 MB localStorage ceiling. The store degrades to memory-only where IndexedDB
+is unavailable. The default cap is 500 entries, oldest evicted first.
+
+### Working with the log
+
+```javascript
+import { callLog } from '@machfivetechchicago/machvive-webmcp-ai/webmcp-analytics';
+
+await callLog.ready;            // restore from IndexedDB is async
+
+callLog.entries;                // captured calls, oldest first
+callLog.toJSON();               // export as JSON
+callLog.import(json);           // merge a previously exported log
+callLog.update(id, { params }); // edit before replaying
+await callLog.replay(id);                    // re-run as captured
+await callLog.replay(id, { sku: 'OTHER' });  // re-run with edited params
+```
+
+Recording is strictly best-effort: a failure inside the log — a throwing subscriber,
+an unwritable store — can never change a tool's result or make a passing call look
+like it errored.
+
+### Google Tag Manager
+
+Pushing to `window.dataLayer` is **off unless you opt in**, so importing the
+component never emits tracking traffic on its own:
+
+```html
+<machvive-webmcp-analytics datalayer></machvive-webmcp-analytics>
+```
+
+Each call then pushes `{ event: 'webmcp_tool_call', webmcp_tool, webmcp_status,
+webmcp_duration_ms, webmcp_params }`. Without the attribute, push individual entries
+on demand with `callLog.pushToDataLayer(id)` or the per-entry button in the UI.
+
 ## TypeScript
 
 Declarations ship with the package — no `@types/*` needed. Importing a component

package/index.d.ts

@@ -12,3 +12,12 @@ export type {
   WebmcpToolResult,
   WebmcpToolSummary
 } from './src/wc/machvive-webmcp-polyfill/machvive-webmcp-polyfill.js';
+export { MachviveWebmcpInspect } from './src/wc/machvive-webmcp-inspect/machvive-webmcp-inspect.js';
+export {
+  MachviveWebmcpAnalytics,
+  CallLog,
+  callLog,
+  installAnalytics,
+  CALL_EVENT
+} from './src/wc/machvive-webmcp-analytics/machvive-webmcp-analytics.js';
+export type { CapturedCall, CallLogOptions } from './src/wc/machvive-webmcp-analytics/machvive-webmcp-analytics.js';

package/index.js

@@ -5,11 +5,25 @@ import {
   installWebmcpPolyfill,
   TOOLS_CHANGED_EVENT
 } from './src/wc/machvive-webmcp-polyfill/machvive-webmcp-polyfill.js';
+import { MachviveWebmcpInspect } from './src/wc/machvive-webmcp-inspect/machvive-webmcp-inspect.js';
+import {
+  MachviveWebmcpAnalytics,
+  CallLog,
+  callLog,
+  installAnalytics,
+  CALL_EVENT
+} from './src/wc/machvive-webmcp-analytics/machvive-webmcp-analytics.js';
 
 // Export them all from a single entry point
 export {
   MachviveLorumIpsum,
   MachviveWebmcpPolyfill,
+  MachviveWebmcpInspect,
+  MachviveWebmcpAnalytics,
+  CallLog,
+  callLog,
   installWebmcpPolyfill,
-  TOOLS_CHANGED_EVENT
+  installAnalytics,
+  TOOLS_CHANGED_EVENT,
+  CALL_EVENT
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@machfivetechchicago/machvive-webmcp-ai",
-  "version": "5.5.6",
+  "version": "5.6.0",
   "description": "I don't want to use your product's agent; I want my agent to be able to use your product.",
   "keywords": [
     "WebMCP",
@@ -40,6 +40,14 @@
       "types": "./src/wc/machvive-webmcp-polyfill/machvive-webmcp-polyfill.d.ts",
       "default": "./src/wc/machvive-webmcp-polyfill/machvive-webmcp-polyfill.js"
     },
+    "./webmcp-inspect": {
+      "types": "./src/wc/machvive-webmcp-inspect/machvive-webmcp-inspect.d.ts",
+      "default": "./src/wc/machvive-webmcp-inspect/machvive-webmcp-inspect.js"
+    },
+    "./webmcp-analytics": {
+      "types": "./src/wc/machvive-webmcp-analytics/machvive-webmcp-analytics.d.ts",
+      "default": "./src/wc/machvive-webmcp-analytics/machvive-webmcp-analytics.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -56,6 +64,7 @@
     "prepublishOnly": "npm test"
   },
   "devDependencies": {
+    "fake-indexeddb": "^6.2.5",
     "jsdom": "^29.1.1"
   }
 }

package/src/wc/machvive-webmcp-analytics/machvive-webmcp-analytics.d.ts

@@ -0,0 +1,83 @@
+import type { WebmcpToolResult } from '../machvive-webmcp-polyfill/machvive-webmcp-polyfill.js';
+
+/** One captured tool invocation. */
+export interface CapturedCall {
+  id: string;
+  tool: string;
+  params?: unknown;
+  result?: unknown;
+  error?: string;
+  status: 'ok' | 'error';
+  startedAt: string;
+  durationMs: number;
+  pushedToDataLayer?: boolean;
+}
+
+export interface CallLogOptions {
+  /** Max entries retained; oldest are evicted first. Default 500. */
+  limit?: number;
+  /** Persist to IndexedDB. Default true. */
+  persist?: boolean;
+}
+
+export interface CallLogChangeEvent {
+  type: 'change';
+  detail: {
+    reason: 'add' | 'update' | 'remove' | 'clear' | 'import' | 'restore';
+    entry: CapturedCall | null;
+    entries: CapturedCall[];
+  };
+}
+
+export class CallLog {
+  constructor(options?: CallLogOptions);
+  /** Resolves once entries have been loaded from IndexedDB. */
+  readonly ready: Promise<void>;
+  /** True when entries are being written to IndexedDB. */
+  readonly persistent: boolean;
+  readonly entries: CapturedCall[];
+  readonly size: number;
+  addEventListener(type: 'change', listener: (e: CallLogChangeEvent) => void): void;
+  removeEventListener(type: 'change', listener: (e: CallLogChangeEvent) => void): void;
+  add(entry: Omit<CapturedCall, 'id'>): CapturedCall;
+  update(id: string, patch: Partial<CapturedCall>): CapturedCall | null;
+  remove(id: string): boolean;
+  clear(): void;
+  toJSON(space?: number): string;
+  /** Merges a previously exported log; returns how many entries were added. */
+  import(json: string | { entries: CapturedCall[] }): number;
+  /** Re-invokes a captured call, optionally with edited params. */
+  replay(id: string, params?: Record<string, unknown>): Promise<WebmcpToolResult>;
+  /** Pushes one entry to window.dataLayer. */
+  pushToDataLayer(id: string): boolean;
+}
+
+/** Shared log used by every <machvive-webmcp-analytics> on the page. */
+export const callLog: CallLog;
+
+/** Event dispatched on window whenever the log changes. */
+export const CALL_EVENT: 'machvive-webmcp-call';
+export const DB_NAME: 'machvive-webmcp';
+export const STORE_NAME: 'calls';
+
+/**
+ * Instruments navigator.modelContext so future registrations are captured.
+ * Tools registered before this runs cannot be instrumented.
+ */
+export function installAnalytics(log?: CallLog): boolean;
+
+export class MachviveWebmcpAnalytics extends HTMLElement {
+  readonly log: CallLog;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'machvive-webmcp-analytics': MachviveWebmcpAnalytics;
+  }
+  interface WindowEventMap {
+    'machvive-webmcp-call': CustomEvent<{ reason: string; entry: CapturedCall | null }>;
+  }
+  interface Window {
+    dataLayer?: unknown[];
+  }
+}

package/src/wc/machvive-webmcp-analytics/machvive-webmcp-analytics.js

@@ -0,0 +1,565 @@
+/**
+ * Captures every WebMCP tool invocation — request, response, timing, errors —
+ * and exposes them for listing, editing, export, replay, and dataLayer push.
+ *
+ * Instrumentation wraps each tool's `execute` handler at registration time rather
+ * than hooking the polyfill's `callTool`. That captures invocations from any
+ * caller, including a native `navigator.modelContext` and real agents, neither of
+ * which route through our code.
+ */
+
+// Importing the polyfill guarantees navigator.modelContext exists before
+// installAnalytics() runs. Without this, importing analytics first — which is
+// exactly what capturing every call requires — finds no registry to instrument
+// and silently captures nothing.
+import '../machvive-webmcp-polyfill/machvive-webmcp-polyfill.js';
+
+export const CALL_EVENT = 'machvive-webmcp-call';
+export const DB_NAME = 'machvive-webmcp';
+export const STORE_NAME = 'calls';
+
+const DB_VERSION = 1;
+const DEFAULT_LIMIT = 500;
+
+/**
+ * Minimal IndexedDB wrapper. Every method resolves to a harmless value when
+ * IndexedDB is unavailable (jsdom, private mode, disabled storage) so capture
+ * degrades to memory-only rather than breaking the page.
+ */
+class IdbStore {
+  #dbPromise = null;
+
+  get available() {
+    return Boolean(globalThis.indexedDB);
+  }
+
+  #db() {
+    if (!this.available) return Promise.resolve(null);
+    this.#dbPromise ??= new Promise((resolve) => {
+      let request;
+      try {
+        request = globalThis.indexedDB.open(DB_NAME, DB_VERSION);
+      } catch {
+        return resolve(null);
+      }
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(STORE_NAME)) {
+          db.createObjectStore(STORE_NAME, { keyPath: 'id' });
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => resolve(null);
+      request.onblocked = () => resolve(null);
+    });
+    return this.#dbPromise;
+  }
+
+  async #tx(mode, run) {
+    const db = await this.#db();
+    if (!db) return null;
+    return new Promise((resolve) => {
+      let tx;
+      try {
+        tx = db.transaction(STORE_NAME, mode);
+      } catch {
+        return resolve(null);
+      }
+      const request = run(tx.objectStore(STORE_NAME));
+      tx.oncomplete = () => resolve(request ? request.result : null);
+      tx.onerror = () => resolve(null);
+      tx.onabort = () => resolve(null);
+    });
+  }
+
+  all() {
+    return this.#tx('readonly', (store) => store.getAll()).then((r) => r ?? []);
+  }
+
+  put(entry) {
+    return this.#tx('readwrite', (store) => store.put(entry));
+  }
+
+  delete(id) {
+    return this.#tx('readwrite', (store) => store.delete(id));
+  }
+
+  clear() {
+    return this.#tx('readwrite', (store) => store.clear());
+  }
+}
+
+let nextId = 0;
+const newId = () => `call-${Date.now().toString(36)}-${(nextId++).toString(36)}`;
+
+/** Deep-copies through JSON so a later mutation of caller state can't rewrite history. */
+function snapshot(value) {
+  if (value === undefined) return undefined;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * The captured call log. A single instance is shared by every
+ * <machvive-webmcp-analytics> element on the page.
+ */
+export class CallLog {
+  #listeners = new Set();
+  #entries = [];
+  #limit;
+  #persist;
+  #store = new IdbStore();
+
+  /** Resolves once persisted entries have been loaded. Await before first read. */
+  ready;
+
+  constructor({ limit = DEFAULT_LIMIT, persist = true } = {}) {
+    this.#limit = limit;
+    this.#persist = persist;
+    this.ready = this.#restore();
+  }
+
+  /** True when entries are being written to IndexedDB. */
+  get persistent() {
+    return this.#persist && this.#store.available;
+  }
+
+  /** EventTarget-shaped for familiarity; only the 'change' type is emitted. */
+  addEventListener(type, listener) {
+    if (type === 'change' && typeof listener === 'function') this.#listeners.add(listener);
+  }
+
+  removeEventListener(type, listener) {
+    if (type === 'change') this.#listeners.delete(listener);
+  }
+
+  get entries() {
+    return [...this.#entries];
+  }
+
+  get size() {
+    return this.#entries.length;
+  }
+
+  add(entry) {
+    const record = { id: newId(), ...entry };
+    this.#entries.push(record);
+    // Oldest-first trim keeps the most recent calls, which are what anyone debugging wants.
+    let evicted = [];
+    if (this.#entries.length > this.#limit) {
+      evicted = this.#entries.splice(0, this.#entries.length - this.#limit);
+    }
+    this.#write((store) => {
+      store.put(record);
+      for (const gone of evicted) store.delete(gone.id);
+    });
+    this.#changed('add', record);
+    return record;
+  }
+
+  update(id, patch) {
+    const entry = this.#entries.find((e) => e.id === id);
+    if (!entry) return null;
+    Object.assign(entry, patch);
+    this.#write((store) => store.put(entry));
+    this.#changed('update', entry);
+    return entry;
+  }
+
+  remove(id) {
+    const index = this.#entries.findIndex((e) => e.id === id);
+    if (index === -1) return false;
+    const [removed] = this.#entries.splice(index, 1);
+    this.#write((store) => store.delete(removed.id));
+    this.#changed('remove', removed);
+    return true;
+  }
+
+  clear() {
+    this.#entries = [];
+    this.#write((store) => store.clear());
+    this.#changed('clear', null);
+  }
+
+  /** Serialized log, suitable for a file or a clipboard. */
+  toJSON(space = 2) {
+    return JSON.stringify({ version: 1, exportedAt: new Date().toISOString(), entries: this.#entries }, null, space);
+  }
+
+  /** Merges a previously exported log. Returns how many entries were added. */
+  import(json) {
+    const parsed = typeof json === 'string' ? JSON.parse(json) : json;
+    const incoming = Array.isArray(parsed) ? parsed : parsed?.entries;
+    if (!Array.isArray(incoming)) throw new TypeError('Analytics: import expects an entries array');
+    for (const entry of incoming) {
+      const record = { ...entry, id: entry.id ?? newId() };
+      this.#entries.push(record);
+      this.#write((store) => store.put(record));
+    }
+    this.#changed('import', null);
+    return incoming.length;
+  }
+
+  /**
+   * Re-invokes a captured call. Passing `params` runs it with edited input
+   * instead of what was originally recorded.
+   */
+  async replay(id, params) {
+    const entry = this.#entries.find((e) => e.id === id);
+    if (!entry) throw new Error(`Analytics: no captured call ${id}`);
+    const mc = globalThis.navigator?.modelContext;
+    if (!mc?.callTool) throw new Error('Analytics: navigator.modelContext.callTool is unavailable');
+    return mc.callTool(entry.tool, params ?? entry.params ?? {});
+  }
+
+  /** Pushes one entry to window.dataLayer in a GTM-friendly flat shape. */
+  pushToDataLayer(id) {
+    const entry = this.#entries.find((e) => e.id === id);
+    if (!entry) return false;
+    const layer = (globalThis.window.dataLayer ||= []);
+    layer.push({
+      event: 'webmcp_tool_call',
+      webmcp_tool: entry.tool,
+      webmcp_status: entry.status,
+      webmcp_duration_ms: entry.durationMs,
+      webmcp_params: entry.params,
+      webmcp_error: entry.error ?? undefined
+    });
+    this.update(id, { pushedToDataLayer: true });
+    return true;
+  }
+
+  #changed(reason, entry) {
+    const detail = { reason, entry, entries: this.entries };
+    for (const listener of this.#listeners) {
+      try {
+        listener({ type: 'change', detail });
+      } catch {
+        // One broken subscriber must not stop the others, nor reach the tool call.
+      }
+    }
+    // Also on window so page code can observe without holding a CallLog reference.
+    try {
+      globalThis.window?.dispatchEvent?.(new CustomEvent(CALL_EVENT, { detail: { reason, entry } }));
+    } catch {
+      // No window, or a CustomEvent from a foreign realm.
+    }
+  }
+
+  /** Fire-and-forget write. Persistence failing must never break capture. */
+  #write(run) {
+    if (!this.persistent) return;
+    this.#runBatch(run).catch(() => {});
+  }
+
+  async #runBatch(run) {
+    // IdbStore exposes one operation per transaction; a batch callback needs a
+    // tiny shim so callers can express several writes in one place.
+    const ops = [];
+    run({
+      put: (entry) => ops.push(['put', entry]),
+      delete: (id) => ops.push(['delete', id]),
+      clear: () => ops.push(['clear'])
+    });
+    for (const [op, arg] of ops) {
+      await this.#store[op](arg);
+    }
+  }
+
+  async #restore() {
+    if (!this.persistent) return;
+    try {
+      const stored = await this.#store.all();
+      if (!Array.isArray(stored) || stored.length === 0) return;
+      // Persisted rows win only where memory has nothing — a call captured during
+      // startup must not be clobbered by the restore that was already in flight.
+      const seen = new Set(this.#entries.map((e) => e.id));
+      const merged = [...stored.filter((e) => !seen.has(e.id)), ...this.#entries];
+      this.#entries = merged.slice(-this.#limit);
+      this.#changed('restore', null);
+    } catch {
+      // Corrupt or unreadable storage must never stop the page from loading.
+    }
+  }
+}
+
+export const callLog = new CallLog();
+
+/** Wraps a descriptor's handler so every invocation is recorded. */
+function instrumentTool(tool, log) {
+  // Leave invalid descriptors alone so the polyfill's own validation still throws.
+  if (!tool || typeof tool !== 'object' || typeof tool.execute !== 'function') return tool;
+  if (tool.execute.__machviveWrapped) return tool;
+
+  const original = tool.execute;
+  const wrapped = async function (params, agent) {
+    const startedAt = new Date().toISOString();
+    const t0 = Date.now();
+    const record = (fields) => {
+      try {
+        log.add(fields);
+      } catch {
+        // Capture is best-effort; never let it change the tool's outcome.
+      }
+    };
+
+    try {
+      const result = await original.call(this, params, agent);
+      record({
+        tool: tool.name,
+        params: snapshot(params),
+        result: snapshot(result),
+        status: 'ok',
+        startedAt,
+        durationMs: Date.now() - t0
+      });
+      return result;
+    } catch (err) {
+      record({
+        tool: tool.name,
+        params: snapshot(params),
+        error: String(err?.message ?? err),
+        status: 'error',
+        startedAt,
+        durationMs: Date.now() - t0
+      });
+      throw err;
+    }
+  };
+  wrapped.__machviveWrapped = true;
+  return { ...tool, execute: wrapped };
+}
+
+let installed = false;
+
+/**
+ * Instruments `navigator.modelContext` so future registrations are captured.
+ *
+ * Tools registered *before* this runs cannot be instrumented — the polyfill hides
+ * handlers from `tools` by design — so import this module before registering.
+ *
+ * @returns {boolean} true if this call instrumented the registry.
+ */
+export function installAnalytics(log = callLog) {
+  const mc = globalThis.navigator?.modelContext;
+  if (!mc || installed) return false;
+
+  if (mc.tools?.length) {
+    console.warn(
+      `WebMCP analytics: ${mc.tools.length} tool(s) were registered before analytics loaded ` +
+        'and will not be captured. Import the analytics module earlier.'
+    );
+  }
+
+  const register = mc.registerTool.bind(mc);
+  mc.registerTool = (tool) => register(instrumentTool(tool, log));
+
+  if (typeof mc.provideContext === 'function') {
+    const provide = mc.provideContext.bind(mc);
+    mc.provideContext = (config = {}) =>
+      provide({ ...config, tools: (config.tools ?? []).map((t) => instrumentTool(t, log)) });
+  }
+
+  installed = true;
+  return true;
+}
+
+const STYLES = `
+  :host { display: block; font: 13px/1.5 system-ui, sans-serif; color: #1a1a1a; }
+  :host([hidden]) { display: none; }
+  .bar { display: flex; gap: 6px; align-items: center; flex-wrap: wrap; margin-bottom: 8px; }
+  .count { font-weight: 600; margin-right: auto; }
+  button { font: inherit; padding: 3px 9px; border: 1px solid #ccc; border-radius: 4px;
+           background: #fff; cursor: pointer; }
+  button:hover { background: #f2f2f2; }
+  button.danger { color: #a01; border-color: #d8a0a0; }
+  ol { list-style: none; margin: 0; padding: 0; border: 1px solid #e2e2e2; border-radius: 6px;
+       max-height: 380px; overflow-y: auto; }
+  li { border-bottom: 1px solid #eee; }
+  li:last-child { border-bottom: 0; }
+  .row { display: flex; gap: 8px; align-items: center; padding: 6px 10px; cursor: pointer; }
+  .row:hover { background: #fafafa; }
+  .tool { font-family: ui-monospace, monospace; font-weight: 600; }
+  .status { font-size: 11px; padding: 1px 6px; border-radius: 10px; }
+  .status.ok { background: #e6f4ea; color: #137333; }
+  .status.error { background: #fce8e6; color: #c5221f; }
+  .ms { color: #777; font-size: 11px; margin-left: auto; }
+  .detail { padding: 8px 10px; background: #fbfbfb; border-top: 1px solid #eee; }
+  .detail label { display: block; font-size: 11px; color: #666; margin: 6px 0 2px; }
+  textarea { width: 100%; box-sizing: border-box; font-family: ui-monospace, monospace;
+             font-size: 12px; border: 1px solid #ddd; border-radius: 4px; padding: 5px; }
+  pre { margin: 0; padding: 6px; background: #fff; border: 1px solid #eee; border-radius: 4px;
+        font-size: 12px; overflow-x: auto; white-space: pre-wrap; word-break: break-word; }
+  .empty { padding: 20px; text-align: center; color: #888; }
+  .err { color: #c5221f; }
+`;
+
+export class MachviveWebmcpAnalytics extends HTMLElement {
+  #log = callLog;
+  #expanded = null;
+  #onChange = () => this.#render();
+
+  static get observedAttributes() {
+    return ['datalayer'];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.shadowRoot.innerHTML = `<style>${STYLES}</style><div id="root"></div>`;
+    this.#log.addEventListener('change', this.#onChange);
+    // Auto-push only when explicitly opted in, so importing this never emits GTM traffic.
+    globalThis.window.addEventListener(CALL_EVENT, this.#maybeAutoPush);
+    this.#render();
+    // Restore is async; repaint once persisted calls have loaded.
+    this.#log.ready?.then(() => this.isConnected && this.#render());
+  }
+
+  disconnectedCallback() {
+    this.#log.removeEventListener('change', this.#onChange);
+    globalThis.window.removeEventListener(CALL_EVENT, this.#maybeAutoPush);
+  }
+
+  /** The shared call log, for page code that wants direct access. */
+  get log() {
+    return this.#log;
+  }
+
+  #maybeAutoPush = (e) => {
+    if (!this.hasAttribute('datalayer')) return;
+    if (e.detail?.reason !== 'add' || !e.detail.entry) return;
+    this.#log.pushToDataLayer(e.detail.entry.id);
+  };
+
+  #render() {
+    const root = this.shadowRoot?.getElementById('root');
+    if (!root) return;
+    const entries = this.#log.entries.slice().reverse();
+
+    root.innerHTML = `
+      <div class="bar">
+        <span class="count">${entries.length} call${entries.length === 1 ? '' : 's'}</span>
+        <button data-act="export">Export</button>
+        <button data-act="copy">Copy JSON</button>
+        <button data-act="clear" class="danger">Clear</button>
+      </div>
+      ${
+        entries.length === 0
+          ? `<div class="empty">No WebMCP calls captured yet.</div>`
+          : `<ol>${entries.map((e) => this.#renderEntry(e)).join('')}</ol>`
+      }
+    `;
+    root.querySelector('.bar').addEventListener('click', (ev) => this.#onBarClick(ev));
+    root.querySelectorAll('li').forEach((li) => this.#wireEntry(li));
+  }
+
+  #renderEntry(entry) {
+    const open = this.#expanded === entry.id;
+    return `
+      <li data-id="${entry.id}">
+        <div class="row">
+          <span class="tool">${escapeHtml(entry.tool ?? '(unknown)')}</span>
+          <span class="status ${entry.status}">${entry.status}</span>
+          <span class="ms">${entry.durationMs ?? 0}ms</span>
+        </div>
+        ${
+          open
+            ? `<div class="detail">
+                 <label>Params (editable — used on replay)</label>
+                 <textarea rows="3" data-role="params">${escapeHtml(
+                   JSON.stringify(entry.params ?? {}, null, 2)
+                 )}</textarea>
+                 <label>${entry.status === 'error' ? 'Error' : 'Result'}</label>
+                 <pre class="${entry.status === 'error' ? 'err' : ''}">${escapeHtml(
+                   entry.status === 'error' ? entry.error ?? '' : JSON.stringify(entry.result ?? null, null, 2)
+                 )}</pre>
+                 <div class="bar" style="margin-top:8px">
+                   <button data-act="save">Save params</button>
+                   <button data-act="replay">Replay</button>
+                   <button data-act="push">Push to dataLayer</button>
+                   <button data-act="remove" class="danger">Delete</button>
+                 </div>
+               </div>`
+            : ''
+        }
+      </li>
+    `;
+  }
+
+  #wireEntry(li) {
+    const id = li.dataset.id;
+    li.querySelector('.row').addEventListener('click', () => {
+      this.#expanded = this.#expanded === id ? null : id;
+      this.#render();
+    });
+    li.querySelectorAll('button[data-act]').forEach((btn) => {
+      btn.addEventListener('click', (ev) => {
+        ev.stopPropagation();
+        this.#onEntryAction(btn.dataset.act, id, li);
+      });
+    });
+  }
+
+  async #onEntryAction(action, id, li) {
+    const readParams = () => {
+      const raw = li.querySelector('[data-role="params"]')?.value ?? '{}';
+      try {
+        return JSON.parse(raw);
+      } catch {
+        globalThis.window.alert('Params must be valid JSON.');
+        return null;
+      }
+    };
+
+    if (action === 'save') {
+      const params = readParams();
+      if (params) this.#log.update(id, { params });
+    } else if (action === 'replay') {
+      const params = readParams();
+      if (params) await this.#log.replay(id, params);
+    } else if (action === 'push') {
+      this.#log.pushToDataLayer(id);
+    } else if (action === 'remove') {
+      if (this.#expanded === id) this.#expanded = null;
+      this.#log.remove(id);
+    }
+  }
+
+  #onBarClick(ev) {
+    const act = ev.target.dataset?.act;
+    if (act === 'clear') {
+      this.#expanded = null;
+      this.#log.clear();
+    } else if (act === 'copy') {
+      globalThis.navigator.clipboard?.writeText(this.#log.toJSON());
+    } else if (act === 'export') {
+      this.#download();
+    }
+  }
+
+  #download() {
+    const blob = new Blob([this.#log.toJSON()], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `webmcp-analytics-${Date.now()}.json`;
+    a.click();
+    URL.revokeObjectURL(url);
+  }
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+}
+
+installAnalytics();
+
+if (!customElements.get('machvive-webmcp-analytics')) {
+  customElements.define('machvive-webmcp-analytics', MachviveWebmcpAnalytics);
+}

package/src/wc/machvive-webmcp-inspect/machvive-webmcp-inspect.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Lists registered WebMCP tools, builds a form from each tool's inputSchema,
+ * and executes it. Inline by default; `floating` docks it as an overlay.
+ */
+export class MachviveWebmcpInspect extends HTMLElement {
+  /** Opens the panel (floating mode only). */
+  show(): void;
+  /** Closes the panel (floating mode only). */
+  hide(): void;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'machvive-webmcp-inspect': MachviveWebmcpInspect;
+  }
+}

package/src/wc/machvive-webmcp-inspect/machvive-webmcp-inspect.js

@@ -0,0 +1,302 @@
+/**
+ * Lists the tools registered with WebMCP, builds a form from each tool's
+ * inputSchema, and executes it with the values entered.
+ *
+ * Renders inline by default; add the `floating` attribute to dock it as an
+ * overlay panel, and `open` to start that panel expanded.
+ *
+ * Importing this also installs the polyfill, since discovery (`tools`) and
+ * invocation (`callTool`) are additions the bare spec does not provide.
+ */
+import { TOOLS_CHANGED_EVENT } from '../machvive-webmcp-polyfill/machvive-webmcp-polyfill.js';
+
+/** Reads a form control back as the JSON type its schema calls for. */
+function readControl(input, schema = {}) {
+  if (input.type === 'checkbox') return input.checked;
+  const raw = input.value;
+  if (raw === '' ) return undefined;
+  if (schema.type === 'number' || schema.type === 'integer') {
+    const n = Number(raw);
+    if (Number.isNaN(n)) throw new TypeError(`"${raw}" is not a number`);
+    return schema.type === 'integer' ? Math.trunc(n) : n;
+  }
+  if (schema.type === 'object' || schema.type === 'array') {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      throw new TypeError(`must be valid JSON`);
+    }
+  }
+  return raw;
+}
+
+const STYLES = `
+  :host { display: block; font: 13px/1.5 system-ui, sans-serif; color: #1a1a1a; }
+  :host([hidden]) { display: none; }
+
+  /* Floating mode docks the panel without disturbing page layout. */
+  :host([floating]) { position: fixed; right: 16px; bottom: 16px; z-index: 2147483000;
+                      display: block; width: auto; }
+  :host([floating]) .panel { display: none; width: min(420px, calc(100vw - 32px));
+                             max-height: min(70vh, 560px); overflow: auto;
+                             box-shadow: 0 8px 28px rgba(0,0,0,.18); background: #fff; }
+  :host([floating][open]) .panel { display: block; }
+  :host([floating]) .fab { display: inline-flex; }
+  .fab { display: none; align-items: center; gap: 6px; margin-top: 8px; float: right;
+         padding: 7px 13px; border-radius: 999px; border: 1px solid #ccc; background: #fff;
+         cursor: pointer; font: inherit; box-shadow: 0 2px 8px rgba(0,0,0,.14); }
+
+  .panel { border: 1px solid #e2e2e2; border-radius: 8px; overflow: hidden; }
+  header { display: flex; align-items: center; gap: 8px; padding: 7px 10px;
+           background: #fafafa; border-bottom: 1px solid #eee; font-weight: 600; }
+  header .close { margin-left: auto; border: 0; background: none; cursor: pointer;
+                  font-size: 16px; line-height: 1; color: #666; }
+  :host(:not([floating])) header .close { display: none; }
+
+  .body { display: flex; min-height: 150px; }
+  @media (max-width: 520px) { .body { flex-direction: column; } }
+
+  .tools { flex: 0 0 150px; border-right: 1px solid #eee; overflow-y: auto; }
+  @media (max-width: 520px) { .tools { flex: none; border-right: 0; border-bottom: 1px solid #eee; } }
+  .tools button { display: block; width: 100%; text-align: left; padding: 6px 10px;
+                  border: 0; background: none; cursor: pointer; font: inherit;
+                  font-family: ui-monospace, monospace; border-bottom: 1px solid #f4f4f4; }
+  .tools button:hover { background: #f6f6f6; }
+  .tools button[aria-current="true"] { background: #e8f0fe; font-weight: 600; }
+
+  .form { flex: 1; padding: 10px; min-width: 0; }
+  .desc { color: #666; margin: 0 0 8px; }
+  label { display: block; margin-bottom: 7px; }
+  .name { font-family: ui-monospace, monospace; font-size: 12px; }
+  .req { color: #c5221f; }
+  .hint { color: #888; font-size: 11px; }
+  input, select, textarea { width: 100%; box-sizing: border-box; font: inherit; font-size: 12px;
+                            padding: 4px 6px; border: 1px solid #ddd; border-radius: 4px; }
+  input[type="checkbox"] { width: auto; }
+  textarea { font-family: ui-monospace, monospace; }
+  .run { margin-top: 4px; padding: 5px 14px; border: 1px solid #1a73e8; border-radius: 4px;
+         background: #1a73e8; color: #fff; cursor: pointer; font: inherit; }
+  .run:disabled { opacity: .6; cursor: default; }
+  pre { margin: 8px 0 0; padding: 7px; background: #fafafa; border: 1px solid #eee;
+        border-radius: 4px; font-size: 12px; white-space: pre-wrap; word-break: break-word;
+        max-height: 180px; overflow: auto; }
+  pre.error { background: #fce8e6; border-color: #f5c6c2; color: #c5221f; }
+  .field-error { color: #c5221f; font-size: 11px; }
+  .empty { padding: 20px; text-align: center; color: #888; }
+`;
+
+export class MachviveWebmcpInspect extends HTMLElement {
+  #selected = null;
+  #result = null;
+  #onToolsChanged = () => this.#render();
+
+  static get observedAttributes() {
+    return ['floating', 'open'];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.shadowRoot.innerHTML = `<style>${STYLES}</style><div id="root"></div>`;
+    globalThis.window.addEventListener(TOOLS_CHANGED_EVENT, this.#onToolsChanged);
+    this.#render();
+  }
+
+  disconnectedCallback() {
+    globalThis.window.removeEventListener(TOOLS_CHANGED_EVENT, this.#onToolsChanged);
+  }
+
+  attributeChangedCallback() {
+    if (this.shadowRoot?.getElementById('root')) this.#render();
+  }
+
+  /** Opens the panel (floating mode only). */
+  show() {
+    this.setAttribute('open', '');
+  }
+
+  /** Closes the panel (floating mode only). */
+  hide() {
+    this.removeAttribute('open');
+  }
+
+  get #context() {
+    return globalThis.navigator?.modelContext ?? null;
+  }
+
+  get #tools() {
+    return this.#context?.tools ?? [];
+  }
+
+  #render() {
+    const root = this.shadowRoot?.getElementById('root');
+    if (!root) return;
+
+    const mc = this.#context;
+    // A native modelContext has no tools/callTool — those are our additions.
+    const usable = Boolean(mc && Array.isArray(mc.tools) && typeof mc.callTool === 'function');
+    const tools = usable ? this.#tools : [];
+    if (this.#selected && !tools.some((t) => t.name === this.#selected)) this.#selected = null;
+    this.#selected ??= tools[0]?.name ?? null;
+    const tool = tools.find((t) => t.name === this.#selected) ?? null;
+
+    root.innerHTML = `
+      <div class="panel">
+        <header>WebMCP Inspector<button class="close" title="Close">&times;</button></header>
+        ${
+          !usable
+            ? `<div class="empty">navigator.modelContext is unavailable here.<br>
+                 <span class="hint">Needs a secure context, and tool discovery requires the machvive polyfill.</span></div>`
+            : tools.length === 0
+              ? `<div class="empty">No tools registered.</div>`
+              : `<div class="body">
+                   <div class="tools">${tools
+                     .map(
+                       (t) =>
+                         `<button data-tool="${escapeAttr(t.name)}" aria-current="${
+                           t.name === this.#selected
+                         }">${escapeHtml(t.name)}</button>`
+                     )
+                     .join('')}</div>
+                   <div class="form">${this.#renderForm(tool)}</div>
+                 </div>`
+        }
+      </div>
+      <button class="fab" title="WebMCP Inspector">&#128295; WebMCP</button>
+    `;
+    this.#wire(root);
+  }
+
+  #renderForm(tool) {
+    if (!tool) return '';
+    const schema = tool.inputSchema ?? {};
+    const props = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    const names = Object.keys(props);
+
+    const fields = names.length
+      ? names.map((name) => this.#renderField(name, props[name], required.has(name))).join('')
+      : `<p class="hint">This tool takes no parameters.</p>`;
+
+    return `
+      ${tool.description ? `<p class="desc">${escapeHtml(tool.description)}</p>` : ''}
+      <form>
+        ${fields}
+        <button type="submit" class="run">Execute</button>
+      </form>
+      ${
+        this.#result
+          ? `<pre class="${this.#result.isError ? 'error' : ''}">${escapeHtml(this.#result.text)}</pre>`
+          : ''
+      }
+    `;
+  }
+
+  #renderField(name, schema = {}, isRequired) {
+    const label = `<span class="name">${escapeHtml(name)}</span>${
+      isRequired ? ' <span class="req" title="required">*</span>' : ''
+    }${schema.description ? ` <span class="hint">— ${escapeHtml(schema.description)}</span>` : ''}`;
+
+    let control;
+    if (Array.isArray(schema.enum)) {
+      control = `<select data-field="${escapeAttr(name)}">${
+        isRequired ? '' : '<option value=""></option>'
+      }${schema.enum
+        .map((v) => `<option value="${escapeAttr(v)}">${escapeHtml(v)}</option>`)
+        .join('')}</select>`;
+    } else if (schema.type === 'boolean') {
+      control = `<input type="checkbox" data-field="${escapeAttr(name)}">`;
+    } else if (schema.type === 'object' || schema.type === 'array') {
+      control = `<textarea rows="3" data-field="${escapeAttr(name)}" placeholder="JSON"></textarea>`;
+    } else {
+      const numeric = schema.type === 'number' || schema.type === 'integer';
+      control = `<input type="${numeric ? 'number' : 'text'}"${
+        schema.type === 'integer' ? ' step="1"' : ''
+      } data-field="${escapeAttr(name)}">`;
+    }
+
+    return `<label>${label}${control}<span class="field-error" data-error="${escapeAttr(
+      name
+    )}"></span></label>`;
+  }
+
+  #wire(root) {
+    root.querySelector('.fab')?.addEventListener('click', () =>
+      this.hasAttribute('open') ? this.hide() : this.show()
+    );
+    root.querySelector('header .close')?.addEventListener('click', () => this.hide());
+
+    root.querySelectorAll('[data-tool]').forEach((btn) =>
+      btn.addEventListener('click', () => {
+        this.#selected = btn.dataset.tool;
+        this.#result = null;
+        this.#render();
+      })
+    );
+
+    root.querySelector('form')?.addEventListener('submit', (ev) => {
+      ev.preventDefault();
+      this.#execute(root);
+    });
+  }
+
+  async #execute(root) {
+    const tool = this.#tools.find((t) => t.name === this.#selected);
+    if (!tool) return;
+    const props = tool.inputSchema?.properties ?? {};
+    const required = new Set(tool.inputSchema?.required ?? []);
+
+    const params = {};
+    let invalid = false;
+    root.querySelectorAll('[data-error]').forEach((el) => (el.textContent = ''));
+
+    for (const [name, schema] of Object.entries(props)) {
+      const input = root.querySelector(`[data-field="${CSS.escape(name)}"]`);
+      if (!input) continue;
+      const errorEl = root.querySelector(`[data-error="${CSS.escape(name)}"]`);
+      try {
+        const value = readControl(input, schema);
+        if (value === undefined) {
+          if (required.has(name)) {
+            if (errorEl) errorEl.textContent = 'required';
+            invalid = true;
+          }
+          continue;
+        }
+        params[name] = value;
+      } catch (err) {
+        if (errorEl) errorEl.textContent = String(err.message ?? err);
+        invalid = true;
+      }
+    }
+    if (invalid) return;
+
+    const button = root.querySelector('.run');
+    if (button) button.disabled = true;
+    try {
+      const result = await this.#context.callTool(tool.name, params);
+      const text = (result?.content ?? [])
+        .map((block) => block?.text ?? JSON.stringify(block))
+        .join('\n');
+      this.#result = { text: text || JSON.stringify(result, null, 2), isError: Boolean(result?.isError) };
+    } catch (err) {
+      // callTool is documented never to reject, but a native impl might.
+      this.#result = { text: String(err?.message ?? err), isError: true };
+    } finally {
+      if (button) button.disabled = false;
+    }
+    this.#render();
+  }
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+}
+const escapeAttr = escapeHtml;
+
+if (!customElements.get('machvive-webmcp-inspect')) {
+  customElements.define('machvive-webmcp-inspect', MachviveWebmcpInspect);
+}