WisWes Magento MCP

Expone las operaciones de catálogo, carrito, checkout, clientes, ventas y lista de deseos de una tienda Magento 2 como herramientas MCP, para que un agente de IA pueda buscar productos y construir un carrito real contra la tienda en vivo.

GitHubPrueba este MCPPatrocinado

Documentación

WisWes MCP para Magento 2

El módulo oficial de WisWes para Magento 2. Conecta tu tienda con el asistente de compras con IA WisWes (wiswes.com) a través del Model Context Protocol (MCP).

El módulo incluye:

Un endpoint HTTP MCP sin estado en /mcp, servido a través de tu servidor web Magento existente — sin proceso separado que gestionar.
22 herramientas tipadas en catálogo, carrito, checkout, cliente, ventas y lista de deseos.
Un handshake de administración con un clic que entrega un secreto compartido a tu espacio de trabajo WisWes.
Envío nocturno del catálogo al índice vectorial de WisWes para búsqueda semántica de productos.

Lo que esto te da: la persona de chat Wes en tu tienda puede leer tus datos de Magento en vivo y actuar sobre el carrito sin código de pegamento. Los compradores hacen preguntas en lenguaje natural, Wes llama a la herramienta correcta, tú envías más pedidos.

Nombre del módulo: WisWes_MCP
Paquete Composer: wiswes/magento-mcp
Versiones de Magento probadas: 2.4.4, 2.4.5, 2.4.6, 2.4.7
PHP: 8.1 / 8.2 / 8.3 / 8.4

Instalación

Elige una de las tres vías de instalación. Composer es recomendado para producción.

Opción A — Composer (recomendada)

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

El paquete está publicado en Packagist. Fija una línea principal con composer require wiswes/magento-mcp:^1.0.

Opción B — Clonar con Git

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

Opción C — Archivo ZIP

Descarga el archivo desde la página de lanzamientos y descomprímelo en la raíz de tu Magento:

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

Conectar a WisWes

El endpoint MCP es servido por tu servidor web existente en https://<your-magento>/mcp. No hay proceso separado que iniciar — una vez que setup:upgrade se ejecuta, la ruta está activa.

Conectar a tu espacio de trabajo WisWes es un handshake de un clic desde el administrador de Magento:

Abre Stores → Configuration → WisWes Chat → WisWes Chat MCP → Connection.
(Opcional) Establece la URL del panel de WisWes si te conectas a un panel de staging o autoalojado. Por defecto: https://api.wiswes.com/.
Guarda la configuración.
Abre Stores → Configuration → WisWes Chat → WisWes Chat Widget → Install y haz clic en el botón Install.
Magento genera un secreto compartido aleatorio largo único para esta instalación, lo persiste (cifrado) bajo wiswes_mcp/auth/shared_secret, y te redirige al panel de WisWes con el secreto incrustado como install_token en la URL.
El panel guarda el token en el CommerceConfig de tu tenant. A partir de ahora, cada chat de WisWes llega a tu tienda como POST https://<your-magento>/mcp con Authorization: Bearer <secret>.

El comerciante nunca ve el secreto en el navegador — viaja de servidor a servidor mediante una redirección sobre HTTPS.

Modelo de autenticación

Las herramientas se dividen en tres categorías según el contexto de Magento que necesitan:

Grupo de herramientas	Tipo de token
Catálogo (búsqueda/filtro/obtener/categoría)	solo secreto compartido de instalación — contexto público de tienda
Carrito, cliente, lista de deseos	secreto compartido + bearer de cliente (reenviado por WisWes cuando el chat está identificado)
Actualizaciones de pedidos	secreto compartido + cliente (pedidos propios) o administrador (cualquier pedido)

WisWes reenvía automáticamente el token de cliente del comprador cuando el chat está iniciado sesión. Los compradores anónimos aún pueden usar herramientas de catálogo, pero no pueden leer el carrito hasta que inicien sesión.

Enviar el catálogo

WisWes sirve la búsqueda de productos desde su propio índice vectorial, poblado desde tu tienda Magento. El envío se ejecuta cada noche a las 03:00 por defecto; actívalo manualmente después de un cambio masivo de catálogo:

# from Magento root
bin/magento wiswes:products:push
# Pushed 4271 products in 43 batches (upserted=4271, skipped_operator=0, skipped_cap=0)

O haz clic en Push catalogue now bajo Stores → Configuration → WisWes Chat → WisWes Chat MCP → Catalogue Sync.

El envío incluye un payload de recuperación compacto (sku, name, url, price) más un blob de metadatos construido a partir del nombre + descripción corta + atributos buscables. El blob es lo que WisWes incrusta; el payload de recuperación es lo que el LLM ve textualmente cuando un resultado coincide.

El envío es incremental — solo se envían productos habilitados y visibles, en lotes de 100 a la vez. La autenticación usa el mismo secreto compartido generado por el handshake de instalación.

Instalar el widget de la tienda

La burbuja de chat de WisWes es una sola etiqueta <script>. El módulo no la inyecta automáticamente — pégala en las áreas de script nativas de Magento, para que tu ruta de instalación sea idéntica a Shopify o cualquier tienda personalizada:

Stores → Configuration → Design → HTML Head → Scripts and Style Sheets, o
default_head_blocks.xml en tu tema

Copia el fragmento desde tu espacio de trabajo WisWes bajo Configuration → Commerce → Embed snippet. Se ve así:

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

El token en el fragmento es tu ID de tenant — cada chat que se carga mediante este fragmento está limitado a tu espacio de trabajo.

Verificar que funciona

Endpoint MCP accesible. Desde cualquier host que WisWes pueda alcanzar:

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"}'

Deberías ver una respuesta JSON-RPC que liste las 22 herramientas integradas.

Herramientas descubiertas en WisWes. Abre WisWes → Behavior → Tools. Las 22 herramientas aparecen en segundos.
Catálogo conectado. Pregunta a Wes: "recomienda un cargador inalámbrico para un iPhone." Wes debería llamar a product:filter y devolver filas reales del catálogo.
Carrito conectado. Mientras estés conectado en la tienda, pregunta: "añade el segundo a mi bolsa." Wes debería llamar a cart:add y confirmar el nuevo artículo de línea.
Conversación registrada. Actualiza Conversations en WisWes — tu chat de prueba aparece con las llamadas a herramientas en el panel derecho.

La referencia completa de herramientas + argumentos está en la documentación de WisWes.

Herramientas incluidas de serie

22 herramientas en seis grupos. Los nombres listados son los IDs de herramienta MCP que ve el agente.

Grupo	Herramienta	Resumen
Catálogo	`category:list`	Árbol de categorías como lista anidada
Catálogo	`product:filter`	Consultas de filtro estructuradas (campo EAV, operador, valor)
Catálogo	`product:filter:options`	Descubre los atributos filtrables + sus valores de opción
Catálogo	`product:get`	Payload completo del producto por SKU o ID
Carrito	`cart:info`	Instantánea del carrito activo
Carrito	`cart:add`	Añadir un producto (configurable / bundle / opciones personalizadas)
Carrito	`cart:update`	Cantidad, aplicar / eliminar cupón
Carrito	`cart:remove`	Eliminar un artículo de línea por id
Checkout	`checkout:set:address`	Dirección de facturación o envío (invitado o conectado)
Checkout	`checkout:shipping_methods`	Métodos de envío disponibles para el carrito activo
Checkout	`checkout:payment_methods`	Métodos de pago disponibles para el carrito activo
Checkout	`checkout:place_order`	Realizar el pedido desde el carrito activo
Cliente	`customer:create`	Registrar un nuevo cliente
Cliente	`customer:info`	Perfil, direcciones, pedidos recientes
Cliente	`customer:update`	Parchear campos de perfil
Cliente	`customer:address:list`	Todas las direcciones guardadas
Cliente	`customer:address:update`	Crear o actualizar una dirección
Cliente	`customer:address:remove`	Eliminar una dirección
Ventas	`order:info`	Estado de pedido compacto + historial + seguimiento
Ventas	`order:update`	Comentar / retener / cancelar / cambiar dirección de envío
Lista de deseos	`wishlist:items`	Todos los artículos en la lista de deseos del cliente
Lista de deseos	`wishlist:add:item`	Añadir un producto a la lista de deseos

Cada herramienta devuelve un array tipado o lanza un LocalizedException de Magento con un mensaje seguro para el comprador — no se filtran trazas de pila crudas al agente.

Uso

Una vez instalado y conectado, el flujo de trabajo diario es:

Los clientes chatean con Wes a través del widget de WisWes en tu tienda.
Wes selecciona herramientas para responder preguntas o tomar acciones — buscar en el catálogo, consultar un pedido, añadir al carrito.
Las llamadas a herramientas llegan a /mcp en tu tienda, que lee/escribe a través de los contratos de servicio estándar de Magento para que todos tus hooks de extensiones existentes se activen (reglas de precio, reservas de stock, reglas de ventas, etc.).
Los resultados regresan a Wes, quien responde en lenguaje natural con tarjetas de producto, actualizaciones de estado o confirmaciones.

Puedes limitar qué herramientas están disponibles por espacio de trabajo bajo Behavior → Tools en WisWes — activa/desactiva herramientas individuales, sobrescribe su descripción (el texto de prompt que lee el modelo), o fija valores predeterminados de argumentos. Nada de esto requiere tocar PHP.

Extender — escribe tu propia herramienta

Cada herramienta de Magento es una clase PHP simple con un atributo #[McpTool]. Coloca una clase en Mcp/Tool/..., reconstruye la caché de DI, limpia el OPcache, y la herramienta aparece en tu espacio de trabajo WisWes en segundos.

Ejemplo mínimo

<?php
declare(strict_types=1);

namespace WisWes\MCP\Mcp\Tool\Loyalty;

use PhpMcp\Server\Attributes\McpTool;

class LoyaltyPointsTool
{
    public function __construct(
        private readonly \Acme\Loyalty\Api\PointsClient $client,
    ) {}

    #[McpTool(
        name: 'loyalty:points',
        description: 'Returns the authenticated customer\'s loyalty tier and current points balance. Arguments: none. Customer bearer token required.'
    )]
    public function points(): array
    {
        $snapshot = $this->client->snapshotForCurrentUser();

        return [
            'tier'          => $snapshot->getTier(),
            'points'        => $snapshot->getBalance(),
            'tier_progress' => $snapshot->getProgressToNext(),
        ];
    }
}

Después:

bin/magento setup:di:compile
bin/magento cache:flush

La herramienta aparece bajo Behavior → Tools en WisWes etiquetada como loyalty:points.

Convenciones que valen la pena

Una herramienta, un trabajo. El modelo elige mejor entre diez herramientas específicas que entre tres amplias.
Sé específico en description. Es el prompt que lee el modelo al decidir si llamar a tu herramienta. Incluye cada argumento, la forma de retorno y cuándo no usar la herramienta.
Valida en el límite. Lanza Magento\Framework\Exception\LocalizedException con un mensaje seguro para el comprador — el agente lo mostrará tal cual.
Devuelve arrays, no DTOs. Los arrays tipados estrictos se serializan limpiamente a MCP. Oculta los internals (row_id, parent_id, flags internos) de la respuesta a menos que el modelo los necesite.
Mantente sin estado. Las herramientas deberían funcionar igual en la primera llamada y en la llamada número 1,000. El estado del carrito / pedido pertenece a Magento, no a la clase de la herramienta.

Herramienta con argumentos

#[McpTool(
    name: 'sales:track_order',
    description: 'Returns carrier and tracking URL for an order. Arguments: order_id (string, required).'
)]
public function track(string $orderId): array
{
    $shipment = $this->client->getLatestShipment($orderId);
    return [
        'order_id'     => $orderId,
        'carrier'      => $shipment->getCarrier(),
        'status'       => $shipment->getStatus(),
        'tracking_url' => $shipment->getTrackingUrl(),
    ];
}

Suprimir herramientas integradas

Para ejecutar un subconjunto curado, establece el valor de configuración wiswes_mcp/tools/include a una lista de globs separada por comas:

bin/magento config:set wiswes_mcp/tools/include 'product:*,cart:*,order:info'
bin/magento cache:flush

* (el valor predeterminado) significa que todas las herramientas integradas + personalizadas están expuestas.

Referencia de configuración

Todos los ajustes están bajo Stores → Configuration → WisWes Chat (o mediante bin/magento config:set).

Conexión (`wiswes_mcp/install/*`)

Ruta	Propósito	Valor predeterminado
`wiswes_mcp/install/wiswes_url`	URL base del panel de WisWes al que redirige el botón Instalar	`https://api.wiswes.com/`

Autenticación — se establece automáticamente mediante el handshake de instalación (`wiswes_mcp/auth/*`)

Ruta	Propósito
`wiswes_mcp/auth/shared_secret`	Secreto compartido cifrado utilizado para autenticar los tokens bearer de `/mcp`
`wiswes_mcp/auth/admin_id`	ID de usuario administrador capturado en el momento de la instalación, controla el ACL

Herramientas (`wiswes_mcp/tools/*`)

Ruta	Propósito	Valor predeterminado
`wiswes_mcp/tools/include`	Lista global de nombres de herramientas a exponer	`*`

Identidad del servidor (`wiswes_mcp/server/*`)

Ruta	Propósito	Valor predeterminado
`wiswes_mcp/server/name`	Nombre del servidor anunciado en el handshake de MCP `initialize`	`WisWes Magento MCP`

Actualización

# Composer
composer update wiswes/magento-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 and unzip over the existing folder, then run the same setup commands.

Desinstalación

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

# Composer
composer remove wiswes/magento-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 ''

En WisWes, elimina la conexión en Configuración → Commerce.

Solución de problemas

El módulo se instala pero no aparecen herramientas en WisWes

Ejecuta bin/magento setup:di:compile — requerido después de añadir cualquier clase de herramienta nueva.
Limpia OPcache (bin/magento cache:flush o reinicia php-fpm) — la detección de herramientas ocurre en la primera solicitud después de un despliegue.

Verifica que la URL de MCP sea accesible desde WisWes (firewall, NAT). Desde un host del lado de WisWes:

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"}'

Las llamadas a herramientas devuelven 401 No autorizado

El secreto compartido se rotó o no se instaló. Vuelve a ejecutar el handshake de instalación desde Stores → Configuration → WisWes Chat → Install.
Para herramientas orientadas al cliente (carrito, cliente, pedido), el chat de la tienda debe estar identificado — los chats anónimos no pueden leer el carrito.

Composer no puede encontrar una versión compatible de `wiswes/magento-mcp`

Ejecuta composer clear-cache y luego reintenta composer require wiswes/magento-mcp:^1.0. Packagist actualiza su índice en segundos después de cada push etiquetado, por lo que casi siempre es una caché local obsoleta.

Para instalar desde una rama de funcionalidad que aún no ha sido etiquetada, añade la fuente de GitHub como repositorio VCS en tu composer.json:

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

El push del catálogo informa `skipped_cap` o `skipped_operator`

skipped_cap — se alcanzó el límite de índice de productos de tu plan de WisWes. Mejora el plan o recorta el filtro del catálogo.
skipped_operator — una fila fue rechazada por el lado de WisWes por estar malformada (SKU faltante, nombre vacío). Inspecciona mediante:
```
bin/magento wiswes:products:push -vvv
```

`/mcp` devuelve 404

Confirma que el módulo está habilitado: bin/magento module:status WisWes_MCP.
Confirma que la ruta mcp está registrada: bin/magento info:routes:url:list 2>/dev/null | grep mcp (o verifica etc/frontend/routes.xml).
Vuelve a ejecutar bin/magento setup:upgrade.

Soporte

Documentación: https://wiswes.com/docs
Guía de instalación: https://wiswes.com/install/magento
Problemas: https://github.com/wiswes/magento/issues
Correo electrónico: services@wiswes.com
Integración de pago: https://wiswes.com/services#magento-dev — instalamos, configuramos y enviamos el widget en tu tienda por ti.

Licencia

Publicado bajo la Licencia Pública General de GNU v3.0 — consulta el archivo LICENSE para conocer los términos completos.