calculate-mcp

English | 简体中文

A comprehensive Model Context Protocol (MCP) server providing precision numerical calculations, low-level binary data operations, IEEE 754 float decomposition, cryptographic utilities, data codecs, and an intelligent chained batch execution engine (batch_calc) designed to eliminate multi-turn round-trip overhead for Large Language Models.

🌟 Highlights

• ⚡ 29 Specialized Tools: Covers arbitrary-precision integer conversions, bitwise logic, endianness swapping, IEEE 754 floating-point layouts, modular arithmetic, cryptography, statistics, and trigonometry.
• 🔗 Zero-Round-Trip Chained Execution (batch_calc): Run multiple operations in a single tool call with step-to-step dependency referencing ({"$step": 0, "field": "resultHex"}), reducing LLM latency and token consumption.
• 🔢 Arbitrary-Precision & Native Bit-Widths: Powered by native BigInt — zero precision loss for 64-bit/128-bit+ integers with full 8/16/32/64-bit signed and unsigned two's complement representations.
• 🛡️ Zero Bloat: Built purely with TypeScript, Node.js standard libraries, and Zod. No heavy native bindings or fragile dependencies.

📦 Installation & Configuration

Option A: Using npx (Recommended)

{
  "mcpServers": {
    "calculate-mcp": {
      "command": "npx",
      "args": ["-y", "calculate-mcp"]
    }
  }
}

Option B: From Source (Clone & Run Locally)

1. Clone and build the server:

git clone https://github.com/KonghuanSmart/calculate-mcp.git
cd calculate-mcp
npm install
npm run build

1. Add to your MCP client config (e.g. claude_desktop_config.json or mcp.json):

{
  "mcpServers": {
    "calculate-mcp": {
      "command": "node",
      "args": ["/path/to/calculate-mcp/build/index.js"]
    }
  }
}

🛠️ Tool Catalog (29 Tools)

1. Pipeline & Batch Execution (1 Tool)

2. Number Systems & Binary Data (6 Tools)

3. Basic Arithmetic & Rounding (9 Tools)

4. Statistics (5 Tools)

5. Trigonometry & Conversions (8 Tools)

💡 Practical Examples

Example 1: Multi-Step Chained Calculation (batch_calc)

In a single prompt, decode a packet header, swap endianness, mask flags, and calculate a checksum without round-trip delay:

{
  "steps": [
    { "op": "data_codec", "args": { "action": "from_base64", "input": "c2VjcmV0", "format": "hex" } },
    { "op": "endian_swap", "args": { "value": "0x78563412", "widthBytes": 4 } },
    { "op": "bitwise", "args": { "operation": "xor", "a": { "$step": 1, "field": "bigEndianHex" }, "b": "0xDEADBEEF", "bitWidth": 32 } },
    { "op": "crypto_calc", "args": { "action": "crc32", "data": { "$step": 0, "field": "decoded" }, "inputFormat": "hex" } }
  ]
}

Example 2: Modular Arithmetic & RSA Private Exponent

Solve $d \equiv e^{-1} \pmod{\phi(n)}$ for $e=65537$ and $\phi(n)=10000000000000000051$:

{
  "action": "mod_inverse",
  "a": "65537",
  "modulus": "10000000000000000051"
}

Example 3: IEEE 754 Floating-Point Decomposition

Decompose machine code 0x3f800000 into float components:

{
  "value": "0x3f800000",
  "precision": "float32"
}

Output:

{
  "value": 1,
  "sign": "+",
  "rawExponentDec": 127,
  "biasedExponent": 0,
  "mantissaHex": "0x000000",
  "type": "normal"
}

💻 Development

# Clone the repository
git clone https://github.com/KonghuanSmart/calculate-mcp.git
cd calculate-mcp

# Install dependencies
npm install

# Build TypeScript to build/
npm run build

# Run locally in stdio mode
npm start

🤖 Companion Agent Skill (Prompt & Tool Guidance)

To prevent AI coding agents (such as Pi, Claude Code, Cursor, etc.) from suffering "mental calculation hallucinations" when dealing with arithmetic, radix conversions, bitwise logic, endianness swapping, and cryptographic hashing, this repository provides a ready-to-use companion Skill specification in skills/calculate-mcp (SKILL.md).

Installation

Copy or symlink skills/calculate-mcp into your agent's skills directory:

For Pi Agent / Universal Agent Harnesses:

# Windows (PowerShell):
Copy-Item -Recurse -Force "skills/calculate-mcp" "$HOME/.agents/skills/"

# Linux / macOS:
cp -r skills/calculate-mcp ~/.agents/skills/

Once installed, the agent will automatically trigger and prioritize calling calculate-mcp tools whenever precise arithmetic, radix conversions (Hex/Bin/Dec/Oct), bitwise operations (AND/OR/XOR), endianness swaps, or hash/encoding tasks are requested.

📄 License

MIT License © 2026