Crucher

Version Node.js Version License: MIT Tests Status

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, standard default, full) to optimize context token usage.
• Basic Arithmetic: Addition, Subtraction, Multiplication, Division, Modulo.
• Expression Evaluation: Safely compute entire plain-text math strings (e.g. (5 + 3) * 10 / 2).
• Power & Roots: Exponentiation (a^b), Square Root.
• Number Theory: Factorial (n!).
• Trigonometry: Sine, Cosine, Tangent, Arcsine (asin), Arccosine (acos), and Arctangent (atan) (with support for degrees and radians).
• Logarithms: Base-10 Logarithm and Natural Logarithm (ln).
• Statistical Functions: Sum, Average, Median, Min, Max, Range, Count, Variance, and Standard Deviation for arrays of numbers.
• Percentage Functions: Percentage-of, percentage-change, and reverse-percentage calculations.
• Unit Conversion: 80+ conversions across 8 categories (length, weight, temperature, area, volume, time, speed, digital_storage).
• Convenience Functions: Absolute Value.
• Constants: Easy access to Math (pi, e, tau, phi, sqrt2, euler_mascheroni), Physics (c, g, G, h, k, R), and Chemistry constants (NA, e_charge, m_e, m_p).
• Memory Functions: M+, M-, MR (Memory Recall), and MC (Memory Clear) - full tier only.

🚀 Installation & Usage

Get Cruncher up and running with Claude Desktop in just a few minutes.

Step 1: Prerequisites

Ensure you have Node.js (version 18.0.0 or newer) installed on your system. You can download it from nodejs.org.

Step 1: Quick Start with npm

Recommended: Install via npm and use directly:

npx @slbdn/cruncher-mcp

This downloads and runs the latest version automatically.

Step 2: Configure Claude Desktop

Recommended: Use the npm package for automatic updates:

{
  "mcpServers": {
    "cruncher": {
      "command": "npx",
      "args": ["-y", "@slbdn/cruncher-mcp"]
    }
  }
}

Step 3: Manual File (Alternative)

If you prefer to download the file manually instead:

1. Download the cruncher.js file directly from GitHub.

2. Place it in a permanent location (e.g., C:\mcp-servers\cruncher.js or /home/user/mcp-servers/cruncher.js).

3. Locate the Claude Desktop configuration file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

4. Add the server configuration pointing to your downloaded file:

   {
     "mcpServers": {
       "cruncher": {
         "command": "node",
         "args": ["C:/Users/YOUR_USERNAME/mcp-servers/cruncher.js"],
         "env": {
           "CRUNCHER_TOOL_SET": "standard"
         }
       }
     }
   }
   

   Note for macOS/Linux Users: Use a POSIX-style path, e.g., "/home/YOUR_USERNAME/mcp-servers/cruncher.js". Make sure your node executable is in your system's PATH.

Step 4: Start Calculating!

1. Save the configuration file and completely quit the Claude Desktop app.
2. Restart Claude Desktop. It will automatically connect to the Cruncher server.
3. Start asking questions!

OpenWebUI (Formerly Ollama WebUI)

OpenWebUI natively supports connecting to stdio MCP servers.

Option A: Using npm package

1. Go to Admin Panel > Settings > Tools > MCP Servers.
2. Click Add Server.
3. Name it "Cruncher", select Command and enter npx, set Args to @slbdn/cruncher-mcp.

Option B: Using downloaded file

1. Go to Admin Panel > Settings > Tools > MCP Servers.
2. Click Add Server.
3. Name it "Cruncher", select stdio, use node as the command, and /path/to/cruncher.js as the argument.

Cursor IDE

You can give Cursor's built-in AI the ability to run math and calculate hashes.

Option A: Using npm package

1. Open Cursor Settings (gear icon) > Features > MCP Servers.
2. Click + Add New MCP Server.
3. Set Type to command, Name to cruncher, and Command to npx @slbdn/cruncher-mcp.

Option B: Using downloaded file

1. Open Cursor Settings (gear icon) > Features > MCP Servers.
2. Click + Add New MCP Server.
3. Set Type to command, Name to cruncher, and Command to node /path/to/cruncher.js.

Cline (VS Code Extension)

If you use Cline for agentic coding in VS Code, open the MCP configuration file (cline_mcp_settings.json) and add:

Option A: Using npm package

{
  "mcpServers": {
    "cruncher": {
      "command": "npx",
      "args": ["-y", "@slbdn/cruncher-mcp"]
    }
  }
}

Option B: Using downloaded file

{
  "mcpServers": {
    "cruncher": {
      "command": "node",
      "args": ["/path/to/cruncher.js"],
      "env": {
        "CRUNCHER_TOOL_SET": "standard"
      }
    }
  }
}

Goose (Terminal Agent)

Goose is a lightweight, terminal‑based AI assistant that fully supports MCP.

Option A: Using npm package

1. Edit ~/.goose/config.yaml (or the local project config).
2. Add a new server entry:

mcpServers:
  cruncher:
    command: npx
    args:
      - -y
      - "@slbdn/cruncher-mcp"

Option B: Using downloaded file

1. Edit ~/.goose/config.yaml (or the local project config).
2. Add a new server entry:

mcpServers:
  cruncher:
    command: node
    args:
      - "/path/to/cruncher.js"
    env:
      CRUNCHER_TOOL_SET: "standard"

3. Restart Goose. You can now ask Goose to run calculations like evaluate_expression or median directly.

Zed Editor (AI Pane)

Zed's built‑in AI pane supports MCP connections.

Option A: Using npm package

1. Open Settings → AI → MCP Servers.
2. Click Add Server and fill in:
   • Name: cruncher
   • Command: npx
   • Args: @slbdn/cruncher-mcp
3. Save. The Zed AI can now call Cruncher for precise arithmetic and statistics.

Option B: Using downloaded file

1. Open Settings → AI → MCP Servers.
2. Click Add Server and fill in:
   • Name: cruncher
   • Command: node
   • Args: /absolute/path/to/cruncher.js
   • Env (optional): CRUNCHER_TOOL_SET=standard
3. Save. The Zed AI can now call Cruncher for precise arithmetic and statistics.

LM Studio (Local LLM + MCP)

LM Studio runs LLMs entirely offline and now includes an MCP client.

Option A: Using npm package

1. Open Settings → MCP in LM Studio.
2. Click Add Server and provide:
   • Executable: npx
   • Arguments: @slbdn/cruncher-mcp
3. Confirm. Your private model can now offload math to Cruncher without any network traffic.

Option B: Using downloaded file

1. Open Settings → MCP in LM Studio.
2. Click Add Server and provide:
   • Executable: node
   • Arguments: /absolute/path/to/cruncher.js
   • Environment (optional): CRUNCHER_TOOL_SET=standard
3. Confirm. Your private model (e.g., Llama 3, DeepSeek-V2) can now offload math to Cruncher without any network traffic.

LibreChat Configuration

If you're using LibreChat, you can add the following configuration to your librechat.yaml file:

Option A: Using npm package

  cruncher:
    type: stdio
    command: npx
    args:
      - -y
      - "@slbdn/cruncher-mcp"

Option B: Using downloaded file

  cruncher:
    type: stdio
    command: node
    args:
      - "/opt/mcp/cruncher.js"
    env:
      CRUNCHER_TIMEOUT: "5000"

Example Questions for Claude

"What is the angle in degrees whose sine is 0.5?"

"Calculate the average, median, and range of these numbers: [15, 22, 8, 41, 19, 30]"

"What is 2 raised to the power of 10?"

"What is the standard deviation of [10, 12, 8, 14, 6]?"

"What is 15% of 240?"

"A stock went from $50 to $75. What's the percentage change?"

"What is the variance of test scores [85, 92, 78, 90, 88]?"

"Calculate the range of values in [3, 7, 2, 9, 1]"

"Evaluate the expression: sin(pi/4) + sqrt(16) + log10(100)"

"What is 10 factorial?"

"What is 17 modulo 5?"

Full Tier Examples (with CRUNCHER_TOOL_SET=full):

"Store 99 in memory, add 5, then recall the total."

"What's the 75th percentile of [10, 20, 30, 40, 50]?"

"Convert 11010 from binary to decimal."

"Batch: square root of 144, add 10, then raise to power 2."

"Switch trigonometric functions to radians mode."

"Clear the result cache and show cache statistics."

"Recall what's in memory, then subtract 15 and store the result."

"What's the 95th percentile of [23, 45, 12, 67, 89, 34, 56, 78, 90, 11]?"

"Convert 0xFF from hex to binary."

---

📋 Available Tools

Cruncher exposes its functions as individual MCP tools. Here is the full list:

Tool Name	Description	Arguments
Basic Arithmetic
evaluate_expression	Evaluates a plain text math expression (e.g. (5 + 3) * 10 / 2).	expression (string)
add	Adds two numbers (a + b).	a (number), b (number)
subtract	Subtracts the second number from the first (a - b).	a (number), b (number)
multiply	Multiplies two numbers (a * b).	a (number), b (number)
divide	Divides the first number by the second (a / b).	a (number), b (number)
modulo	Calculates the remainder (a mod b).	a (number), b (number)
Power & Roots
power	Calculates a raised to the power of b (a^b).	base (number), exponent (number)
sqrt	Calculates the square root of a value.	value (number)
Number Theory
factorial	Calculates the factorial of a non-negative integer (n!).	n (number, non-negative integer)
Unit Conversion
convert_unit	Convert between common units. 8 categories, 80+ units.	value (number), category (string), from (string), to (string)
Base Conversion (Full Tier)
convert_base	Converts between bases 2, 8, 10, 16.	value (string), from_base (2, 8, 10, 16), to_base (2, 8, 10, 16)
Trigonometry
sine	Calculates the sine of an angle.	angle (number), unit (degrees/radians, optional)
cosine	Calculates the cosine of an angle.	angle (number), unit (degrees/radians, optional)
tangent	Calculates the tangent of an angle.	angle (number), unit (degrees/radians, optional)
asin	Calculates the inverse sine (arcsine) of a value. Returns an angle.	value (number), unit (degrees/radians, optional)
acos	Calculates the inverse cosine (arccosine) of a value. Returns an angle.	value (number), unit (degrees/radians, optional)
atan	Calculates the inverse tangent (arctangent) of a value. Returns an angle.	value (number), unit (degrees/radians, optional)
Logarithms
logarithm	Calculates the base-10 logarithm of a value.	value (number)
natural_log	Calculates the natural logarithm (base-e) of a value.	value (number)
Statistical Functions
sum	Calculates the sum of an array of numbers.	numbers (array of numbers)
avg	Calculates the average of an array of numbers.	numbers (array of numbers)
median	Calculates the median of an array of numbers.	numbers (array of numbers)
min	Finds the minimum value in an array of numbers.	numbers (array of numbers)
max	Finds the maximum value in an array of numbers.	numbers (array of numbers)
count	Counts the number of elements in an array.	numbers (array of numbers)
range	Calculates the range (max - min) of an array.	numbers (array of numbers)
percentile	Calculates the value at a given percentile (0-100). Full tier.	numbers (array of numbers), percentile (number, 0-100)
variance	Variance of an array. Sample (n-1) or population (n).	numbers (array of numbers), population (boolean, optional)
std_dev	Standard deviation. Sample (n-1) or population (n).	numbers (array of numbers), population (boolean, optional)
percentage_of	What is X% of Y? e.g., 15% of 200 = 30.	percent (number), total (number)
percentage_change	% change from A to B. e.g., 50→80 = 60%.	from (number), to (number)
percentage_reverse	X is Y% of what? e.g., 30 is 15% of 200.	value (number), percent (number)
Other
absolute	Calculates the absolute value of a number.	value (number)
Constants
get_constant	Returns the value of a mathematical, physical, or chemical constant.	name ("pi", "e", "tau", "phi", "sqrt2", "euler_mascheroni", "c", "g", "G", "h", "k", "R", "NA", "e_charge", "m_e", "m_p")
Memory Functions (Full Tier)
memory_clear	Clears the calculator memory (MC).	(no arguments)
memory_recall	Recalls the value stored in memory (MR).	(no arguments)
memory_add	Adds a value to the current memory (M+).	value (number)
memory_subtract	Subtracts a value from the current memory (M-).	value (number)
Angle Mode (Standard Tier)
set_angle_mode	Set global angle mode (default: degrees).	unit ("degrees" or "radians")
get_angle_mode	Get current angle mode.	(no arguments)
Admin Tools (Full Tier)
batch	Execute multiple tool calls sequentially.	operations (array of {tool, arguments})
cache_clear	Clear computation cache.	(no arguments)
cache_info	Show cache stats.	(no arguments)

⚙️ Configuration

Environment Variables

Variable	Default	Description
CRUNCHER_TIMEOUT	3000	Worker thread execution timeout (ms). Range 100-60000
CRUNCHER_TOOL_SET	standard	Controls tool exposure: minimal (5), standard (34 default), full (43)

Tool Tiers - Full Reference

Cruncher exposes 3 tiers via the CRUNCHER_TOOL_SET environment variable. Each tier is a strict superset of the one before it.

Tier Overview

Tier	Tools	Use Case
Minimal (5)	Core arithmetic only	Lightweight calculators, simple math agents
Standard (34 - default)	All minimal + trig, stats, constants, unit conversion	General-purpose AI assistant math
Full (43)	All standard + memory, batch, cache, base conversion, advanced stats	Power users, multi-step workflows

Minimal Tier (5 Tools)

All tools run in the worker thread with timeout protection.

#	Tool	Description
1	evaluate_expression	Evaluates a math expression string
2	add	Addition (a + b)
3	subtract	Subtraction (a - b)
4	multiply	Multiplication (a × b)
5	divide	Division (a ÷ b)

Standard Tier (34 Tools - includes all 5 Minimal)

#	Tool	Category
6	sqrt	Square root
7	power	Exponentiation (a^b)
8	absolute	Absolute value
9	modulo	Remainder (a mod b)
10	factorial	Factorial (n!)
11	logarithm	Base-10 logarithm
12	natural_log	Natural logarithm (ln)
13	get_constant	Fetch physical/math constants
14-16	sine, cosine, tangent	Trigonometry
17-19	asin, acos, atan	Inverse trigonometry
20	set_angle_mode	Toggle degrees/radians (global)
21	get_angle_mode	Check current angle mode
22-25	sum, avg, min, max	Basic statistics
26	count	Count elements
27	variance	Variance (sample or population)
28	std_dev	Standard deviation (sample or population)
29	percentage_of	X% of Y
30	percentage_change	% change A→B
31	percentage_reverse	X is Y% of what?
32	median	Median value
33	range	Range (max - min)
34	convert_unit	80+ unit conversions, 8 categories

Full Tier (43 Tools - includes all 34 Standard)

#	Tool	Category
35	percentile	Value at Nth percentile
36	convert_base	Base 2/8/10/16 conversion
37	memory_add	Add to running total
38	memory_subtract	Subtract from running total
39	memory_recall	Get current memory value
40	memory_clear	Reset memory to zero
41	batch	Execute up to 50 operations in one call
42	cache_clear	Clear result cache
43	cache_info	Show cache statistics

Fuzzy Tool Name Matching

If the LLM calls a tool that doesn't exist, Cruncher uses Levenshtein distance to find the closest match and suggests it:

Typo	Suggestion	Match Type
fact	factorial	Prefix match
fac	factorial	Prefix match
sinn	sine	1-char typo
squrt	sqrt	Transposition
adddd	add	Extra letters
divid	divide	Missing suffix
totally_wrong	(none)	Too different - no suggestion

Response format:

{
  "error": {
    "code": -32601,
    "message": "Tool 'fact' not found. Did you mean 'factorial'?"
  }
}

Extended evaluate_expression Built-ins

Beyond basic arithmetic, evaluate_expression supports these functions natively:

Function	Description	Example	Result
sin(x)	Sine (radians, always in expressions)	sin(pi / 2)	1
cos(x)	Cosine (radians, always in expressions)	cos(pi)	-1
tan(x)	Tangent (radians)	tan(pi / 4)	~1
asin(x)	Arc-sine (result in radians)	asin(1)	π/2
acos(x)	Arc-cosine (result in radians)	acos(0)	π/2
atan(x)	Arc-tangent (result in radians)	atan(1)	π/4
sqrt(x)	Square root	sqrt(144)	12
log10(x)	Base-10 logarithm	log10(1000)	3
ln(x)	Natural log (base e)	ln(e)	1
log(x, b)	Arbitrary base logarithm	log(8, 2)	3
abs(x)	Absolute value	abs(-5)	5
round(x)	Round to nearest int	round(3.7)	4
floor(x)	Round down	floor(3.9)	3
ceil(x)	Round up	ceil(3.1)	4
min(a,b,...)	Minimum value	min(3, 1, 4)	1
max(a,b,...)	Maximum value	max(3, 1, 4)	4

Combine freely: sin(pi/6) + sqrt(16) + log10(100) = 6.5

Improved Error Messages

Domain errors now tell you what went wrong:

• sqrt(-1) → "Check for: sqrt(negative), log(negative/zero), asin/acos out of [-1,1]"
• 1/0 → "Check for division by zero or overflow"
• asin(5) → "asin/acos out of [-1,1]"

Constants in Expressions

You can now use mathematical and physical constant names directly inside evaluate_expression:

Constant	Description	Value
pi	π (circle ratio)	3.14159...
e	Euler's number	2.71828...
tau	τ = 2π	6.28318...
phi	Golden ratio (φ)	1.61803...
sqrt2	√2	1.41421...
euler_mascheroni	Euler-Mascheroni (γ)	0.57721...
c	Speed of light (m/s)	299792458
g	Gravity (m/s2)	9.80665
G	Gravitational constant	6.6743e-11
h	Planck constant (J·s)	6.62607015e-34
k	Boltzmann constant (J/K)	1.380649e-23
R	Ideal gas constant (J/mol·K)	8.314462618
NA	Avogadro constant (1/mol)	6.02214076e23
e_charge	Elementary charge (C)	1.602176634e-19
m_e	Electron mass (kg)	9.1093837015e-31
m_p	Proton mass (kg)	1.67262192369e-27

Examples:

2 * pi * 5       → 31.4159...
phi ^ 2          → 2.61803...
G * 1e11         → 6.6743
sqrt2 * sqrt2    → 2
e * e            → 7.38906...
c * 2            → 599584916

Rules:

• Use explicit operators: 2 * pi works, 2pi does not (no implicit multiplication)
• Constants coexist with scientific notation: 1e6 and e * 2 both work correctly
• Longest constant names match first: euler_mascheroni won't become 299792458uler_mascheroni

Tiered Tool Exposure

The CRUNCHER_TOOL_SET environment variable lets you optimize context token usage by exposing only the tools you actually need:

Tier	Tools	Token Budget	Use Case
minimal	5	~160 tokens	Basic arithmetic. All complex math via evaluate_expression
standard	34	~1,150 tokens	Arithmetic, trig, stats, percentages, constants, unit conversion (default)
full	43	~1,500 tokens	Standard + memory, base conversion, percentile, batch, cache

Note: Even in minimal mode, evaluate_expression handles complex math - individual tools (sin, sqrt, etc.) just aren't registered as separate MCP tool calls. This saves up to 90% on context tokens.

Example MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "cruncher-minimal": {
      "command": "node",
      "args": ["/path/to/cruncher.js"],
      "env": { "CRUNCHER_TOOL_SET": "minimal" }
    }
  }
}

⛏️ How It Works (For Developers)

Cruncher is a plain Node.js JavaScript application that communicates over standard input/output (stdio). This makes it a lightweight, portable, and secure MCP server. The entire flow for a single tool call looks like this:

1. Initialization: On startup, the server listens for an initialize request from the MCP client and responds with its capabilities and version info (v1.2.29).
2. Tool Discovery: The client sends a tools/list request, and the server responds with the full list of available calculator tools and their inputSchema, which defines the required arguments and their types.
3. Input Validation: Before any tool is executed, the server runs a custom recursive validateArguments function against the tool's inputSchema. This ensures required fields are present, types are correct (number, string, array), enum values are valid, and min/max constraints are respected - all without any external library.
4. Worker Thread Execution: Once validated, the tool call is handed off to an isolated Node.js worker_thread. This completely protects the main thread (and its stdio communication) from being blocked by a long-running or infinite calculation.
5. Timeout Protection: A configurable timer (CRUNCHER_TIMEOUT, default 3000ms) watches the worker. If the worker takes too long, the main thread forcefully terminates it via worker.terminate() and returns a -32000 error to the AI client.
6. Safe Math & Result: The worker executes the handler function using safeMath (integer-scaling) for decimal-safe arithmetic, then posts the result back to the main thread, which formats and writes the final JSON-RPC 2.0 response to stdout.

🤝 Contributing

Contributions are welcome! If you'd like to add a new function, fix a bug, or improve the documentation, please feel free to open an issue or submit a pull request.

📜 License

This project is licensed under the MIT License.