calculator-mcp-server

---

Herramientas

Una sola herramienta para todas las operaciones matemáticas:

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

calculate

Una única herramienta que cubre el 100 % del propósito del servidor. El parámetro operation tiene como valor predeterminado evaluate, por lo que el caso común es simplemente { expression: "..." }.

• Evaluar — aritmética, trigonometría, logaritmos, estadística, matrices, números complejos, conversión de unidades, combinatoria
• Simplificar — reduce expresiones algebraicas simbólicamente (p. ej., 2x + 3x -> 5 * x). Admite identidades algebraicas y trigonométricas
• Derivada — calcula derivadas simbólicas (p. ej., 3x^2 + 2x + 1 -> 6 * x + 2)
• Alcance de variables mediante el parámetro scope: { "x": 5, "y": 3 }
• Precisión configurable para resultados numéricos
• Los valores opcionales vacíos de variable y precision de clientes MCP basados en formularios se tratan como omitidos

---

Recursos

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

---

Características

Construido sobre @cyanheads/mcp-ts-core:

• Definiciones declarativas de herramientas — un archivo por herramienta, el framework gestiona el registro y la validación
• Manejo unificado de errores en todas las herramientas
• Registro estructurado con seguimiento OpenTelemetry opcional
• Se ejecuta localmente (stdio/HTTP) o en Docker

Específicas de la calculadora:

• Instancia reforzada de math.js v15 — funciones peligrosas deshabilitadas, evaluación en zona de pruebas mediante vm.runInNewContext() con tiempo de espera
• 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, rechazo de separadores de expresión (puntos y comas y saltos de línea), aplicación de regex para nombres de variables
• Validación de resultados: tipos de resultado bloqueados (funciones, analizadores, conjuntos de resultados), tamaño máximo de resultado configurable
• Saneamiento del alcance: solo valores numéricos, prevención de contaminación de prototipos (__proto__, constructor, etc. bloqueados)

---

Primeros pasos

Instancia pública alojada

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

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

Autohospedado / Local

Añade a la configuración de tu cliente MCP (p. ej., claude_desktop_config.json):

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

Requisitos previos

• Bun v1.3.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_PORT	Puerto para el servidor HTTP.	3010
MCP_AUTH_MODE	Modo de autenticación: none, jwt o oauth.	none
MCP_LOG_LEVEL	Nivel de registro (RFC 5424).	info

---

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

---

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.

---

Guía de desarrollo

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

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

---

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas. Ejecuta las comprobaciones antes de enviar:

bun run devcheck
bun run test

---

Licencia

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