# mcp-ferramentas-dev

[![CI](https://github.com/Guilherme-Jardim/mcp-ferramentas-dev/actions/workflows/ci.yml/badge.svg)](https://github.com/Guilherme-Jardim/mcp-ferramentas-dev/actions/workflows/ci.yml)

Servidor MCP em TypeScript com ferramentas úteis para quem desenvolve para o Brasil: CPF/CNPJ, Pix (BR Code), boleto, parcelas e faixas salariais.

## O que é MCP

O Model Context Protocol (MCP) é um protocolo aberto que padroniza como aplicações de IA conversam com ferramentas e fontes de dados externas.
Um servidor MCP expõe ferramentas (funções com entrada e saída tipadas), recursos (dados para leitura) e prompts (modelos de pedido).
Um cliente MCP se conecta ao servidor, descobre o que ele oferece e chama as ferramentas quando necessário.

## Instalação

Requer Node.js 18 ou superior.

```bash
git clone https://github.com/Guilherme-Jardim/mcp-ferramentas-dev.git
cd mcp-ferramentas-dev
npm install
npm run build
```

O servidor usa o transporte stdio: `node dist/index.js`.

## Registrar em um cliente MCP

A maioria dos clientes aceita uma configuração JSON neste formato (o nome do arquivo e do campo raiz variam de cliente para cliente):

```json
{
  "mcpServers": {
    "ferramentas-dev": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp-ferramentas-dev/dist/index.js"],
      "env": {
        "MCP_FAIXAS_PATH": "/caminho/opcional/para/minhas-faixas.json"
      }
    }
  }
}
```

`MCP_FAIXAS_PATH` é opcional. Sem ele, a ferramenta de salário usa `config/faixas-salariais.json`.

## Ferramentas

Todas validam a entrada com Zod, descrevem o schema de saída e devolvem `structuredContent` além de um resumo em texto. Erros de execução voltam com `isError: true` e uma mensagem clara.

### `validar_documento`

Valida CPF (11 dígitos) ou CNPJ (14 dígitos numéricos) e formata.

```json
{ "documento": "52998224725" }
```
```json
{ "valido": true, "tipo": "cpf", "somenteDigitos": "52998224725", "formatado": "529.982.247-25" }
```

### `gerar_pix`

Gera o Pix copia e cola estático com CRC16. Campos: `chave`, `nome`, `cidade`, e opcionais `valor`, `txid`, `descricao`.

```json
{ "chave": "12345678909", "nome": "Loja Exemplo", "cidade": "Curitiba", "valor": 49.9, "txid": "PEDIDO1" }
```
```json
{
  "payload": "00020101021226330014br.gov.bcb.pix011112345678909520400005303986540549.905802BR5912Loja Exemplo6008Curitiba62110507PEDIDO16304C74D",
  "tamanho": 125,
  "crc": "C74D"
}
```

### `validar_pix`

Confere o CRC16, os campos obrigatórios e extrai chave, nome, cidade, valor e txid.

```json
{ "payload": "0002010102122633...6304C74D" }
```
```json
{ "valido": true, "erros": [], "crcInformado": "C74D", "crcCalculado": "C74D", "chave": "12345678909", "valor": 49.9, "tipo": "uso_unico" }
```

O campo `tipo` reflete o ponto de iniciação do BR Code: `reutilizavel` (11) ou `uso_unico` (12, usado quando há valor).

### `validar_boleto`

Confere os dígitos verificadores da linha digitável de 47 dígitos (bancário) ou 48 dígitos (arrecadação).

```json
{ "linhaDigitavel": "23790.00115 ..." }
```
```json
{ "valido": true, "tipo": "bancario", "erros": [], "banco": "237", "moeda": "9", "fatorVencimento": 9500, "valor": 150, "codigoDeBarras": "..." }
```

### `calcular_parcelas`

Tabela Price (parcelas fixas, juros compostos). A taxa é em % ao mês.

```json
{ "valor": 10000, "taxaMensal": 1, "parcelas": 12 }
```
```json
{
  "valorParcela": 888.49,
  "totalPago": 10661.86,
  "totalJuros": 661.86,
  "taxaMensal": 1,
  "tabela": [{ "numero": 1, "parcela": 888.49, "juros": 100, "amortizacao": 788.49, "saldoDevedor": 9211.51 }]
}
```

(a tabela completa traz as 12 linhas; a última parcela é ajustada para o saldo fechar em zero)

### `comparar_salario`

Diz em qual faixa um salário cai, segundo um JSON configurável. Mínimo é inclusivo, máximo é exclusivo, e só a última faixa pode ter `maximo: null`.

```json
{ "salario": 7000 }
```
```json
{
  "salario": 7000,
  "faixa": { "nome": "Pleno", "minimo": 6000, "maximo": 10000 },
  "indice": 2,
  "abaixoDaPrimeira": false,
  "proximaFaixa": { "nome": "Sênior", "minimo": 10000, "maximo": 16000 },
  "faltaParaProxima": 3000,
  "arquivo": ".../config/faixas-salariais.json"
}
```

Formato do arquivo de faixas:

```json
{
  "faixas": [
    { "nome": "Júnior", "minimo": 3000, "maximo": 6000 },
    { "nome": "Pleno", "minimo": 6000, "maximo": null }
  ]
}
```

## Recurso e prompt

- Recurso `ferramentas://catalogo`: JSON com a lista das ferramentas e suas descrições.
- Prompt `conferir_cobranca` (argumentos `documento` e `pix`): pede ao cliente que confira o CPF/CNPJ e o Pix de uma cobrança usando as ferramentas acima.

## Desenvolvimento

```bash
npm run lint    # ESLint
npm run build   # compila para dist/
npm test        # compila e roda os testes (unitários + integração por stdio)
```

A lógica pura fica em `src/core` (sem dependência do MCP) e o servidor em `src/servidor.ts`.

## Limites

- A validação de CPF/CNPJ é só matemática (dígitos verificadores). Não consulta a Receita Federal, então não diz se o documento existe ou está regular. CNPJ alfanumérico (novo formato) não é suportado.
- O Pix gerado é estático, sem consulta ao PSP. Não valida se a chave existe nem cria cobrança dinâmica (campo `url`). Nome e cidade perdem acentos e são truncados, como pede o BR Code.
- O boleto é verificado apenas pelos dígitos. Não consulta banco ou câmara, então não informa pagamento, vencimento real ou valor atualizado. O fator de vencimento é devolvido cru: ele reinicia a cada 9000 dias (houve reinício em 22/02/2025), então a data exata fica ambígua sem contexto. A conferência de arrecadação cobre os DVs dos quatro blocos, e não a validação do convênio.
- Price assume taxa nominal mensal constante, sem IOF, tarifas, seguros, CET nem carência. Arredondamento em centavos, com ajuste na última parcela. Use como estimativa, não como proposta financeira.
- As faixas salariais são só as que você configurar; o arquivo de exemplo é ilustrativo e não representa nenhuma tabela oficial ou de mercado.
- Pensado para uso local por stdio. Não há autenticação nem transporte HTTP.

## Licença

MIT. Veja [LICENSE](LICENSE).