Cruncher MCP

A calculadora científica construída como um servidor Model Context Protocol (MCP)

Documentação

Cruncher: O Servidor MCP de Calculadora Científica

Uma calculadora científica poderosa para o seu assistente de IA, construída como um servidor Model Context Protocol (MCP). O Cruncher permite que clientes de IA compatíveis (como o Claude Desktop) realizem cálculos matemáticos complexos, gerenciem memória, façam análises estatísticas e acessem constantes científicas com uma interface simples, segura e padronizada.

🌟 A Promessa de Pureza (Zero Dependências)

O Cruncher é construído como uma ferramenta altamente educacional e extremamente leve. Ele alcança recursos poderosos sem depender de bibliotecas externas pesadas (sem mathjs, sem zod, sem @modelcontextprotocol/sdk). Tudo é tratado usando capacidades nativas do Node.js:

Avaliação Segura de Expressões: Em vez de depender de mathjs ou de eval() perigosos, o Cruncher usa new Function() protegido por uma Regex de lista de permissões estrita que garante que apenas números e operadores matemáticos possam passar.
Validação de Entrada: Em vez de bibliotecas de esquema pesadas como Zod, uma função de validação recursiva personalizada impõe rigidamente as entradas da IA contra JSON Schemas diretamente.
Proteção contra Timeout: Em vez de gerenciadores de processos complexos, ele aproveita o worker_threads do Node.js para gerar cálculos. Se uma IA solicitar um fatorial de loop de milhões, o thread principal termina facilmente o worker após um timeout estrito (padrão de 3 segundos). Esse timeout é configurável através da variável de ambiente CRUNCHER_TIMEOUT (em milissegundos), garantindo que o servidor permaneça responsivo mesmo durante cargas computacionais pesadas.
Precisão de Ponto Flutuante: Em vez de usar decimal.js, ele resolve o clássico erro de matemática JS (0.1 + 0.2 = 0.30000000000000004) via lógica dinâmica de escalonamento de inteiros nos bastidores.

📚 Uma Abordagem Educacional para MCP

Este projeto serve como um excelente recurso de aprendizado para desenvolvedores que desejam entender profundamente o Model Context Protocol (MCP). Como ele evita deliberadamente usar o @modelcontextprotocol/sdk oficial, toda a implementação do protocolo MCP, manipulação de mensagens JSON-RPC, validações de entrada e formatação de erros é exposta em JavaScript puro.

Ler o cruncher.js fornece uma visão incomparável e transparente de exatamente como um servidor MCP se comunica via stdio, analisa solicitações recebidas (initialize, tools/list, tools/call) e responde de volta ao cliente de IA—desmistificando a "mágica" que os SDKs geralmente escondem.

O que é o Model Context Protocol?

O Model Context Protocol (MCP) é um padrão aberto que permite que aplicações de IA se conectem com segurança a fontes de dados e ferramentas externas. Pense nele como uma API universal para IA. Ao implementar o Cruncher como um servidor MCP, qualquer IA que entenda MCP pode ganhar instantaneamente capacidades poderosas de calculadora integradas, sem integrações personalizadas.

✨ Recursos

O Cruncher fornece um conjunto abrangente de funções de calculadora construídas completamente do zero, sem dependências pesadas:

Arquitetura Robusta:
- Zero Dependências: Depende puramente das bibliotecas padrão do Node.js.
- Validação Estrita de Entrada: Validador de esquema personalizado previne alucinações da IA e dados inválidos.
- Proteção contra Loop Infinito: Utiliza o worker_threads do Node.js com um timeout estrito de 3 segundos para evitar que cálculos complexos congelem o servidor.
- Matemática Decimal Precisa: Usa uma abordagem de escalonamento de inteiros para prevenir erros clássicos de ponto flutuante do JS (por exemplo, 0.1 + 0.2 === 0.3).
Exposição de Ferramentas em Camadas: Três camadas (minimal, standard padrão, full) para otimizar o uso de tokens de contexto.
Aritmética Básica: Adição, Subtração, Multiplicação, Divisão, Módulo.
Avaliação de Expressões: Calcule com segurança strings matemáticas inteiras em texto simples (por exemplo, (5 + 3) * 10 / 2).
Potências e Raízes: Exponenciação (a^b), Raiz Quadrada.
Teoria dos Números: Fatorial (n!).
Trigonometria: Seno, Cosseno, Tangente, Arco Seno (asin), Arco Cosseno (acos) e Arco Tangente (atan) (com suporte para graus e radianos).
Logaritmos: Logaritmo de Base 10 e Logaritmo Natural (ln).
Funções Estatísticas: Soma, Média, Mediana, Mínimo, Máximo, Amplitude, Contagem, Variância e Desvio Padrão para arrays de números.
Funções de Porcentagem: Porcentagem de, variação percentual e cálculos de porcentagem reversa.
Conversão de Unidades: Mais de 80 conversões em 8 categorias (comprimento, peso, temperatura, área, volume, tempo, velocidade, armazenamento digital).
Funções de Conveniência: Valor Absoluto.
Constantes: Acesso fácil a constantes de Matemática (pi, e, tau, phi, sqrt2, euler_mascheroni), Física (c, g, G, h, k, R) e Química (NA, e_charge, m_e, m_p).
Funções de Memória: M+, M-, MR (Recuperação de Memória) e MC (Limpeza de Memória) - apenas na camada completa.

🚀 Instalação e Uso

Coloque o Cruncher em funcionamento com o Claude Desktop em apenas alguns minutos.

Passo 1: Pré-requisitos

Certifique-se de ter o Node.js (versão 18.0.0 ou mais recente) instalado no seu sistema. Você pode baixá-lo em nodejs.org.

Passo 1: Início Rápido com npm

Recomendado: Instale via npm e use diretamente:

npx @slbdn/cruncher-mcp

Isso baixa e executa a versão mais recente automaticamente.

Passo 2: Configure o Claude Desktop

Recomendado: Use o pacote npm para atualizações automáticas:

{
  "mcpServers": {
    "cruncher": {
      "command": "npx",
      "args": ["-y", "@slbdn/cruncher-mcp"]
    }
  }
}

Passo 3: Arquivo Manual (Alternativa)

Se você preferir baixar o arquivo manualmente:

Baixe o arquivo cruncher.js diretamente do GitHub.
Coloque-o em um local permanente (por exemplo, C:\mcp-servers\cruncher.js ou /home/user/mcp-servers/cruncher.js).
Localize o arquivo de configuração do Claude Desktop:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Adicione a configuração do servidor apontando para o arquivo baixado:
```
{
  "mcpServers": {
    "cruncher": {
      "command": "node",
      "args": ["C:/Users/YOUR_USERNAME/mcp-servers/cruncher.js"],
      "env": {
        "CRUNCHER_TOOL_SET": "standard"
      }
    }
  }
}
```
Nota para usuários de macOS/Linux: Use um caminho no estilo POSIX, por exemplo, "/home/YOUR_USERNAME/mcp-servers/cruncher.js". Certifique-se de que o executável node esteja no PATH do seu sistema.

Passo 4: Comece a Calcular!

Salve o arquivo de configuração e saia completamente do aplicativo Claude Desktop.
Reinicie o Claude Desktop. Ele se conectará automaticamente ao servidor Cruncher.
Comece a fazer perguntas!

OpenWebUI (Antigo Ollama WebUI)

O OpenWebUI suporta nativamente a conexão a servidores MCP stdio.

Opção A: Usando o pacote npm

Vá para Painel de Administração > Configurações > Ferramentas > Servidores MCP.
Clique em Adicionar Servidor.
Nomeie-o como "Cruncher", selecione Comando e insira npx, defina Args como @slbdn/cruncher-mcp.

Opção B: Usando arquivo baixado

Vá para Painel de Administração > Configurações > Ferramentas > Servidores MCP.
Clique em Adicionar Servidor.
Nomeie-o como "Cruncher", selecione stdio, use node como o comando e /path/to/cruncher.js como o argumento.

IDE Cursor

Você pode dar à IA integrada do Cursor a capacidade de executar matemática e calcular hashes.

Opção A: Usando o pacote npm

Abra as Configurações do Cursor (ícone de engrenagem) > Recursos > Servidores MCP.
Clique em + Adicionar Novo Servidor MCP.
Defina o Tipo como command, Nome como cruncher e Comando como npx @slbdn/cruncher-mcp.

Opção B: Usando arquivo baixado

Abra as Configurações do Cursor (ícone de engrenagem) > Recursos > Servidores MCP.
Clique em + Adicionar Novo Servidor MCP.
Defina o Tipo como command, Nome como cruncher e Comando como node /path/to/cruncher.js.

Cline (Extensão do VS Code)

Se você usa o Cline para codificação agêntica no VS Code, abra o arquivo de configuração MCP (cline_mcp_settings.json) e adicione:

Opção A: Usando o pacote npm

{
  "mcpServers": {
    "cruncher": {
      "command": "npx",
      "args": ["-y", "@slbdn/cruncher-mcp"]
    }
  }
}

Opção B: Usando arquivo baixado

{
  "mcpServers": {
    "cruncher": {
      "command": "node",
      "args": ["/path/to/cruncher.js"],
      "env": {
        "CRUNCHER_TOOL_SET": "standard"
      }
    }
  }
}

Goose (Agente de Terminal)

O Goose é um assistente de IA leve baseado em terminal que suporta totalmente MCP.

Opção A: Usando o pacote npm

Edite ~/.goose/config.yaml (ou a configuração do projeto local).
Adicione uma nova entrada de servidor:

mcpServers:
  cruncher:
    command: npx
    args:
      - -y
      - "@slbdn/cruncher-mcp"

Opção B: Usando arquivo baixado

Edite ~/.goose/config.yaml (ou a configuração do projeto local).
Adicione uma nova entrada de servidor:

mcpServers:
  cruncher:
    command: node
    args:
      - "/path/to/cruncher.js"
    env:
      CRUNCHER_TOOL_SET: "standard"

Reinicie o Goose. Agora você pode pedir ao Goose para executar cálculos como evaluate_expression ou median diretamente.

Editor Zed (Painel de IA)

O painel de IA integrado do Zed suporta conexões MCP.

Opção A: Usando o pacote npm

Abra Configurações → IA → Servidores MCP.
Clique em Adicionar Servidor e preencha:
- Nome: cruncher
- Comando: npx
- Args: @slbdn/cruncher-mcp
Salve. A IA do Zed agora pode chamar o Cruncher para aritmética e estatísticas precisas.

Opção B: Usando arquivo baixado

Abra Configurações → IA → Servidores MCP.
Clique em Adicionar Servidor e preencha:
- Nome: cruncher
- Comando: node
- Args: /absolute/path/to/cruncher.js
- Env (opcional): CRUNCHER_TOOL_SET=standard
Salve. A IA do Zed agora pode chamar o Cruncher para aritmética e estatísticas precisas.

LM Studio (LLM Local + MCP)

O LM Studio executa LLMs totalmente offline e agora inclui um cliente MCP.

Opção A: Usando o pacote npm

Abra Configurações → MCP no LM Studio.
Clique em Adicionar Servidor e forneça:
- Executável: npx
- Argumentos: @slbdn/cruncher-mcp
Confirme. Seu modelo privado agora pode transferir matemática para o Cruncher sem nenhum tráfego de rede.

Opção B: Usando arquivo baixado

Abra Configurações → MCP no LM Studio.
Clique em Adicionar Servidor e forneça:
- Executável: node
- Argumentos: /absolute/path/to/cruncher.js
- Ambiente (opcional): CRUNCHER_TOOL_SET=standard
Confirme. Seu modelo privado (por exemplo, Llama 3, DeepSeek-V2) agora pode transferir matemática para o Cruncher sem nenhum tráfego de rede.

Configuração do LibreChat

Se você estiver usando o LibreChat, pode adicionar a seguinte configuração ao seu arquivo librechat.yaml:

Opção A: Usando o pacote npm

  cruncher:
    type: stdio
    command: npx
    args:
      - -y
      - "@slbdn/cruncher-mcp"

Opção B: Usando arquivo baixado

  cruncher:
    type: stdio
    command: node
    args:
      - "/opt/mcp/cruncher.js"
    env:
      CRUNCHER_TIMEOUT: "5000"

Exemplos de Perguntas para o Claude

"Qual é o ângulo em graus cujo seno é 0,5?"

"Calcule a média, a mediana e a amplitude destes números: [15, 22, 8, 41, 19, 30]"

"Quanto é 2 elevado à potência de 10?"

"Qual é o desvio padrão de [10, 12, 8, 14, 6]?"

"Quanto é 15% de 240?"

"Uma ação foi de $50 para $75. Qual é a variação percentual?"

"Qual é a variância das notas do teste [85, 92, 78, 90, 88]?"

"Calcule a amplitude dos valores em [3, 7, 2, 9, 1]"

"Avalie a expressão: sin(pi/4) + sqrt(16) + log10(100)"

"Quanto é 10 fatorial?"

"Quanto é 17 módulo 5?"

Exemplos da Camada Completa (com CRUNCHER_TOOL_SET=full):

"Armazene 99 na memória, adicione 5 e depois recupere o total."

"Qual é o 75º percentil de [10, 20, 30, 40, 50]?"

"Converta 11010 de binário para decimal."

"Lote: raiz quadrada de 144, adicione 10 e depois eleve à potência de 2."

"Mude as funções trigonométricas para o modo radianos."

"Limpe o cache de resultados e mostre as estatísticas do cache."

"Recupere o que está na memória, depois subtraia 15 e armazene o resultado."

"Qual é o 95º percentil de [23, 45, 12, 67, 89, 34, 56, 78, 90, 11]?"

"Converta 0xFF de hexadecimal para binário."

📋 Ferramentas Disponíveis

O Cruncher expõe suas funções como ferramentas MCP individuais. Aqui está a lista completa:

Nome da Ferramenta	Descrição	Argumentos
Aritmética Básica
`evaluate_expression`	Avalia uma expressão matemática em texto simples (ex.: `(5 + 3) * 10 / 2`).	`expression` (string)
`add`	Soma dois números (a + b).	`a` (número), `b` (número)
`subtract`	Subtrai o segundo número do primeiro (a - b).	`a` (número), `b` (número)
`multiply`	Multiplica dois números (a * b).	`a` (número), `b` (número)
`divide`	Divide o primeiro número pelo segundo (a / b).	`a` (número), `b` (número)
`modulo`	Calcula o resto (a mod b).	`a` (número), `b` (número)
Potência e Raízes
`power`	Calcula a elevado à potência de b (a^b).	`base` (número), `exponent` (número)
`sqrt`	Calcula a raiz quadrada de um valor.	`value` (número)
Teoria dos Números
`factorial`	Calcula o fatorial de um inteiro não negativo (n!).	`n` (número, inteiro não negativo)
Conversão de Unidades
`convert_unit`	Converte entre unidades comuns. 8 categorias, mais de 80 unidades.	`value` (número), `category` (string), `from` (string), `to` (string)
Conversão de Base (Nível Completo)
`convert_base`	Converte entre bases 2, 8, 10, 16.	`value` (string), `from_base` (2, 8, 10, 16), `to_base` (2, 8, 10, 16)
Trigonometria
`sine`	Calcula o seno de um ângulo.	`angle` (número), `unit` (graus/radianos, opcional)
`cosine`	Calcula o cosseno de um ângulo.	`angle` (número), `unit` (graus/radianos, opcional)
`tangent`	Calcula a tangente de um ângulo.	`angle` (número), `unit` (graus/radianos, opcional)
`asin`	Calcula o seno inverso (arco seno) de um valor. Retorna um ângulo.	`value` (número), `unit` (graus/radianos, opcional)
`acos`	Calcula o cosseno inverso (arco cosseno) de um valor. Retorna um ângulo.	`value` (número), `unit` (graus/radianos, opcional)
`atan`	Calcula a tangente inversa (arco tangente) de um valor. Retorna um ângulo.	`value` (número), `unit` (graus/radianos, opcional)
Logaritmos
`logarithm`	Calcula o logaritmo na base 10 de um valor.	`value` (número)
`natural_log`	Calcula o logaritmo natural (base e) de um valor.	`value` (número)
Funções Estatísticas
`sum`	Calcula a soma de um array de números.	`numbers` (array de números)
`avg`	Calcula a média de um array de números.	`numbers` (array de números)
`median`	Calcula a mediana de um array de números.	`numbers` (array de números)
`min`	Encontra o valor mínimo em um array de números.	`numbers` (array de números)
`max`	Encontra o valor máximo em um array de números.	`numbers` (array de números)
`count`	Conta o número de elementos em um array.	`numbers` (array de números)
`range`	Calcula a amplitude (máx - mín) de um array.	`numbers` (array de números)
`percentile`	Calcula o valor em um determinado percentil (0-100). Nível completo.	`numbers` (array de números), `percentile` (número, 0-100)
`variance`	Variância de um array. Amostra (n-1) ou população (n).	`numbers` (array de números), `population` (booleano, opcional)
`std_dev`	Desvio padrão. Amostra (n-1) ou população (n).	`numbers` (array de números), `population` (booleano, opcional)
`percentage_of`	Quanto é X% de Y? Ex.: 15% de 200 = 30.	`percent` (número), `total` (número)
`percentage_change`	Variação % de A para B. Ex.: 50→80 = 60%.	`from` (número), `to` (número)
`percentage_reverse`	X é Y% de quanto? Ex.: 30 é 15% de 200.	`value` (número), `percent` (número)
Outros
`absolute`	Calcula o valor absoluto de um número.	`value` (número)
Constantes
`get_constant`	Retorna o valor de uma constante matemática, física ou química.	`name` ("pi", "e", "tau", "phi", "sqrt2", "euler_mascheroni", "c", "g", "G", "h", "k", "R", "NA", "e_charge", "m_e", "m_p")
Funções de Memória (Nível Completo)
`memory_clear`	Limpa a memória da calculadora (MC).	(sem argumentos)
`memory_recall`	Recupera o valor armazenado na memória (MR).	(sem argumentos)
`memory_add`	Adiciona um valor à memória atual (M+).	`value` (número)
`memory_subtract`	Subtrai um valor da memória atual (M-).	`value` (número)
Modo de Ângulo (Nível Padrão)
`set_angle_mode`	Define o modo de ângulo global (padrão: graus).	`unit` ("degrees" ou "radians")
`get_angle_mode`	Obtém o modo de ângulo atual.	(sem argumentos)
Ferramentas de Administração (Nível Completo)
`batch`	Executa múltiplas chamadas de ferramentas sequencialmente.	`operations` (array de {tool, arguments})
`cache_clear`	Limpa o cache de computação.	(sem argumentos)
`cache_info`	Mostra estatísticas do cache.	(sem argumentos)

⚙️ Configuração

Variáveis de Ambiente

Variável	Padrão	Descrição
`CRUNCHER_TIMEOUT`	`3000`	Tempo limite de execução do thread de trabalho (ms). Intervalo 100-60000
`CRUNCHER_TOOL_SET`	`standard`	Controla a exposição de ferramentas: `minimal` (5), `standard` (34 padrão), `full` (43)

Níveis de Ferramentas - Referência Completa

O Cruncher expõe 3 níveis por meio da variável de ambiente CRUNCHER_TOOL_SET. Cada nível é um superconjunto estrito do anterior.

Visão Geral dos Níveis

Nível	Ferramentas	Caso de Uso
Mínimo (5)	Apenas aritmética básica	Calculadoras leves, agentes matemáticos simples
Padrão (34 - padrão)	Todo o mínimo + trigonometria, estatísticas, constantes, conversão de unidades	Matemática geral para assistentes de IA
Completo (43)	Todo o padrão + memória, lote, cache, conversão de base, estatísticas avançadas	Usuários avançados, fluxos de trabalho com múltiplas etapas

Nível Mínimo (5 Ferramentas)

Todas as ferramentas são executadas no thread de trabalho com proteção de tempo limite.

#	Ferramenta	Descrição
1	`evaluate_expression`	Avalia uma string de expressão matemática
2	`add`	Adição (a + b)
3	`subtract`	Subtração (a - b)
4	`multiply`	Multiplicação (a × b)
5	`divide`	Divisão (a ÷ b)

Nível Padrão (34 Ferramentas - inclui todas as 5 do Mínimo)

#	Ferramenta	Categoria
6	`sqrt`	Raiz quadrada
7	`power`	Exponenciação (a^b)
8	`absolute`	Valor absoluto
9	`modulo`	Resto (a mod b)
10	`factorial`	Fatorial (n!)
11	`logarithm`	Logaritmo na base 10
12	`natural_log`	Logaritmo natural (ln)
13	`get_constant`	Buscar constantes físicas/matemáticas
14-16	`sine`, `cosine`, `tangent`	Trigonometria
17-19	`asin`, `acos`, `atan`	Trigonometria inversa
20	`set_angle_mode`	Alternar graus/radianos (global)
21	`get_angle_mode`	Verificar modo de ângulo atual
22-25	`sum`, `avg`, `min`, `max`	Estatísticas básicas
26	`count`	Contar elementos
27	`variance`	Variância (amostra ou população)
28	`std_dev`	Desvio padrão (amostra ou população)
29	`percentage_of`	X% de Y
30	`percentage_change`	Variação % A→B
31	`percentage_reverse`	X é Y% de quanto?
32	`median`	Valor mediano
33	`range`	Amplitude (máx - mín)
34	`convert_unit`	Mais de 80 conversões de unidades, 8 categorias

Nível Completo (43 Ferramentas - inclui todas as 34 do Padrão)

#	Ferramenta	Categoria
35	`percentile`	Valor no enésimo percentil
36	`convert_base`	Conversão de base 2/8/10/16
37	`memory_add`	Adicionar ao total acumulado
38	`memory_subtract`	Subtrair do total acumulado
39	`memory_recall`	Obter valor atual da memória
40	`memory_clear`	Redefinir memória para zero
41	`batch`	Executar até 50 operações em uma chamada
42	`cache_clear`	Limpar cache de resultados
43	`cache_info`	Mostrar estatísticas do cache

Correspondência Difusa de Nomes de Ferramentas

Se o LLM chamar uma ferramenta que não existe, o Cruncher usa a distância de Levenshtein para encontrar a correspondência mais próxima e sugerir:

Erro de digitação	Sugestão	Tipo de Correspondência
`fact`	`factorial`	Correspondência de prefixo
`fac`	`factorial`	Correspondência de prefixo
`sinn`	`sine`	Erro de 1 caractere
`squrt`	`sqrt`	Transposição
`adddd`	`add`	Letras extras
`divid`	`divide`	Sufixo ausente
`totally_wrong`	(nenhum)	Muito diferente - sem sugestão

Formato de resposta:

{
  "error": {
    "code": -32601,
    "message": "Tool 'fact' not found. Did you mean 'factorial'?"
  }
}

Built-ins Estendidos do evaluate_expression

Além da aritmética básica, o evaluate_expression suporta estas funções nativamente:

Função	Descrição	Exemplo	Resultado
`sin(x)`	Seno (radianos, sempre em expressões)	`sin(pi / 2)`	1
`cos(x)`	Cosseno (radianos, sempre em expressões)	`cos(pi)`	-1
`tan(x)`	Tangente (radianos)	`tan(pi / 4)`	~1
`asin(x)`	Arco seno (resultado em radianos)	`asin(1)`	π/2
`acos(x)`	Arco cosseno (resultado em radianos)	`acos(0)`	π/2
`atan(x)`	Arco tangente (resultado em radianos)	`atan(1)`	π/4
`sqrt(x)`	Raiz quadrada	`sqrt(144)`	12
`log10(x)`	Logaritmo na base 10	`log10(1000)`	3
`ln(x)`	Logaritmo natural (base e)	`ln(e)`	1
`log(x, b)`	Logaritmo em base arbitrária	`log(8, 2)`	3
`abs(x)`	Valor absoluto	`abs(-5)`	5
`round(x)`	Arredondar para o inteiro mais próximo	`round(3.7)`	4
`floor(x)`	Arredondar para baixo	`floor(3.9)`	3
`ceil(x)`	Arredondar para cima	`ceil(3.1)`	4
`min(a,b,...)`	Valor mínimo	`min(3, 1, 4)`	1
`max(a,b,...)`	Valor máximo	`max(3, 1, 4)`	4

Combine livremente: sin(pi/6) + sqrt(16) + log10(100) = 6.5

Mensagens de Erro Melhoradas

Erros de domínio agora informam o que deu errado:

sqrt(-1) → "Verifique: sqrt(negativo), log(negativo/zero), asin/acos fora de [-1,1]"
1/0 → "Verifique divisão por zero ou estouro"
asin(5) → "asin/acos fora de [-1,1]"

Constantes em Expressões

Agora você pode usar nomes de constantes matemáticas e físicas diretamente dentro de evaluate_expression:

Constante	Descrição	Valor
`pi`	π (razão da circunferência)	3.14159...
`e`	Número de Euler	2.71828...
`tau`	τ = 2π	6.28318...
`phi`	Proporção áurea (φ)	1.61803...
`sqrt2`	√2	1.41421...
`euler_mascheroni`	Euler-Mascheroni (γ)	0.57721...
`c`	Velocidade da luz (m/s)	299792458
`g`	Gravidade (m/s2)	9.80665
`G`	Constante gravitacional	6.6743e-11
`h`	Constante de Planck (J·s)	6.62607015e-34
`k`	Constante de Boltzmann (J/K)	1.380649e-23
`R`	Constante dos gases ideais (J/mol·K)	8.314462618
`NA`	Constante de Avogadro (1/mol)	6.02214076e23
`e_charge`	Carga elementar (C)	1.602176634e-19
`m_e`	Massa do elétron (kg)	9.1093837015e-31
`m_p`	Massa do próton (kg)	1.67262192369e-27

Exemplos:

2 * pi * 5       → 31.4159...
phi ^ 2          → 2.61803...
G * 1e11         → 6.6743
sqrt2 * sqrt2    → 2
e * e            → 7.38906...
c * 2            → 599584916

Regras:

Use operadores explícitos: 2 * pi funciona, 2pi não (sem multiplicação implícita)
Constantes coexistem com notação científica: 1e6 e e * 2 funcionam corretamente
Nomes de constantes mais longos são correspondidos primeiro: euler_mascheroni não se tornará 299792458uler_mascheroni

Exposição de Ferramentas em Camadas

A variável de ambiente CRUNCHER_TOOL_SET permite otimizar o uso de tokens de contexto expondo apenas as ferramentas que você realmente precisa:

Camada	Ferramentas	Orçamento de Tokens	Caso de Uso
`minimal`	5	~160 tokens	Aritmética básica. Toda matemática complexa via `evaluate_expression`
`standard`	34	~1.150 tokens	Aritmética, trigonometria, estatísticas, porcentagens, constantes, conversão de unidades (padrão)
`full`	43	~1.500 tokens	Padrão + memória, conversão de base, percentil, lote, cache

Nota: Mesmo no modo minimal, o evaluate_expression lida com matemática complexa - ferramentas individuais (sin, sqrt, etc.) simplesmente não são registradas como chamadas de ferramentas MCP separadas. Isso economiza até 90% em tokens de contexto.

Exemplo de configuração MCP (claude_desktop_config.json):

{
  "mcpServers": {
    "cruncher-minimal": {
      "command": "node",
      "args": ["/path/to/cruncher.js"],
      "env": { "CRUNCHER_TOOL_SET": "minimal" }
    }
  }
}

⛏️ Como Funciona (Para Desenvolvedores)

Cruncher é um aplicativo JavaScript Node.js simples que se comunica via entrada/saída padrão (stdio). Isso o torna um servidor MCP leve, portátil e seguro. O fluxo completo para uma única chamada de ferramenta é assim:

Inicialização: Na inicialização, o servidor escuta uma solicitação initialize do cliente MCP e responde com suas capacidades e informações de versão (v1.2.31).
Descoberta de Ferramentas: O cliente envia uma solicitação tools/list, e o servidor responde com a lista completa de ferramentas de calculadora disponíveis e seus inputSchema, que define os argumentos necessários e seus tipos.
Validação de Entrada: Antes de qualquer ferramenta ser executada, o servidor executa uma função recursiva personalizada validateArguments contra o inputSchema da ferramenta. Isso garante que os campos obrigatórios estejam presentes, os tipos estejam corretos (número, string, array), os valores de enum sejam válidos e as restrições de mínimo/máximo sejam respeitadas - tudo sem qualquer biblioteca externa.
Execução em Thread de Trabalho: Uma vez validada, a chamada de ferramenta é repassada para um worker_thread Node.js isolado. Isso protege completamente o thread principal (e sua comunicação stdio) de ser bloqueado por um cálculo de longa duração ou infinito.
Proteção por Tempo Limite: Um temporizador configurável (CRUNCHER_TIMEOUT, padrão 3000ms) monitora o worker. Se o worker demorar demais, o thread principal o encerra à força via worker.terminate() e retorna um erro -32000 ao cliente de IA.
Matemática Segura e Resultado: O worker executa a função de manipulação usando safeMath (escala de inteiros) para aritmética segura com decimais, e então envia o resultado de volta ao thread principal, que formata e escreve a resposta final JSON-RPC 2.0 para stdout.

🤝 Contribuindo

Contribuições são bem-vindas! Se você quiser adicionar uma nova função, corrigir um bug ou melhorar a documentação, sinta-se à vontade para abrir uma issue ou enviar um pull request.

📜 Licença

Este projeto está licenciado sob a Licença MIT.