# Cadê Meu Dinheiro

Servidor MCP que sincroniza os dados bancários da sua conexão [Meu Pluggy](https://meu.pluggy.ai) para um Postgres próprio e responde, dentro do Claude Desktop/Code, à pergunta que importa: **"para onde foi meu dinheiro esse mês?"**. Além do resumo de gastos por categoria com comparação mês a mês, dá para definir orçamentos por categoria, buscar transações e criar regras permanentes de categorização que são reaplicadas ao histórico.

São três camadas em um processo Node: o **sync** (Pluggy → Postgres, via cron de 6 em 6 horas, com janela de sobreposição de 7 dias), o **motor de insights** (funções puras sobre os dados já persistidos) e a **interface MCP** (Streamable HTTP protegido por bearer token).

O fluxo de branches, o padrão de commit e o que nunca entra no repositório estão em [CONTRIBUTING.md](CONTRIBUTING.md).

## Pré-requisitos

- Conta no [Meu Pluggy](https://meu.pluggy.ai) com os bancos e cartões já conectados.
- Credenciais de API (`clientId` e `clientSecret`) em [dashboard.pluggy.ai](https://dashboard.pluggy.ai).
- Os **item IDs** de cada conexão bancária, copiados do dashboard — é o que o sync percorre.
- Node 22+ e Docker.

## Setup local

```bash
cp .env.example .env     # preencha as credenciais e o token
docker compose up -d postgres
npm install
npm run dev
```

O `MCP_BEARER_TOKEN` deve ser gerado com `openssl rand -hex 32`.

**Nenhuma contraparte vem cadastrada.** O padrão que identifica você mesma é o seu
nome, e nome de ninguém entra em repositório — cadastre o seu na primeira conversa
com o Claude: *"marca PIX pra FULANO DE TAL como conta minha"* dispara
`set_internal_counterparty` e reclassifica o histórico inteiro.

Se alguma porta do host já estiver ocupada por outro projeto, todas são
configuráveis no `.env`: `POSTGRES_HOST_PORT`, `MCP_HOST_PORT`, `N8N_HOST_PORT`,
`WAHA_HOST_PORT`.

## Testes

Os testes de repositório rodam contra o banco `cade_test` do compose, então o Postgres precisa estar de pé:

```bash
docker compose up -d postgres
npm test
```

## Deploy na VPS

```bash
docker compose up -d --build
```

Sobe o Postgres, o servidor MCP (porta 3333), o n8n e o WAHA. Confira com `curl http://localhost:3333/health` e `docker compose logs mcp-server`.

## Conectando ao Claude

**Claude Code:**

```bash
claude mcp add --transport http cade-meu-dinheiro http://SEU_IP:3333/mcp --header "Authorization: Bearer SEU_TOKEN"
```

**Claude Desktop:** Settings → Connectors → Add custom connector, com a mesma URL e o mesmo header `Authorization`.

Depois disso, pergunte "para onde foi meu dinheiro esse mês?" — o Claude chama `get_spending_summary` e responde com os seus números.

### Tools disponíveis

| Tool | O que faz |
| --- | --- |
| `get_spending_summary` | Gastos do mês por categoria, delta vs. mês anterior e top estabelecimentos |
| `get_budget_status` | Orçamento vs. realizado, com projeção linear de fim de mês |
| `search_transactions` | Busca por texto, conta, categoria e período; devolve `total` (só gasto) e `totalMovimentado` (tudo) |
| `analyze_spending` | Soma, contagem e média de gastos, com agrupamento por mês, categoria ou conta |
| `query_finances` | Um `SELECT` livre sobre o banco (somente leitura, 200 linhas, 3s) para o que as outras não cobrem |
| `set_budget` | Define o limite mensal de uma categoria |
| `set_category_rule` | Cria regra de categorização e reaplica ao histórico |
| `set_internal_counterparty` | Marca um padrão como conta sua: deixa de contar como gasto ou renda |
| `remove_internal_counterparty` | Desfaz a marcação acima e reclassifica o histórico |
| `set_income_pattern` | Marca um padrão de entrada como renda de verdade |
| `remove_income_pattern` | Desfaz a marcação acima e reclassifica o histórico |

Toda resposta vem com um bloco de **frescor** dizendo até quando cada conta tem dado — número nenhum aparece sem data.

**Gasto não é sinal negativo, é `kind`:** cada transação é classificada em `consumo`, `transferencia_terceiro`, `movimentacao_interna`, `credito_tomado`, `fatura_sem_detalhe`, `renda`, `entrada_nao_renda` ou `nao_classificado`. Contam como gasto apenas `consumo`, `transferencia_terceiro`, `credito_tomado` e `fatura_sem_detalhe` — então PIX entre contas suas e pagamento de fatura de cartão que já reporta as compras param de ser contados como dinheiro gasto.

Há também o prompt `financial-coach`, que carrega a persona de coach financeiro já com o seu contexto de orçamento do mês.

## Segurança

- Token forte e único (`openssl rand -hex 32`); trate-o como senha do seu extrato bancário.
- **Nunca** commite o `.env` — ele está no `.gitignore` e deve continuar lá.
- Screenshots e gravações públicas só com dados de sandbox da Pluggy, nunca com os seus.

## n8n e WAHA (Fase 2)

Os dois já sobem no compose para você explorar desde já: n8n em `http://localhost:5678` e WAHA em `http://localhost:3000`. As portas ficam presas a `127.0.0.1`, então na VPS o acesso é por túnel SSH:

```bash
ssh -L 5678:localhost:5678 usuario@vps
```

**Apple Silicon:** a tag padrão do WAHA só tem build amd64. No `.env`, use
`WAHA_IMAGE=devlikeapro/waha:noweb-arm` (engine NOWEB, sem Chromium). Fixe também
`WAHA_API_KEY` e `WAHA_SWAGGER_PASSWORD`, senão o WAHA sorteia credenciais novas a
cada boot e o n8n perde o acesso.

Os workflows de alerta por WhatsApp chegam na Fase 2.