Metadata-Version: 2.4
Name: contai-mcp
Version: 0.1.0
Summary: MCP server Python para 26 calculadoras fiscais brasileiras (CLT, PJ, impostos, finanças, saúde) — HTTP client da API Contaí. Use com Claude Desktop, Cursor, Cline.
Project-URL: Homepage, https://calculas.com.br
Project-URL: Documentation, https://docs.calculas.com.br
Project-URL: Repository, https://github.com/lfhillesheim/calculadora
Project-URL: Issues, https://github.com/lfhillesheim/calculadora/issues
Author-email: Contaí <api@calculas.com.br>
License: MIT
License-File: LICENSE
Keywords: anthropic,brasil,calculadora,calculas,claude,contai,fiscal,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# contai-mcp

[![PyPI](https://img.shields.io/pypi/v/contai-mcp.svg)](https://pypi.org/project/contai-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

**MCP server Python para 26 calculadoras fiscais brasileiras.**

CLT, PJ, impostos, finanças, saúde — usando [Model Context Protocol](https://modelcontextprotocol.io). Funciona dentro de **Claude Desktop, Cursor, Cline, Continue**, ou qualquer cliente MCP que fale stdio.

Não rola engine local: é um **HTTP client da [API Contaí](https://api.calculas.com.br)**, que executa o engine TypeScript versionado, mesma fórmula que roda em [calculas.com.br](https://calculas.com.br).

---

## Por que Python?

A versão TypeScript ([`@contai-evoluke/mcp-server`](https://www.npmjs.com/package/@contai-evoluke/mcp-server)) é a primária. Esta versão Python existe pra:

- **ML/data engineers** que já têm Python configurado e não querem instalar Node
- Usuários de Cursor/Cline com setup Python pré-existente
- Pipelines automatizados onde Python é o ambiente nativo

## Instalação

### Recomendado — via uvx (sem install)

```bash
uvx contai-mcp
```

Funciona em Claude Desktop direto:

```json
{
  "mcpServers": {
    "contai": {
      "command": "uvx",
      "args": ["contai-mcp"]
    }
  }
}
```

### Via pip

```bash
pip install contai-mcp
contai-mcp
```

## Configuração

### Claude Desktop

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

```json
{
  "mcpServers": {
    "contai": {
      "command": "uvx",
      "args": ["contai-mcp"]
    }
  }
}
```

Reinicie o Claude Desktop. As tools `calcular_rescisao_clt`, `calcular_salario_liquido`, etc., aparecem.

### Cursor

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

- **Name**: `contai`
- **Command**: `uvx contai-mcp`

### Cline / Continue / outros

Aponte qualquer cliente MCP que suporte stdio transport para:

```
uvx contai-mcp
```

## Variáveis de ambiente (opcional)

```bash
# API key (Pro/Team — sem ela usa free tier 100/dia por IP)
export CONTAI_API_KEY="ck_live_..."

# Override base URL (default https://api.calculas.com.br)
export CONTAI_API_URL="http://localhost:8787"

# Timeout em ms (default 5000)
export CONTAI_TIMEOUT_MS=10000
```

## Tools disponíveis (26)

> Nota: a API REST tem **27** calcs no total, mas `porcentagem` (a×b/100) é trivial demais para justificar uma tool MCP — LLMs lidam com isso direto. Os 5 lookup tools (`consultar_inss_vigente`, etc.) só existem na versão TS via stdio. Roadmap futuro pode adicionar GETs REST equivalentes.

### Trabalhistas (12)

`calcular_rescisao_clt`, `calcular_salario_liquido`, `calcular_13o_salario`, `calcular_ferias`, `calcular_horas_extras`, `calcular_horas_extras_dsr`, `calcular_fgts_acumulado`, `calcular_adicional_noturno`, `calcular_aviso_previo`, `calcular_inss_facultativo`, `calcular_insalubridade_periculosidade`, `calcular_seguro_desemprego`

### PJ (4)

`calcular_mei_das`, `calcular_simples_nacional`, `calcular_lucro_presumido`, `calcular_comparador_regime_tributario`

### Imóveis (2)

`calcular_financiamento_imobiliario`, `calcular_itbi`

### Impostos (2)

`calcular_itcmd`, `calcular_irpf_restituicao`

### Veículos (1)

`calcular_ipva`

### Finanças (3)

`calcular_juros_compostos`, `calcular_simulador_aposentadoria`, `calcular_consorcio_vs_financiamento`

### Saúde (2)

`calcular_imc`, `calcular_calculadora_gestacional`

## Como funciona

```
Claude Desktop                contai-mcp (Python)            api.calculas.com.br
     │                              │                                │
     │── tools/list ────────────────▶                                │
     │◀── 27 tools listadas ────────│                                │
     │                              │                                │
     │── call_tool(rescisao_clt) ──▶│                                │
     │                              │── POST /v1/calc/rescisao-clt ▶│
     │                              │◀── { totalLiquidoCents: ... } │
     │◀── resultado JSON ──────────│                                │
```

Sem rede em runtime do LLM = não há latência extra além do HTTP da API. Cache CDN da API absorve a maioria dos hits idempotentes.

## Verificar funcionamento

No Claude Desktop, pergunte:

> "Calcule a rescisão CLT pra alguém com salário R$ 5.000 admitido em 01/01/2024 e demitido sem justa causa em 01/04/2026"

Deve invocar `calcular_rescisao_clt` automaticamente.

## Erros estruturados

Em vez de raise, retorna envelope:

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

Codes: `INVALID_INPUT`, `UNKNOWN_CALC`, `RATE_NOT_AVAILABLE`, `SCHEMA_DRIFT`, `INTERNAL`, `TIMEOUT`, `NETWORK`, `RATE_LIMITED`, `INVALID_KEY`.

## Rate limits

| Tier | Limite | Auth |
|---|---|---|
| Free | 100 req/dia (IP-based) | sem `CONTAI_API_KEY` |
| Pro | 10.000 req/dia | `ck_live_...` |
| Team | 50.000 req/dia | `ck_live_...` |

Detalhes em [docs.calculas.com.br/rate-limits](https://docs.calculas.com.br/rate-limits).

## Desenvolvimento

```bash
cd packages/mcp-server-python
uv sync                       # cria venv + instala deps
uv run pytest                 # roda tests
uv run ruff check src tests   # lint
uv run python scripts/sync-tools.py  # valida sync com OpenAPI da API
```

## Licença

MIT
