@salla.sa/twilight 3.0.0-beta.1 → 3.0.0

package/README.md

@@ -252,6 +252,35 @@ This is particularly useful for debugging, support, and ensuring compatibility b
 
 <p align="right">(<a href="#top">back to top</a>)</p>
 
+### WebMCP (tools for in-browser AI agents)
+
+Twilight can register [WebMCP](https://webmachinelearning.github.io/webmcp/) tools so an AI agent running in the shopper's browser can search, fill the cart and head to checkout. The tools call the regular SDK (`salla.cart.*`, `salla.product.*`) in the shopper's own tab, so they fire the normal cart events and the cart badge and mini-cart update as they would for a click. They never call the `/mcp` worker, whose carts are not the tab's cart.
+
+| Tool | Read-only | What it does |
+|------|-----------|--------------|
+| `search_products` | yes | Search the store's products by keyword (`query`, optional `limit`). |
+| `get_product` | yes | Product details by `product_id`. |
+| `get_cart` | yes | The shopper's current cart: items, totals, coupon. |
+| `add_to_cart` | no | Add `product_id` (`quantity`, and `options` keyed by option id for products that need them). |
+| `update_cart_item` | no | Change the quantity of a cart item. |
+| `remove_cart_item` | no | Remove a cart item. |
+| `apply_coupon` | no | Apply a coupon code. |
+| `go_to_checkout` | no | Navigate to checkout (guests go to login first). It only navigates; **it never places an order**, the shopper pays on the checkout page. |
+
+Failures come back as `{ isError: true, content: [...] }` with the API's own message.
+
+**Off by default.** Stores opt in through the config passed to `Salla.init`:
+
+```js
+Salla.init({ store: { id: 1234 }, webmcp: { enabled: true } });
+```
+
+Only the boolean `true` (or `'true'` / `1`) turns it on. Salla Store renders this value for you from `TWILIGHT_WEBMCP_ENABLED` (all stores) or the `themes::webmcp.enabled` store setting; set it back to `false` to switch the tools off. No Twilight release is involved.
+
+**Browser support.** Needs a browser that implements WebMCP and an HTTPS page. It looks for `document.modelContext` first, then `navigator.modelContext`, and does nothing when neither exists (all other browsers, including current Firefox and Safari) or on HTTP. In Chrome 146+ the API is behind the `chrome://flags/#enable-webmcp-testing` flag ("WebMCP for testing"). Registering the same tool twice (for example when init runs twice) is tolerated.
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
 ## Support
 
 The team is always here to help you. Happen to face an issue? Want to report a bug? You can submit one here on GitHub using the [Issue Tracker](https://github.com/SallaApp/twilight-vscode-extension/issues/new). If you still have any questions, please contact us via the [Telegram Bot](https://t.me/SallaSupportBot) or join the Global Developer Community on [Telegram](https://t.me/salladev).