Skip to main content
Glama

Defesa Pronta

Servidor MCP que confere as provas de uma contestação de compra (chargeback) contra as regras da YouShop e monta a defesa em rascunho.

Protótipo feito para o Desafio de Inovação do Programa de Estágio YouShop 2027. Dados fictícios. Não é um produto oficial da YouShop.

Painel com as três contestações abertas, ordenadas pelo prazo

O problema

Quando uma compra é contestada, o produtor tem 2 dias corridos para enviar provas (Termos de Uso, Cláusula 8.9), e a YouShop recusa provas com endereço divergente, sem identificação do recebedor, com data posterior à contestação ou com rastreio que não mostra a entrega (Cláusula 8.10). O Defesa Pronta confere tudo isso antes do envio.

Related MCP server: genpark-autonomous-refund-dispute-arbitrator-skill

Como funciona

flowchart LR
    P[Produtor] --> A["Agente (Claude)"]
    A --> F["Ferramentas MCP<br/>pedido, rastreio, conversas,<br/>logs, documentos"]
    F --> R[Motor de regras]
    R --> V{"Veredito"}
    V -->|forte| D[Dossiê em rascunho]
    V -->|incompleta| D
    V -->|vai ser recusada| D
    D --> E[Produtor revisa e envia]
  • A IA lê os documentos (imagens) e extrai o que está escrito neles.

  • As regras decidem o veredito: código determinístico e testado, que cita a cláusula de cada item.

  • O produtor envia: não existe ferramenta de envio, aprovação ou reembolso.

Prints

Contestação CB-002: veredito, o que resolver e documentos

Contestação CB-002 no painel: o veredito, o que resolver em cada item (com botão para trocar o comprovante ou anexar a nota fiscal) e os documentos.

Topo do dossiê da CB-002

Dossiê gerado em saida/dossie-CB-002.html: faixa de rascunho, veredito e o que corrigir antes de enviar.

Comprovante fictício da CB-002. O número 545 (o pedido diz 455) e a falta de RG só aparecem lendo a imagem.

Ferramentas MCP

Todas são de leitura, exceto gerar_dossie, que grava o rascunho em saida/.

Ferramenta

O que faz

listar_contestacoes

Lista as contestações abertas com prazo, horas restantes e urgência, da mais urgente para a menos urgente.

buscar_pedido

Pedido e comprador como cadastrados na compra (CPF mascarado, sem dados do cartão).

buscar_rastreio

Código, transportadora e eventos do rastreio; "não se aplica" para produto digital.

buscar_conversas

Mensagens entre produtor e comprador.

buscar_logs_acesso

Acessos do comprador à área de membros (produto digital, IP parcialmente mascarado).

buscar_documentos

Documentos da contestação como imagens, com instruções do que extrair de cada um.

conferir_provas

Roda o motor de regras sobre o que foi extraído e devolve checklist, veredito e o que corrigir.

gerar_dossie

Confere de novo e grava o dossiê em rascunho (saida/dossie-<id>.html).

Regras implementadas

Fonte: Termos de Uso da YouShop, Cláusula 8. Código em src/regras/conferir.ts.

Cláusula

Regra

8.5.A

Produto físico: nota fiscal da venda.

8.5.B

Produto físico: AR ou comprovante de entrega.

8.5.C

Produto físico: código de rastreio.

8.5.D

Produto digital: logs de acesso do comprador antes da contestação.

8.5.E

Conversas com o comprador.

8.9

Prazo de 2 dias corridos (48h) a partir da abertura; alerta com 12h ou menos.

8.10.A

AR/comprovante precisa identificar quem recebeu (sem RG = recusa).

8.10.B

Documento não pode indicar devolução.

8.10.C

Nome e endereço do documento iguais aos do pedido (diz qual campo diverge).

8.10.D

Documento não pode ser posterior à abertura da contestação.

8.10.E

Rastreio precisa mostrar a entrega antes da abertura da contestação.

Vereditos (só erros e itens faltando contam; alertas aparecem à parte e não rebaixam o veredito):

  • Defesa forte: nenhum erro e nada faltando.

  • Defesa possível, mas incompleta: falta algum item da 8.5.

  • Defesa vai ser recusada: alguma prova cai em uma regra da 8.10 ou o prazo acabou.

Como rodar

Requisitos: Node 20+ e o Claude Desktop ou o Claude Code CLI logado.

npm install
npm run gerar-docs   # gera os documentos fictícios (PNG) em data/docs/ e data/demo/
npm run build
npm test

Data simulada (AGORA). Os prazos da demo são calculados a partir de AGORA=2026-11-20T10:00:00-03:00, para a demo não "vencer". Esse é o padrão; AGORA=real usa o relógio do computador.

Claude Desktop

Adicione ao claude_desktop_config.json, trocando pelo caminho da sua pasta:

{
  "mcpServers": {
    "defesa-pronta": {
      "command": "node",
      "args": ["/caminho/para/defesa-pronta/dist/index.js"],
      "env": { "AGORA": "2026-11-20T10:00:00-03:00" }
    }
  }
}

Onde fica o arquivo (ou em Settings → Developer → Edit Config):

  • Windows: %APPDATA%\Claude\claude_desktop_config.json (no JSON, use C:\\... com barras duplicadas)

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Reinicie o Claude Desktop; o servidor aparece com 8 ferramentas. Se o node não for encontrado (comum com nvm), use o caminho absoluto dele em command.

Painel web

npm run painel       # http://127.0.0.1:3333

O painel usa o login do Claude Code CLI (claude -p), sem chave de API. Ao iniciar, ele grava painel/mcp.json com os caminhos desta máquina. Para usar o servidor direto no Claude Code, copie painel/mcp.example.json para painel/mcp.json, ajuste o caminho e rode claude --mcp-config painel/mcp.json. Se o claude estiver fora do PATH, defina CLAUDE_BIN. npm run limpar apaga os dossiês e anexos gerados.

Demo em 1 minuto

No Claude Desktop, com o servidor conectado:

  1. "Tenho contestações abertas?" A lista vem ordenada pelo prazo; a CB-003 aparece primeiro, com 1h30 restante.

  2. "Monta a defesa da CB-002." O modelo busca pedido, rastreio e documentos, lê o comprovante e chama conferir_provas. Resultado: vai ser recusada, com 4 pontos: número 545 no comprovante e 455 no pedido (8.10.C), sem RG de quem recebeu (8.10.A), rastreio parado em "objeto em trânsito" (8.10.E) e falta a nota fiscal (8.5.A).

  3. "E a CB-001? Gera o dossiê dela." Defesa forte, e o dossiê fica em saida/dossie-CB-001.html.

No painel, a CB-002 pode ser corrigida: Trocar comprovante com data/demo/CB-002-comprovante-corrigido.png, Anexar nota fiscal com data/demo/CB-002-nota-fiscal.png e Conferir de novo. Sobra só o rastreio, que depende da transportadora.

Testes

npm test roda 43 testes (vitest) que cobrem os três casos de ponta a ponta, cada regra, normalização de nome e endereço, cálculo de prazo, geração do dossiê e anexos.

Estrutura

defesa-pronta/
  src/       servidor MCP: ferramentas, motor de regras, dossiê e backend do painel
  painel/    frontend do painel (web/) e mcp.example.json
  data/      dados fictícios (JSON) e documentos (PNG)
  scripts/   gerador dos documentos fictícios
  test/      testes (vitest)
  docs/      DESIGN.md (sistema visual do painel) e img/

Limites e cuidados

  • Dados fictícios. Pessoas, endereços, transportadora, e-mails e IPs são inventados, e todo documento tem a marca d'água "DOCUMENTO FICTÍCIO — PROTÓTIPO". Não há integração com a YouShop nem com transportadoras.

  • Regra 8.10.A simplificada. Não dá para julgar se uma assinatura é identificável, então comprovante sem RG é tratado como recusado. É mais rígido que a regra real.

  • Sem envio automático. Não existe ferramenta de envio; o dossiê é sempre um rascunho que o produtor revisa e envia.

  • Minimização de dados. CPF mascarado, IP parcialmente mascarado, RG só como sim/não e nenhum dado de cartão sai do servidor.

  • Auditoria. Cada chamada de ferramenta é registrada em logs/auditoria.jsonl.

  • A IA pode ler errado. Por isso o veredito é das regras, e o dossiê mostra, ao lado de cada imagem, o que foi extraído dela, para o produtor conferir.

Licença

MIT. Veja LICENSE.

Available Tools

8 tools
buscar_conversasBuscar conversasB
Read-only

Mensagens trocadas entre produtor e comprador (autor, data, texto). Servem como prova complementar (Cláusula 8.5.E).

Inputs: contestacao_id (required).

buscar_documentosBuscar documentos (imagens)A
Read-only

Retorna cada documento da contestação como imagem PNG, com metadados (nome do arquivo e tipo declarado: ar, comprovante_entrega, nota_fiscal, email_acesso). Leia cada imagem e extraia: tipo do documento, nome do recebedor, se há assinatura, se há RG, endereço completo, data do documento, código de rastreio, se indica devolução. Depois chame conferir_provas com esses campos. Transcreva exatamente o que está na imagem (ex.: número do endereço, campo de RG em branco = tem_rg false); não corrija nem complete com os dados do pedido. Minimização de dados: NUNCA repita na conversa números de documentos pessoais lidos nas imagens (RG, CPF, chave de NF); diga apenas 'com RG' ou 'sem RG'.

Inputs: contestacao_id (required).

buscar_logs_acessoBuscar logs de acessoA
Read-only

Só para produto digital: acessos do comprador à área de membros (data/hora, e-mail, IP parcialmente mascarado, aula). É a principal prova em 'não reconheço a compra' (Cláusula 8.5.D).

Inputs: contestacao_id (required).

buscar_pedidoBuscar pedidoA
Read-only

Dados do pedido e do comprador COMO CADASTRADOS NA COMPRA (nome, endereço, CPF mascarado, e-mail, tipo físico/digital, data, valor). É contra esses dados que as provas são comparadas (Cláusula 8.10.C). Não inclui dados do cartão.

Inputs: contestacao_id (required).

buscar_rastreioBuscar rastreioA
Read-only

Código de rastreio, transportadora e eventos com data, direto da base do servidor. Para produto digital retorna 'não se aplica'. A regra 8.10.E usa estes eventos.

Inputs: contestacao_id (required).

conferir_provasConferir provas contra as regrasA
Read-only

Roda o motor de regras da YouShop (Cláusula 8: 8.5 completude, 8.9 prazo, 8.10 recusas) sobre o que você extraiu das imagens e os dados do servidor (pedido, rastreio, conversas, logs). Retorna checklist, veredito, alertas e o que corrigir. A DECISÃO É DAS REGRAS, NÃO DO MODELO: apresente o veredito e os motivos como retornados, sem suavizar nem contradizer.

Inputs: contestacao_id (required), provas_extraidas (required).

gerar_dossieGerar dossiê em rascunho (HTML)A

Roda conferir_provas de novo e gera o dossiê em RASCUNHO saida/dossie-.html (resumo, prazo, checklist, provas usadas, provas descartadas e por quê, o que corrigir, e o que foi extraído de cada imagem). NÃO envia nada: o produtor revisa e envia por conta própria. Retorna o caminho do arquivo e o checklist das regras (veredito, Atenção, o que corrigir) — repasse esses motivos ao produtor como retornados.

Inputs: contestacao_id (required), provas_extraidas (required).

listar_contestacoesListar contestações abertasA
Read-only

Lista as contestações (chargebacks) abertas do produtor, ordenadas pelo menor prazo. O prazo para enviar provas é de 2 dias corridos (48h) a partir da abertura (Cláusula 8.9). Use para responder qual contestação é a mais urgente. Mencione a urgência ao listar; nas respostas seguintes não repita lembretes de urgência a cada mensagem.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation4/5

    The five 'buscar_*' tools each target a clearly different evidence source (access logs, order, tracking, conversations, documents), and listar_contestacoes is distinct. The only real overlap is conferir_provas vs gerar_dossie, since the latter re-runs the former; the descriptions explain the difference (rules verdict vs. HTML draft file), but an agent could still pick the wrong one for a quick check.

    Naming Consistency5/5

    All names are snake_case Portuguese verb_noun pairs (buscar_*, listar_*, conferir_*, gerar_*), with the verb accurately signaling the action and the noun the resource. No mixed conventions or camelCase outliers.

    Tool Count5/5

    Eight tools map cleanly onto one workflow: list open chargebacks, gather the five evidence sources, run the rule engine, and produce the dossier. Nothing looks redundant or bolted on, and no step of the workflow is split into unnecessary micro-tools.

    Completeness4/5

    The surface covers the full chain from contestation listing through evidence collection, rule checking, and dossier generation, with the deliberate non-goal of sending the response stated explicitly. Minor gap: there is no tool to retrieve a single contestation's detail/status beyond the ordered list, and no direct way to refresh or re-verify a dossier once generated.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers