# mcp-calculadora-rtc

Servidor MCP sobre a **Calculadora de Tributos sobre o Consumo** da Receita Federal —
CBS, IBS e Imposto Seletivo da reforma tributária (EC 132/2023, LC 214/2025).

Não reimplementa a regra tributária: **conversa com a calculadora oficial da RFB** e
devolve o resultado com procedência anexada.

## Por que existir

A RFB publica a calculadora de graça, em duas formas: um serviço público e um
**componente para uso local**. Nenhuma das duas fala MCP, e nenhuma delas carrega
procedência no resultado. Este servidor resolve as duas coisas:

- **Fonte oficial.** A regra é da Receita, não nossa. Nenhuma alíquota hardcoded.
- **Perímetro sob controle.** Aponte `RTC_BASE_URL` para o componente local e o dado
  do cliente nunca sai da máquina. É o mesmo servidor, só muda a variável.
- **Trilha.** Toda resposta vem embrulhada com `_procedencia`: URL chamada, modo
  (local ou público), versão do app e do banco de dados da RFB, data da versão e
  timestamp da chamada. Sem isso, número de tributo não se defende.
- **Data obrigatória.** A API oficial é versionada por data. Este servidor nunca
  chama sem `data` — o que vale hoje é falso em 2029.

## Instalação

Requer [uv](https://docs.astral.sh/uv/). Um comando, nada para clonar:

```bash
claude mcp add calculadora-rtc -- \
  uvx --from "git+https://github.com/Izaiaspertrelly/mcp-calculadora-rtc" mcp-calculadora-rtc
```

Confira com `claude mcp list` (deve aparecer `✔ Connected`) e use perguntando em
português — não há sintaxe a decorar.

Em qualquer outro cliente MCP, o equivalente em JSON:

```json
{
  "mcpServers": {
    "calculadora-rtc": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/Izaiaspertrelly/mcp-calculadora-rtc",
        "mcp-calculadora-rtc"
      ]
    }
  }
}
```

### Apontando para o componente local da RFB

Por padrão o servidor fala com o serviço público da Receita. Para que nenhum dado
saia da máquina, baixe o componente offline na página oficial da calculadora
(*Calculadora Offline → Download*; há versão programa e versão Java/JAR — o link é
gerado pelo portal no navegador), suba-o e acrescente:

```json
"env": { "RTC_BASE_URL": "http://localhost:8080/servico/calculadora-consumo/api" }
```

O servidor detecta sozinho que é local e passa a marcar `modo: "local"`. Em modo
público, toda chamada que envia operação volta com aviso de egresso de dado.

## Modo remoto (HTTP autenticado)

O mesmo servidor fala HTTP com autenticação Bearer. Ele **falha fechado**: sem
`RTC_MCP_TOKEN`, não sobe — não existe modo "público sem senha".

```bash
RTC_MCP_TOKEN="$(openssl rand -base64 32)" uv run python -m mcp_calculadora_rtc.http_app
# escuta em 127.0.0.1:8787, endpoint MCP em /mcp, sonda pública em /health
```

Variáveis:

| Variável | Para quê |
|---|---|
| `RTC_MCP_TOKEN` | Token Bearer. Obrigatório em HTTP. |
| `RTC_BASE_URL` | Backend da RFB (público ou componente local). |
| `RTC_HOSPEDAGEM` | Rótulo da hospedagem, vai na procedência de toda resposta. |
| `RTC_MCP_PATH` | Caminho do endpoint MCP. Padrão `/mcp`. |
| `RTC_ALLOWED_HOSTS` / `RTC_ALLOWED_ORIGINS` | Restrição de host/origem. Com valor diferente de `*`, liga a proteção contra DNS rebinding. |
| `RTC_ALLOW_NO_AUTH=1` | Desliga a autenticação. Só para localhost, e sabendo o que está fazendo. |

Cliente MCP apontando para o remoto:

```json
{
  "mcpServers": {
    "calculadora-rtc-remoto": {
      "type": "http",
      "url": "https://SEU-HOST/mcp",
      "headers": { "Authorization": "Bearer SEU_TOKEN" }
    }
  }
}
```

### O que muda no risco

Rodando remoto, o dado da operação atravessa infraestrutura de terceiro antes de
chegar à RFB. O servidor detecta isso e **acrescenta um aviso explícito** em toda
resposta que enviou dado. Para engajamento com dado real de cliente, o desenho
correto continua sendo stdio local com o componente offline da Receita.

A detecção de hospedagem não confia em `VERCEL=1` — essa variável vaza para shell de
desenvolvedor e carimbaria procedência falsa. Ela usa `VERCEL_REGION` /
`AWS_LAMBDA_FUNCTION_NAME`, que só existem dentro do runtime, ou `RTC_HOSPEDAGEM`
declarada no deploy.

## Ferramentas

| Ferramenta | O que faz |
|---|---|
| `rtc_status` | Base URL, modo, versão do app e do banco da RFB |
| `rtc_calcular_tributos` | Cálculo de CBS/IBS/IS de uma operação completa |
| `rtc_calcular_com_trilha` | Mesmo cálculo, com observabilidade da RFB |
| `rtc_aliquota_referencia` | Alíquota oficial por data (União, UF, município) |
| `rtc_situacoes_tributarias` | Tabela de CST vigente na data |
| `rtc_classificacoes_tributarias` | Tabela de cClassTrib, opcionalmente por CST |
| `rtc_validar_ncm` / `rtc_validar_nbs` | Valida NCM/NBS contra um cClassTrib na data |
| `rtc_fundamentacao_legal` | Fundamentação legal das classificações |
| `rtc_base_calculo_mercadorias` | Base de cálculo de CBS/IBS em mercadorias |
| `rtc_imposto_seletivo` | Base de cálculo do IS em mercadorias |
| `rtc_nfse_base_calculo` | Base de cálculo para NFS-e |
| `rtc_validar_xml_dfe` | Valida XML de documento fiscal |
| `rtc_gerar_xml_dfe` | Gera XML de documento fiscal |
| `rtc_descrever_erro` | Traduz código de erro da calculadora |
| `rtc_chamar` | Escape hatch: qualquer endpoint da API oficial |

## Limites — leia antes de usar com cliente

- A calculadora oficial está em **beta** e a própria RFB não a oferece como garantia
  de conformidade. Resultado é simulação; a responsabilidade continua de quem assina.
- As alíquotas devolvidas são as **vigentes na data consultada**. Em 2026 isso
  significa 0,9% de CBS e 0,1% de IBS — as de teste. A alíquota de referência
  definitiva ainda depende do rito RFB → TCU → Senado.
- Este servidor **não modela crédito de cadeia, cenário, nem premissa**. Ele calcula
  operação. Modelagem de transição é camada de cima.

## Licença

MIT. Não é software oficial da Receita Federal nem do Comitê Gestor do IBS — é um
cliente independente da API pública deles.