calculator-mcp-server

Avaliação matemática, simplificação, derivadas

GitHub

Experimente este MCPPatrocinado

Documentação

@cyanheads/calculator-mcp-server

Avalie, simplifique e diferencie expressões matemáticas via MCP. STDIO ou Streamable HTTP.

1 Ferramenta • 1 Recurso

Servidor Público Hospedado: https://calculator.caseyjhand.com/mcp

Visão Geral

Calculadora alimentada por math.js. Verifique resultados numéricos, simplifique expressões algébricas e calcule derivadas simbólicas por meio de uma única ferramenta. Funciona como um processo stdio, um servidor Streamable HTTP local ou o endpoint público hospedado acima.

Ferramentas

Ferramenta	Descrição
`calculate`	Avalie expressões matemáticas, simplifique expressões algébricas ou calcule derivadas simbólicas.

Recursos

Recurso	Descrição
`calculator://help`	Funções, operadores, constantes e referência de sintaxe disponíveis.

Referência de capacidades

`calculate` _ferramenta

Uma expression por chamada. operation seleciona evaluate (padrão), simplify ou derivative; derivadas exigem variable (ex.: "x").
Avalie aritmética, trigonometria, logaritmos, estatística, matrizes, números complexos, unidades e combinatória; atribua variáveis numéricas por meio de scope, ex.: { "x": 5 }.
numericType seleciona number, BigNumber (64 dígitos significativos, para valores que excedem um float de 64 bits) ou Fraction (racionais exatos). O modo fração retorna fraction_unsupported, com orientação para alterar o tipo numérico, quando um resultado não tem valor racional exato (sqrt(2)), a expressão chama uma função que o modo fração não consegue calcular (sqrt(4), 5!) ou usa um valor que o modo fração mantém apenas como float arredondado (pi, 2^(1/2)).
precision define de 1 a 16 dígitos significativos para resultados numéricos. Valores opcionais em branco de variable e precision são tratados como omitidos; escopo e precisão não afetam operações simbólicas.
A simplificação inclui identidades algébricas e trigonométricas (2x + 3x → 5 * x); unchanged: true identifica expressões que o simplificador não consegue reduzir, incluindo casos de fatoração polinomial e cancelamento racional.
Retorna a string do resultado, o tipo do resultado, a expressão original e a operação. Falhas de validação incluem motivos tipados e dicas de recuperação.

`calculator://help` _recurso

Referência em Markdown para funções, operadores, constantes, unidades e sintaxe de expressões; sem parâmetros.
Exemplos cobrem escopo, matrizes, números complexos, precisão e todas as três operações.
Armazenável em cache por 24 horas com escopo público (cacheHint) — conteúdo estático que nunca muda em tempo de execução.

Recursos

Construído sobre @cyanheads/mcp-ts-core: transportes stdio e Streamable HTTP, autenticação plugável (none / jwt / oauth), armazenamento substituível (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estruturado com rastreamento OpenTelemetry opcional.

Específico da calculadora:

Instância endurecida do math.js v15 — funções perigosas desabilitadas, avaliação executada sob timeout de vm
Sem autenticação necessária — todas as operações são somente leitura e sem estado
Validação de entrada: limites de comprimento de expressão e rejeição de múltiplas declarações; separadores de linhas de matriz e conteúdos de string permanecem válidos
Validação de resultado: tipos de resultado bloqueados (funções, parsers, conjuntos de resultados), tamanho máximo configurável do resultado
Limites de tamanho: funções que constroem uma matriz ou string a partir de um argumento de tamanho, produto, broadcast, índice ou precisão são limitadas por chamada, e cada avaliação tem um orçamento total de elementos; solicitações excessivamente grandes falham rapidamente com result_too_large
Sanitização de escopo: valores somente numéricos, prevenção de poluição de protótipo (bloqueio de __proto__, constructor, etc.)

Saída amigável para agentes:

Eco de chamada efetiva — cada resposta ecoa a expressão e a operação, além de quais variáveis de escopo e qual precisão foram aplicadas, para que agentes possam verificar o que foi realmente calculado
Contratos de saída discriminados — unchanged: true em simplify sinaliza um resultado sem operação em vez de retornar silenciosamente a mesma expressão
Motivos de erro tipados — falhas de validação e avaliação carregam um reason tipado (ex.: fraction_unsupported, evaluation_timeout, disallowed_result_type) além de uma dica de recuperação acionável, em vez de uma exceção bruta

Primeiros passos

Instância Pública Hospedada

Uma instância pública está disponível em https://calculator.caseyjhand.com/mcp — sem necessidade de instalação. Aponte qualquer cliente MCP para ela via Streamable HTTP:

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "streamable-http",
      "url": "https://calculator.caseyjhand.com/mcp"
    }
  }
}

Auto-hospedado / Local

Adicione um dos seguintes ao arquivo de configuração do seu cliente MCP:

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/calculator-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Ou com npx (sem necessidade de Bun):

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/calculator-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Ou com Docker:

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/calculator-mcp-server:latest"
      ]
    }
  }
}

Para Streamable HTTP, defina o transporte e inicie o servidor integrado:

MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Pré-requisitos

Bun v1.4.0 ou superior

Instalação

Clone o repositório:

git clone https://github.com/cyanheads/calculator-mcp-server.git

Navegue até o diretório:

cd calculator-mcp-server

Instale as dependências:

bun install

Configuração

Variável	Descrição	Padrão
`CALC_MAX_EXPRESSION_LENGTH`	Comprimento máximo permitido da string de expressão (10–10.000).	`1000`
`CALC_EVALUATION_TIMEOUT_MS`	Tempo máximo de avaliação em milissegundos (100–30.000).	`5000`
`CALC_MAX_RESULT_LENGTH`	Comprimento máximo da string de resultado em caracteres (1.000–1.000.000).	`100000`
`MCP_TRANSPORT_TYPE`	Transporte: `stdio` ou `http`.	`stdio`
`MCP_HTTP_HOST`	Hostname para o servidor HTTP.	`127.0.0.1`
`MCP_HTTP_PORT`	Porta para o servidor HTTP.	`3010`
`MCP_HTTP_ENDPOINT_PATH`	Caminho para o endpoint MCP HTTP.	`/mcp`
`MCP_HTTP_MAX_BODY_BYTES`	Tamanho máximo de solicitação HTTP de entrada; `0` desativa o limite.	`1048576`
`MCP_AUTH_MODE`	Modo de autenticação: `none`, `jwt` ou `oauth`.	`none`
`MCP_SESSION_MODE`	`auto`, `stateful` ou `stateless`. O servidor declara `stateless` no código, então cada caminho de inicialização resolve da mesma forma; definir isso substitui essa declaração.	`stateless`
`MCP_LOG_LEVEL`	Nível de registro (RFC 5424).	`info`

Consulte .env.example para configurações opcionais de sessão, retomabilidade, registro e telemetria.

Executando o servidor

Desenvolvimento local

Compile e execute a versão de produção:

bun run build
bun run start:http   # or start:stdio

Execute verificações e testes:

bun run devcheck     # Lints, formats, type-checks
bun run test         # Runs test suite

Docker

docker build -t calculator-mcp-server .
docker run -p 3010:3010 calculator-mcp-server

A imagem usa como padrão Streamable HTTP na porta 3010, sessões sem estado e registros em /var/log/calculator-mcp-server. Dependências OpenTelemetry são instaladas por padrão; compile com --build-arg OTEL_ENABLED=false para omiti-las.

Estrutura do projeto

Diretório	Finalidade
`src/mcp-server/tools/`	Definições de ferramentas (`*.tool.ts`).
`src/mcp-server/resources/`	Definições de recursos (`*.resource.ts`).
`src/services/`	Integrações de serviços de domínio (MathService).
`src/config/`	Análise e validação de variáveis de ambiente com Zod.
`docs/`	Árvore de diretórios gerada.
`tests/`	Testes de cálculo, configuração e contratos de resposta.

Guia de desenvolvimento

Consulte AGENTS.md ou CLAUDE.md para diretrizes de desenvolvimento e regras arquiteturais. A versão resumida:

Handlers lançam exceções, o framework captura — sem try/catch na lógica de ferramentas
Use ctx.log para registro
Registre novas ferramentas e recursos em src/index.ts

Contribuindo

Issues são bem-vindas. Execute as verificações antes de enviar:

bun run devcheck
bun run test

Licença

Apache-2.0 — consulte LICENSE para detalhes.

calculator-mcp-server

Documentação

@cyanheads/calculator-mcp-server

Visão Geral

Ferramentas

Recursos

Referência de capacidades

calculate ferramenta

calculator://help recurso

Recursos

Primeiros passos

Instância Pública Hospedada

Auto-hospedado / Local

Pré-requisitos

Instalação

Configuração

Executando o servidor

Desenvolvimento local

Docker

Estrutura do projeto

Guia de desenvolvimento

Contribuindo

Licença

`calculate` _ferramenta

`calculator://help` _recurso