@maxwellmezadre/kotas-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maxwell Mezadre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# kotas-mcp
+
+[![MIT](https://img.shields.io/badge/licença-MIT-blue.svg)](LICENSE)
+[![Bun ≥ 1.3](https://img.shields.io/badge/bun-%E2%89%A5%201.3-black.svg)](https://bun.sh)
+[![TypeScript strict](https://img.shields.io/badge/typescript-strict-3178c6.svg)](tsconfig.json)
+[![CI](https://github.com/maxwellmezadre/kotas-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/maxwellmezadre/kotas-mcp/actions/workflows/ci.yml)
+
+CLI e servidor MCP para as suas assinaturas compartilhadas no
+[Kotas](https://kotas.com.br): grupos, o que você paga em cada um, faturas,
+créditos, cauções, repasses recebidos como administrador, saldo, economia
+acumulada e o histórico completo — inclusive das assinaturas que você já
+encerrou. Tudo em um cache local, para que uma pergunta como *"quanto já gastei
+no Kotas?"* seja respondida sem abrir o site.
+
+O Kotas não tem API pública de cliente. Este projeto conversa com a mesma API
+que o app `app.kotas.com.br` usa, com a sua própria sessão, **somente leitura**:
+nenhuma tool cancela assinatura, saca, paga ou muda um valor.
+
+## Sumário
+
+- [Instalação](#instalação)
+- [Login](#login)
+- [Uso — CLI](#uso--cli)
+- [Uso — MCP](#uso--mcp)
+- [Variáveis de ambiente](#variáveis-de-ambiente)
+- [Tools](#tools)
+- [Como funciona](#como-funciona)
+- [Troubleshooting](#troubleshooting)
+- [Documentação](#documentação)
+- [Licença](#licença)
+
+## Instalação
+
+### Tudo de uma vez (Claude Code)
+
+```sh
+bun run setup
+```
+
+Compila o binário, instala em `~/.local/bin/kotas`, registra o servidor MCP no
+escopo de usuário do `~/.claude.json` e instala a Skill em
+`~/.claude/skills/kotas-mcp/`.
+
+### npm
+
+```sh
+npm install -g @maxwellmezadre/kotas-mcp
+```
+
+### Binário único
+
+Baixe o executável do seu sistema na [página de
+releases](https://github.com/maxwellmezadre/kotas-mcp/releases) e ponha no
+`PATH`. Não precisa de runtime instalado.
+
+## Login
+
+Três caminhos, todos gravando o mesmo `session.enc` cifrado:
+
+```sh
+kotas login                              # e-mail e senha (pergunta, ou KOTAS_EMAIL/KOTAS_SENHA)
+kotas login --from-browser chrome        # importa a sessão de um navegador já logado (macOS)
+kotas login --paste                      # cola os três valores do localStorage
+```
+
+O login do Kotas não tem captcha, então o caminho por senha é HTTP puro e não
+precisa de navegador. A senha é usada uma vez e **nunca é gravada**: só ficam os
+dois tokens e o identificador do dispositivo.
+
+Se a conta tiver verificação em duas etapas, passe o código:
+
+```sh
+kotas login --pin 123456
+```
+
+Se o Kotas pedir liberação de dispositivo (HTTP 412), ele manda um e-mail, SMS
+ou mensagem no Telegram. Confirme e rode `kotas login` de novo — o identificador
+já foi salvo, então não troque de máquina no meio do processo.
+
+## Uso — CLI
+
+```sh
+kotas sync                    # baixa o histórico para o cache (repete os blocos sozinho)
+kotas subscriptions           # as assinaturas que você tem hoje
+kotas history                 # tudo que você já assinou, inclusive o que encerrou
+kotas spending --by month     # quanto por mês
+kotas payouts                 # o que você recebe como administrador
+kotas balance                 # saldo e economia acumulada
+kotas invoices --status pago --from 2026-01-01
+kotas subscription 397075     # plano, rateio, vagas e participantes
+kotas export history --format csv
+```
+
+Todo comando aceita `--json`, que imprime o mesmo objeto que a tool MCP devolve.
+
+## Uso — MCP
+
+```sh
+claude mcp add -s user kotas -- /Users/você/.local/bin/kotas mcp
+```
+
+Ou à mão, no `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "kotas": {
+      "type": "stdio",
+      "command": "/Users/você/.local/bin/kotas",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Use o caminho absoluto: clientes MCP não herdam o `PATH` do seu shell. Depois é
+só perguntar: *"quanto já gastei no Kotas?"*, *"quais assinaturas eu tenho e
+quanto pago em cada uma?"*, *"quanto vou receber como administrador este mês?"*
+
+## Variáveis de ambiente
+
+| Variável | Default | Para quê |
+| --- | --- | --- |
+| `KOTAS_CONFIG_DIR` | `~/.config/kotas-mcp` | Onde ficam sessão, chave e cache |
+| `KOTAS_SESSION_KEY` | — | Chave AES em base64 de 32 bytes; sem ela, uma é gerada em `session.key` |
+| `KOTAS_EXPORT_DIR` | `~/Downloads/kotas-export` | O único diretório onde `export` escreve |
+| `KOTAS_READ_ONLY` | `0` | Não registra `login`, `sync` e `export` |
+| `KOTAS_COMPACT` | `0` | Respostas mínimas por padrão, para economizar contexto |
+| `KOTAS_EMAIL` / `KOTAS_SENHA` | — | Só para o bootstrap do `login`; nunca são gravadas |
+| `KOTAS_IMPORT_BROWSER` | — | `arc` \| `chrome` \| `chromium` \| `brave` \| `edge` |
+| `KOTAS_APP_VERSION` | `1.127.0.0` | Header `versao`; se a API responder 426, atualize |
+| `KOTAS_API_TOKEN` | (chave do front) | Chave estática da API, igual para todo mundo |
+| `KOTAS_MIN_INTERVAL_MS` | `300` | Intervalo mínimo entre requisições |
+| `KOTAS_JITTER_MS` | `200` | Variação aleatória somada ao intervalo |
+| `KOTAS_HTTP_TIMEOUT_MS` | `30000` | Timeout de cada requisição |
+| `KOTAS_LOG_FILE` | — | Espelha o log (que sai no stderr) em um arquivo |
+| `KOTAS_BASE_URL` | `https://api-front.kotas.com.br` | Só para testes |
+
+## Tools
+
+| Tool | Comando | Rede |
+| --- | --- | --- |
+| `auth_status` | `kotas status [--verify]` | 0 (1 com `--verify`) |
+| `login` | `kotas login` | 1–2 |
+| `doctor` | `kotas doctor` | ≈ 6 (3 com `--shallow`) |
+| `sync` | `kotas sync [--full\|--reparse]` | em blocos |
+| `list_subscriptions` | `kotas subscriptions` | 0 |
+| `get_subscription` | `kotas subscription <id>` | 0 (1 se não estiver no cache) |
+| `list_invoices` | `kotas invoices` | 0 |
+| `get_invoice` | `kotas invoice <id>` | 0 (1 se faltarem os itens) |
+| `list_credits` | `kotas credits` | 0 |
+| `balance` | `kotas balance` | 2 |
+| `list_payouts` | `kotas payouts` | 0 |
+| `purchase_history` | `kotas history` | 0 |
+| `spending_summary` | `kotas spending --by …` | 0 |
+| `search_services` | `kotas search <termo>` | 1 |
+| `export` | `kotas export <escopo>` | 0 |
+| `raw_get` | `kotas raw <rota>` | 1 |
+
+Referência completa dos parâmetros em [`docs/TOOLS.md`](docs/TOOLS.md), gerada a
+partir do registry.
+
+## Como funciona
+
+1. **Sessão.** Dois tokens JWT (acesso e renovação) mais o identificador do
+   dispositivo, cifrados com AES-256-GCM em `~/.config/kotas-mcp/session.enc`,
+   modo 0600. O token de acesso dura 15 minutos e é renovado sozinho.
+2. **Um funil só.** Toda requisição passa por `src/core/http.ts`, que serializa
+   as chamadas, respeita um intervalo mínimo com jitter, faz backoff em 429/5xx
+   e cuida da renovação do token.
+3. **Faturas como raiz.** Um grupo cancelado some da API, então o histórico é
+   reconstruído a partir da descrição das faturas
+   (`Fatura grupo <produto> #<id>`). É por isso que `purchase_history` enxerga
+   assinaturas que o site já não mostra.
+4. **Cache local.** SQLite em `~/.config/kotas-mcp/cache.db`, com o payload cru
+   guardado ao lado do dado interpretado — assim `sync --reparse` reprocessa
+   todo o histórico sem gastar uma requisição.
+
+## Troubleshooting
+
+| Sintoma | O que fazer |
+| --- | --- |
+| `Nenhuma sessão do Kotas salva` | `kotas login` ou `kotas login --from-browser chrome` |
+| `O Kotas pediu a liberação do dispositivo` (412) | Confirme o e-mail/SMS/Telegram e rode `kotas login` de novo |
+| `A conta tem verificação em duas etapas` | `kotas login --pin 123456` |
+| `sync` devolve `done: false` | É esperado: chame de novo até `done: true` (o CLI já faz isso) |
+| Listas vazias | O cache está vazio: rode `kotas sync` |
+| HTTP 426 | A versão do front mudou: ajuste `KOTAS_APP_VERSION` |
+| HTTP 400 em um grupo | O grupo foi encerrado e não existe mais na API; use `kotas history` |
+| Algo quebrou de um jeito estranho | `kotas doctor` diz qual camada |
+
+## Documentação
+
+| Arquivo | Conteúdo |
+| --- | --- |
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Camadas, regras duras e por que cada uma existe |
+| [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) | Variáveis, arquivos em disco e registro no Claude Code |
+| [`docs/USAGE.md`](docs/USAGE.md) | Do zero à primeira pergunta |
+| [`docs/CLI.md`](docs/CLI.md) | Referência dos comandos |
+| [`docs/TOOLS.md`](docs/TOOLS.md) | Referência das tools (gerada) |
+| [`docs/LOGIN.md`](docs/LOGIN.md) | Os três caminhos de login e o que fica gravado |
+| [`docs/DATA-MODEL.md`](docs/DATA-MODEL.md) | Modelo de domínio e schema do cache |
+| [`docs/INTERNAL-API.md`](docs/INTERNAL-API.md) | A API do Kotas e as armadilhas confirmadas |
+| [`docs/REDISCOVERY.md`](docs/REDISCOVERY.md) | O que fazer quando o Kotas mudar |
+| [`docs/adr/`](docs/adr) | Uma decisão por arquivo |
+| [`test/fixtures/README.md`](test/fixtures/README.md) | O que as fixtures são e o que a anonimização faz |
+
+## Licença
+
+MIT. Veja [LICENSE](LICENSE).

package/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: kotas-mcp
+description: >-
+  Assinaturas compartilhadas do Kotas da conta do usuário via MCP `kotas`:
+  grupos, o que ele paga em cada um, faturas, créditos, cauções, repasses
+  recebidos como administrador, saldo, economia acumulada e o histórico
+  completo — inclusive das assinaturas já encerradas. Use para perguntas como
+  "quanto já gastei no Kotas", "quais assinaturas eu tenho e quanto pago",
+  "quanto vou receber como administrador", "quando eu assinei a Netflix e por
+  quanto tempo". Triggers: kotas, assinatura, assinaturas, grupo, kota, rateio,
+  vaga, fatura, mensalidade, quanto gastei, quanto pago, repasse, recebimento,
+  administrador, membro, crédito, caução, saldo, economia, saque, fidelidade,
+  Netflix, Spotify, Google One, SetApp, 1Password, Canva, Disney, HBO,
+  Youtube Premium.
+---
+
+# Kotas — assinaturas compartilhadas
+
+MCP `kotas` (`mcp__kotas__*`), 16 tools. Referência completa de parâmetros em
+`TOOLS.md`, ao lado deste arquivo.
+
+O Kotas é o serviço onde várias pessoas dividem uma assinatura. Cada assinatura
+é um **grupo**, cada vaga é uma **kota**, e cada pessoa paga a sua parte. Quem
+cria o grupo é o **administrador**: paga o serviço por fora e recebe o rateio
+dos membros.
+
+## Leia antes de responder
+
+1. **Comece por `auth_status` quando qualquer coisa falhar.** Ele responde sem
+   rede e diz se há sessão, de quem é, até quando o token vale e o que já está
+   no cache. O token de acesso dura 15 minutos, então `accessTokenExpired: true`
+   é normal — ele é renovado sozinho na chamada seguinte.
+
+2. **O cache responde quase tudo.** `list_subscriptions`, `list_invoices`,
+   `list_credits`, `list_payouts`, `purchase_history` e `spending_summary` não
+   usam a rede. Se vierem vazios, rode `sync`.
+
+3. **`sync` trabalha em blocos.** Se devolver `done: false`, chame de novo com
+   os mesmos parâmetros até `done: true`. Não aumente `max_requests` para
+   "acelerar" e não chame em paralelo: o ritmo existe para o uso ficar parecido
+   com o de uma pessoa. Um histórico de ~260 faturas leva ~305 requisições e
+   uns 2 minutos.
+
+4. **Fatura cancelada ou estornada NÃO é gasto.** Só `status: "pago"` é dinheiro
+   que saiu. `spending_summary` já conta só as pagas; se você somar à mão, some
+   `total`, nunca `amount` — `total` é o que de fato saiu, com juros, reajuste
+   e desconto embutidos.
+
+5. **Grupo encerrado não existe mais na API.** `get_subscription` responde erro
+   para ele, e `list_subscriptions` só mostra os que continuam ativos. O
+   histórico das assinaturas antigas vive **nas faturas**, e é isso que
+   `purchase_history` reconstrói. Para "o que eu já assinei", use
+   `purchase_history`, nunca `list_subscriptions`.
+
+6. **Nos créditos, use `available`, não `amount`.** A API zera o valor de face
+   de todo lançamento já consumido, então `amount` vem 0 em quase tudo.
+   `available` é a cifra que existe e é a que fecha com o saldo da carteira.
+
+7. **Saldo bloqueado não é dinheiro perdido.** São as cauções das inscrições
+   (crédito tipo 96): ficam retidas enquanto a assinatura durar e voltam quando
+   ela é encerrada.
+
+8. **Grupo que o usuário administra não gera fatura.** Ele paga o serviço por
+   fora e recebe o rateio, então aparece em `purchase_history` com
+   `monthsPaid: 0` e `totalPaid: null`, e o dinheiro dele está em
+   `receivedAsAdmin` e em `list_payouts`. Não diga que ele "não pagou nada".
+
+9. **Repasse com status `Cancelado` não vai mais acontecer.** Só some no
+   previsto o que está `Agendado` — é o que `scheduledTotal` já faz.
+
+10. **`search_services` é o catálogo, não o histórico.** Serve para "quanto
+    custa o plano X no Kotas", não para "o que eu assino".
+
+11. **As credenciais do serviço compartilhado (login e senha da Netflix, do
+    Spotify…) não são acessíveis por aqui, de propósito.** Não existe tool para
+    elas e a rota é bloqueada. Se pedirem, diga que estão no app do Kotas.
+
+12. **Este servidor nunca altera a conta.** Não cancela assinatura, não saca,
+    não paga, não muda valor de grupo. Se pedirem, explique que é só leitura.
+
+## Tools ↔ CLI
+
+| Tool | Comando | Para quê |
+| --- | --- | --- |
+| `auth_status` | `kotas status [--verify]` | Sessão, perfil, validade do token, cache |
+| `login` | `kotas login [--from-browser chrome]` | Salva a sessão cifrada em disco |
+| `doctor` | `kotas doctor [--shallow]` | Diz qual camada quebrou |
+| `sync` | `kotas sync [--full\|--reparse]` | Baixa o histórico para o cache |
+| `list_subscriptions` | `kotas subscriptions [--role]` | As assinaturas que ainda existem |
+| `get_subscription` | `kotas subscription <id>` | Plano, rateio, vagas, participantes |
+| `list_invoices` | `kotas invoices [--status --from --to]` | As faturas |
+| `get_invoice` | `kotas invoice <id>` | Uma fatura com os itens |
+| `list_credits` | `kotas credits [--kind]` | Cauções, repasses, adições, estornos |
+| `balance` | `kotas balance` | Saldo e economia acumulada (ao vivo) |
+| `list_payouts` | `kotas payouts [--group]` | O que se recebe como administrador |
+| `purchase_history` | `kotas history [--active]` | Tudo que já foi assinado, inclusive encerrado |
+| `spending_summary` | `kotas spending --by month` | Gastos por mês, ano, produto ou situação |
+| `search_services` | `kotas search <termo>` | Catálogo de serviços e planos |
+| `export` | `kotas export <escopo>` | CSV/JSON em `~/Downloads/kotas-export` |
+| `raw_get` | `kotas raw <rota> [-q k=v]` | Válvula de escape para redescoberta |
+
+## Receitas
+
+| Pergunta | O que chamar |
+| --- | --- |
+| "quanto já gastei no Kotas?" | `spending_summary` com `by: "year"` |
+| "quanto gasto por mês?" | `spending_summary` com `by: "month"` |
+| "o que eu mais paguei?" | `spending_summary` com `by: "product"` |
+| "quais assinaturas eu tenho?" | `list_subscriptions` |
+| "o que eu já assinei um dia?" | `purchase_history` |
+| "por quanto tempo tive a Canva?" | `purchase_history`, campo `monthsPaid` |
+| "quanto vou receber este mês?" | `list_payouts`, campo `scheduledTotal` |
+| "quanto tenho de saldo?" | `balance` |
+| "quem está no meu grupo?" | `get_subscription` do grupo administrado |
+| "quanto economizei?" | `balance`, campo `saved` |
+
+## Avisos
+
+- Somente leitura. Nenhuma tool altera a conta.
+- Ritmo próximo ao de uma pessoa (~2 requisições por segundo). Não force.
+- `KOTAS_READ_ONLY=1` remove `login`, `sync` e `export` do registro.
+- O refresh token é o segredo de verdade: não o mostre nem o peça em texto.