Kawakami MCP Server

MCP Server que expõe o catálogo do Supermercados Kawakami (Paraguaçu Paulista/SP) como ferramentas para Claude, ChatGPT, OpenCode e qualquer cliente MCP.

Arquitetura

Cliente MCP (ChatGPT/Claude/OpenCode)
        │
        ▼
Cloudflare Tunnel (kawakami.axischat.com.br)
        │
        ▼
FastMCP (Python) ← httpx → VIP Commerce API
        │
        ▼
SQLite (sessoes/carrinho/listas)

src/
├── main.py                 # Entrypoint + argparse
├── server.py               # FastMCP + tool registration
├── config.py               # Settings via env vars
├── domain/
│   ├── models.py           # Produto, Oferta, CarrinhoItem...
│   └── exceptions.py       # VipCommerceUnavailable, TokenExpired...
├── infrastructure/
│   ├── auth.py             # TokenManager (load/save/refresh)
│   ├── vipcommerce_client.py  # HTTP client + retry + cache + circuit breaker
│   ├── session_store.py    # SQLite-backed sessions
│   ├── circuit_breaker.py  # Circuit breaker state machine
│   ├── validation.py       # Input sanitization
│   └── error_handler.py    # @safe_tool decorator
├── presentation/
│   └── formatters.py       # Text formatting
└── tools/
    ├── busca.py            # buscar_produtos, buscar_por_ean
    ├── catalogo.py         # listar_departamentos, produtos_por_departamento, detalhes_produto
    ├── ofertas.py          # ofertas_do_dia, verificar_estoque
    ├── carrinho.py         # adicionar, ver, remover, limpar
    └── listas.py           # salvar, minhas, ver, excluir

Deploy rápido

cp .env.example .env   # Preencha KWK_VIP_TOKEN e KWK_VIP_SESSAO_ID
make up                # Build + sobe API + tunnel

Tools (16)

Tool	Descrição
criar_sessao	Cria um identificador isolado para carrinho e listas
buscar_produtos	Busca produtos por nome
buscar_por_ean	Busca por código de barras
listar_departamentos	Lista departamentos com contagem
produtos_por_departamento	Produtos de um departamento
detalhes_produto	Detalhes completos por ID
ofertas_do_dia	Ranking de melhores ofertas
verificar_estoque	Estoque de um produto
adicionar_ao_carrinho	Adiciona item ao carrinho
ver_carrinho	Mostra carrinho atual
remover_do_carrinho	Remove item do carrinho
limpar_carrinho	Esvazia carrinho
salvar_lista	Salva lista de compras
minhas_listas	Lista listas salvas
ver_lista	Detalha uma lista
excluir_lista	Remove uma lista

As tools de carrinho e listas exigem o session_id retornado por criar_sessao. O identificador é uma capacidade privada: não compartilhe entre usuários ou conversas.

MCP Apps UI

As tools de produtos e ofertas retornam texto e structuredContent. Clientes compatíveis com MCP Apps carregam o resource ui://kawakami/catalog-v2.html.

Para desenvolver a interface:

cd ui
npm ci
npm run lint
npm run build

O build Vite é embutido no resource MCP. A imagem Docker compila a UI automaticamente.

Variáveis de ambiente

Ver .env.example para todas as opções. Essenciais:

Var	Descrição
KWK_VIP_TOKEN	Token JWT da sessão anônima VIP Commerce
KWK_VIP_SESSAO_ID	Session ID do VIP Commerce
KWK_DEFAULT_CEP	CEP padrão (default: 19700000)
KWK_SESSION_DB_PATH	Caminho persistente do SQLite
KWK_TOKEN_FILE_PATH	Caminho persistente do token renovado
KWK_WIDGET_DOMAIN	Origem HTTPS dedicada do widget

Healthcheck

GET /health retorna {"status":"ok"} quando o processo está pronto. O endpoint não consulta a VIP Commerce, evitando reinícios durante indisponibilidade do fornecedor.

Desenvolvimento

make dev        # stdio (para testar no OpenCode/Claude Desktop)
make dev-http   # HTTP (para testar no navegador)
make test       # pytest
make lint       # ruff