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)

7. Statistics Summary - Comprehensive statistical summary of datasets

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

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

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

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

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

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

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

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

12. Loan Comparison - Compare multiple loan scenarios

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

13. 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): 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

Weight/Mass Units

Temperature Units

Volume Units

Area Units

🔢 Mathematical Functions Reference

Trigonometric Functions

Logarithmic Functions

Power & Root Functions

Other Functions

Mathematical Constants

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