Swell MCP

Servidor Swell MCP

Um servidor Model Context Protocol que integra assistentes de IA com a plataforma de e-commerce da Swell. Construído sobre uma base TypeScript pronta para produção, fornece acesso abrangente às lojas Swell para gerenciamento de produtos, processamento de pedidos e gerenciamento de clientes por meio de interfaces de ferramentas CLI e MCP.

Construído por Devkind - Parceiros oficiais da Swell atendendo empresas globalmente com soluções de e-commerce de ponta.

Recursos

• Integração com E-commerce Swell: Acesso completo à API da Swell para produtos, pedidos e clientes
• Suporte a Transporte Duplo: Transportes STDIO e HTTP para integração com assistentes de IA e web
• Arquitetura em 5 Camadas: Separação limpa entre CLI, ferramentas, controladores, serviços e utilitários
• Segurança de Tipos: Implementação completa em TypeScript com validação de esquema Zod
• Cliente HTTP Avançado: Construído sobre o SDK swell-node com pooling de conexões e lógica de repetição
• Testes Abrangentes: Testes unitários e de integração com simulação da API Swell
• Ferramentas de Produção: Integração com ESLint, Prettier, semantic-release e MCP Inspector
• Tratamento de Erros: Tratamento estruturado de erros com contextos de erro específicos da Swell

Integração com E-commerce Swell

Este servidor MCP fornece integração abrangente com a plataforma de e-commerce da Swell:

Ferramentas e Comandos Disponíveis

Ferramentas MCP:

• swell_list_products - Listar produtos com filtragem e paginação
• swell_get_product - Obter informações detalhadas do produto
• swell_search_products - Pesquisar produtos com múltiplos critérios
• swell_check_inventory - Verificar níveis de inventário do produto
• swell_list_orders - Listar pedidos com opções de filtragem
• swell_get_order - Obter informações detalhadas do pedido
• swell_update_order_status - Atualizar status do pedido
• swell_list_customers - Listar clientes com recursos de pesquisa
• swell_get_customer - Obter informações detalhadas do cliente
• swell_search_customers - Pesquisar clientes com múltiplos critérios

Recursos Demonstrados

• Gerenciamento de Produtos: Acesso completo ao catálogo de produtos com rastreamento de inventário
• Processamento de Pedidos: Gerenciamento do ciclo de vida do pedido com atualizações de status
• Gerenciamento de Clientes: Perfis de clientes com histórico de pedidos e análises
• Tratamento de Erros: Erros estruturados para falhas de API e problemas de validação
• Formatação de Respostas: Saída Markdown limpa com tabelas de dados estruturados

Requisitos de Configuração

# 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

Precisa de um Checkout Swell Avançado?

Este servidor MCP demonstra o tipo de integrações Swell sofisticadas que alimentam o CheckoutJet - uma solução de checkout de nível empresarial para lojas Swell construída pela Devkind.

CheckoutJet transforma seu checkout Swell com:

• 🏢 Excelência B2B - Faturamento profissional, pagamentos Net 30 e preços de atacado
• 📦 Envio Inteligente - Tarifas em tempo real de múltiplas localizações com roteamento inteligente de pedidos
• ⚡ Entregas Divididas - Lidar com atendimento complexo de múltiplos fornecedores e múltiplos armazéns
• 🎨 Personalização Completa - Experiência de checkout perfeita em pixels e alinhada à marca
• 🤖 Automação - Faturamento automatizado, POs e gerenciamento de pedidos
• 💰 Preços Avançados - Descontos dinâmicos e lógica de preços escalonados

Resultados Comprovados: Mais de €500.000 processados para comerciantes Swell com melhorias de 23% na taxa de conversão.

Pronto para atualizar seu checkout Swell? Agende uma demonstração de 15 minutos

O que é MCP?

Model Context Protocol (MCP) é um padrão aberto para conectar com segurança sistemas de IA a ferramentas externas e fontes de dados. Este servidor implementa a especificação MCP para fornecer aos assistentes de IA acesso abrangente à plataforma de e-commerce da Swell, permitindo gerenciamento inteligente de loja e automação de atendimento ao cliente.

Primeiros Passos

Primeiro, instale o servidor Swell MCP com seu assistente de IA ou cliente MCP.

Requisitos

• Node.js 18 ou mais recente
• VS Code, Cursor, Windsurf, Claude Desktop ou qualquer outro cliente MCP
• Credenciais da loja Swell (Store ID e Secret Key)

Configuração padrão funciona na maioria dos 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"
			}
		}
	}
}

Configuração

Obtendo Suas Credenciais Swell

1. Faça login no seu painel Swell em login.swell.store
2. Navegue até Developer → API Keys
3. Copie seu Store ID (este é o seu SWELL_STORE_ID)
4. Copie sua Secret Key (esta é a sua SWELL_SECRET_KEY - use a chave de backend/admin, não a chave pública)

Variáveis de Ambiente

• SWELL_STORE_ID: Seu identificador de loja Swell (obrigatório)
• SWELL_SECRET_KEY: Sua chave secreta/privada Swell (obrigatória)
• DEBUG: Defina como "true" para ativar o modo de depuração com respostas JSON brutas (opcional)

Exemplo de Configuração

{
	"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

Depois de instalado no seu cliente MCP (veja Primeiros Passos acima), você pode usar as ferramentas Swell MCP diretamente por meio do seu assistente de IA:

Exemplos de Interações

"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 Depuração

Ative o modo de depuração para ver respostas JSON brutas em vez de saída formatada:

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

Modos de Transporte

Transporte STDIO

• Comunicação JSON-RPC via stdin/stdout
• Usado por Claude Desktop, Cursor AI e outros assistentes de IA locais
• Execute com: TRANSPORT_MODE=stdio node dist/index.js

Transporte HTTP Streamable

• Transporte baseado em HTTP com Server-Sent Events (SSE)
• Suporta múltiplas conexões concorrentes e integrações web
• Executa na porta 3000 por padrão (configurável via variável de ambiente PORT)
• Endpoint MCP: http://localhost:3000/mcp
• Verificação de Saúde: http://localhost:3000/ → Retorna a versão do servidor
• Execute com: TRANSPORT_MODE=http node dist/index.js

Visão Geral da Arquitetura

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)

Arquitetura em 5 Camadas

O servidor segue uma arquitetura limpa e em camadas que promove a manutenibilidade e a separação clara de responsabilidades:

1. Camada CLI (src/cli/)

• Propósito: Interfaces de linha de comando para uso direto de ferramentas e testes
• Implementação: Análise de argumentos baseada em Commander com tratamento contextual de erros
• Exemplo: list-products --active --category electronics
• Padrão: Registrar comandos → Analisar argumentos → Chamar controladores → Tratar erros

2. Camada de Ferramentas (src/tools/)

• Propósito: Definições de ferramentas MCP que assistentes de IA podem invocar
• Implementação: Validação de esquema Zod com respostas estruturadas
• Exemplo: ferramenta swell_list_products com opções de filtragem e paginação
• Padrão: Definir esquema → Validar argumentos → Chamar controlador → Formatar resposta MCP

3. Camada de Recursos (src/resources/)

• Propósito: Recursos MCP que fornecem dados contextuais acessíveis via URIs (recurso planejado)
• Implementação: Manipuladores de recursos que respondem a solicitações baseadas em URI
• Exemplo: recurso swell://products/123 fornecendo detalhes do produto
• Padrão: Registrar padrões de URI → Analisar solicitações → Retornar conteúdo formatado

4. Camada de Controladores (src/controllers/)

• Propósito: Orquestração de lógica de negócios com tratamento abrangente de erros
• Implementação: Validação de opções, lógica de fallback, formatação de respostas
• Exemplo: Gerenciamento de produtos com rastreamento de inventário, processamento de pedidos com atualizações de status
• Padrão: Validar entradas → Aplicar padrões → Chamar serviços → Formatar respostas

5. Camada de Serviços (src/services/)

• Propósito: Interações diretas com APIs externas com lógica de negócios mínima
• Implementação: Utilitários de transporte HTTP com tratamento estruturado de erros
• Exemplo: Chamadas à API Swell com autenticação e validação de dados
• Padrão: Construir solicitações → Fazer chamadas de API → Validar respostas → Retornar dados brutos

6. Camada de Utilitários (src/utils/)

• Propósito: Funcionalidade compartilhada em todas as camadas
• Componentes Principais:
  • logger.util.ts: Registro contextual (contexto arquivo:método)
  • error.util.ts: Formatação de erros específica do MCP
  • transport.util.ts: Utilitários HTTP/API com lógica de repetição
  • config.util.ts: Gerenciamento de configuração de ambiente

Configuração de Desenvolvimento

Para desenvolvedores que desejam contribuir ou modificar o servidor:

Pré-requisitos

• Node.js (>=18.x): Baixar
• Git: Para controle de versão

Início 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 Desenvolvimento

# 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

Variáveis de Ambiente

Configuração Principal

• TRANSPORT_MODE: Modo de transporte (stdio | http, padrão: stdio)
• PORT: Porta do servidor HTTP (padrão: 3000)
• DEBUG: Ativar registro de depuração (true | false, padrão: false)

Configuração da API Swell

• SWELL_STORE_ID: Seu ID de loja Swell (obrigatório)
• SWELL_SECRET_KEY: Sua chave secreta Swell (obrigatória)

Exemplo de Arquivo .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

Ferramentas de Depuração

• MCP Inspector: Ferramenta visual para testar suas ferramentas MCP

  • Execute o servidor com npm run mcp:inspect
  • Abra a URL exibida no terminal
  • Teste suas ferramentas interativamente

• Registro de Depuração: Ative com a variável de ambiente DEBUG=true

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

Ferramentas Disponíveis

O servidor Swell MCP fornece ferramentas abrangentes de gerenciamento de e-commerce para assistentes de IA. A lista abaixo corresponde aos nomes das ferramentas e esquemas de parâmetros implementados em src/tools/.

Estendendo o Servidor

Este servidor é construído com uma arquitetura modular que facilita a adição de novas integrações com a API Swell ou lógica de negócios personalizada. As ferramentas Swell existentes (produtos, pedidos, clientes) servem como exemplos para implementar funcionalidades adicionais.

Para padrões de implementação detalhados, consulte os controllers, services e tools existentes no código-fonte.

Uso Independente

Se você quiser executar o servidor de forma independente (não através de um cliente MCP):

Instalação Global

npm install -g swell-mcp

Uso Direto

# 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

🚀 Leve Sua Loja Swell Além

Impressionado com as capacidades deste servidor MCP? Isso é apenas um vislumbre do que é possível com desenvolvimento Swell especializado.

🛒 CheckoutJet - Checkout Swell Empresarial

Transforme sua loja Swell com nossa solução de checkout testada em batalha:

• Potência B2B - Faturamento profissional, pagamentos Net 30, preços de atacado
• Envio Inteligente - Tarifas em tempo real de múltiplas localidades com roteamento inteligente
• Entregas Divididas - Atendimento complexo multi-vendedor e multi-armazém
• Personalização Total - Experiência de checkout perfeita e alinhada à marca
• Resultados Comprovados - €500.000+ processados, melhorias de 23% na conversão

Veja o CheckoutJet em Ação →

🤖 IA e Desenvolvimento Personalizado

• Integrações com IA como este servidor MCP
• Aplicativos e temas Swell personalizados
• Implementações de comércio headless
• Otimização de desempenho e automação

Pronto para transformar seu negócio de e-commerce?

Estratégia de Testes

O servidor inclui infraestrutura abrangente de testes:

Estrutura de Testes

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

Boas Práticas de Teste

• Testes Unitários: Testar utilitários e funções puras (*.util.test.ts)
• Testes de Controllers: Testar lógica de negócios com chamadas de serviço simuladas
• Testes de Services: Testar integração de API com chamadas HTTP reais/simuladas
• Testes de CLI: Testar análise e execução de comandos
• Detecção de Ambiente de Teste: Tratamento automático de modo de teste nos controllers

Executando Testes

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

Metas de Cobertura

• Meta: >80% de cobertura de testes
• Foco em lógica de negócios (controllers) e utilitários
• Simular serviços externos adequadamente

Licença

Licença ISC

Recursos e Documentação

Recursos do Protocolo MCP

• Especificação MCP
• Documentação do SDK MCP
• Inspetor MCP - Ferramenta de depuração visual

Referências de Implementação

• Anúncio MCP da Anthropic
• Servidores MCP Incríveis - Exemplos da comunidade
• Documentação TypeScript

Recursos Swell

• Documentação Swell - Documentação oficial da API
• SDK Node Swell - O SDK subjacente usado por este servidor

Serviços Profissionais Swell

Procurando desenvolvimento Swell especializado? Devkind é um parceiro oficial Swell que atende empresas globalmente com nossa equipe remota, especializada em:

• CheckoutJet - Solução de checkout empresarial com B2B, automação de envio e entregas divididas
• Serviços de Desenvolvimento Swell - Aplicativos personalizados, temas e integrações
• E-commerce Headless - Vitrines e experiências orientadas por API

Comece Agora: Veja a Demonstração do CheckoutJet | Agende uma consulta GRATUITA | E-mail: hello@devkind.com.au | Equipe Remota Global