calculator-mcp-server

---

Resumen

Calculadora impulsada por math.js. Verifica resultados numéricos, simplifica expresiones algebraicas y calcula derivadas simbólicas mediante una sola herramienta. Se ejecuta como proceso stdio, como servidor local Streamable HTTP o mediante el endpoint público alojado indicado arriba.

Herramientas

Herramienta	Descripción
calculate	Evalúa expresiones matemáticas, simplifica expresiones algebraicas o calcula derivadas simbólicas.

Recursos

Recurso	Descripción
calculator://help	Funciones, operadores, constantes y referencia de sintaxis disponibles.

Referencia de capacidades

calculate _herramienta

• Una expression por llamada. operation selecciona evaluate (predeterminado), simplify o derivative; las derivadas requieren variable (p. ej., "x").
• Evalúa aritmética, trigonometría, logaritmos, estadística, matrices, números complejos, unidades y combinatoria; asigna variables numéricas mediante scope, p. ej., { "x": 5 }.
• numericType selecciona number, BigNumber (64 dígitos significativos, para valores que desbordan un flotante de 64 bits) o Fraction (racionales exactos). El modo fracción devuelve fraction_unsupported, con orientación para cambiar el tipo numérico, cuando un resultado no tiene un valor racional exacto (sqrt(2)), la expresión llama a una función que el modo fracción no puede calcular (sqrt(4), 5!) o usa un valor que el modo fracción conserva solo como flotante redondeado (pi, 2^(1/2)).
• precision establece de 1 a 16 dígitos significativos para resultados numéricos. Los valores opcionales en blanco de variable y precision se tratan como omitidos; el alcance y la precisión no afectan las operaciones simbólicas.
• La simplificación incluye identidades algebraicas y trigonométricas (2x + 3x → 5 * x); unchanged: true identifica expresiones que el simplificador no puede reducir, incluidos casos de factorización polinómica y cancelación racional.
• Devuelve la cadena de resultado, el tipo de resultado, la expresión original y la operación. Los fallos de validación incluyen razones tipadas y sugerencias de recuperación.

---

calculator://help _recurso

• Referencia en Markdown para funciones, operadores, constantes, unidades y sintaxis de expresiones; sin parámetros.
• Los ejemplos cubren alcance, matrices, números complejos, precisión y las tres operaciones.
• Almacenable en caché durante 24 horas con alcance público (cacheHint): contenido estático que nunca cambia en tiempo de ejecución.

Características

Construido sobre @cyanheads/mcp-ts-core: transportes stdio y Streamable HTTP, autenticación conectable (none / jwt / oauth), almacenamiento intercambiable (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estructurado con rastreo opcional de OpenTelemetry.

Específico de la calculadora:

• Instancia reforzada de math.js v15: funciones peligrosas deshabilitadas, evaluación ejecutada bajo un tiempo de espera de vm
• Sin autenticación requerida: todas las operaciones son de solo lectura y sin estado
• Validación de entrada: límites de longitud de expresión y rechazo de múltiples declaraciones; los separadores de filas de matrices y los contenidos de cadenas siguen siendo válidos
• Validación de resultados: tipos de resultado bloqueados (funciones, analizadores, conjuntos de resultados), tamaño máximo de resultado configurable
• Límites de tamaño: las funciones que construyen una matriz o cadena a partir de un argumento de tamaño, producto, difusión, índice o precisión están limitadas por llamada, y cada evaluación tiene un presupuesto total de elementos; las solicitudes sobredimensionadas fallan rápidamente con result_too_large
• Saneamiento del alcance: valores solo numéricos, prevención de contaminación de prototipos (bloqueo de __proto__, constructor, etc.)

Salida amigable para agentes:

• Eco de llamada efectiva: cada respuesta repite la expresión y la operación, además de qué variables de alcance y qué precisión se aplicaron, para que los agentes puedan verificar qué se calculó realmente
• Contratos de salida discriminados: unchanged: true en simplify marca un resultado sin operación en lugar de devolver silenciosamente la misma expresión
• Razones de error tipadas: los fallos de validación y evaluación llevan un reason tipado (p. ej., fraction_unsupported, evaluation_timeout, disallowed_result_type) además de una sugerencia de recuperación accionable, en lugar de una excepción cruda

Primeros pasos

Instancia pública alojada

Hay una instancia pública disponible en https://calculator.caseyjhand.com/mcp: no se requiere instalación. Apunta cualquier cliente MCP a ella mediante Streamable HTTP:

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

Autohospedado / Local

Agrega una de las siguientes opciones a tu archivo de configuración del 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"
      }
    }
  }
}

O con npx (sin necesidad 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"
      }
    }
  }
}

O con 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, configura el transporte e inicia el servidor integrado:

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

Requisitos previos

• Bun v1.4.0 o superior

Instalación

1. Clona el repositorio:

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

2. Navega al directorio:

cd calculator-mcp-server

3. Instala las dependencias:

bun install

Configuración

Variable	Descripción	Predeterminado
CALC_MAX_EXPRESSION_LENGTH	Longitud máxima permitida de la cadena de expresión (10–10,000).	1000
CALC_EVALUATION_TIMEOUT_MS	Tiempo máximo de evaluación en milisegundos (100–30,000).	5000
CALC_MAX_RESULT_LENGTH	Longitud máxima de la cadena de resultado en caracteres (1,000–1,000,000).	100000
MCP_TRANSPORT_TYPE	Transporte: stdio o http.	stdio
MCP_HTTP_HOST	Nombre de host para el servidor HTTP.	127.0.0.1
MCP_HTTP_PORT	Puerto para el servidor HTTP.	3010
MCP_HTTP_ENDPOINT_PATH	Ruta para el endpoint MCP HTTP.	/mcp
MCP_HTTP_MAX_BODY_BYTES	Tamaño máximo de solicitud HTTP entrante; 0 deshabilita el límite.	1048576
MCP_AUTH_MODE	Modo de autenticación: none, jwt o oauth.	none
MCP_SESSION_MODE	auto, stateful o stateless. El servidor declara stateless en el código, por lo que cada ruta de inicio se resuelve de la misma manera; configurar esto anula esa declaración.	stateless
MCP_LOG_LEVEL	Nivel de registro (RFC 5424).	info

Consulta .env.example para configuraciones opcionales de sesión, reanudabilidad, registro y telemetría.

Ejecución del servidor

Desarrollo local

• Compila y ejecuta la versión de producción:

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

• Ejecuta comprobaciones y pruebas:

  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

La imagen usa por defecto Streamable HTTP en el puerto 3010, sesiones sin estado y registros en /var/log/calculator-mcp-server. Las dependencias de OpenTelemetry se instalan por defecto; compila con --build-arg OTEL_ENABLED=false para omitirlas.

Estructura del proyecto

Directorio	Propósito
src/mcp-server/tools/	Definiciones de herramientas (*.tool.ts).
src/mcp-server/resources/	Definiciones de recursos (*.resource.ts).
src/services/	Integraciones de servicios de dominio (MathService).
src/config/	Análisis y validación de variables de entorno con Zod.
docs/	Árbol de directorios generado.
tests/	Pruebas de cálculo, configuración y contratos de respuesta.

Guía de desarrollo

Consulta AGENTS.md o CLAUDE.md para pautas de desarrollo y reglas arquitectónicas. La versión breve:

• Los manejadores lanzan excepciones, el marco las captura: sin try/catch en la lógica de herramientas
• Usa ctx.log para el registro
• Registra nuevas herramientas y recursos en src/index.ts

Contribuciones

Las incidencias son bienvenidas. Ejecuta las comprobaciones antes de enviar:

bun run devcheck
bun run test

Licencia

Apache-2.0: consulta LICENSE para más detalles.