@adobe-commerce/elsie 1.8.0 → 1.9.0-alpha-20260325145838

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adobe-commerce/elsie
 
+## 1.9.0-alpha-20260325145838
+
+### Minor Changes
+
+- f1f629b: Add `useWebMCP` hook for registering WebMCP tools with `navigator.modelContext`, enabling AI agents to interact with storefront drop-ins through structured function calls.
+
 ## 1.8.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe-commerce/elsie",
-  "version": "1.8.0",
+  "version": "1.9.0-alpha-20260325145838",
   "license": "SEE LICENSE IN LICENSE.md",
   "description": "Domain Package SDK",
   "engines": {

package/src/docs/Utilities/useWebMCP.mdx

@@ -0,0 +1,50 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="Utilities/useWebMCP" />
+<Unstyled>
+
+# useWebMCP(tool)
+
+A Preact hook that registers a WebMCP tool with the browser's `navigator.modelContext` API on mount and unregisters it on unmount. This allows AI agents to interact with the storefront through structured function calls.
+
+The tool is registered once. If the `execute` function is re-created between renders (for example because it closes over component state or callbacks), the hook automatically forwards calls to the latest version without re-registering the tool.
+
+The hook degrades gracefully in browsers that do not support WebMCP — no errors are thrown and existing functionality is unaffected.
+
+## Params
+
+`tool.name`: Unique tool identifier used by agents to call it
+
+`tool.description`: Human-readable description of what the tool does
+
+`tool.inputSchema`: JSON Schema object describing the parameters the tool accepts
+
+`tool.execute`: Function called when the agent invokes the tool. Receives the agent-supplied args and returns any value.
+
+## Returns
+
+`void`
+
+## Examples
+
+```ts
+import { useWebMCP } from '@adobe-commerce/elsie/lib';
+
+useWebMCP({
+  name: 'apply_coupon',
+  description: 'Apply a coupon code to the cart',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      code: { type: 'string', description: 'The coupon code to apply' },
+    },
+    required: ['code'],
+  },
+  execute: async ({ code }) => {
+    await applyCoupon(code as string);
+    return { content: [{ type: 'text', text: 'Coupon applied' }] };
+  },
+});
+```
+
+</Unstyled>

package/src/lib/index.ts

@@ -26,3 +26,4 @@ export * from '@adobe-commerce/elsie/lib/deviceUtils';
 export * from '@adobe-commerce/elsie/lib/get-path-value';
 export * from '@adobe-commerce/elsie/lib/get-cookie';
 export * from '@adobe-commerce/elsie/lib/get-price-formatter';
+export * from '@adobe-commerce/elsie/lib/webmcp';

package/src/lib/webmcp.ts

@@ -0,0 +1,47 @@
+/********************************************************************
+ *  Copyright 2026 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  Adobe permits you to use, modify, and distribute this
+ * file in accordance with the terms of the Adobe license agreement
+ * accompanying it.
+ *******************************************************************/
+
+import { useEffect, useRef } from 'preact/hooks';
+
+export interface WebMCPToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  execute: (args: Record<string, unknown>) => unknown;
+}
+
+declare global {
+  interface Navigator {
+    modelContext?: {
+      registerTool: (tool: WebMCPToolDefinition) => void;
+      unregisterTool: (name: string) => void;
+    };
+  }
+}
+
+export function useWebMCP(tool: WebMCPToolDefinition): void {
+  const executeRef = useRef(tool.execute);
+  executeRef.current = tool.execute;
+
+  useEffect(() => {
+    if (!navigator.modelContext) return;
+
+    const stableTool: WebMCPToolDefinition = {
+      ...tool,
+      execute: (args) => executeRef.current(args),
+    };
+
+    navigator.modelContext.registerTool(stableTool);
+
+    return () => {
+      navigator.modelContext?.unregisterTool(tool.name);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+}