Sample MCP Server - Go (calculator-server)

[crivetimihai]

Overview

Create a simple MCP Server in Go that provides comprehensive mathematical operations and calculations, perfect for demonstrating basic MCP server development patterns.

Server Specifications

Server Details

• Name: calculator-server
• Language: Go 1.21+
• Location: mcp-servers/go/calculator-server/
• Complexity: ⭐ Beginner-friendly
• Purpose: Demonstrate simple mathematical computation via MCP with Go's performance benefits

Core Features

• Basic arithmetic operations (add, subtract, multiply, divide)
• Advanced mathematical functions (trigonometry, logarithms, statistics)
• Expression evaluation with order of operations
• Mathematical constants and unit conversions
• Statistical analysis of datasets

Tools Provided

1. basic_math

Perform basic arithmetic operations

type BasicMathRequest struct {
    Operation string    `json:"operation"` // add, subtract, multiply, divide, power
    Numbers   []float64 `json:"numbers"`
    Precision int       `json:"precision,omitempty"` // decimal places
}

2. advanced_math

Advanced mathematical functions

type AdvancedMathRequest struct {
    Function string    `json:"function"` // sin, cos, tan, log, ln, sqrt, abs, factorial
    Value    float64   `json:"value"`
    Unit     string    `json:"unit,omitempty"` // degrees, radians for trig functions
    Base     *float64  `json:"base,omitempty"`  // for logarithm base
}

3. evaluate_expression

Evaluate mathematical expressions with order of operations

type ExpressionRequest struct {
    Expression string            `json:"expression"` // "2 + 3 * 4 - sqrt(16)"
    Variables  map[string]float64 `json:"variables,omitempty"` // variable substitution
    Constants  bool              `json:"constants,omitempty"` // enable pi, e, etc.
    Precision  int               `json:"precision,omitempty"`
}

4. statistics

Statistical analysis of numerical datasets

type StatisticsRequest struct {
    Data       []float64 `json:"data"`
    Operations []string  `json:"operations"` // mean, median, mode, std, variance
    Percentiles []float64 `json:"percentiles,omitempty"` // 25, 50, 75, 95, 99
}

5. convert_units

Unit conversion between different measurement systems

type UnitConversionRequest struct {
    Value    float64 `json:"value"`
    FromUnit string  `json:"from_unit"` // kg, lb, m, ft, celsius, fahrenheit
    ToUnit   string  `json:"to_unit"`
    Category string  `json:"category,omitempty"` // weight, length, temperature
}

6. financial_calculations

Financial and business calculations

type FinancialRequest struct {
    Calculation string            `json:"calculation"` // compound_interest, loan_payment, roi
    Parameters  map[string]float64 `json:"parameters"`
    Periods     int               `json:"periods,omitempty"`
    Precision   int               `json:"precision,omitempty"`
}

Implementation Requirements

Directory Structure

mcp-servers/go/calculator-server/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── calculator/
│   │   ├── basic.go
│   │   ├── advanced.go
│   │   ├── expression.go
│   │   ├── statistics.go
│   │   └── units.go
│   ├── handlers/
│   │   ├── math_handler.go
│   │   ├── stats_handler.go
│   │   └── finance_handler.go
│   └── parser/
│       ├── expression_parser.go
│       └── unit_parser.go
├── pkg/
│   └── types/
│       └── requests.go
├── go.mod
├── go.sum
├── README.md
├── tests/
│   ├── basic_test.go
│   ├── expression_test.go
│   └── integration_test.go
└── examples/
    ├── basic_usage.go
    ├── expression_eval.go
    └── statistics.go

Dependencies

// go.mod
module github.com/IBM/mcp-context-forge/mcp-servers/go/calculator-server

go 1.21

require (
    github.com/IBM/mcp-context-forge/mcp-servers/go/mcp v0.1.0
    github.com/Knetic/govaluate v3.0.0  // Expression evaluation
    github.com/shopspring/decimal v1.3.1 // Precise decimal arithmetic
    gonum.org/v1/gonum v0.14.0          // Scientific computing
)

Usage Examples

Basic Arithmetic

# Addition
echo '{
  "method": "tools/call",
  "params": {
    "name": "basic_math",
    "arguments": {
      "operation": "add",
      "numbers": [10, 25, 5.5],
      "precision": 2
    }
  }
}' | calculator-server

# Result: {"result": 40.5}

Expression Evaluation

# Complex expression
echo '{
  "method": "tools/call",
  "params": {
    "name": "evaluate_expression",
    "arguments": {
      "expression": "2 * pi * r + sqrt(x^2 + y^2)",
      "variables": {"r": 5, "x": 3, "y": 4},
      "constants": true,
      "precision": 4
    }
  }
}' | calculator-server

# Result: {"result": 36.4159, "expression": "2 * π * 5 + √(3² + 4²)"}

Statistics

# Statistical analysis
echo '{
  "method": "tools/call",
  "params": {
    "name": "statistics", 
    "arguments": {
      "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
      "operations": ["mean", "median", "std", "variance"],
      "percentiles": [25, 50, 75, 95]
    }
  }
}' | calculator-server

Unit Conversion

# Temperature conversion
echo '{
  "method": "tools/call",
  "params": {
    "name": "convert_units",
    "arguments": {
      "value": 100,
      "from_unit": "celsius",
      "to_unit": "fahrenheit",
      "category": "temperature"
    }
  }
}' | calculator-server

# Result: {"result": 212, "formula": "°F = (°C × 9/5) + 32"}

Advanced Features

• Mathematical Constants: π, e, φ (golden ratio), etc.
• Expression Parser: Support for complex mathematical expressions
• Precision Control: Configurable decimal precision
• History Tracking: Optional calculation history
• Formula Display: Show formulas used for calculations

Supported Operations

// Supported mathematical operations
var SupportedOperations = map[string]string{
    // Basic arithmetic
    "add": "Addition of numbers",
    "subtract": "Subtraction of numbers",
    "multiply": "Multiplication of numbers", 
    "divide": "Division of numbers",
    "power": "Exponentiation",
    "modulo": "Modulo operation",
    
    // Advanced functions
    "sin": "Sine (trigonometric)",
    "cos": "Cosine (trigonometric)",
    "tan": "Tangent (trigonometric)",
    "log": "Logarithm (base 10)",
    "ln": "Natural logarithm (base e)",
    "sqrt": "Square root",
    "abs": "Absolute value",
    "factorial": "Factorial",
    "gcd": "Greatest common divisor",
    "lcm": "Least common multiple",
}

Acceptance Criteria

• Go MCP server with 6+ mathematical tools
• Basic arithmetic operations (add, subtract, multiply, divide)
• Advanced mathematical functions (trig, log, sqrt, etc.)
• Expression evaluation with variable substitution
• Statistical analysis capabilities
• Unit conversion between measurement systems
• Configurable precision and output formatting
• Comprehensive test suite (>95% coverage)
• Clear error handling for invalid operations
• Complete documentation with mathematical examples

Priority

Low - Perfect beginner project for learning MCP server development

Use Cases

• Educational math applications
• Engineering and scientific calculations
• Financial and business computations
• Data analysis and statistics
• Unit conversion for international applications
• Quick calculation tools for developers
• Mathematical expression evaluation in AI applications

Learning Opportunities

• Basic MCP server development patterns
• Go programming language fundamentals
• Mathematical computation in software
• Test-driven development practices
• API design and error handling