Calculator

Calculator Server - Go MCP Server

A comprehensive Go-based MCP (Model Context Protocol) server for mathematical computations, implementing 13 mathematical tools with advanced features and high precision calculations.

Owner & Maintainer: Avinash Sangle (avinash.sangle123@gmail.com)

🧮 Features

Core Mathematical Tools (13 Tools)

Basic Mathematical Tools (6 Tools)

1. Basic Math Operations - Precision arithmetic with configurable decimal places

   • Addition, subtraction, multiplication, division
   • Multiple operand support
   • Decimal precision control (0-15 places)

2. Advanced Mathematical Functions - Scientific calculations

   • Trigonometric: sin, cos, tan, asin, acos, atan
   • Logarithmic: log, log10, ln
   • Other: sqrt, abs, factorial, exp, pow
   • Unit support: degrees/radians for trig functions
   • Power function with base and exponent parameters

3. Expression Evaluation - Complex mathematical expressions

   • Variable substitution support
   • Mathematical constants (π, e)
   • Nested expressions with parentheses
   • Function calls within expressions

4. Statistical Analysis - Comprehensive data analysis

   • Descriptive statistics: mean, median, mode
   • Variability: standard deviation, variance
   • Percentile calculations
   • Data validation and error handling

5. Unit Conversion - Multi-category unit conversion

   • Length: mm, cm, m, km, in, ft, yd, mi, mil, μm, nm
   • Weight: mg, g, kg, t, oz, lb, st (stone), ton (US ton)
   • Temperature: °C, °F, K, R (Rankine)
   • Volume: ml, cl, dl, l, kl, fl_oz, cup, pt, qt, gal, tsp, tbsp, bbl
   • Area: mm², cm², m², km², in², ft², yd², mi², acre, ha

6. Financial Calculations - Comprehensive financial modeling

   • Interest calculations: simple & compound
   • Loan payment calculations
   • Return on Investment (ROI)
   • Present/Future value calculations
   • Net Present Value (NPV) & Internal Rate of Return (IRR)

Advanced Specialized Tools (7 Tools)

1. Statistics Summary - Comprehensive statistical summary of datasets

   • Complete statistical overview including all measures
   • Data preview with first/last elements
   • Common percentiles (25th, 50th, 75th)

2. Percentile Calculation - Calculate specific percentiles (0-100)

   • Any percentile value between 0 and 100
   • Data count and preview information
   • Accurate percentile calculations using empirical method

3. Batch Unit Conversion - Convert multiple values between units at once

   • Bulk conversion operations
   • Same unit categories as single conversion
   • Efficient batch processing

4. Net Present Value (NPV) - Advanced NPV calculations with cash flows

   • Multiple cash flow periods
   • Discount rate calculations
   • Investment decision support

5. Internal Rate of Return (IRR) - IRR calculations for investment analysis

   • Cash flow analysis
   • Newton-Raphson method for accurate IRR calculation
   • Investment performance evaluation

6. Loan Comparison - Compare multiple loan scenarios

   • Multiple loan option analysis
   • Payment calculations for each scenario
   • Comparison metrics and recommendations

7. Investment Scenarios - Compare multiple investment scenarios

   • Multiple investment option analysis
   • Future value calculations for each scenario
   • Investment comparison and recommendations

Technical Features

• High Precision: Uses shopspring/decimal for financial calculations
• Scientific Computing: Powered by gonum.org/v1/gonum
• Expression Engine: Advanced parsing with govaluate
• Comprehensive Testing: >95% test coverage
• Error Handling: Detailed error messages and validation
• MCP Protocol: Full compliance with MCP specification
• Build Automation: Complete Makefile with CI/CD support
• Streamable HTTP Transport: MCP-compliant HTTP transport with SSE support

🚀 Quick Start

Prerequisites

• Go 1.21+ (required)
• Git (for version control)

Installation

# Clone the repository
git clone <repository-url>
cd calculator-server

# Install dependencies
make deps

# Build the server
make build

# Run the server
make run

Alternative Setup

# Initialize Go module
go mod init calculator-server
go mod tidy

# Build and run
go build -o calculator-server ./cmd/server
./calculator-server -transport=stdio

📊 Usage Examples

Basic Mathematics

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "basic_math",
    "arguments": {
      "operation": "add",
      "operands": [15.5, 20.3, 10.2],
      "precision": 2
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text", 
        "text": "{\"result\": 46.0}"
      }
    ]
  }
}

Advanced Mathematical Functions

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "advanced_math",
    "arguments": {
      "function": "pow",
      "value": 2,
      "exponent": 8
    }
  }
}

Statistics Summary

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "stats_summary",
    "arguments": {
      "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    }
  }
}

Percentile Calculation

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "percentile",
    "arguments": {
      "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
      "percentile": 90
    }
  }
}

Net Present Value

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "npv",
    "arguments": {
      "cashFlows": [-50000, 15000, 20000, 25000, 30000],
      "discountRate": 8
    }
  }
}

Batch Unit Conversion

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "batch_conversion",
    "arguments": {
      "values": [100, 200, 300],
      "fromUnit": "cm",
      "toUnit": "m",
      "category": "length"
    }
  }
}

🌐 MCP Streamable HTTP Transport

The server implements MCP-compliant streamable HTTP transport according to the official MCP specification, providing real-time communication with Server-Sent Events (SSE) streaming support.

MCP Protocol Compliance

✅ Single Endpoint: /mcp only (per MCP specification)
✅ Required Headers: MCP-Protocol-Version, Accept
✅ Session Management: Cryptographically secure session IDs
✅ SSE Streaming: Server-Sent Events for real-time responses
✅ CORS Support: Origin validation and security headers

HTTP Endpoints

Single MCP Endpoint (Specification Compliant)

• POST /mcp - MCP JSON-RPC with optional SSE streaming
• GET /mcp - SSE stream establishment
• OPTIONS /mcp - CORS preflight handling

Example Usage

# Start MCP-compliant HTTP server
./calculator-server -transport=http -port=8080

# Basic JSON-RPC request
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "MCP-Protocol-Version: 2024-11-05" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "basic_math",
      "arguments": {
        "operation": "add",
        "operands": [15, 25],
        "precision": 2
      }
    }
  }'

# SSE streaming request (for real-time responses)
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "MCP-Protocol-Version: 2024-11-05" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "stats_summary",
      "arguments": {"data": [1,2,3,4,5]}
    }
  }'

🏗️ Project Structure

calculator-server/
├── cmd/
│   └── server/
│       └── main.go              # Main server entry point
├── internal/
│   ├── calculator/
│   │   ├── basic.go            # Basic math operations
│   │   ├── advanced.go         # Advanced mathematical functions
│   │   ├── expression.go       # Expression evaluation
│   │   ├── statistics.go       # Statistical analysis
│   │   ├── units.go           # Unit conversion
│   │   └── financial.go       # Financial calculations
│   ├── handlers/
│   │   ├── math_handler.go    # Math operation handlers
│   │   ├── stats_handler.go   # Statistics & specialized handlers
│   │   └── finance_handler.go # Financial handlers
│   ├── config/
│   │   ├── config.go          # Configuration structures
│   │   ├── loader.go          # Configuration loader
│   │   └── errors.go          # Configuration errors
│   └── types/
│       └── requests.go        # Request/response types
├── pkg/
│   └── mcp/
│       ├── protocol.go        # MCP protocol handling
│       └── streamable_http_transport.go # HTTP transport
├── tests/
│   ├── basic_test.go         # Basic math tests
│   ├── advanced_test.go      # Advanced math tests
│   ├── expression_test.go    # Expression evaluation tests
│   ├── integration_test.go   # Integration tests
│   ├── config_test.go        # Configuration tests
│   └── streamable_http_transport_test.go # HTTP transport tests
├── config.sample.yaml        # Sample YAML configuration
├── config.sample.json        # Sample JSON configuration
├── go.mod                    # Go module definition
├── go.sum                    # Go module checksums
├── Makefile                  # Build automation
└── README.md                 # Project documentation

🛠️ Development

Building

# Build for current platform
make build

# Build for all platforms
make build-all

# Install to $GOPATH/bin
make install

Testing

# Run all tests
make test

# Run tests with coverage
make coverage

# Run tests with race detection
make test-race

# Run benchmarks
make benchmark

Quality Assurance

# Format code
make fmt

# Run linter
make lint

# Run vet
make vet

# Run all quality checks
make quality

# Pre-commit checks
make pre-commit

# CI pipeline
make ci

Development Mode

# Run without building (development)
make run-dev

# Run with rebuild
make run

📋 Available Tools

Core Tools (6)

1. basic_math

Purpose: Basic arithmetic operations with precision control

Parameters:

• operation (string): "add", "subtract", "multiply", "divide"
• operands (array of numbers): Numbers to operate on (minimum 2)
• precision (integer, optional): Decimal places (0-15, default: 2)

2. advanced_math

Purpose: Advanced mathematical functions

Parameters:

• function (string): Function name (sin, cos, tan, asin, acos, atan, log, log10, ln, sqrt, abs, factorial, pow, exp)
• value (number): Input value (base for pow function)
• exponent (number, optional): Exponent for pow function (required for pow)
• unit (string, optional): "radians" or "degrees" for trig functions

3. expression_eval

Purpose: Evaluate mathematical expressions with variables

Parameters:

• expression (string): Mathematical expression to evaluate
• variables (object, optional): Variable name-value pairs

4. statistics

Purpose: Statistical analysis of datasets

Parameters:

• data (array of numbers): Dataset to analyze
• operation (string): Statistical operation (mean, median, mode, std_dev, variance, percentile)

5. unit_conversion

Purpose: Convert between measurement units

Parameters:

• value (number): Value to convert
• fromUnit (string): Source unit
• toUnit (string): Targe

…