@marketbasketanalysis/mcp

Un servidor MCP que ofrece a cualquier agente de IA acceso a inteligencia real de compra conjunta y herramientas de operaciones de comerciante a partir del historial de pedidos de un comercio electrónico. 19 herramientas en descubrimiento, paquetes, información, reposición, operaciones de comerciante y minería avanzada. Funciona con Claude Desktop, Claude Code, Cursor, Windsurf, Cline, el OpenAI Agent SDK y cualquier otro host que hable el protocolo MCP stdio. Funciona para comerciantes en Shopify, BigCommerce, WooCommerce, Magento y OroCommerce. Consulta "Cobertura de plataforma" más abajo para ver qué herramientas llegan a los backends autoalojados.

Por qué existe esto

Cuando un cliente pregunta a un agente de compras con IA "¿qué combina con la mochila de gimnasio?", el agente debe dar una respuesta real basada en los datos reales de pedidos del comerciante, no una suposición genérica de "también te puede gustar". Cuando un comerciante pregunta a Claude "¿en qué debería trabajar esta semana?", el agente debe extraer de un plan semanal clasificado, no inventar tareas. Este servidor pone ambos flujos a disposición de cualquier host MCP en una línea de configuración.

Instalación en 5 líneas (Claude Desktop)

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": { "MBA_API_KEY": "mba_live_YOUR_KEY_HERE" }
    }
  }
}

Pégalo en ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), reinicia Claude Desktop, y el servidor marketbasketanalysis aparece en la lista de herramientas con las 19 herramientas.

Instalación cero: el endpoint alojado

El mismo servidor se ejecuta alojado en https://mcp.marketbasketanalysis.com/mcp (MCP streamable HTTP). No hay nada que instalar; envía tu clave como cabecera bearer en lugar de una variable de entorno:

claude mcp add --transport http marketbasketanalysis \
  https://mcp.marketbasketanalysis.com/mcp \
  --header "Authorization: Bearer mba_live_YOUR_KEY_HERE"

Funciona con cualquier cliente MCP con capacidad remota (Claude Code, Cursor, Smithery, agentes personalizados). Cabeceras opcionales: X-MBA-Base re-apunta a otro plano operado por MBA (por ejemplo https://bigcommerce.marketbasketanalysis.com); X-MBA-Platform refleja la variable de entorno MBA_PLATFORM. Las tiendas WooCommerce y Magento autoalojadas no son accesibles desde el endpoint alojado por diseño; usa la instalación npx anterior con MBA_API_BASE apuntando a tu propio sitio.

Apunta el servidor a tu tienda (MBA_API_BASE)

La URL base es una configuración por tienda. Por defecto, el servidor se comunica con el backend alojado compartido en https://app.marketbasketanalysis.com. Si tus datos están en cualquier otro lugar, una tienda BigCommerce, un backend autoalojado o una instancia de staging, establece MBA_API_BASE para que todas las herramientas lleguen a tu propio plano de datos:

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": {
        "MBA_API_KEY": "mba_live_YOUR_KEY_HERE",
        "MBA_API_BASE": "https://your-store-backend.example.com"
      }
    }
  }
}

MBA_API_BASE es el único interruptor que re-apunta todo el servidor; las 19 herramientas pasan por él. El valor debe ser una URL https:// para hosts no locales (se rechazan los hosts de loopback, privados, link-local y de servicio de metadatos). Para desarrollo local contra un backend en localhost, establece ALLOW_LOCAL_API_BASE=1 para permitir una base http://localhost. Los cambios en las variables de entorno tienen efecto al arrancar el servidor, así que reinicia tu host MCP después de editar el valor.

MBA_API_BASE por plataforma

La URL base es una configuración por tienda. Las tiendas Shopify, BigCommerce y OroCommerce son servidas por el backend alojado compartido, por lo que usan el valor predeterminado. WooCommerce y Magento ejecutan el backend localmente dentro de la instalación de la tienda, así que apunta el servidor al dominio propio de la tienda:

Cobertura de plataforma

El servidor escribe rutas canónicas /api/v1/... y las reescribe por plataforma, porque WooCommerce y Magento ejecutan el backend dentro de la tienda con sus propias convenciones REST (marketbasketanalysis/v1 y V1/marketbasketanalysis, respectivamente).

10 de las 19 herramientas llegan a WooCommerce y Magento: las seis que derivan de /recommendations (get_recommendations, get_bundle_for_cart, score_cross_sell, analyze_basket, propose_subscription_bundle, score_return_risk), más find_substitutes, get_rationale, forecast_bundle y predict_reorder.

Las otras 9 son la superficie de operaciones de comerciante: get_opportunities, triage_opportunity, get_weekly_plan, execute_weekly_plan_action, get_drift_alerts, get_forecast_alerts, explain_opportunity, explain_drift y mine_hui_itemsets. Esos endpoints no existen en los backends autoalojados. Llamar a uno allí devuelve un error claro de "no disponible en esta plataforma" que nombra el endpoint, sin ida y vuelta de red, en lugar de un 404 opaco.

Para la instalación paso a paso (ubicación del archivo de configuración por sistema operativo, dónde generar una clave API, resolución de problemas):

• Claude Desktop: dist/mcp/claude-desktop-setup.md

• Cursor: dist/mcp/cursor-setup.md

• Windsurf: dist/mcp/windsurf-setup.md

Autenticación

El servidor lee MBA_API_KEY del entorno que tu host MCP proporciona y lo envía como token Bearer en cada solicitud. Para obtener una clave:

1. Abre el panel de administración de MarketBasketAnalysis (el cajón de aplicaciones de Shopify, o el admin de BigCommerce / WooCommerce / Magento / OroCommerce).

2. Haz clic en "Claves de API" en la navegación izquierda.

3. Haz clic en "Crear clave", ponle nombre y copia el valor mba_live_ (se muestra una sola vez).

Las claves son por tienda, revocables y se rotan desde la misma pantalla. Solo se almacena el hash SHA-256, así que vuelve a generarla si una clave se filtra.

El modelo de autenticación difiere según el marketplace; el servidor MCP lo abstrae, pero conviene saberlo:

• Shopify, BigCommerce: Bearer mba_live_... directo. Es la vía común.

• WooCommerce: Bearer contra una clave emitida por Woo, que debe llevar el alcance customer_data para predict_reorder.

• Magento: las herramientas acceden a la tienda a través de la superficie REST de Magento (/V1/marketbasketanalysis/* y /V1/mba/*); algunas rutas están restringidas por token de administrador / ACL en el lado de la tienda.

• OroCommerce: la tienda está detrás del cortafuegos OAuth2 de la plataforma para las rutas /api/; el backend alojado al que el cliente ligero hace de proxy es lo que el servidor MCP realmente llama, por lo que la clave mba_live_ sigue aplicándose.

Catálogo de herramientas

19 herramientas, organizadas en los cuatro roles de Basket AI agent más dos grupos operativos. La columna Marketplace indica qué backends incluyen la ruta que llama la herramienta, lo cual no es lo mismo que qué backends puede ALCANZAR actualmente este servidor: consulta "Cobertura de plataforma" más arriba. "Las cinco" significa Shopify, BigCommerce, WooCommerce, Magento, OroCommerce.

Descubrimiento

Paquete

Estas derivan todo de /recommendations (el servidor compone la lógica de paquetes/puntuación en el cliente), por lo que no necesitan ninguna ruta extra de backend y funcionan en todas partes.

Información

También derivadas de /recommendations, por lo que son universales.

Reposición + previsión

Operaciones de comerciante

Estas llaman a rutas /api/v1 con Bearer que hoy se incluyen en BigCommerce. Shopify sirve oportunidades, deriva y el plan semanal a través de sus vistas de administración integradas en lugar de una ruta /api/v1, por lo que estas herramientas se resuelven contra un backend de BigCommerce. La única excepción es /explain-opportunity, que ahora se incluye en BigCommerce y Shopify; /explain-drift sigue siendo solo de BigCommerce. Las herramientas muestran un 404 limpio del upstream en plataformas que carecen de la ruta.

Minería avanzada

Ejemplos de prompts por herramienta

Pega cualquiera de estos en un chat de Claude Desktop / Claude Code / Cursor después de configurar el servidor:

• get_recommendations: "Usa marketbasketanalysis para encontrar qué compran también los clientes con la mochila de gimnasio (producto 8472918765)."

• find_substitutes: "El cuerpo de la DSLR está agotado. ¿Cuál es un buen sustituto?"

• get_rationale: "¿Por qué se recomienda la botella de agua con la mochila de gimnasio?"

• get_bundle_for_cart: "Tengo en el carrito un cuerpo de cámara, una tarjeta SD de 32 GB y un trípode. ¿Qué falta probablemente para tener un kit completo?"

• propose_subscription_bundle: "Crea un kit de suscripción mensual para el cliente 9876."

• score_cross_sell: "¿Es un kit de limpieza una buena venta cruzada para el cuerpo de la cámara DSLR?"

• score_return_risk: *"¿Cuál es el riesgo de devolución de la cámara + lente

  • trípode + bolsa?"*

• analyze_basket: "Estoy pensando en agrupar cámara + lente + tarjeta SD + bolsa. Según los datos reales de clientes, ¿es un paquete sólido?"

• predict_reorder: "¿Qué tiene que reordenar Acme Corp (cliente 7654321) esta semana?"

• forecast_bundle: "Pronostica el paquete b-camera-kit para las próximas 12 semanas y recomienda una cantidad de compra."

• get_weekly_plan: "¿Qué hay en mi plan semanal?"

• execute_weekly_plan_action: "Ejecuta la acción a-42 de mi plan semanal, confirmado."

• get_opportunities: "Muéstrame mis tres mejores oportunidades propuestas."

• explain_opportunity: "¿Por qué la oportunidad opp-17 es una buena venta cruzada?"

• triage_opportunity: "Activa la oportunidad opp-17, confirmado."

• get_drift_alerts: "¿Se está desviando alguna de mis reglas?"

• explain_drift: "¿Por qué se desvió el par de la alerta de deriva alert-7?"

• get_forecast_alerts: "¿Qué paquetes están en riesgo de quedarse sin existencias?"

• mine_hui_itemsets: "Extrae los 20 mejores conjuntos de ítems de alta utilidad de este payload de pedidos de 90 días." (Nivel Plus / Enterprise)

La documentación narrativa de cada herramienta está en el cookbook.

Variables de entorno

Desarrollo

git clone https://github.com/48x-ai/marketbasketanalysis-mcp
cd marketbasketanalysis-mcp
npm install
npm run typecheck
npm test
npm run dev    # tsx-based local run
npm run build  # emit ./dist

Añadir una nueva herramienta

Cada herramienta es un módulo independiente dentro de src/tools/. Para añadir una:

1. Crea src/tools/myNewTool.ts que exporte definition y handler. Imita la estructura de src/tools/getRecommendations.ts para un GET simple, o de src/tools/triageOpportunity.ts para un POST con confirmación.

2. Regístrala en src/tools/index.ts importando y añadiendo el módulo al array allModules.

3. Añade pruebas en src/tools/myNewTool.test.ts, que cubran: respuesta por clave faltante, el caso de éxito y al menos un caso de error del upstream. Imita src/tools/findSubstitutes.test.ts.

4. Documéntala en la tabla anterior y en dist/mcp/smithery.yaml.

Artefactos de distribución

El directorio dist/mcp/ en la raíz del monorepo contiene los ejemplos de instalación (Claude Desktop, Cursor, Windsurf), el YAML de Smithery y el contenido de envío al marketplace de Anthropic. Consulta dist/mcp/README.md para ver la estructura completa.

Publicación

Incrementa la versión en package.json (mantén server.json y src/index.ts sincronizados), fusiona con main, luego crea la etiqueta mcp-v$VERSION y súbela. El workflow ejecuta la comprobación de tipos, las pruebas, la compilación, una comprobación de coincidencia entre etiqueta y versión, y luego npm publish --access public --provenance usando el secreto del repositorio NPM_TOKEN. Hay un disparador manual workflow_dispatch disponible para ejecuciones de rescate.

La lista de comprobación completa para el operador, incluida la configuración única de NPM_TOKEN y una alternativa de publicación manual sin CI, se encuentra en docs/RELEASE.md.

Solución de problemas

Para un diagnóstico más profundo, consulta cada documento de configuración por IDE en dist/mcp/.

Licencia

UNLICENSED, propietario.