🛒 Yampi MCP Server

Servidor MCP (Model Context Protocol) para integração com a plataforma de e-commerce Yampi, permitindo que assistentes de IA como Claude acessem e gerenciem sua loja Yampi de forma inteligente.

✨ Funcionalidades

📊 Resources (Dados)

• Informações da loja: Configurações e dados básicos
• Catálogo de produtos: Lista paginada com filtros
• Pedidos: Histórico e status de pedidos

🛠️ Tools (Ações)

• Gerenciar produtos: Criar, atualizar e consultar produtos
• Buscar pedidos: Filtrar por status, data e cliente
• Webhooks: Configurar notificações automáticas
• Cupons: Criar cupons de desconto
• Analytics: Obter métricas de vendas

💬 Prompts (Templates)

• Análise de vendas: Relatórios inteligentes de performance
• Relatório de produtos: Insights sobre catálogo
• Recuperação de carrinho: Estratégias de re-engajamento

🚀 Instalação

1. Configurar o projeto

# Clonar/criar diretório
mkdir yampi-mcp-server && cd yampi-mcp-server

# Instalar dependências
npm install

# Compilar TypeScript
npm run build

2. Obter credenciais do Yampi

Para usar este servidor, você precisa das credenciais da API do Yampi:

1. Acesse o painel da sua loja Yampi
2. Vá em "Configurações" → "API" ou clique no avatar → "Credenciais da API"
3. Anote as seguintes informações:
   • Nome (alias da loja)
   • API Token
   • Secret Key

3. Configurar variáveis de ambiente

Opção A: Arquivo .env (recomendado para desenvolvimento)

# Copie o arquivo de exemplo
cp env.example .env

# Edite o arquivo .env com suas credenciais
YAMPI_API_TOKEN=seu_token_da_api_yampi_aqui
YAMPI_ALIAS=seu_alias_da_loja_yampi_aqui

Opção B: Variáveis do sistema

# Linux/Mac
export YAMPI_ALIAS="sua-loja"
export YAMPI_USER_TOKEN="seu-api-token"
export YAMPI_USER_SECRET_KEY="sua-secret-key"

# Windows (PowerShell)
$env:YAMPI_ALIAS="sua-loja"
$env:YAMPI_USER_TOKEN="seu-api-token"
$env:YAMPI_USER_SECRET_KEY="sua-secret-key"

# Opcional: URL personalizada
export YAMPI_BASE_URL="https://api.dooki.com.br/v2"

⚠️ Importante sobre segurança:

• O arquivo .env está no .gitignore e não será commitado
• Em produção, use variáveis de ambiente do sistema
• Nunca exponha suas credenciais em código ou repositórios públicos

4. Configurar no Claude Desktop

Adicione no seu claude_desktop_config.json:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "yampi": {
      "command": "node",
      "args": ["/caminho/para/yampi-mcp-server/dist/index.js"],
      "env": {
        "YAMPI_ALIAS": "sua-loja",
        "YAMPI_USER_TOKEN": "seu-api-token",
        "YAMPI_USER_SECRET_KEY": "sua-secret-key"
      }
    }
  }
}

5. Testar a conexão

# Testar o servidor
npm run start

# Usar o inspector para debug
npm run inspector

💡 Exemplos de Uso

📊 Consultar dados

# No Claude Desktop:
"Mostre-me as informações da minha loja"
"Liste os últimos produtos cadastrados"
"Quais são os pedidos pendentes hoje?"

🛠️ Executar ações

"Crie um produto chamado 'Camiseta Básica' com SKU 'CAM-001' por R$ 29,90"
"Busque todos os pedidos pagos dos últimos 7 dias"
"Configure um webhook para notificar sobre novos pedidos"
"Crie um cupom de 15% de desconto com código 'PROMO15'"

💬 Usar templates

"Execute uma análise de vendas dos últimos 30 dias"
"Gere um relatório de produtos com foco em estoque baixo"
"Crie uma estratégia de recuperação de carrinho para clientes jovens"

🔧 Desenvolvimento

Estrutura do projeto

yampi-mcp-server/
├── src/
│   ├── index.ts          # Servidor MCP principal
│   └── yampi-client.ts   # Cliente da API Yampi
├── dist/                 # Código compilado
├── package.json
├── tsconfig.json
└── README.md

Scripts disponíveis

npm run build      # Compilar TypeScript
npm run start      # Executar servidor
npm run dev        # Desenvolvimento com watch
npm run inspector  # Debug com MCP Inspector

Adicionar novos recursos

1. Resource: Adicione um novo server.registerResource() em src/index.ts
2. Tool: Adicione um novo server.registerTool() com schema de validação
3. Prompt: Adicione um novo server.registerPrompt() com template

🛡️ Segurança

• ✅ Credenciais por variáveis de ambiente
• ✅ Validação de entrada com Zod
• ✅ Tratamento de erros robusto
• ✅ Logs de operações

⚠️ Mantenha suas credenciais seguras e nunca as compartilhe em código público!

📚 APIs Yampi Suportadas

| Categoria | Endpoints | Status | |-----------|-----------|---------| | Catálogo | /products, /categories | ✅ | | Pedidos | /orders | ✅ | | Webhooks | /webhooks | ✅ | | Marketing | /coupons | ✅ | | Configurações | /configurations | ✅ | | Relatórios | /reports/sales | ✅ | | Clientes | /customers | 🔄 Em desenvolvimento | | Checkout | /checkout | 🔄 Planejado |

🤝 Contribuição

1. Fork este repositório
2. Crie sua feature branch (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -am 'Adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

📖 Recursos Úteis

• 📘 Documentação do MCP
• 🛒 API do Yampi
• 🤖 Claude Desktop
• 🔧 SDK TypeScript MCP

📄 Licença

MIT License - veja LICENSE para detalhes.

💬 Suporte

• Issues: GitHub Issues
• Discussões: GitHub Discussions
• Email: [email protected]

🚀 Construído com amor para a comunidade brasileira de e-commerce!