PHPackages wiswes/magento-mcp - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. wiswes/magento-mcp ActiveMagento2-module[API Development](/categories/api) wiswes/magento-mcp ================== WisWes MCP module for Magento 2 — exposes catalog, cart, checkout, customer, sales and wishlist tools to the WisWes shopping assistant via Model Context Protocol. 1.0.7(1mo ago)00GPL-3.0-or-laterPHPPHP ~8.1.0||~8.2.0||~8.3.0||~8.4.0 Since May 4Pushed 1mo agoCompare [ Source](https://github.com/wiswes/magento)[ Packagist](https://packagist.org/packages/wiswes/magento-mcp)[ Docs](https://wiswes.com)[ RSS](/packages/wiswes-magento-mcp/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (2)Versions (9)Used By (0) WisWes MCP for Magento 2 ======================== [](#wiswes-mcp-for-magento-2) [![Version](https://camo.githubusercontent.com/1a0870952590d12609fd51b9b86611c3e561aa7ac4a013bb664e4a904d281c3f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e302e372d626c75652e737667)](https://github.com/wiswes/magento/releases)[![License: GPL v3](https://camo.githubusercontent.com/48bf9b56d44f38db53ce21294cf0b9487d0a3734ab3ba1fe4c69858ae20db2c1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d47504c76332d626c75652e737667)](LICENSE)[![Magento](https://camo.githubusercontent.com/c47dbdb0b1083634227b492e3bc0bd118a85e50fefc9ffac4af44724fcb5c1b9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d6167656e746f2d322e342e342532422d6f72616e67652e737667)](https://magento.com)[![PHP](https://camo.githubusercontent.com/eefdb4df87ca8a71e3b08ef2b0c7bf2b8f02aa3443b030113b475e76b6660b20/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e31253230253743253230382e32253230253743253230382e33253230253743253230382e342d3737374242342e737667)](https://php.net) The official WisWes module for Magento 2. Plugs your store into the **WisWes** AI shopping assistant ([wiswes.com](https://wiswes.com)) over the **Model Context Protocol (MCP)**. The module ships: - A stateless MCP HTTP endpoint at `/mcp`, served through your existing Magento web server — no separate process to manage. - 22 typed tools across catalog, cart, checkout, customer, sales, and wishlist. - A one-click admin handshake that hands a shared secret to your WisWes workspace. - Nightly catalogue push to the WisWes vector index for semantic product search. > **What this gives you:** the `Wes` chat persona on your storefront can read your live Magento data and act on the cart with no glue code. Shoppers ask questions in natural language, Wes calls the right tool, you ship more orders. - **Module name:** `WisWes_MCP` - **Composer package:** `wiswes/magento-mcp` - **Tested Magento versions:** 2.4.4, 2.4.5, 2.4.6, 2.4.7 - **PHP:** 8.1 / 8.2 / 8.3 / 8.4 --- Table of contents ----------------- [](#table-of-contents) - [Install](#install) - [Option A — Composer (recommended)](#option-a--composer-recommended) - [Option B — Git clone](#option-b--git-clone) - [Option C — ZIP archive](#option-c--zip-archive) - [Connect to WisWes](#connect-to-wiswes) - [Push the catalogue](#push-the-catalogue) - [Install the storefront widget](#install-the-storefront-widget) - [Verify it works](#verify-it-works) - [Tools shipped out of the box](#tools-shipped-out-of-the-box) - [Use](#use) - [Extend — write your own tool](#extend--write-your-own-tool) - [Configuration reference](#configuration-reference) - [Upgrade](#upgrade) - [Uninstall](#uninstall) - [Troubleshoot](#troubleshoot) - [Support](#support) - [License](#license) --- Install ------- [](#install) Pick one of the three install paths. Composer is recommended for production. ### Option A — Composer (recommended) [](#option-a--composer-recommended) ``` composer require wiswes/magento-mcp bin/magento module:enable WisWes_MCP bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:flush ``` The package is published on [Packagist](https://packagist.org/packages/wiswes/magento-mcp). Pin a major line with `composer require wiswes/magento-mcp:^1.0`. ### Option B — Git clone [](#option-b--git-clone) ``` mkdir -p app/code/WisWes git clone https://github.com/wiswes/magento.git app/code/WisWes/MCP cd app/code/WisWes/MCP && git checkout v1.0.7 && cd - bin/magento module:enable WisWes_MCP bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:flush ``` ### Option C — ZIP archive [](#option-c--zip-archive) Download the archive from the [Releases page](https://github.com/wiswes/magento/releases/latest) and unzip into your Magento root: ``` unzip ~/Downloads/wiswes-magento-1.0.7.zip -d . mkdir -p app/code/WisWes && mv wiswes-magento-1.0.7 app/code/WisWes/MCP bin/magento module:enable WisWes_MCP bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:flush ``` --- Connect to WisWes ----------------- [](#connect-to-wiswes) The MCP endpoint is served by your existing web server at `https:///mcp`. There is **no separate process to start** — once `setup:upgrade` runs, the route is live. Connecting to your WisWes workspace is a one-click handshake from the Magento admin: 1. Open **Stores → Configuration → WisWes Chat → WisWes Chat MCP → Connection**. 2. (Optional) Set the **WisWes Dashboard URL** if you're connecting to a staging or self-hosted dashboard. Default: `https://api.wiswes.com/`. 3. Save the config. 4. Open **Stores → Configuration → WisWes Chat → WisWes Chat Widget → Install** and click the **Install** button. 5. Magento generates a long random shared secret unique to this install, persists it (encrypted) under `wiswes_mcp/auth/shared_secret`, and redirects you to the WisWes dashboard with the secret embedded as `install_token` in the URL. 6. The dashboard saves the token on your tenant's CommerceConfig. From now on every WisWes chat reaches your store as `POST https:///mcp` with `Authorization: Bearer `. The merchant never sees the secret in the browser — it travels server-to-server via a redirect over HTTPS. ### Auth model [](#auth-model) Tools fall into three categories based on the Magento context they need: Tool groupToken typeCatalog (search/filter/get/category)shared install secret only — public storefront contextCart, customer, wishlistshared secret + customer bearer (forwarded by WisWes when chat is identified)Order updatesshared secret + customer (own orders) or admin (any order)WisWes forwards the shopper's customer token automatically when the chat is logged in. Anonymous shoppers can still use catalog tools but can't read the cart until they sign in. --- Push the catalogue ------------------ [](#push-the-catalogue) WisWes serves product search out of its own vector index, populated from your Magento store. The push runs nightly at 03:00 by default; trigger it manually after a bulk catalogue change: ``` # from Magento root bin/magento wiswes:products:push # Pushed 4271 products in 43 batches (upserted=4271, skipped_operator=0, skipped_cap=0) ``` Or click **Push catalogue now** under **Stores → Configuration → WisWes Chat → WisWes Chat MCP → Catalogue Sync**. The push ships a compact retrieval payload (`sku`, `name`, `url`, `price`) plus a metadata blob built from name + short description + searchable attributes. The blob is what WisWes embeds; the retrieval payload is what the LLM sees verbatim when a result matches. The push is incremental — only enabled, visible products are sent, batched 100 at a time. Auth uses the same shared secret minted by the Install handshake. --- Install the storefront widget ----------------------------- [](#install-the-storefront-widget) The WisWes chat bubble is a single `` tag. The module does **not** auto-inject it — paste it into Magento's native script areas instead, so your install path is identical to Shopify or any custom storefront: - **Stores → Configuration → Design → HTML Head → Scripts and Style Sheets**, or - `default_head_blocks.xml` in your theme Copy the snippet from your WisWes workspace under **Configuration → Commerce → Embed snippet**. It looks like: ``` ``` The token in the snippet is your tenant ID — every chat that loads via this snippet is scoped to your workspace. --- Verify it works --------------- [](#verify-it-works) 1. **MCP endpoint reachable.** From any host that WisWes can reach: ``` curl -X POST https:///mcp \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` You should see a JSON-RPC response listing the 22 built-in tools. 2. **Tools discovered in WisWes.** Open WisWes → **Behavior → Tools**. The 22 tools appear within seconds. 3. **Catalog wired.** Ask Wes: *"recommend a wireless charger for an iPhone."* Wes should call `product:filter` and return real catalog rows. 4. **Cart wired.** While logged in on the storefront, ask: *"add the second one to my bag."* Wes should call `cart:add` and confirm the new line item. 5. **Conversation logged.** Refresh **Conversations** in WisWes — your test chat appears with the tool calls in the right pane. Full tool reference + arguments lives in the [WisWes docs](https://wiswes.com/docs#magento-tools). --- Tools shipped out of the box ---------------------------- [](#tools-shipped-out-of-the-box) 22 tools across six groups. Names listed are the MCP tool ids the agent sees. GroupToolSummaryCatalog`category:list`Category tree as a nested listCatalog`product:filter`Structured filter queries (EAV field, operator, value)Catalog`product:filter:options`Discover the filterable attributes + their option valuesCatalog`product:get`Full product payload by SKU or IDCart`cart:info`Snapshot of the active cartCart`cart:add`Add a product (configurable / bundle / custom options)Cart`cart:update`Quantity, coupon apply / removeCart`cart:remove`Remove a line item by idCheckout`checkout:set:address`Billing or shipping address (guest or logged-in)Checkout`checkout:shipping_methods`Available shipping methods for the active cartCheckout`checkout:payment_methods`Available payment methods for the active cartCheckout`checkout:place_order`Place the order from the active cartCustomer`customer:create`Register a new customerCustomer`customer:info`Profile, addresses, recent ordersCustomer`customer:update`Patch profile fieldsCustomer`customer:address:list`All saved addressesCustomer`customer:address:update`Create or update an addressCustomer`customer:address:remove`Delete an addressSales`order:info`Compact order status + history + trackingSales`order:update`Comment / hold / cancel / change shipping addressWishlist`wishlist:items`All items in the customer wishlistWishlist`wishlist:add:item`Add a product to the wishlistEvery tool returns a typed array or throws a Magento `LocalizedException` with a shopper-safe message — no raw stack traces leak to the agent. --- Use --- [](#use) Once installed and connected, the day-to-day workflow is: 1. **Customers chat** with Wes via the WisWes widget on your storefront. 2. **Wes selects tools** to answer questions or take actions — search the catalog, look up an order, add to cart. 3. **Tool calls hit `/mcp` on your store**, which reads/writes through Magento's standard service contracts so all your existing extension hooks fire (price rules, stock reservations, sales rules, etc.). 4. **Results return to Wes**, who replies in natural language with product cards, status updates, or confirmations. You can scope which tools are available per workspace under **Behavior → Tools** in WisWes — toggle individual tools on/off, override their description (the prompt text the model reads), or pin argument defaults. None of this requires touching PHP. --- Extend — write your own tool ---------------------------- [](#extend--write-your-own-tool) Every Magento tool is a plain PHP class with a `#[McpTool]` attribute. Drop a class into `Mcp/Tool/...`, rebuild the DI cache, clear the OPcache, and the tool appears in your WisWes workspace within seconds. ### Minimal example [](#minimal-example) ```