calculator-server

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)

  ![Build Status]() ![Coverage]()

🧮 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)

1. 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

1. Expression Evaluation - Complex mathematical expressions

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

1. Statistical Analysis - Comprehensive data analysis

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

1. 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

1. 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)

1. 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

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

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

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

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

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

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

1. Loan Comparison - Compare multiple loan scenarios

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

1. 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: ``json { "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): Target unit
• category (string): Unit category (length, weight, temperature, volume, area)

6. financial

Purpose: Financial calculations and modeling

Parameters:

• operation (string): Financial operation type (compound_interest, simple_interest, loan_payment, roi, present_value, future_value)
• principal (number): Principal amount
• rate (number): Interest rate (percentage)
• time (number): Time period in years
• periods (integer, optional): Compounding periods per year
• futureValue (number, optional): Future value for some calculations

Specialized Tools (7)

7. stats_summary

Purpose: Comprehensive statistical summary of datasets

Parameters:

• data (array of numbers): Dataset for summary statistics

8. percentile

Purpose: Calculate specific percentiles

Parameters:

• data (array of numbers): Dataset to analyze
• percentile (number): Percentile to calculate (0-100)

9. batch_conversion

Purpose: Convert multiple values between units

Parameters:

• values (array of numbers): Values to convert
• fromUnit (string): Source unit
• toUnit (string): Target unit
• category (string): Unit category

10. npv

Purpose: Calculate Net Present Value

Parameters:

• cashFlows (array of numbers): Cash flows (negative for outflows, positive for inflows)
• discountRate (number): Discount rate as percentage

11. irr

Purpose: Calculate Internal Rate of Return

Parameters:

• cashFlows (array of numbers): Cash flows (minimum 2 values)

12. loan_comparison

Purpose: Compare multiple loan scenarios

Parameters:

• loans (array of objects): Loan scenarios with principal, rate, and time

13. investment_scenarios

Purpose: Compare multiple investment scenarios

Parameters:

• scenarios (array of objects): Investment scenarios with principal, rate, and time

🔧 Configuration

Command Line Options

./calculator-server [OPTIONS]

Options:
  -transport string
        Transport method (stdio, http) (default "stdio")
  -port int
        Port for HTTP transport (default 8080)
  -host string
        Host for HTTP transport (default "127.0.0.1")
  -config string
        Path to configuration file (YAML or JSON)

Examples:
  ./calculator-server                           # Run with stdio transport (default)
  ./calculator-server -transport=http          # Run with HTTP transport on port 8080
  ./calculator-server -transport=http -port=9000 -host=localhost  # Custom host/port
  ./calculator-server -config=config.yaml     # Load configuration from file

Configuration Files

The server supports configuration files in YAML and JSON formats. Configuration files are searched in the following locations:

1. Current directory (./config.yaml, ./config.json)
2. ./config/ directory
3. /etc/calculator-server/
4. $HOME/.calculator-server/

Sample YAML Configuration

server:
  transport: "http"
  http:
    host: "127.0.0.1"  # Localhost for security
    port: 8080
    session_timeout: "5m"
    max_connections: 100
    cors:
      enabled: true
      origins: ["http://localhost:3000", "http://127.0.0.1:3000"]  # Never use "*" in production

logging:
  level: "info"
  format: "json"
  output: "stdout"

tools:
  precision:
    max_decimal_places: 15
    default_decimal_places: 2
  expression_eval:
    timeout: "10s"
    max_variables: 100
  statistics:
    max_data_points: 10000
  financial:
    currency_default: "USD"

security:
  rate_limiting:
    enabled: true
    requests_per_minute: 100
  request_size_limit: "1MB"

Environment Variables

Environment variables override configuration file settings:

• CALCULATOR_TRANSPORT: Transport method (stdio, http)
• CALCULATOR_HTTP_HOST: HTTP server host
• CALCULATOR_HTTP_PORT: HTTP server port
• CALCULATOR_LOG_LEVEL: Set logging level (debug, info, warn, error)
• CALCULATOR_LOG_FORMAT: Log format (json, text)
• CALCULATOR_LOG_OUTPUT: Log output (stdout, stderr)

📈 Performance

Benchmarks

• Basic Operations: ~1-5 μs per operation
• Advanced Functions: ~10-50 μs per operation
• Expression Evaluation: ~100-500 μs per expression
• Statistical Operations: ~10-100 μs per dataset (depends on size)
• Unit Conversions: ~1-10 μs per conversion
• Financial Calculations: ~50-200 μs per calculation

Memory Usage

• Base Memory: ~10-20 MB
• Per Operation: ~1-10 KB additional
• Large Datasets: Linear scaling with data size

🧪 Testing

The project includes comprehensive tests with >95% coverage:

• Unit Tests: Test individual calculators and functions
• Integration Tests: Test MCP protocol integration
• Error Handling Tests: Validate error conditions
• Performance Tests: Benchmark critical operations

# Run specific test suites
go test ./tests/basic_test.go -v
go test ./tests/advanced_test.go -v
go test ./tests/integration_test.go -v

# Generate coverage report
make coverage

🚢 Deployment

Docker Deployment

# Build Docker image
make docker-build

# Run in Docker
make docker-run

# Push to registry
make docker-push

Binary Distribution

# Create release build
make release

# Binaries will be in ./dist/release/
ls -la ./dist/release/

📝 API Reference

MCP Protocol Support

The server implements the full MCP (Model Context Protocol) specification:

• Initialize: Server initialization and capability negotiation
• Tools List: Dynamic tool discovery
• Tools Call: Tool execution with parameter validation
• Error Handling: Comprehensive error responses

Tool Schemas

All tools include comprehensive JSON Schema definitions for parameter validation and documentation. Schemas are automatically generated and include:

• Parameter types and validation rules
• Required vs optional parameters
• Default values and constraints
• Documentation strings

📏 Unit Conversion Reference

Length Units

| Unit | Abbreviation | Conversion to Meters | |------|--------------|---------------------| | Millimeter | mm | 0.001 | | Centimeter | cm | 0.01 | | Meter | m | 1.0 | | Kilometer | km | 1000.0 | | Inch | in | 0.0254 | | Foot | ft | 0.3048 | | Yard | yd | 0.9144 | | Mile | mi | 1609.344 | | Mil | mil | 0.0000254 | | Micrometer | μm | 0.000001 | | Nanometer | nm | 0.000000001 |

Weight/Mass Units

| Unit | Abbreviation | Conversion to Grams | |------|--------------|-------------------| | Milligram | mg | 0.001 | | Gram | g | 1.0 | | Kilogram | kg | 1000.0 | | Metric Ton | t | 1000000.0 | | Ounce | oz | 28.3495 | | Pound | lb | 453.592 | | Stone | st | 6350.29 | | US Ton | ton | 907185 |

Temperature Units

| Unit | Abbreviation | Description | |------|--------------|-------------| | Celsius | C | Degrees Celsius | | Fahrenheit | F | Degrees Fahrenheit | | Kelvin | K | Kelvin (absolute) | | Rankine | R | Degrees Rankine |

Volume Units

| Unit | Abbreviation | Conversion to Liters | |------|--------------|---------------------| | Milliliter | ml | 0.001 | | Centiliter | cl | 0.01 | | Deciliter | dl | 0.1 | | Liter | l | 1.0 | | Kiloliter | kl | 1000.0 | | US Fluid Ounce | fl_oz | 0.0295735 | | US Cup | cup | 0.236588 | | US Pint | pt | 0.473176 | | US Quart | qt | 0.946353 | | US Gallon | gal | 3.78541 | | Teaspoon | tsp | 0.00492892 | | Tablespoon | tbsp | 0.0147868 | | Barrel | bbl | 158.987 |

Area Units

| Unit | Abbreviation | Conversion to m² | |------|--------------|------------------| | Square Millimeter | mm2 | 0.000001 | | Square Centimeter | cm2 | 0.0001 | | Square Meter | m2 | 1.0 | | Square Kilometer | km2 | 1000000.0 | | Square Inch | in2 | 0.00064516 | | Square Foot | ft2 | 0.092903 | | Square Yard | yd2 | 0.836127 | | Square Mile | mi2 | 2589988.11 | | Acre | acre | 4046.86 | | Hectare | ha | 10000.0 |

🔢 Mathematical Functions Reference

Trigonometric Functions

| Function | Syntax | Description | Example | |----------|--------|-------------|---------| | Sine | sin(x) | Sine of x (radians) | sin(pi/2) → 1.0 | | Cosine | cos(x) | Cosine of x (radians) | cos(0) → 1.0 | | Tangent | tan(x) | Tangent of x (radians) | tan(pi/4) → 1.0 | | Arcsine | asin(x) | Inverse sine | asin(1) → 1.5708 | | Arccosine | acos(x) | Inverse cosine | acos(1) → 0.0 | | Arctangent | atan(x) | Inverse tangent | atan(1) → 0.7854 |

Logarithmic Functions

| Function | Syntax | Description | Example | |----------|--------|-------------|---------| | Common Log | log(x) | Base-10 logarithm | log(100) → 2.0 | | Natural Log | ln(x) | Natural logarithm (base e) | ln(e) → 1.0 |

Power & Root Functions

| Function | Syntax | Description | Example | |----------|--------|-------------|---------| | Square Root | sqrt(x) | Square root of x | sqrt(16) → 4.0 | | Power | pow(x, y) | x raised to power y | pow(2, 3) → 8.0 | | Exponential | exp(x) | e raised to power x | exp(1) → 2.7183 |

Other Functions

| Function | Syntax | Description | Example | |----------|--------|-------------|---------| | Absolute Value | abs(x) | Absolute value of x | abs(-5) → 5.0 | | Factorial | factorial(x) | Factorial of x | factorial(5) → 120.0 |

Mathematical Constants

| Constant | Value | Description | |----------|-------|-------------| | pi | 3.14159... | Pi (π) | | e | 2.71828... | Euler's number |

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Create a Pull Request

Development Guidelines

• Follow Go best practices and conventions
• Maintain >95% test coverage
• Add comprehensive documentation
• Use meaningful commit messages
• Run make quality before submitting

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Go Team: For the excellent programming language
• MCP Protocol: Model Context Protocol specification
• External Libraries:
• shopspring/decimal: Precise decimal arithmetic
• Knetic/govaluate: Expression evaluation
• gonum: Scientific computing
• gopkg.in/yaml.v3: YAML configuration support

📞 Support & Contact

Primary Contact:

• Maintainer: Avinash Sangle
• Email: avinash.sangle123@gmail.com
• GitHub: https://github.com/avisangle
• Website: https://avisangle.github.io/

Project Resources:

• Issues: GitHub Issues
• Documentation: This README and inline code documentation
• Examples: See make example-* commands

Getting Help:

1. Check this README for comprehensive documentation
2. Review the test files for usage examples
3. Submit issues with detailed error information
4. Contact the maintainer for direct support

---

Built with ❤️ by Avinash Sangle for the IBM MCP Context Forge project

Connect with the Author:

• 🌐 Website: https://avisangle.github.io/
• 💻 GitHub: https://github.com/avisangle
• 📧 Email: avinash.sangle123@gmail.com

For more information about MCP servers and the Context Forge project, visit the IBM MCP Context Forge repository.