calculator

The Calculator MCP server implements a Go-based MCP (Model Context Protocol) server that exposes 13 mathematical tools across basic, advanced, statistical, unit conversion, financial, and specialized categories. It uses high-precision arithmetic (via shopspring/decimal) and scientific computing libraries to provide reliable results for operations such as addition/subtraction/multiplication/division, trigonometric and logarithmic functions, expression evaluation, batch unit conversions, and financial metrics like NPV and IRR. The server follows MCP endpoints and supports streamable HTTP transport, enabling JSON-RPC calls over a single /mcp endpoint with optional server-sent events streaming for real-time responses. Typical usage involves sending a JSON-RPC request with the tool name and arguments, and receiving a structured result that can include exact values, arrays, or nested results depending on the tool.

You can access tools like basic_math for arithmetic with configurable precision, advanced_math for trig/logs/power/abs/factorial, expression evaluation with constants and nested expressions, stats_summary for descriptive statistics, batch_conversion for multi-value unit conversions, and financial tools such as npv and irr. The server supports both standard JSON-RPC calls and SSE streaming for long-running computations, making it suitable for interactive calculations or batch processing in applications.

Prerequisites:

• Go 1.21+ (as indicated by the repository) for building from source, or a runtime environment with Go available if you choose to run the binary directly.
• Git for cloning the repository (optional if using Docker).
• Docker (optional) if you prefer running the server via a container image.

Option A: Build and run from source (Go-based server)

1. Install dependencies (if using the provided Makefile):

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

# Install dependencies
make deps

# Build the server
make build

# Run the server (default transport is http)
make run

2. Use the provided binaries or built executable (if you prefer manual steps):

# Build a standalone binary (example path may vary)
go build -o calculator-server ./cmd/server

# Run the server (HTTP transport, port 8080 by default)
./calculator-server -transport=http -port=8080

Option B: Run via Docker (recommended if you want a quick start without building)

1. Pull and run the Docker image (replace with the exact image tag if needed):

docker pull avisangle/calculator-server
docker run -p 8080:8080 -it avisangle/calculator-server

2. If the image requires a specific entrypoint or environment, refer to the image docs or adjust the docker run command accordingly.

Prerequisites recap:

• Git and Go installed locally if building from source
• Docker installed if using the container approach
• Basic familiarity with JSON-RPC and MCP transport parameters

Tips and common considerations:

• Transport options: The server supports MCP-compliant HTTP transport with an endpoint at /mcp. You can use -transport=http to enable JSON-RPC calls over HTTP (and -port to set the listening port).
• Precision control: Many math tools expose precision controls (e.g., decimal places for basic math). Ensure you pass the desired precision in the arguments where supported.
• Unit categories: When using unit conversion, specify the category (length, weight, temperature, volume, area) to ensure correct mapping of units.
• Streaming responses: For long-running calculations or batched requests, enable SSE to receive real-time updates. Use Accept: text/event-stream in the request headers.
• Environment variables: If you need to customize endpoints, ports, or enable verbose logging, consider environment variables supported by the server (e.g., MCP protocol version, transport, port) as documented in the repo or image documentation.
• Testing: Example requests in the README demonstrate typical JSON-RPC payloads. Use those as templates to validate your integration before production use.