Back to search
defesa-pronta
MCP serverGitHub
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
Markdown
[](/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
- # 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.
- 
- ## 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 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.
- 
- 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).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.