Skip to content
Back to search

defesa-pronta

Servidor MCP que confere as provas de uma contestação (chargeback) e monta a defesa em rascunho

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fernandoscarabeli--defesa-pronta/badge.svg)](/listings/fernandoscarabeli--defesa-pronta)

HTML

<a href="/listings/fernandoscarabeli--defesa-pronta"><img src="/api/listings/fernandoscarabeli--defesa-pronta/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 166 lines
  1. # Defesa Pronta
  2. Servidor MCP que confere as provas de uma contestação de compra (chargeback) contra as regras da YouShop e monta a defesa em rascunho.
  3. 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.
  4. ![Painel com as três contestações abertas, ordenadas pelo prazo](docs/img/painel.png)
  5. ## O problema
  6. 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.
  7. ## Como funciona
  8. ```mermaid
  9. flowchart LR
  10. P[Produtor] --> A["Agente (Claude)"]
  11. A --> F["Ferramentas MCP<br/>pedido, rastreio, conversas,<br/>logs, documentos"]
  12. F --> R[Motor de regras]
  13. R --> V{"Veredito"}
  14. V -->|forte| D[Dossiê em rascunho]
  15. V -->|incompleta| D
  16. V -->|vai ser recusada| D
  17. D --> E[Produtor revisa e envia]
  18. ```
  19. - **A IA lê** os documentos (imagens) e extrai o que está escrito neles.
  20. - **As regras decidem** o veredito: código determinístico e testado, que cita a cláusula de cada item.
  21. - **O produtor envia**: não existe ferramenta de envio, aprovação ou reembolso.
  22. ## Prints
  23. ![Contestação CB-002: veredito, o que resolver e documentos](docs/img/contestacao.png)
  24. 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.
  25. ![Topo do dossiê da CB-002](docs/img/dossie.png)
  26. Dossiê gerado em `saida/dossie-CB-002.html`: faixa de rascunho, veredito e o que corrigir antes de enviar.
  27. <img src="docs/img/comprovante.png" alt="Comprovante de entrega fictício da CB-002" width="480">
  28. Comprovante fictício da CB-002. O número 545 (o pedido diz 455) e a falta de RG só aparecem lendo a imagem.
  29. ## Ferramentas MCP
  30. Todas são de leitura, exceto `gerar_dossie`, que grava o rascunho em `saida/`.
  31. | Ferramenta | O que faz |
  32. |---|---|
  33. | `listar_contestacoes` | Lista as contestações abertas com prazo, horas restantes e urgência, da mais urgente para a menos urgente. |
  34. | `buscar_pedido` | Pedido e comprador como cadastrados na compra (CPF mascarado, sem dados do cartão). |
  35. | `buscar_rastreio` | Código, transportadora e eventos do rastreio; "não se aplica" para produto digital. |
  36. | `buscar_conversas` | Mensagens entre produtor e comprador. |
  37. | `buscar_logs_acesso` | Acessos do comprador à área de membros (produto digital, IP parcialmente mascarado). |
  38. | `buscar_documentos` | Documentos da contestação como imagens, com instruções do que extrair de cada um. |
  39. | `conferir_provas` | Roda o motor de regras sobre o que foi extraído e devolve checklist, veredito e o que corrigir. |
  40. | `gerar_dossie` | Confere de novo e grava o dossiê em rascunho (`saida/dossie-<id>.html`). |
  41. ## Regras implementadas
  42. Fonte: Termos de Uso da YouShop, Cláusula 8. Código em `src/regras/conferir.ts`.
  43. | Cláusula | Regra |
  44. |---|---|
  45. | 8.5.A | Produto físico: nota fiscal da venda. |
  46. | 8.5.B | Produto físico: AR ou comprovante de entrega. |
  47. | 8.5.C | Produto físico: código de rastreio. |
  48. | 8.5.D | Produto digital: logs de acesso do comprador antes da contestação. |
  49. | 8.5.E | Conversas com o comprador. |
  50. | 8.9 | Prazo de 2 dias corridos (48h) a partir da abertura; alerta com 12h ou menos. |
  51. | 8.10.A | AR/comprovante precisa identificar quem recebeu (sem RG = recusa). |
  52. | 8.10.B | Documento não pode indicar devolução. |
  53. | 8.10.C | Nome e endereço do documento iguais aos do pedido (diz qual campo diverge). |
  54. | 8.10.D | Documento não pode ser posterior à abertura da contestação. |
  55. | 8.10.E | Rastreio precisa mostrar a entrega antes da abertura da contestação. |
  56. Vereditos (só erros e itens faltando contam; alertas aparecem à parte e não rebaixam o veredito):
  57. - **Defesa forte**: nenhum erro e nada faltando.
  58. - **Defesa possível, mas incompleta**: falta algum item da 8.5.
  59. - **Defesa vai ser recusada**: alguma prova cai em uma regra da 8.10 ou o prazo acabou.
  60. ## Como rodar
  61. Requisitos: Node 20+ e o Claude Desktop ou o Claude Code CLI logado.
  62. ```bash
  63. npm install
  64. npm run gerar-docs # gera os documentos fictícios (PNG) em data/docs/ e data/demo/
  65. npm run build
  66. npm test
  67. ```
  68. **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.
  69. ### Claude Desktop
  70. Adicione ao `claude_desktop_config.json`, trocando pelo caminho da sua pasta:
  71. ```json
  72. {
  73. "mcpServers": {
  74. "defesa-pronta": {
  75. "command": "node",
  76. "args": ["/caminho/para/defesa-pronta/dist/index.js"],
  77. "env": { "AGORA": "2026-11-20T10:00:00-03:00" }
  78. }
  79. }
  80. }
  81. ```
  82. Onde fica o arquivo (ou em Settings → Developer → Edit Config):
  83. - Windows: `%APPDATA%\Claude\claude_desktop_config.json` (no JSON, use `C:\\...` com barras duplicadas)
  84. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  85. - Linux: `~/.config/Claude/claude_desktop_config.json`
  86. 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`.
  87. ### Painel web
  88. ```bash
  89. npm run painel # http://127.0.0.1:3333
  90. ```
  91. 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.
  92. ## Demo em 1 minuto
  93. No Claude Desktop, com o servidor conectado:
  94. 1. **"Tenho contestações abertas?"** A lista vem ordenada pelo prazo; a CB-003 aparece primeiro, com 1h30 restante.
  95. 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).
  96. 3. **"E a CB-001? Gera o dossiê dela."** Defesa forte, e o dossiê fica em `saida/dossie-CB-001.html`.
  97. 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.
  98. ## Testes
  99. `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.
  100. ## Estrutura
  101. ```
  102. defesa-pronta/
  103. src/ servidor MCP: ferramentas, motor de regras, dossiê e backend do painel
  104. painel/ frontend do painel (web/) e mcp.example.json
  105. data/ dados fictícios (JSON) e documentos (PNG)
  106. scripts/ gerador dos documentos fictícios
  107. test/ testes (vitest)
  108. docs/ DESIGN.md (sistema visual do painel) e img/
  109. ```
  110. ## Limites e cuidados
  111. - **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.
  112. - **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.
  113. - **Sem envio automático.** Não existe ferramenta de envio; o dossiê é sempre um rascunho que o produtor revisa e envia.
  114. - **Minimização de dados.** CPF mascarado, IP parcialmente mascarado, RG só como sim/não e nenhum dado de cartão sai do servidor.
  115. - **Auditoria.** Cada chamada de ferramenta é registrada em `logs/auditoria.jsonl`.
  116. - **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.
  117. ## Licença
  118. MIT. Veja [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.