Cruncher: The Scientific Calculator MCP Server

A powerful scientific calculator for your AI assistant, built as a Model Context Protocol (MCP) server. Cruncher allows compatible AI clients (like Claude Desktop) to perform complex mathematical calculations, handle memory, perform statistical analysis, and access scientific constants with a simple, secure, and standardized interface.

🌟 The Purity Promise (Zero Dependencies)

Cruncher is built as a highly educational, extremely lightweight tool. It accomplishes powerful features without pulling in any heavy external libraries (no mathjs, no zod, no @modelcontextprotocol/sdk). Everything is handled using native Node.js capabilities:

• Safe Expression Evaluation: Instead of relying on mathjs or dangerous eval(), Cruncher uses new Function() guarded by a strict whitelist Regex that guarantees only numbers and math operators can pass.
• Input Validation: Instead of heavy schema libraries like Zod, a custom recursive validation function rigidly enforces AI inputs against JSON Schemas directly.
• Timeout Protection: Instead of complex process managers, it leverages Node.js worker_threads to spawn calculations. If an AI requests a multi-million loop factorial, the main thread easily terminates the worker after a strict timeout (default 3 seconds). This timeout is configurable via the CRUNCHER_TIMEOUT environment variable (in milliseconds), ensuring the server remains responsive even during heavy computational loads.
• Floating-Point Accuracy: Instead of using decimal.js, it solves the classic JS math error (0.1 + 0.2 = 0.30000000000000004) via dynamic integer-scaling logic under the hood.

📚 An Educational Approach to MCP

This project serves as an excellent learning resource for developers looking to understand the Model Context Protocol (MCP) deeply. Because it deliberately avoids using the official @modelcontextprotocol/sdk, the entire implementation of the MCP protocol, JSON-RPC message handling, input validations, and error formatting is exposed in plain JavaScript.

Reading through cruncher.js provides unparalleled, transparent insight into exactly how an MCP server communicates over stdio, parses incoming requests (initialize, tools/list, tools/call), and responds back to the AI client-demystifying the "magic" that SDKs usually hide away.

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard that allows AI applications to securely connect with external data sources and tools. Think of it as a universal API for AI. By implementing Cruncher as an MCP server, any AI that understands MCP can instantly gain powerful, built-in calculator capabilities without custom integrations.

✨ Features

Cruncher provides a comprehensive set of calculator functions built completely from scratch without heavy dependencies:

• Robust Architecture:
  • Zero Dependencies: Relies purely on Node.js standard libraries.
  • Strict Input Validation: Custom schema validator prevents AI hallucinations and invalid data.
  • Infinite Loop Protection: Utilizes Node.js worker_threads with a 3-second strict timeout to prevent complex calculations from freezing the server.
  • Accurate Decimal Math: Uses an integer-scaling approach to prevent classic JS floating-point errors (e.g., 0.1 + 0.2 === 0.3).
• Tiered Tool Exposure: Three tiers (minimal, `st

... View full README on GitHub