@justmpm/calculator

MCP Server com ferramentas de cálculo: contagem de tokens, calculadora adaptável com expressões nomeadas e mais.

Descrição

Este servidor MCP (Model Context Protocol) reúne ferramentas de cálculo úteis para o dia a dia de desenvolvimento:

• token_count — Estima tokens de arquivos e diretórios (~4 chars/token)
• calc — Calculadora adaptável com expressões nomeadas, referências entre variáveis, porcentagem, sufixo k, funções math, modo exato (BigNumber) e detecção de referência circular

Por que usar?

• Sem API key: Não precisa de nenhuma chave ou configuração
• Zero pré-requisitos: Não depende de Python ou qualquer runtime externo
• Inteligente: Ignora automaticamente node_modules, .git, lock files e outros arquivos irrelevantes (token_count)
• Calculadora completa: Suporta orçamentos, juros compostos, rateios, fórmulas encadeadas com resolução automática de dependências (calc)
• Precisão exata: Modo BigNumber evita erros de floating point em cálculos financeiros
• Integração MCP: Funciona com Claude Desktop, OpenCode e outros clientes MCP

Instalação

Opção 1 - Via npx (sem instalar)

Basta configurar no seu cliente MCP -- ele baixa automaticamente:

{
  "mcpServers": {
    "calculator": {
      "command": "npx",
      "args": ["-y", "@justmpm/calculator"]
    }
  }
}

Opção 2 - Instalação global

npm install -g @justmpm/calculator

Depois configure no cliente MCP:

{
  "mcpServers": {
    "calculator": {
      "command": "calculator"
    }
  }
}

Opção 3 - Desenvolvimento local

git clone https://github.com/justmpm/calculator-mcp
cd calculator-mcp
npm install
npm run build

Configure apontando para o build:

{
  "mcpServers": {
    "calculator": {
      "command": "node",
      "args": ["D:\\caminho\\para\\calculator\\dist\\index.js"]
    }
  }
}

Configuração

Claude Desktop

Edite o arquivo claude_desktop_config.json:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "calculator": {
      "command": "npx",
      "args": ["-y", "@justmpm/calculator"]
    }
  }
}

Reinicie o Claude Desktop após salvar.

OpenCode

Adicione ao arquivo de configuração do OpenCode:

{
  "mcpServers": {
    "calculator": {
      "command": "npx",
      "args": ["-y", "@justmpm/calculator"]
    }
  }
}

Cursor / Windsurf / outros clientes MCP

Siga o padrão de configuração do seu cliente usando npx -y @justmpm/calculator como comando.

Tools Disponíveis

token_count - Conta tokens de arquivos e diretórios

Estima a quantidade de tokens de arquivos e diretórios, retornando uma tabela ordenada por maior consumo.

Parâmetros:

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | paths | string[] | Sim | Caminhos dos arquivos ou diretórios (relativos ao cwd) | | ext | string | Não | Filtrar por extensões separadas por vírgula (ex: .ts,.tsx) | | cwd | string | Sim | Diretório de trabalho para resolver caminhos relativos |

Exemplo:

{
  "paths": ["src/"],
  "cwd": "D:\\Pictures\\MeuProjeto"
}

Retorno:

--------------------------------------------------------------------
Arquivo                          Bytes       Tokens
--------------------------------------------------------------------
src/components/Dashboard.tsx    12.450      3.113
src/hooks/useAuth.ts             8.200      2.050
src/utils/format.ts              3.100        775
--------------------------------------------------------------------
TOTAL (3 arquivos)              23.750      5.938
--------------------------------------------------------------------

  Pulados: 15 arquivo(s) (12 binários, 3 filtrados)

calc - Calculadora adaptável com expressões nomeadas

Resolve expressões nomeadas com referências entre si. Suporta porcentagem, sufixo k, funções math, constantes, modo exato (BigNumber) e detecção de referência circular.

Parâmetros:

| Parâmetro | Tipo | Obrigatório | Default | Descrição | |-----------|------|-------------|---------|-----------| | entries | string[] | Sim | — | Lista de strings no formato "Nome: Expressão" | | exact | boolean | Não | false | Precisão exata (BigNumber). Recomendado para cálculos financeiros | | precision | number | Não | 2 | Casas decimais. Use 0 para inteiros | | showSum | boolean | Não | false | Mostra soma total ao final da tabela | | format | string | Não | "table" | "table" para tabela ASCII, "json" para JSON estruturado |

Recursos suportados:

• Operações: +, -, *, /, **, %, ^
• Porcentagem: 15% vira 0.15, Bruto * 10% funciona direto
• Sufixo k: 5k vira 5000, 1.5K vira 1500
• Nomes com espaços: "Preço Unitário: 150" referenciado como Preço Unitário
• Referências entre variáveis: A ordem não importa, resolve automaticamente
• Funções math: sqrt, log, log10, sin, cos, ceil, floor, factorial, abs, min, max, sum, round
• Constantes: pi, e, tau, inf
• Detecção de referência circular: Erro claro se A depende de B que depende de A

Exemplos:

Contagem de restaurante:

{
  "entries": ["Pizza: 89.90", "Pessoas: 4", "PorPessoa: Pizza / Pessoas"],
  "showSum": true
}

Folha de pagamento:

{
  "entries": ["Horas: 160", "ValorHora: 150", "Total: Horas * ValorHora", "INSS: Total * 8%", "Liquido: Total - INSS"],
  "exact": true
}

Juros compostos:

{
  "entries": ["Capital: 1000", "Taxa: 2%", "Meses: 12", "Montante: Capital * (1 + Taxa) ** Meses"],
  "exact": true
}

Rateio com nome composto:

{
  "entries": ["Preço Unitário: 89.90", "Quantidade: 5", "Total: Preço Unitário * Quantidade"],
  "showSum": true
}

Saída em JSON:

{
  "entries": ["Bruto: 5000", "Imposto: Bruto * 15%", "Liquido: Bruto - Imposto"],
  "format": "json"
}

Retorno (tabela):

--------------------------------------------
Nome     Expressão                 Resultado
--------------------------------------------
Bruto    5000                       5.000,00
Imposto  Bruto * 15%                  750,00
Liquido  Bruto - Imposto            4.250,00
--------------------------------------------
TOTAL (3 itens)                   10.000,00
--------------------------------------------

Retorno (JSON):

{
  "items": [
    { "nome": "Bruto", "expressao": "5000", "valor": 5000 },
    { "nome": "Imposto", "expressao": "Bruto * 15%", "valor": 750 },
    { "nome": "Liquido", "expressao": "Bruto - Imposto", "valor": 4250 }
  ],
  "total": 10000
}

Método de Contagem (token_count)

| Aspecto | Detalhe | |---------|---------| | Fórmula | tokens = Math.ceil(caracteres / 4) | | Ratio | ~4 caracteres por token | | Precisão | Estimativa (não é contagem exata via tokenizer) | | Arquivos grandes | Leitura em chunks de 64KB (>1MB) | | Binários | Ignorados automaticamente |

Nota: Esta é uma estimativa genérica. Tokenizers reais (como o do Claude ou GPT) podem variar. Para decisões críticas de custo, use o tokenizer oficial do modelo.

Arquivos Ignorados Automaticamente (token_count)

Diretórios

node_modules, .git, .next, .turbo, .nuxt, .output, dist, build, out, coverage, target, .cache, .tmp, .vercel, .netlify, .firebase, .analyze, .claude, .github, .vscode, .idea, .cursor

Arquivos

package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, bun.lock, composer.lock, Gemfile.lock, cargo.lock, .DS_Store, Thumbs.db

Extensões reconhecidas como texto

.ts, .tsx, .js, .jsx, .mjs, .cjs, .json, .md, .mdx, .txt, .yaml, .yml, .toml, .xml, .html, .css, .scss, .less, .py, .rb, .go, .rs, .java, .kt, .swift, .sh, .bash, .zsh, .ps1, .sql, .graphql, .gql, .vue, .svelte, .astro

Arquivos sem extensão reconhecidos

Makefile, Dockerfile, Jenkinsfile, Vagrantfile, LICENSE, README, CHANGELOG, CONTRIBUTING, CNAME, .gitignore, .dockerignore, .editorconfig, .env, .npmrc, .nvmrc, .gitattributes

Estrutura do Projeto

calculator/
├── src/
│   ├── index.ts              # Servidor MCP principal
│   ├── types.ts              # Tipos (FileResult, CountOptions)
│   ├── constants.ts          # Constantes (ratios, extensões, filtros)
│   ├── utils/
│   │   ├── calc/
│   │   │   ├── types.ts      # Tipos da calculadora (Entry, CalcResult, etc.)
│   │   │   ├── parser.ts     # Parsing de entradas, aliases, dependências
│   │   │   ├── evaluator.ts  # Avaliação com mathjs, topological sort
│   │   │   ├── formatter.ts  # Formatação tabela ASCII e JSON
│   │   │   └── index.ts      # Barrel export
│   │   ├── fs.ts             # Resolução recursiva de caminhos
│   │   ├── estimate.ts       # Contagem de chars e estimativa de tokens
│   │   └── format.ts         # Formatação da tabela ASCII
│   ├── tools/
│   │   ├── count.ts          # Tool token_count
│   │   └── calc.ts           # Tool calc
│   └── __tests__/
│       ├── calc/
│       │   ├── parser.test.ts      # Testes do parser
│       │   ├── evaluator.test.ts   # Testes do evaluator
│       │   ├── formatter.test.ts   # Testes do formatter
│       │   └── handler.test.ts     # Testes de integração
│       ├── constants.test.ts
│       ├── fs.test.ts
│       ├── estimate.test.ts
│       ├── format.test.ts
│       └── count.test.ts
├── dist/                     # Build compilado
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── README.md
└── AGENTS.md

Desenvolvimento

# Clonar repositório
git clone https://github.com/justmpm/calculator-mcp
cd calculator-mcp

# Instalar dependências
npm install

# Build
npm run build

# Desenvolvimento com watch
npm run dev

# Testes
npm test

# Executar localmente
npm start

Testar com MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Abre uma interface visual no navegador para testar as tools.

Documentação Adicional

AGENTS.md

Guia simplificado para subagents sobre como usar as tools. Inclui referência rápida, exemplos de uso e dicas.

Para Subagents: Consulte AGENTS.md para orientações rápidas.

Troubleshooting

"Nenhum arquivo encontrado" (token_count)

Verifique se cwd está correto e se os caminhos em paths existem dentro desse diretório.

"Referência circular detectada" (calc)

Uma variável depende de si mesma (direta ou indiretamente). Crie uma etapa intermediária para quebrar o ciclo.

"Identificador desconhecido" (calc)

Confira se o nome da variável foi escrito exatamente igual ao definido na entrada, incluindo espaços e acentos.

Tokens menores que o esperado (token_count)

Arquivos binários (imagens, fontes, etc) e lock files são ignorados automaticamente. Arquivos dentro de node_modules, .git, dist e outras pastas também são ignorados.

O MCP não inicia

1. Verifique se o cliente MCP foi reiniciado após a configuração
2. Confirme se o Node.js está instalado (node --version)
3. Teste manualmente: npx -y @justmpm/calculator --version

Licença

MIT - Koda AI Studio

Links

• Koda AI Studio: https://kodaai.app
• Model Context Protocol: https://modelcontextprotocol.io/
• Repositório: https://github.com/justmpm/calculator-mcp