calculator-mcp-server

Servidor público alojado: https://calculator.caseyjhand.com/mcp

Herramientas

Una única herramienta para todas las operaciones matemáticas:

calculate

Una única herramienta que cubre el 100% del propósito del servidor. El parámetro operation por defecto es 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)

• Ámbito de variables mediante el parámetro scope: { "x": 5, "y": 3 }

• Precisión configurable para resultados numéricos

• Los valores opcionales en blanco de variable y precision de clientes MCP basados en formularios se tratan como omitidos

Related MCP server: pycodemath

Recursos

Características

Construido sobre @cyanheads/mcp-ts-core:

• Definiciones declarativas de herramientas: un solo archivo por herramienta, el framework gestiona el registro y la validación

• Manejo unificado de errores en todas las herramientas

• Registro estructurado con trazado opcional de OpenTelemetry

• Se ejecuta localmente (stdio/HTTP) o en Docker

Específico de la calculadora:

• Instancia endurecida de math.js v15: funciones peligrosas deshabilitadas, evaluación en sandbox mediante vm.runInNewContext() con tiempo de espera

• No se requiere autenticación: 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 nuevas líneas), valores de ámbito solo numéricos

• Validación de resultados: tipos de resultado bloqueados (funciones, analizadores, conjuntos de resultados), tamaño máximo de resultado configurable

• Saneamiento del ámbito: valores solo numéricos, prevención de contaminación de prototipos (bloqueados __proto__, constructor, etc.)

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 HTTP Streamable:

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

Autohospedado / Local

Añade 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"]
    }
  }
}

O con npx (no se requiere Bun):

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

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"
      ]
    }
  }
}

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

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

Ejecutar el 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 HTTP Streamable en el puerto 3010, sesiones sin estado y registros en /var/log/calculator-mcp-server.

Estructura del proyecto

Guía de desarrollo

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

• Los manejadores lanzan excepciones, el framework las captura: no hay 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 las 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.