@contai-evoluke/mcp-server

Calculadoras fiscais brasileiras para LLMs via Model Context Protocol.

v0.5: 32 tools — 26 calculadoras (trabalhistas, PJ, impostos, finanças, saúde) + 5 ferramentas de consulta (tabelas INSS/IRRF/SM por mês_ano + busca em base curada de ~30 leis brasileiras core) + 1 Decisão Guiada (decisao_clt_vs_pj — wizard que orquestra 4 calcs e devolve veredicto financeiro CLT vs PJ). Mantém os ganhos de v0.4: erros estruturados, timeout guard, telemetria opt-in. Roda dentro de Claude Desktop, Cursor, Cline e qualquer cliente MCP — sem dep de rede em runtime, tudo local.

Engine de cálculo é pura, versionada e testada com >95% de cobertura — mesma que roda em calculas.com.br.

Instalação

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "contai": {
      "command": "npx",
      "args": ["-y", "@contai-evoluke/mcp-server"]
    }
  }
}

Reinicia Claude Desktop. As tools calcular_rescisao_clt, calcular_salario_liquido etc. aparecem na barra de tools.

Cursor

Settings → Cursor Settings → MCP → Add new MCP server:

• Name: contai
• Command: npx -y @contai-evoluke/mcp-server

Cline / Continue / outros

Aponte qualquer cliente MCP que suporte stdio transport para:

npx -y @contai-evoluke/mcp-server

Tools disponíveis (v0.5 — 32 total)

Trabalhistas (12)

| Tool | O que calcula | |---|---| | calcular_rescisao_clt | Rescisão completa (4 tipos: sem justa, pedido, acordo, justa causa). Aplica INSS+IRRF | | calcular_salario_liquido | Bruto → líquido com INSS + IRRF + dependentes | | calcular_13o_salario | 13º proporcional, 1ª e 2ª parcela, descontos | | calcular_ferias | Férias + 1/3 constitucional, abono pecuniário | | calcular_horas_extras | HE com adicional + DSR reflexo (Súmula TST 172) | | calcular_horas_extras_dsr | Granular: HE 50% (dia útil) e 100% (DSR/feriado) separados | | calcular_fgts_acumulado | Saldo FGTS ao longo do tempo (8% + rendimento + 13º) | | calcular_adicional_noturno | Urbano 22h-5h, +20%, hora reduzida 52min30s. Rural variantes | | calcular_aviso_previo | 30 dias + 3/ano até 90 (Lei 12.506) | | calcular_inss_facultativo | 5% / 11% / 20% — autônomo, dona de casa, MEI complementar | | calcular_insalubridade_periculosidade | Compara excludentes (NR-15 × NR-16) | | calcular_seguro_desemprego | Faixas 2026 + carência + nº parcelas |

PJ / tributos empresariais (4)

| Tool | O que calcula | |---|---| | calcular_mei_das | DAS-MEI mensal (5% SM + ICMS/ISS) | | calcular_simples_nacional | DAS Simples (5 anexos + Fator R) | | calcular_lucro_presumido | IRPJ + CSLL + PIS/COFINS + ISS/ICMS trimestral | | calcular_comparador_regime_tributario | MEI × Simples × LP, recomenda o melhor regime |

Imóveis (2)

| Tool | O que calcula | |---|---| | calcular_financiamento_imobiliario | SAC vs PRICE, parcelas, total de juros | | calcular_itbi | Imposto municipal de transmissão (com regra SFH) |

Impostos (2)

| Tool | O que calcula | |---|---| | calcular_irpf_restituicao | Compara modelo completo × simplificado, melhor opção | | calcular_itcmd | Herança/doação por estado |

Veículos (1)

| Tool | O que calcula | |---|---| | calcular_ipva | IPVA por UF/tipo, com desconto à vista |

Finanças (3)

| Tool | O que calcula | |---|---| | calcular_juros_compostos | VF com aportes mensais | | calcular_simulador_aposentadoria | FIRE-style, renda perpétua via taxa de retirada | | calcular_consorcio_vs_financiamento | Decisão entre os dois pra um bem |

Saúde (2)

| Tool | O que calcula | |---|---| | calcular_imc | Peso/altura² + classificação OMS | | calcular_calculadora_gestacional | Idade gestacional + DPP (Naegele modificada) |

Consulta (5)

| Tool | O que faz | |---|---| | consultar_tabela_inss_irrf | Faixas oficiais INSS+IRRF 2026 numa chamada | | consultar_salario_minimo | Retorna SM nacional vigente + valor anual + fonte legal | | consultar_inss_vigente | Faixas progressivas + alíquotas + teto + dedução dependente | | consultar_irpf_tabela | Faixas IRRF + dedução por dependente + redutor Lei 15.270/25 | | buscar_lei | Busca em base curada de ~30 leis BR core (CLT, CTN, CF, LC 123, Lei 9.250 IRPF, etc.). Retorna ementa, link planalto, artigos chave |

Decisões Guiadas (1) — engine layer 4

Orquestram 3-7 calcs existentes e devolvem veredicto financeiro com breakdown auditável. ADR-017 documenta a arquitetura.

| Tool | O que faz | |---|---| | decisao_clt_vs_pj | Wizard CLT × PJ — vale a pena trocar? Combina salário líquido CLT (com benefícios), simula impostos PJ (Simples Anexo III/V ou Lucro Presumido), pró-labore, distribuição de lucros (isenta — Lei 9.249/95), FGTS perdido, INSS facultativo opcional. Retorna verdict ('CLT'/'PJ'/'TIE'), deltaAnualCents, breakdown completo, riscos qualitativos (sem FGTS, sem 13º, pejotização). Fonte: CLT, LC 123/2006, Lei 9.249/95 art. 10. |

Próximas Decisões planejadas (Q3+ 2026): decisao_compro_ou_alugo, decisao_quanto_aposentar, decisao_devo_abrir_empresa.

Todos os valores monetários em centavos (integer) internamente, retornados também formatados em BRL.

Exemplos de uso

"Calcula minha rescisão"

Usuário: "Fui demitido sem justa causa. Entrei em março de 2022 ganhando
         R$ 4.500. Saí ontem (22/abril). Quanto vou receber líquido?"

Claude (usando calcular_rescisao_clt):
{
  "tipo": "sem_justa_causa",
  "salarioBrutoCents": 450000,
  "admissao": "2022-03-01",
  "demissao": "2026-04-22"
}
→ R$ 17.842,35 líquido. Breakdown: saldo R$ 667, aviso indenizado
  R$ 4.500, 13º proporcional R$ 1.500, férias R$ 5.625, multa FGTS 40%
  R$ 5.900, menos INSS R$ 180 e IRRF R$ 170.

"Quanto guardar pra aposentar aos 60?"

Usuário: "Tenho 30 anos, quero aposentar aos 60 com R$ 2 milhões
         guardados. Quanto preciso aportar por mês a 0.8% ao mês?"

Claude (usando calcular_juros_compostos):
{ "capitalInicialCents": 0, "aporteMensalCents": ???,
  "taxaMensalPercent": 0.8, "prazoMeses": 360 }
→ Itera até achar que R$ 1.040/mês dá R$ 2.003.500 em 30 anos.

"Compara SAC vs PRICE"

Usuário: "Imóvel R$ 500k, entrada R$ 100k, 360 meses a 10.49% a.a.
         Qual sistema compensa?"

Claude (duas chamadas):
  SAC   → primeira R$ 4.600, última R$ 1.400, total R$ 680k
  PRICE → parcela fixa R$ 3.660, total R$ 1.320k
→ "SAC economiza R$ 640k ao longo de 30 anos. Parcela inicial é 25%
   mais alta mas total pago é metade."

Preço & uso

Open source / free tier

Grátis, sem limite, sem registro. A engine é livre (MIT). Download via NPM, roda local.

Pro (Q2 2026 — em breve)

Quando o tráfego orgânico crescer, plano Pro incluirá:

• ✅ Todas as +100 calcs do Contaí (não só as 5 iniciais)
• ✅ Remote mode (não precisa rodar NPM local — chamada vai direto pra API do Contaí)
• ✅ Cache de resultado por LLM session
• ✅ Tabelas atualizadas automaticamente (INSS/IRRF mudam → atualização global sem precisar npm update)
• ✅ Support direto, SLA

Inscreva-se em calculas.com.br/mcp-early-access pra saber quando abrir.

Reliability (v0.4)

O servidor expõe garantias claras pra LLM clients:

Erros estruturados

Em vez de throw nu, falhas viram envelope:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "salarioBrutoCents: must be positive",
    "details": { "path": ["salarioBrutoCents"], "cause": "must be positive" }
  }
}

Catálogo de codes:

| Code | Quando | |---|---| | INVALID_INPUT | Args não passam no schema Zod | | UNKNOWN_CALC | Tool name não existe no registry | | RATE_NOT_AVAILABLE | Tabela fiscal/lookup ausente para o período pedido | | SCHEMA_DRIFT | Output do engine não bate com schema esperado | | INTERNAL | Bug ou exceção inesperada | | TIMEOUT | Handler ultrapassou o limite |

Timeout

Default 5s por chamada. Configurável via env:

export CONTAI_TIMEOUT_MS=10000  # 10s, faixa 10-60000

Excedeu = { ok: false, error: { code: "TIMEOUT", ... } }. Cliente LLM pode retry ou cair pra fallback.

Semver policy

• patch (0.4.x) — bugfixes, sem mudança de contrato
• minor (0.x.0) — novas tools, novos campos opt-in em outputs existentes
• major (x.0.0) — breaking changes em inputs/outputs, com migration guide

Telemetria (opt-in)

Default OFF (LGPD). Para ligar:

export CONTAI_TELEMETRY=1

Manda apenas:

{
  "tool": "calcular_rescisao_clt",
  "durationMs": 12,
  "ok": true,
  "version": "0.4.0",
  "ts": "2026-04-26T12:00:00Z",
  "installId": "inst_a3f7b2c9"
}

Nunca envia inputs, outputs, IP, email, ou qualquer dado do usuário. installId é random por processo (não persiste). Endpoint configurável via CONTAI_TELEMETRY_URL.

Por que ligar? Ajuda a priorizar bugs em tools menos populares + melhorar latência. Por que não ligar? Privacidade total — qualquer ambiente regulado.

Desenvolvimento

git clone https://github.com/lfhillesheim/calculadora
cd calculadora
pnpm install
pnpm --filter @contai-evoluke/mcp-server dev

Para testar localmente:

{
  "mcpServers": {
    "contai-dev": {
      "command": "node",
      "args": ["/caminho/para/calculadora/packages/mcp-server/dist/index.js"]
    }
  }
}

Publish workflow (npm + MCP Registry)

Para publicar uma nova versão ao npm e ao MCP Registry oficial (registry.modelcontextprotocol.io):

# 1) Bump da versão em package.json + server.json (sincronizado).
# 2) Atualizar CHANGELOG.md.
# 3) Build + publish npm:
cd packages/mcp-server
pnpm build
npm publish --access public

# 4) Instalar mcp-publisher (uma vez):
# macOS/Linux:
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" \
  | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

# Windows (PowerShell):
#   $arch = if ([Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }
#   Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_$arch.tar.gz" -OutFile mcp-publisher.tar.gz
#   tar xf mcp-publisher.tar.gz mcp-publisher.exe
#   # Mova mcp-publisher.exe para um diretório no PATH (ex.: %USERPROFILE%\.local\bin)

# 5) Login com GitHub OAuth (interativo — device flow):
mcp-publisher login github

# 6) Publish ao Registry (rodar dentro de packages/mcp-server, onde está server.json):
mcp-publisher publish

O namespace io.github.lfhillesheim/contai-mcp-server é validado contra o GitHub username do owner — o login GitHub deve ser do @lfhillesheim para passar a verificação de ownership.

Contribuição

Issues em github.com/lfhillesheim/calculadora/issues.

Áreas quentes para contribuir:

• Mais tools: IPVA, ITBI, ITCMD, INSS contribuinte, simples nacional
• Output formats: tabelas markdown, gráficos ASCII
• i18n: tools em inglês (calculate_*) como aliases

Licença

MIT © Contaí / Evoluke 2026