Swell MCP

Servidor Swell MCP

Un servidor de Model Context Protocol que integra asistentes de IA con la plataforma de comercio electrónico de Swell. Construido sobre una base TypeScript lista para producción, proporciona acceso integral a las tiendas Swell para gestión de productos, procesamiento de pedidos y gestión de clientes a través de interfaces CLI y herramientas MCP.

Creado por Devkind - Socios oficiales de Swell que atienden a empresas a nivel mundial con soluciones de comercio electrónico de vanguardia.

Características

• Integración de comercio electrónico Swell: Acceso completo a la API de Swell para productos, pedidos y clientes
• Soporte de transporte dual: Transportes STDIO y HTTP para integración con asistentes de IA y web
• Arquitectura de 5 capas: Separación limpia entre CLI, herramientas, controladores, servicios y utilidades
• Seguridad de tipos: Implementación completa en TypeScript con validación de esquemas Zod
• Cliente HTTP avanzado: Construido sobre el SDK swell-node con agrupación de conexiones y lógica de reintentos
• Pruebas exhaustivas: Pruebas unitarias y de integración con simulación de la API de Swell
• Herramientas de producción: Integración con ESLint, Prettier, semantic-release y MCP Inspector
• Manejo de errores: Manejo estructurado de errores con contextos de error específicos de Swell

Integración de comercio electrónico Swell

Este servidor MCP proporciona integración integral con la plataforma de comercio electrónico de Swell:

Herramientas y comandos disponibles

Herramientas MCP:

• swell_list_products - Listar productos con filtrado y paginación
• swell_get_product - Obtener información detallada del producto
• swell_search_products - Buscar productos con múltiples criterios
• swell_check_inventory - Verificar niveles de inventario de productos
• swell_list_orders - Listar pedidos con opciones de filtrado
• swell_get_order - Obtener información detallada del pedido
• swell_update_order_status - Actualizar estado del pedido
• swell_list_customers - Listar clientes con capacidades de búsqueda
• swell_get_customer - Obtener información detallada del cliente
• swell_search_customers - Buscar clientes con múltiples criterios

Características demostradas

• Gestión de productos: Acceso completo al catálogo de productos con seguimiento de inventario
• Procesamiento de pedidos: Gestión del ciclo de vida de pedidos con actualizaciones de estado
• Gestión de clientes: Perfiles de clientes con historial de pedidos y análisis
• Manejo de errores: Errores estructurados para fallos de API y problemas de validación
• Formato de respuestas: Salida Markdown limpia con tablas de datos estructuradas

Requisitos de configuración

# Required - Swell API credentials
SWELL_STORE_ID=your-store-id
SWELL_SECRET_KEY=your-secret-key

# Development
DEBUG=true                    # Enable detailed logging
TRANSPORT_MODE=http          # Use HTTP transport
PORT=3001                    # Custom port

¿Necesitas un checkout Swell avanzado?

Este servidor MCP demuestra el tipo de integraciones Swell sofisticadas que impulsan CheckoutJet - una solución de checkout de nivel empresarial para tiendas Swell creada por Devkind.

CheckoutJet transforma tu checkout Swell con:

• 🏢 Excelencia B2B - Facturación profesional, pagos Net 30 y precios al por mayor
• 📦 Envío inteligente - Tarifas en vivo desde múltiples ubicaciones con enrutamiento inteligente de pedidos
• ⚡ Entregas divididas - Gestión de cumplimiento complejo multi-vendedor y multi-almacén
• 🎨 Personalización completa - Experiencia de checkout perfecta y acorde a tu marca
• 🤖 Automatización - Facturación automatizada, órdenes de compra y gestión de pedidos
• 💰 Precios avanzados - Descuentos dinámicos y lógica de precios escalonados

Resultados comprobados: Más de €500,000 procesados para comerciantes Swell con mejoras del 23% en la tasa de conversión.

¿Listo para mejorar tu checkout Swell? Reserva una demo de 15 minutos

¿Qué es MCP?

Model Context Protocol (MCP) es un estándar abierto para conectar de forma segura sistemas de IA a herramientas y fuentes de datos externas. Este servidor implementa la especificación MCP para proporcionar a los asistentes de IA acceso integral a la plataforma de comercio electrónico de Swell, permitiendo gestión inteligente de tiendas y automatización del servicio al cliente.

Primeros pasos

Primero, instala el servidor Swell MCP con tu asistente de IA o cliente MCP.

Requisitos

• Node.js 18 o superior
• VS Code, Cursor, Windsurf, Claude Desktop o cualquier otro cliente MCP
• Credenciales de la tienda Swell (Store ID y Secret Key)

Configuración estándar funciona en la mayoría de los clientes MCP:

{
	"mcpServers": {
		"swell-mcp": {
			"command": "npx",
			"args": ["swell-mcp"],
			"env": {
				"DEBUG": "false",
				"SWELL_STORE_ID": "your_store_id",
				"SWELL_SECRET_KEY": "your_private_token"
			},
			"disabled": false
		}
	}
}

{
	"mcpServers": {
		"swell-mcp": {
			"command": "npx",
			"args": ["swell-mcp"],
			"env": {
				"SWELL_STORE_ID": "your_store_id",
				"SWELL_SECRET_KEY": "your_private_token"
			}
		}
	}
}

# For VS Code
code --add-mcp '{"name":"swell-mcp","command":"npx","args":["swell-mcp"],"env":{"SWELL_STORE_ID":"your_store_id","SWELL_SECRET_KEY":"your_private_token"}}'

{
	"mcpServers": {
		"swell-mcp": {
			"command": "npx",
			"args": ["swell-mcp"],
			"env": {
				"SWELL_STORE_ID": "your_store_id",
				"SWELL_SECRET_KEY": "your_private_token"
			}
		}
	}
}

Configuración

Cómo obtener tus credenciales de Swell

1. Inicia sesión en tu panel de Swell en login.swell.store
2. Navega a Developer → API Keys
3. Copia tu Store ID (este es tu SWELL_STORE_ID)
4. Copia tu Secret Key (esta es tu SWELL_SECRET_KEY - usa la clave de backend/admin, no la clave pública)

Variables de entorno

• SWELL_STORE_ID: Tu identificador de tienda Swell (obligatorio)
• SWELL_SECRET_KEY: Tu clave secreta/privada de Swell (obligatorio)
• DEBUG: Establece en "true" para habilitar el modo de depuración con respuestas JSON sin procesar (opcional)

Ejemplo de configuración

{
	"mcpServers": {
		"swell-mcp": {
			"command": "npx",
			"args": ["swell-mcp"],
			"env": {
				"DEBUG": "false",
				"SWELL_STORE_ID": "my-awesome-store",
				"SWELL_SECRET_KEY": "sk_live_abc123def456..."
			},
			"disabled": false
		}
	}
}

Uso

Una vez instalado en tu cliente MCP (consulta Primeros pasos arriba), puedes usar las herramientas Swell MCP directamente a través de tu asistente de IA:

Ejemplos de interacción

"List my active products"
→ Uses swell_list_products with active=true

"Show me pending orders from this week"
→ Uses swell_list_orders with status=pending and date filtering

"Update customer John Doe's email to john@example.com"
→ Uses swell_update_customer to modify customer information

"Check inventory for product ID abc123"
→ Uses swell_check_inventory for stock levels

Modo de depuración

Habilita el modo de depuración para ver respuestas JSON sin procesar en lugar de la salida formateada:

{
	"env": {
		"DEBUG": "true",
		"SWELL_STORE_ID": "your_store_id",
		"SWELL_SECRET_KEY": "your_private_token"
	}
}

Modos de transporte

Transporte STDIO

• Comunicación JSON-RPC a través de stdin/stdout
• Usado por Claude Desktop, Cursor AI y otros asistentes de IA locales
• Ejecutar con: TRANSPORT_MODE=stdio node dist/index.js

Transporte HTTP transmisible

• Transporte basado en HTTP con Server-Sent Events (SSE)
• Soporta múltiples conexiones concurrentes e integraciones web
• Se ejecuta en el puerto 3000 por defecto (configurable mediante la variable de entorno PORT)
• Endpoint MCP: http://localhost:3000/mcp
• Verificación de salud: http://localhost:3000/ → Devuelve la versión del servidor
• Ejecutar con: TRANSPORT_MODE=http node dist/index.js

Descripción general de la arquitectura

src/
├── cli/                    # Command-line interfaces
│   └── index.ts            # CLI entry point with Commander setup
├── controllers/            # Business logic orchestration
│   ├── swell.products.controller.ts    # Product management logic
│   ├── swell.products.formatter.ts     # Product response formatting
│   ├── swell.orders.controller.ts      # Order management logic
│   ├── swell.orders.formatter.ts       # Order response formatting
│   ├── swell.customers.controller.ts   # Customer management logic
│   └── swell.customers.formatter.ts    # Customer response formatting
├── services/               # External API interactions
│   ├── swell.products.service.ts       # Swell products API service
│   ├── swell.products.types.ts         # Product type definitions
│   ├── swell.orders.service.ts         # Swell orders API service
│   ├── swell.orders.types.ts           # Order type definitions
│   ├── swell.customers.service.ts      # Swell customers API service
│   └── swell.customers.types.ts        # Customer type definitions
├── tools/                  # MCP tool definitions (AI interface)
│   ├── swell.products.tool.ts          # Product management tools
│   ├── swell.orders.tool.ts            # Order management tools
│   └── swell.customers.tool.ts         # Customer management tools
├── types/                  # Global type definitions
│   └── common.types.ts     # Shared interfaces (ControllerResponse, etc.)
├── utils/                  # Shared utilities
│   ├── logger.util.ts      # Contextual logging system
│   ├── error.util.ts       # MCP-specific error formatting
│   ├── error-handler.util.ts # Error handling utilities
│   ├── config.util.ts      # Environment configuration
│   ├── constants.util.ts   # Version and package constants
│   ├── formatter.util.ts   # Markdown formatting
│   ├── swell-client.util.ts # Swell SDK client wrapper
│   └── transport.util.ts   # HTTP transport utilities
└── index.ts                # Server entry point (dual transport)

Arquitectura de 5 capas

El servidor sigue una arquitectura limpia y en capas que promueve la mantenibilidad y una clara separación de responsabilidades:

1. Capa CLI (src/cli/)

• Propósito: Interfaces de línea de comandos para uso directo de herramientas y pruebas
• Implementación: Análisis de argumentos basado en Commander con manejo de errores contextual
• Ejemplo: list-products --active --category electronics
• Patrón: Registrar comandos → Analizar argumentos → Llamar controladores → Manejar errores

2. Capa de herramientas (src/tools/)

• Propósito: Definiciones de herramientas MCP que los asistentes de IA pueden invocar
• Implementación: Validación de esquemas Zod con respuestas estructuradas
• Ejemplo: Herramienta swell_list_products con opciones de filtrado y paginación
• Patrón: Definir esquema → Validar argumentos → Llamar controlador → Formatear respuesta MCP

3. Capa de recursos (src/resources/)

• Propósito: Recursos MCP que proporcionan datos contextuales accesibles mediante URIs (característica planificada)
• Implementación: Manejadores de recursos que responden a solicitudes basadas en URI
• Ejemplo: Recurso swell://products/123 que proporciona detalles del producto
• Patrón: Registrar patrones URI → Analizar solicitudes → Devolver contenido formateado

4. Capa de controladores (src/controllers/)

• Propósito: Orquestación de lógica de negocio con manejo integral de errores
• Implementación: Validación de opciones, lógica de respaldo, formato de respuestas
• Ejemplo: Gestión de productos con seguimiento de inventario, procesamiento de pedidos con actualizaciones de estado
• Patrón: Validar entradas → Aplicar valores predeterminados → Llamar servicios → Formatear respuestas

5. Capa de servicios (src/services/)

• Propósito: Interacciones directas con API externas con lógica de negocio mínima
• Implementación: Utilidades de transporte HTTP con manejo estructurado de errores
• Ejemplo: Llamadas a la API de Swell con autenticación y validación de datos
• Patrón: Construir solicitudes → Realizar llamadas API → Validar respuestas → Devolver datos sin procesar

6. Capa de utilidades (src/utils/)

• Propósito: Funcionalidad compartida en todas las capas
• Componentes clave:
  • logger.util.ts: Registro contextual (contexto archivo:método)
  • error.util.ts: Formato de errores específico de MCP
  • transport.util.ts: Utilidades HTTP/API con lógica de reintentos
  • config.util.ts: Gestión de configuración de entorno

Configuración de desarrollo

Para desarrolladores que quieran contribuir o modificar el servidor:

Requisitos previos

• Node.js (>=18.x): Descargar
• Git: Para control de versiones

Inicio rápido

# Clone the repository
git clone https://github.com/devkindhq/swell-mcp.git
cd swell-mcp

# Install dependencies
npm install

# Configure your Swell credentials
cp .env.example .env
# Edit .env and add your SWELL_STORE_ID and SWELL_SECRET_KEY

# Build the project
npm run build

# Run in different modes:

# 1. STDIO Transport - For AI assistant integration (Claude Desktop, Cursor)
npm run mcp:stdio

# 2. HTTP Transport - For web-based integrations
npm run mcp:http

# 3. Development with MCP Inspector
npm run mcp:inspect                         # Auto-opens browser with debugging UI

Scripts de desarrollo

# Build and Clean
npm run build               # Build TypeScript to dist/
npm run clean               # Remove dist/ and coverage/
npm run prepare             # Build + ensure executable permissions (for npm publish)

# CLI Testing (coming soon)
# npm run cli -- list-products --active                   # List active products
# npm run cli -- get-product <product-id>                 # Get product details
# npm run cli -- list-orders --status pending             # List pending orders

# MCP Server Modes
npm run mcp:stdio           # STDIO transport for AI assistants
npm run mcp:http            # HTTP transport on port 3000
npm run mcp:inspect         # HTTP + auto-open MCP Inspector

# Development with Debugging
npm run dev:stdio           # STDIO with MCP Inspector integration
npm run dev:http            # HTTP with debug logging enabled

# Testing
npm test                    # Run all tests (Jest)
npm run test:coverage       # Generate coverage report
npm run test:cli            # Run CLI-specific tests

# Code Quality
npm run lint                # ESLint with TypeScript rules
npm run format              # Prettier formatting
npm run update:deps         # Update dependencies

Variables de entorno

Configuración principal

• TRANSPORT_MODE: Modo de transporte (stdio | http, predeterminado: stdio)
• PORT: Puerto del servidor HTTP (predeterminado: 3000)
• DEBUG: Habilitar registro de depuración (true | false, predeterminado: false)

Configuración de la API de Swell

• SWELL_STORE_ID: Tu ID de tienda Swell (obligatorio)
• SWELL_SECRET_KEY: Tu clave secreta de Swell (obligatorio)

Ejemplo de archivo .env

# Basic configuration
TRANSPORT_MODE=http
PORT=3001
DEBUG=true

# Swell API credentials (required)
SWELL_STORE_ID=your-store-id
SWELL_SECRET_KEY=your-secret-key

Herramientas de depuración

• MCP Inspector: Herramienta visual para probar tus herramientas MCP

  • Ejecuta el servidor con npm run mcp:inspect
  • Abre la URL que se muestra en la terminal
  • Prueba tus herramientas de forma interactiva

• Registro de depuración: Habilítalo con la variable de entorno DEBUG=true

{
	"swell-mcp": {
		"environments": {
			"DEBUG": "true",
			"TRANSPORT_MODE": "http",
			"PORT": "3000",
			"SWELL_STORE_ID": "your-store-id",
			"SWELL_SECRET_KEY": "your-secret-key"
		}
	}
}

Herramientas disponibles

El servidor Swell MCP proporciona herramientas integrales de gestión de comercio electrónico para asistentes de IA. La lista siguiente coincide con los nombres de herramientas y esquemas de parámetros implementados bajo src/tools/.

Extendiendo el Servidor

Este servidor está construido con una arquitectura modular que facilita agregar nuevas integraciones de la API de Swell o lógica de negocio personalizada. Las herramientas existentes de Swell (productos, pedidos, clientes) sirven como ejemplos para implementar funcionalidad adicional.

Para patrones de implementación detallados, consulta los controladores, servicios y herramientas existentes en el código base.

Uso Independiente

Si deseas ejecutar el servidor de forma independiente (no a través de un cliente MCP):

Instalación Global

npm install -g swell-mcp

Uso Directo

# Set your credentials
export SWELL_STORE_ID=your-store-id
export SWELL_SECRET_KEY=your-secret-key

# Run the server
swell-mcp

Modo HTTP

# Run with HTTP transport on port 3000
TRANSPORT_MODE=http swell-mcp

# Custom port
PORT=8080 TRANSPORT_MODE=http swell-mcp

🚀 Lleva tu Tienda Swell Más Allá

¿Impresionado por las capacidades de este servidor MCP? Esto es solo un vistazo de lo que es posible con desarrollo experto de Swell.

CheckoutJet - Checkout Empresarial para Swell

Transforma tu tienda Swell con nuestra solución de checkout probada en batalla:

• Potencia B2B - Facturación profesional, pagos Net 30, precios al por mayor
• Envío Inteligente - Tarifas en vivo desde múltiples ubicaciones con enrutamiento inteligente
• Entregas Divididas - Cumplimiento complejo de múltiples proveedores y múltiples almacenes
• Personalización Completa - Experiencia de checkout perfecta y acorde a tu marca
• Resultados Comprobados - Más de €500,000 procesados, mejoras del 23% en conversión

Ver CheckoutJet en Acción →

🤖 IA y Desarrollo Personalizado

• Integraciones impulsadas por IA como este servidor MCP
• Aplicaciones y temas personalizados de Swell
• Implementaciones de comercio headless
• Optimización de rendimiento y automatización

¿Listo para transformar tu negocio de comercio electrónico?

Estrategia de Pruebas

El servidor incluye infraestructura integral de pruebas:

Estructura de Pruebas

tests/               # Not present - tests are in src/
src/
├── **/*.test.ts     # Co-located with source files
├── utils/           # Utility function tests
├── controllers/     # Business logic tests
├── services/        # API integration tests
└── cli/             # CLI command tests

Mejores Prácticas de Pruebas

• Pruebas Unitarias: Probar utilidades y funciones puras (*.util.test.ts)
• Pruebas de Controladores: Probar lógica de negocio con llamadas de servicio simuladas
• Pruebas de Servicios: Probar integración de API con llamadas HTTP reales/simuladas
• Pruebas CLI: Probar análisis y ejecución de comandos
• Detección de Entorno de Pruebas: Manejo automático del modo de prueba en controladores

Ejecución de Pruebas

npm test                    # Run all tests
npm run test:coverage       # Generate coverage report
npm run test:cli           # CLI-specific tests only

Objetivos de Cobertura

• Objetivo: >80% de cobertura de pruebas
• Enfocarse en lógica de negocio (controladores) y utilidades
• Simular servicios externos de manera apropiada

Licencia

Licencia ISC

Recursos y Documentación

Recursos del Protocolo MCP

• Especificación MCP
• Documentación del SDK MCP
• Inspector MCP - Herramienta de depuración visual

Referencias de Implementación

• Anuncio MCP de Anthropic
• Servidores MCP Increíbles - Ejemplos de la comunidad
• Documentación de TypeScript

Recursos de Swell

• Documentación de Swell - Documentación oficial de la API
• SDK de Node para Swell - El SDK subyacente utilizado por este servidor

Servicios Profesionales de Swell

¿Buscas desarrollo experto de Swell? Devkind es un socio oficial de Swell que atiende a empresas a nivel global con nuestro equipo remoto, especializado en:

• CheckoutJet - Solución de checkout empresarial con B2B, automatización de envíos y entregas divididas
• Servicios de Desarrollo de Swell - Aplicaciones, temas e integraciones personalizadas
• Comercio Headless - Tiendas y experiencias impulsadas por API

Comienza Ahora: Ver Demo de CheckoutJet | Reservar consulta GRATIS | Correo electrónico: hello@devkind.com.au | Equipo Remoto Global