#MCP AUVP

Servidor MCP (Model Context Protocol) que dá ao seu agente de IA — Cursor, Claude Code, Claude Desktop, Windsurf, VS Code, etc. — acesso direto aos produtos da AUVP: Finanças, Analítica, Comunidade, Carteira (Diagrama do Cerrado) e Dicionário do Mercado.

Na prática: você loga uma vez no navegador e depois conversa com seus dados.

"Quanto gastei em mercado esse mês?" "Mostra o ranking de dividend yield das ações brasileiras." "Qual a nota dos meus ativos no Diagrama do Cerrado e onde devo aportar R$ 1.000?" "Procura na Comunidade o que falaram sobre Tesouro IPCA 2035."

---

#Sumário

• O que é isso, em 30 segundos
• Como funciona por dentro
• Os cinco módulos
• Instalação
• Autenticação — os fluxos de login
• Catálogo completo de tools
• Variáveis de ambiente
• Desenvolvimento
• Solução de problemas
• Estrutura do repositório

---

#O que é isso, em 30 segundos

MCP é o protocolo que permite a um LLM chamar ferramentas (tools) externas. Este servidor expõe as APIs dos sites da AUVP como tools, cada uma com nome, descrição e schema de parâmetros. O agente lê essa lista, escolhe a tool certa para o seu pedido em português e o MCP faz a chamada HTTP autenticada.

Três coisas que ele resolve para você:

1. Login. As APIs da AUVP são protegidas por SSO (Keycloak) e cookies de sessão. O MCP abre um Chrome, você loga uma vez, e ele captura e guarda bearer token, cookies e tokens de cada produto em ~/.auvp-financas/.
2. Renovação. Sessão expirada é renovada em silêncio (navegador headless com o perfil salvo). O navegador visível só aparece quando não há alternativa.
3. Contrato. As rotas foram mapeadas a partir de HARs, bundles JS e probes ao vivo, e ficam versionadas em catalog.ts de cada módulo — com formatos de data, filtros aceitos e as pegadinhas conhecidas de cada endpoint.

Nada sai da sua máquina além das chamadas para os próprios sites da AUVP. Não há servidor intermediário.

---

#Como funciona por dentro

flowchart LR
    A["Agente de IA<br/>(Cursor, Claude Code…)"] -- "stdio / JSON-RPC" --> B["mcp-auvp<br/>server.ts"]
    B --> C["registry.ts<br/>lista e despacha tools"]
    C --> D["http-client.ts<br/>headers + auth por site"]
    D --> E1["financas-api.auvp.com.br"]
    D --> E2["analitica.auvp.com.br"]
    D --> E3["comunidade.auvp.com.br"]
    D --> E4["ferramentas-backend.auvp.com.br"]
    D --> E5["worker.auvp.com.br"]
    F["~/.auvp-financas/<br/>token + cookies + perfil"] -. "lidos a cada chamada" .-> D
    G["auth/browser-login.ts<br/>Playwright"] -- "grava credenciais" --> F

O ciclo de uma chamada:

1. O agente pede tools/list → o MCP devolve só as tools dos módulos habilitados.
2. O agente chama uma tool → o registry relê token e cookies do disco (por isso um login feito em outro chat vale imediatamente, sem reiniciar o servidor).
3. Os argumentos passam por validação Zod + JSON Schema antes de virar request.
4. O http-client monta os headers certos para cada site (bearer, cookie, XSRF, user-agent, origin/referer).
5. Se a resposta for 401, o MCP tenta uma renovação silenciosa e repete a chamada uma vez antes de devolver erro.
6. Erros da API voltam traduzidos: mensagem de validação da API, dica de rota (ex.: "403 — restrição de plano") e sugestão de chamar auvp_ensure_auth.

Cada módulo é uma pasta independente em src/ com o mesmo formato: catalog.ts (rotas observadas), tools.ts (tools MCP), scan-tools.ts (varredura ao vivo) e um README.md próprio.

---

#Os cinco módulos

O que cada um cobre:

• Finanças — contas (bancárias e cartões), transações, dashboard, fluxo de caixa, orçamento, categorias, tags, faturas e conexão bancária via Pluggy.
• Analítica — análise fundamentalista: rankings paginados, cotações, balanço, DRE, dividendos, composição acionária, documentos, notícias, vídeos, simulador de rentabilidade, comparador e resumo de FIIs.
• Comunidade — fórum Invision (IPS): busca, listagem de tópicos por fórum, leitura de tópico com comentários, notificações e rankings de contribuidores.
• Carteira — Diagrama do Cerrado: ativos, notas, metas percentuais, cálculo de aporte, registro de compra/venda, perguntas do diagrama e mapa de ratings por país.
• Dicionário — Dicionário do Mercado: busca e leitura de termos, com metadados pessoais dos autores removidos da resposta.

---

#Instalação

#Pré-requisitos

• Node.js ≥ 20.18 — nodejs.org
• Conta AUVP ativa (login em sso.auvp.com.br)
• Um cliente MCP com suporte a stdio

#Cursor

Crie ou edite ~/.cursor/mcp.json (global) ou .cursor/mcp.json (só neste projeto):

{
  "mcpServers": {
    "mcp-auvp": {
      "command": "npx",
      "args": ["-y", "github:rod-moraes/mcp-auvp"]
    }
  }
}

Depois: Settings → MCP → Restart (ou reinicie o Cursor). Exemplo pronto em .cursor/mcp.json.example.

#Claude Code

claude mcp add mcp-auvp -- npx -y github:rod-moraes/mcp-auvp

#Claude Desktop e outros clientes

Mesmo bloco mcpServers do Cursor, no claude_desktop_config.json (ou no arquivo de configuração MCP do seu cliente).

#Carregando só alguns módulos

Por padrão os cinco módulos sobem juntos (118 tools). Para reduzir a lista — e o consumo de contexto do agente — use --modules:

{
  "mcpServers": {
    "mcp-auvp": {
      "command": "npx",
      "args": [
        "-y",
        "github:rod-moraes/mcp-auvp",
        "--modules",
        "financas,carteira"
      ]
    }
  }
}

Também funciona via AUVP_MODULES=financas,carteira. A flag tem precedência; ausente ou vazia, carrega todos. As tools de autenticação continuam disponíveis em qualquer seleção, e o auvp_ensure_auth passa a validar apenas os módulos escolhidos.

#Primeira execução

O npx baixa o repositório, roda npm install e compila sozinho (script prepare). Não é preciso clonar nem rodar npm run build na mão.

Repositório privado? Use token na URL:

"args": ["-y", "git+https://TOKEN@github.com/rod-moraes/mcp-auvp.git"]

Fixar versão (em vez de seguir a main):

"args": ["-y", "github:rod-moraes/mcp-auvp#main"]

#Chromium do Playwright (só se o login falhar)

Se o login reclamar da falta de navegador, rode uma vez:

npx -y --package=github:rod-moraes/mcp-auvp -c "playwright install chromium"

Com o repositório clonado: npm run playwright:install.

#Testando

No chat, peça ao agente:

• "Chame auvp_ensure_auth para logar na AUVP."
• "Liste minhas contas com auvp_financas_list_accounts."
• "Confirme o status com auvp_get_auth_status."

---

#Autenticação — os fluxos de login

Esta é a parte mais importante do projeto: cada produto AUVP autentica de um jeito diferente, e o MCP resolve todos em um único login.

#O que cada módulo precisa

O JWT do Finanças tem sua validade (exp) verificada antes do uso; expirado, dispara renovação.

#Fluxo principal — auvp_ensure_auth

É a única tool que você precisa chamar. Ela tenta o caminho mais barato primeiro e só escala quando necessário:

flowchart TD
    A["auvp_ensure_auth"] --> B["Carrega token/cookies do disco"]
    B --> C{"Credenciais válidas<br/>nos módulos ativos?"}
    C -- "sim" --> Z["authenticated<br/>method: existing_token"]
    C -- "não" --> D["Login silencioso<br/>Chromium headless + storage-state"]
    D --> E{"Renovou?"}
    E -- "sim" --> Z2["authenticated<br/>method: silent_browser"]
    E -- "não" --> F{"interactive = true?"}
    F -- "não" --> Y["login_required"]
    F -- "sim" --> G["Adquire o lock de login"]
    G --> H["Abre Chrome visível em<br/>financas.auvp.com.br/sign-in"]
    H --> I["Você conclui o SSO"]
    I --> J["Captura bearer, visita Analítica,<br/>Comunidade e Carteira"]
    J --> K["Grava credenciais + storage-state"]
    K --> Z3["authenticated<br/>method: interactive_browser"]

A validação não é só "existe token": o MCP faz uma chamada real por módulo ativo — GET /users/profile (Finanças), /api/session (Analítica), / (Comunidade), /auth/me (Carteira). 401/403 significa credencial morta.

Parâmetros:

Resposta: status (authenticated | login_required | failed), method (existing_token | silent_browser | interactive_browser | none), quais credenciais foram capturadas, os caminhos dos arquivos e uma message em português.

#Login automático ao iniciar o servidor

Quando o MCP sobe, ele já roda esse mesmo fluxo em background e loga o resultado no stderr ([mcp-auvp] Auth authenticated (existing_token): …). Para desativar:

AUVP_FINANCAS_AUTO_LOGIN_ON_START=0

Para forçar o navegador visível já no startup: AUVP_FINANCAS_FORCE_LOGIN_ON_START=1.

#Renovação silenciosa no meio do caminho

Se qualquer tool de produto receber 401, o MCP tenta sozinho um login headless com o perfil salvo e repete a chamada uma vez. Você normalmente nem percebe. As quatro tools de auth não entram nesse retry (para não criar loop).

#Lock entre chats

Dois chats abertos não podem abrir duas janelas de login ao mesmo tempo. O primeiro cria ~/.auvp-financas/auth-login.lock; os outros aguardam (até 10 min) e recarregam as credenciais assim que o primeiro terminar. Locks abandonados são considerados obsoletos após 15 minutos.

#Trocar de conta ou limpar a sessão

Chame auvp_ensure_auth com fresh: true

Isso apaga perfil do navegador, storage-state.json, bearer, cookies do Analítica e da Comunidade e o token da Carteira — e recomeça o login do zero.

#Fluxo SSO manual (alternativa)

Só use se o navegador automático não for viável. A API valida o state que ela gerou, então não monte a URL na mão:

1. auvp_create_sso_login_url → devolve a URL com state válido (aceita state, scope, redirectUri opcionais).
2. Abra a URL no navegador e conclua o login.
3. Se o redirect for rápido demais: DevTools → Network → Preserve log → filtre callback → copie a URL completa.
4. auvp_complete_sso_login com callbackUrl (ou code + state) na mesma sessão do MCP.
5. O bearer é salvo em disco automaticamente.

#O que fica no seu disco

Sua senha nunca é lida nem armazenada — quem cuida disso é o navegador, na tela do SSO. O auvp_get_auth_status mostra se existe cada credencial, nunca o valor.

---

#Catálogo completo de tools

118 tools. Nomes completos = prefixo do módulo + nome da tabela (ex.: list_accounts → auvp_financas_list_accounts). Tools marcadas com ✏️ escrevem dados; 🔥 são irreversíveis.

Toda tool *_list_observed_routes devolve o catálogo local de rotas daquele módulo — útil para descobrir o que existe sem sair do chat.

#🔐 Auth — sem prefixo de módulo (4)

#💰 Finanças — auvp_financas_* (36)

Catálogo, plano e perfil

Contas, bancos e faturas

Transações

Dashboard e orçamento

Categorias e tags

#📊 Analítica — auvp_analitica_* (45, somente leitura)

Sessão, plano e conta

Rankings e visualizações

rankingType aceita: upside_graham, upside_bazin, dividend_yield, valor_mercado, receita_liquida, lucro_liquido, caixa, roe, margem_liquida, p_l, cagr_receita_5_anos, cagr_lucro_liquido_5_anos, altas_30_dias, altas_12_meses, roic, sem_prejuizo, divida_liquida_ebitda, earning_yield.

Ativo — fundamentos

Mercado, conteúdo e simuladores

Comparador, templates e páginas

#💬 Comunidade — auvp_comunidade_* (8, somente leitura)

#🌾 Carteira / Diagrama do Cerrado — auvp_carteira_* (22)

Leitura

Cálculo

Escrita — ativos

type do ativo: acoes_nacionais, acoes_internacionais, fundos_imobiliarios, reits, criptomoedas, rendafixa, rendafixa_internacional.

Escrita — metas e perguntas

#📖 Dicionário do Mercado — auvp_dicionario_* (3, público)

As respostas passam por sanitização: e-mail, foto e demais metadados pessoais dos autores são descartados antes de chegar ao agente.

---

#Variáveis de ambiente

Todas são opcionais — os defaults funcionam sem configurar nada no mcp.json. Declare em env apenas se precisar de caminho customizado ou valor inline (sem arquivo em disco):

"env": {
  "AUVP_MODULES": "financas,carteira",
  "AUVP_FINANCAS_ACCESS_TOKEN_FILE": "/outro/caminho/access-token"
}

Seleção de módulos e login

Credenciais (arquivo ou inline)

Endpoints e HTTP

SSO

---

#Desenvolvimento

git clone https://github.com/rod-moraes/mcp-auvp.git
cd mcp-auvp
npm install                  # já dispara o build (script prepare)
npm run playwright:install   # primeira vez, para o login
npm test

Apontando o cliente MCP para o clone:

{
  "mcpServers": {
    "mcp-auvp": {
      "command": "npx",
      "args": ["-y", "mcp-auvp"],
      "cwd": "/caminho/para/mcp-auvp"
    }
  }
}

Scripts:

Os scans exigem autenticação (menos o do Dicionário) e são somente leitura por padrão. O ciclo de criação e remoção de dados do Finanças só roda com AUVP_SCAN_ALLOW_WRITES=1, usando o prefixo MCP_SCAN e limpando tudo ao final.

#Adicionando uma rota nova

1. Descubra a rota (ver skill auvp-scrapling e scripts/discover_endpoints.py).
2. Adicione a entrada em src/<modulo>/catalog.ts.
3. Crie a tool em src/<modulo>/tools.ts + schemas em src/mcp/schemas/ (JSON Schema e Zod).
4. Inclua o probe em src/<modulo>/scan-tools.ts se for leitura.
5. npm run scan:<modulo> && npm test.

---

#Solução de problemas

Logs do servidor saem no stderr com o prefixo [mcp-auvp] — no Cursor, em Output → MCP Logs.

---

#Estrutura do repositório

src/
├── index.ts              # entrypoint (resolve módulos e sobe o stdio server)
├── server.ts             # servidor MCP: list_tools / call_tool
├── mcp/
│   ├── modules.ts        # seleção de módulos (--modules / AUVP_MODULES)
│   ├── registry.ts       # agrega tools, sincroniza credenciais, retry em 401
│   ├── tool-utils.ts     # defineTool, jsonResult, formatação de erros
│   └── schemas/          # JSON Schema (json.ts) + validação Zod (zod.ts)
├── core/
│   ├── config.ts         # defaults e variáveis de ambiente
│   ├── http-client.ts    # cliente HTTP multi-site com auth por destino
│   ├── errors.ts         # AuvpApiError / AuvpConfigError
│   └── query.ts          # serialização de query params
├── auth/
│   ├── tools.ts          # as 4 tools de autenticação
│   ├── ensure-auth.ts    # orquestra validação → silencioso → interativo
│   ├── browser-login.ts  # Playwright: captura bearer, cookies e token da Carteira
│   ├── login-lock.ts     # lock entre chats
│   ├── storage.ts        # persistência do bearer (0600) e do perfil
│   └── sso.ts            # fluxo SSO manual
├── financas/  analitica/  comunidade/  carteira/  dicionario/
│                         # cada um: catalog.ts, tools.ts, scan-tools.ts, README.md
scripts/                  # scans TypeScript + discovery Scrapling (Python)
data/                     # relatórios de scan e catálogos extraídos
test/                     # Vitest

scan:financas também é somente leitura por padrão. O ciclo de criação e remoção de dados só roda com AUVP_SCAN_ALLOW_WRITES=1.

---

#Origem do catálogo

O contrato de cada módulo foi extraído de HARs, bundles JS e probes ao vivo com Scrapling, e fica versionado em catalog.ts — incluindo as rotas sem tool dedicada, documentadas para quem for estender o projeto.

Documentação por módulo: Finanças · Analítica · Comunidade · Carteira · Dicionário