auvp-scrapling

name	auvp-scrapling
description	Descobre e documenta endpoints HTTP dos três produtos AUVP (Finanças, Analítica e Comunidade) usando Scrapling, para implementar tools no MCP mcp-auvp. Instalação deve seguir https://scrapling.readthedocs.io/en/latest/index.html#installation (scrapling[all] + scrapling install). Use ao mapear rotas, descobrir APIs ou expandir catálogos MCP. NÃO é para extrair conteúdo de páginas.

AUVP Scrapling — descoberta de endpoints para o MCP

Objetivo: para Finanças, Analítica e Comunidade, descobrir quais endpoints existem, como são chamados e o que retornam — para criar/atualizar tools MCP.

Não é: raspagem de conteúdo editorial ou dados pessoais do usuário.

Stack: Scrapling + sessão ~/.auvp-financas/.

Setup — instalação Scrapling (obrigatório)

SEMPRE siga a instalação oficial antes de usar fetchers, spiders ou CLI:

scrapling.readthedocs.io — Installation

Não improvise versões, extras ou comandos. Se import scrapling.fetchers falhar, a instalação está incompleta (ver aviso da doc: pip install scrapling sozinho não inclui fetchers).

Requisitos (doc oficial)

• Python 3.10+
• Para este projeto: extras scrapling[all] (fetchers + shell + MCP) — ver Optional Dependencies

Procedimento neste repositório

cd /caminho/para/mcp-auvp

# 1. venv (Python 3.10+)
python3 -m venv .venv-scrapling
source .venv-scrapling/bin/activate

# 2. Instalar com extras — NÃO usar só `pip install scrapling`
pip install -r scripts/scrapling-requirements.txt
# equivalente doc: pip install "scrapling[all]"

# 3. Obrigatório após extras: browsers e deps de sistema (doc oficial)
scrapling install
# reinstalar se necessário: scrapling install --force

# 4. Verificar fetchers
python -c "from scrapling.fetchers import Fetcher, DynamicFetcher; print('ok')"

Se scrapling não estiver no $PATH, use o binário do venv: .venv-scrapling/bin/scrapling install.

Alternativa Docker (doc oficial)

Somente para CLI/extract, sem código Python — ver Docker:

docker pull pyd4vinci/scrapling
# ou: docker pull ghcr.io/d4vinci/scrapling:latest

Para descoberta de endpoints AUVP com capture_xhr e probes autenticados, prefira o venv local acima.

Auth AUVP (após Scrapling ok)

auvp_ensure_auth (MCP) · python scripts/auvp_auth.py status

Doc geral Scrapling: readthedocs.io/en/latest

---

Lógica unificada (os 3 produtos seguem o mesmo fluxo)

Cada produto AUVP tem a mesma estrutura de descoberta:

Etapa	O que fazer	Artefato
1. Catálogo	Listar rotas já conhecidas	src/{produto}/catalog.ts
2. Coleta	HAR, capture_xhr, bundles JS	data/endpoint-discovery/
3. Probe	Chamar endpoint e registrar status/shape	script ou Scrapling
4. Tool MCP	Implementar wrapper tipado	src/{produto}/tools.ts
5. Scan	Validar tools ao vivo	npm run scan:{produto}

Progresso (repetir por produto):
- [ ] 1. Escopo: qual feature/tela nova?
- [ ] 2. Auth ok para esse produto?
- [ ] 3. Listar catálogo atual (tool list_observed_routes)
- [ ] 4. Coletar candidatos (HAR / capture_xhr / probe)
- [ ] 5. Atualizar src/{produto}/catalog.ts
- [ ] 6. Criar tool + schema Zod
- [ ] 7. npm run scan:{produto} && npm test

---

Finanças

Item	Valor
API	https://financas-api.auvp.com.br
Frontend (dispara XHR)	https://financas.auvp.com.br
Auth	Bearer (~/.auvp-financas/access-token)
Catálogo	src/financas/catalog.ts
Tool catálogo	auvp_financas_list_observed_routes
Scan	npm run scan:financas

Como descobrir: probe REST direto com bearer; navegar SPA com capture_xhr=r"financas-api\.auvp\.com\.br/"; HAR financas.auvp.com.br.har.

Contrato: { status, message, data } · normalizar IDs → :accountId, :transactionId.

python scripts/discover_endpoints.py financas --path /dashboard/transactions
python scripts/discover_endpoints.py probe --site financas_api --path /budgets

---

Analítica

Item	Valor
API	https://analitica.auvp.com.br/api/*
Frontend (dispara XHR)	https://analitica.auvp.com.br
Auth	Cookie + X-XSRF-TOKEN (~/.auvp-financas/analitica-cookie)
Catálogo	src/analitica/catalog.ts
Tool catálogo	auvp_analitica_list_observed_routes
Scan	npm run scan:analitica

Como descobrir: DynamicFetcher + capture_xhr=r"analitica\.auvp\.com\.br/api/" em cada tela (/acoes/:ticker, /rankings/...); probe GET /api/...; HAR analitica.auvp.com.br.har.

Contrato: JSON REST; rotas RSC em /rankings/:segment/:rankingType retornam HTML/RSC.

python scripts/discover_endpoints.py analitica-all
python scripts/discover_endpoints.py analitica --path /acoes/PETR4
python scripts/discover_endpoints.py probe --site analitica --path /api/codes --query "code=PETR4"

---

Comunidade

Item	Valor
API/AJAX	https://comunidade.auvp.com.br (IPS Suite)
Frontend	mesmo host
Auth	Cookie IPS (ips4_member_id, ips4_login_key)
Catálogo	src/comunidade/catalog.ts
Tool catálogo	auvp_comunidade_list_observed_routes
Scan	npm run scan:comunidade

Como descobrir: probe GET /search/ (JSON com HTML embutido); capture_xhr ao navegar fóruns/tópicos; inspecionar type, nodes, paginação na busca IPS.

Contrato: /search/ → { title, content, filters }; tópicos → HTML (/topic/:id-:slug/).

python scripts/discover_endpoints.py comunidade-all
python scripts/discover_endpoints.py comunidade --path /search/
python scripts/discover_endpoints.py probe --site comunidade --path /search/ --query "q=tesouro&type=forums_topic"

---

Coleta com Scrapling (comum aos 3)

XHR ao navegar SPA

from scripts.auvp_auth import headers_for_site
from scrapling.fetchers import DynamicFetcher

# Padrão regex por produto (NÃO usar glob):
# financas:  r"financas-api\.auvp\.com\.br/"
# analitica: r"analitica\.auvp\.com\.br/api/"
# comunidade: r"comunidade\.auvp\.com\.br/"

page = DynamicFetcher.fetch(
    "https://analitica.auvp.com.br/acoes/PETR4",
    headers=headers_for_site("analitica"),
    headless=True,
    network_idle=True,
    capture_xhr=r"analitica\.auvp\.com\.br/api/",
)
for resp in page.captured_xhr:
    print(resp.status, resp.url)

Probe REST direto

from scrapling.fetchers import Fetcher
from scripts.auvp_auth import headers_for_site

resp = Fetcher.get(
    "https://financas-api.auvp.com.br/accounts",
    headers=headers_for_site("financas_api"),
    impersonate="chrome",
)

CLI unificada

# Captura XHR ao abrir página
python scripts/discover_endpoints.py {financas|analitica|comunidade} --path /rota

# Probe de endpoint candidato
python scripts/discover_endpoints.py probe --site {financas_api|analitica|comunidade} \
  --method GET --path /caminho [--query "k=v"]

Saída: data/endpoint-discovery/{produto}-*.json

---

HAR (fonte histórica)

Produto	HAR de referência
Finanças	financas.auvp.com.br.har
Analítica	analitica.auvp.com.br.har
Comunidade	capturar ao explorar busca/fóruns

Fluxo: DevTools → Preserve log → navegar feature → exportar HAR → extrair hosts AUVP → normalizar paths → catalog.ts → probe → scan.

---

Entregável por rota descoberta

{
  "product": "analitica",
  "method": "GET",
  "path": "/api/quotes/:ticker",
  "queryKeys": ["period"],
  "auth": "analitica-cookie + X-XSRF-TOKEN",
  "statusProbe": 200,
  "responseShape": "{ ... }",
  "mcpTool": "auvp_analitica_get_quotes",
  "discoveredFrom": "/acoes/:ticker"
}

Artefato	Caminho
Catálogo	src/financas/catalog.ts · src/analitica/catalog.ts · src/comunidade/catalog.ts
Tools	src/{produto}/tools.ts
Schemas	src/mcp/schemas/zod.ts + json.ts
Scan	src/{produto}/scan-tools.ts
Relatório	data/{produto}-tools-report.json

---

Validação

npm run scan:financas
npm run scan:analitica
npm run scan:comunidade
npm test

Anti-padrões

• Não instalar Scrapling fora da doc oficial de instalação — sem scrapling[fetchers]/[all] + scrapling install, fetchers falham.
• Não extrair conteúdo (posts, cotações, transações) — só mapear contratos de endpoint.
• Não commitar HAR, tokens ou PII em data/.
• Não usar capture_xhr com glob — é regex.
• Escrita (POST/PATCH/DELETE): só com probe controlado (scan Finanças usa marker MCP_SCAN).

Recursos

• Instalação Scrapling (oficial) — fonte obrigatória para setup
• Optional Dependencies
• sites.md — detalhes por produto AUVP
• examples/discover_xhr.py
• scripts/discover_endpoints.py
• scripts/auvp_auth.py
• scripts/scrapling-requirements.txt — pin scrapling[all] do projeto