Skip to main content
Glama
README.md
# 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](docs/img/painel.png)

## 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.

## Como funciona

```mermaid
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](docs/img/contestacao.png)

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](docs/img/dossie.png)

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

<img src="docs/img/comprovante.png" alt="Comprovante de entrega fictício da CB-002" width="480">

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.

```bash
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:

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

```bash
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](LICENSE).

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