Install WisWes for Magento 2

Requirements

• Magento 2.4.4 or newer (tested through 2.4.7)
• PHP 8.1, 8.2, or 8.3
• Shell access to your Magento root (or your CI / deploy runner)
• Composer 2.x if you choose Option A
• The php-mcp/server library at runtime — install once at the project root: composer require php-mcp/server

Option A — Install via Composer (recommended)

The package is published on Packagist as wiswes/module-mcp. Versioned, upgradable with composer update, ships clean rollbacks.

composer require wiswes/module-mcp
bin/magento module:enable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Option B — Clone from GitHub

Use this when you want to read or fork the source, or pin to an exact commit. The repo lives at:

https://github.com/wiswes/magento

mkdir -p app/code/WisWes
git clone https://github.com/wiswes/magento.git app/code/WisWes/MCP

# (optional) pin to a release tag
cd app/code/WisWes/MCP && git checkout v1.0.0 && cd -

bin/magento module:enable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Option C — Install from the ZIP archive

Fastest way to try the module on a sandbox. Download the current release, unzip into your Magento root, enable.

Download magento-mcp-plugin.zip (v1.0.0)

# from your Magento root
unzip ~/Downloads/magento-mcp-plugin.zip -d .

bin/magento module:enable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

The archive layout matches what Magento expects:

<magento-root>/
  app/code/WisWes/MCP/
    composer.json
    registration.php
    etc/
    Console/
    Controller/
    Mcp/Tool/
    Model/
    Service/
    view/

Enable the module

All three install paths converge here. Confirm the module is wired in:

bin/magento module:status WisWes_MCP
# Module is enabled

bin/magento module:enable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

The MCP endpoint is now live at https://<your-magento>/mcp — served by your existing Apache / Nginx + PHP-FPM. There is no separate process to manage.

Connect to WisWes

Connecting your WisWes workspace is a one-click admin handshake. Magento mints a long random shared secret, hands it to the WisWes dashboard via redirect, and from then on every chat reaches your store with the right Authorization: Bearer header.

1. Open Stores → Configuration → WisWes Chat → WisWes Chat MCP → Connection.
2. (Optional) Set WisWes Dashboard URL if you're connecting to staging or a self-hosted dashboard. Default: https://api.wiswes.com/.
3. Save the config.
4. Open Stores → Configuration → WisWes Chat → WisWes Chat Widget → Install and click Install.
5. You'll be redirected to the WisWes dashboard with the install token embedded — sign in / sign up. The dashboard saves the token on your tenant's commerce config.

Install the storefront widget

The chat bubble is a single <script> 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:

<script src="https://app.wiswes.com/api/widget/embed.js?user_token=YOUR_TENANT_TOKEN" defer></script>

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.

Verify it works

1. Smoke-test the MCP endpoint:

   curl -X POST https://<your-magento>/mcp \
     -H 'Authorization: Bearer <your-shared-secret>' \
     -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. Open Behavior → Tools in WisWes — the 22 Magento tools (Catalog, Cart, Checkout, Customer, Sales, Wishlist) appear within seconds.
3. Visit a product page on your storefront, open the chat, ask "recommend something for a beach holiday" — Wes should call product:filter and return real catalog items.

Full tool reference: Magento MCP — every built-in tool.

Upgrade

# Composer
composer update wiswes/module-mcp
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

# Git
cd app/code/WisWes/MCP && git fetch && git checkout v<new-tag> && cd -
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

# ZIP
# Download the new archive, unzip over the existing folder, then run the same setup commands.

Uninstall

bin/magento module:disable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

# Composer
composer remove wiswes/module-mcp

# Git / ZIP
rm -rf app/code/WisWes/MCP

# Optional — wipe the install secret
bin/magento config:set wiswes_mcp/auth/shared_secret ''
bin/magento config:set wiswes_mcp/auth/admin_id ''

In WisWes, clear the connection under Configuration → Commerce.

Troubleshoot

The module installs but tools don't appear in WisWes

• Run bin/magento setup:di:compile — required after any new tool class is added.
• Clear OPcache (bin/magento cache:flush or restart php-fpm) — tool discovery happens at first request after a deploy.
• Check the MCP URL is reachable from WisWes (firewall, NAT). From a WisWes-side host:

  curl -i -X POST https://<your-magento>/mcp \
    -H 'Authorization: Bearer <your-secret>' \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tool calls return 401 Unauthorized

• The shared secret rotated or wasn't installed. Re-run the Install handshake from Stores → Configuration → WisWes Chat → Install.
• For customer-scoped tools (cart, customer, order) the storefront chat must be identified — anonymous chats can't read the cart.

Composer can't find a matching version

Run composer clear-cache, then re-try composer require wiswes/module-mcp:^1.0. Packagist refreshes its index within seconds of every tagged push, so this is almost always a stale local cache.

If you need to install from a feature branch that hasn't been tagged yet, add the GitHub source as a VCS repository:

{
  "repositories": [
    { "type": "vcs", "url": "https://github.com/wiswes/magento" }
  ]
}