Metadata-Version: 2.4
Name: p6plab-mcp-calculator
Version: 1.0.1
Summary: Scientific Calculator MCP Server - Comprehensive mathematical computation service for AI assistants
Project-URL: Homepage, https://github.com/peepeepopapapeepeepo/mcp-calculator
Project-URL: Repository, https://github.com/peepeepopapapeepeepo/mcp-calculator
Project-URL: Issues, https://github.com/peepeepopapapeepeepo/mcp-calculator/issues
Project-URL: Documentation, https://github.com/peepeepopapapeepeepo/mcp-calculator/blob/main/README.md
Project-URL: Changelog, https://github.com/peepeepopapapeepeepo/mcp-calculator/blob/main/CHANGELOG.md
Author-email: MCP Calculator Team <peepeepopapapeepeepo@gmail.com>
Maintainer-email: MCP Calculator Team <peepeepopapapeepeepo@gmail.com>
License: MIT License
        
        Copyright (c) 2025 MCP Calculator Team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: calculator,calculus,linear-algebra,mathematics,mcp,model-context-protocol,scientific-computing,statistics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: loguru>=0.6.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: sympy>=1.9.0
Provides-Extra: currency
Requires-Dist: requests>=2.25.0; extra == 'currency'
Provides-Extra: dev
Requires-Dist: build>=0.10.0; extra == 'dev'
Requires-Dist: pyright>=1.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Scientific Calculator MCP Server

[![PyPI - Version](https://img.shields.io/pypi/v/p6plab-mcp-calculator.svg)](https://pypi.org/project/p6plab-mcp-calculator)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/p6plab-mcp-calculator.svg)](https://pypi.org/project/p6plab-mcp-calculator)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Development Status](https://img.shields.io/badge/Development%20Status-5%20Production/Stable-brightgreen.svg)](https://pypi.org/project/p6plab-mcp-calculator)

A comprehensive mathematical computation service that provides AI assistants with advanced calculation capabilities through the Model Context Protocol (MCP). Built with FastMCP v2.0+ and featuring 68 mathematical tools across 11 configurable tool groups.

## 🚀 Features

### 🔢 Mathematical Capabilities (68 Tools Across 11 Groups)

#### **Basic Arithmetic** (8 tools) - Always Enabled
- **Core Operations**: Addition, subtraction, multiplication, division, power, square root
- **Expression Evaluation**: Safe mathematical expression parsing with SymPy
- **Health Monitoring**: Server status and configuration reporting

#### **Advanced Mathematics** (5 tools) - Optional
- **Trigonometric Functions**: sin, cos, tan, sec, csc, cot, arcsin, arccos, arctan
- **Logarithmic Functions**: Natural log, base-10, custom base logarithms
- **Exponential Functions**: e^x, custom base exponentials
- **Hyperbolic Functions**: sinh, cosh, tanh
- **Angle Conversion**: Radians ↔ degrees conversion

#### **Statistics & Probability** (5 tools) - Optional
- **Descriptive Statistics**: Mean, median, mode, standard deviation, variance, quartiles
- **Probability Distributions**: Normal, binomial, Poisson, uniform, exponential
- **Correlation Analysis**: Pearson correlation coefficients with p-values
- **Regression Analysis**: Linear regression with R-squared and equation
- **Hypothesis Testing**: One-sample t-test, two-sample t-test, chi-square test

#### **Matrix Operations** (8 tools) - Optional
- **Linear Algebra**: Matrix multiplication, determinant, inverse, eigenvalues
- **System Solving**: Linear system solving (Ax = b)
- **Matrix Operations**: Transpose, trace, rank, norms, SVD, QR decomposition
- **Matrix Arithmetic**: Addition, subtraction, scalar multiplication
- **Matrix Creation**: Identity matrices, zero matrices

#### **Complex Numbers** (6 tools) - Optional
- **Complex Arithmetic**: Add, subtract, multiply, divide, power operations
- **Complex Properties**: Magnitude, phase/argument, complex conjugate
- **Form Conversion**: Rectangular ↔ polar coordinate conversion
- **Complex Functions**: Complex exponential, logarithm, square root, trigonometric

#### **Unit Conversion** (7 tools) - Optional
- **Physical Units**: Length, weight, temperature, volume, time, energy, pressure
- **Conversion Tools**: Unit compatibility validation, conversion factors
- **Multi-Unit Conversion**: Convert to multiple target units simultaneously
- **Unit Discovery**: Find units by name, get detailed unit information

#### **Calculus** (9 tools) - Optional
- **Symbolic Calculus**: Derivatives, integrals, limits using SymPy
- **Numerical Methods**: Numerical derivatives and integrals with multiple algorithms
- **Series Expansion**: Taylor series expansion around any point
- **Critical Analysis**: Critical points, gradient calculation
- **Expression Evaluation**: Variable substitution and evaluation

#### **Equation Solving** (6 tools) - Optional
- **Linear Equations**: Single variable linear equation solving
- **Quadratic Analysis**: Quadratic equations with discriminant and vertex analysis
- **Polynomial Solving**: Equations of any degree with root analysis
- **System Solving**: Multiple equations with multiple variables
- **Numerical Root Finding**: Multiple algorithms (Newton, bisection, Brent)
- **Equation Analysis**: Automatic equation type detection and properties

#### **Financial Mathematics** (7 tools) - Optional
- **Interest Calculations**: Compound interest with flexible compounding
- **Loan Analysis**: Payment calculations, amortization schedules
- **Investment Analysis**: NPV, IRR, present value, future value
- **Annuity Calculations**: Future value of annuities (ordinary and due)
- **Financial Planning**: Comprehensive loan and investment analysis

#### **Currency Conversion** (4 tools) - Optional & Privacy-Controlled
- **Real-Time Rates**: Current exchange rates with multiple fallback APIs
- **Currency Tools**: Supported currency lists, rate information
- **Privacy First**: Disabled by default, requires explicit enablement
- **Fallback System**: API key → free tier → cached rates

#### **Constants & References** (3 tools) - Optional
- **Mathematical Constants**: π, e, φ (golden ratio), etc. with high precision
- **Physical Constants**: Speed of light, Planck's constant, Avogadro's number
- **Constant Discovery**: Search and browse constants by category

### 🛡️ Security & Performance
- **Input Validation**: Comprehensive validation using Pydantic models
- **Safe Evaluation**: No code injection - uses SymPy for expression parsing
- **Resource Limits**: Configurable computation time and memory limits
- **High Precision**: 15+ decimal place accuracy using Python's Decimal module
- **Optimized Performance**: Caching, efficient algorithms, sub-second response times
- **Privacy Controls**: Local computation preferred, external APIs disabled by default

### 🔧 Tool Group Management
- **Selective Enablement**: Enable only the mathematical capabilities you need
- **Security by Default**: Only basic arithmetic enabled by default (8 tools)
- **Preset Combinations**: Scientific, Business, Engineering, or All tools
- **Individual Control**: Fine-grained control over each tool group
- **Configuration Validation**: Comprehensive environment variable validation
- **Access Monitoring**: Track usage patterns and provide recommendations

## 📦 Installation

### Using uvx (Recommended for MCP Servers)
```bash
# Install and run latest stable version
uvx p6plab-mcp-calculator@latest

# Install from Test PyPI for development/testing
uvx --index-url https://test.pypi.org/simple/ p6plab-mcp-calculator@latest

# Install specific version
uvx p6plab-mcp-calculator@1.0.1
```

### Using pip
```bash
# Install from PyPI
pip install p6plab-mcp-calculator

# Install from Test PyPI
pip install --index-url https://test.pypi.org/simple/ p6plab-mcp-calculator

# Install with optional currency conversion support
pip install p6plab-mcp-calculator[currency]

# Install development dependencies
pip install p6plab-mcp-calculator[dev]
```

### From Source
```bash
# Clone and install
git clone https://github.com/peepeepopapapeepeepo/mcp-calculator.git
cd p6plab-mcp-calculator
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

## 🚀 Quick Start

### Basic Configuration (8 Tools)
For basic arithmetic operations only:

```json
{
  "mcpServers": {
    "p6plab-p6plab-mcp-calculator": {
      "command": "uvx",
      "args": ["p6plab-mcp-calculator@latest"],
      "env": {
        "CALCULATOR_PRECISION": "15",
        "CALCULATOR_LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": ["health_check", "add", "subtract", "multiply", "divide"]
    }
  }
}
```

### All Tools Configuration (68 Tools)
For complete mathematical capabilities:

```json
{
  "mcpServers": {
    "p6plab-p6plab-mcp-calculator": {
      "command": "uvx",
      "args": ["p6plab-mcp-calculator@latest"],
      "env": {
        "CALCULATOR_ENABLE_ALL": "true",
        "CALCULATOR_PRECISION": "15",
        "CALCULATOR_LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Preset Configurations

#### Scientific Configuration (42 Tools)
```json
{
  "env": {
    "CALCULATOR_ENABLE_SCIENTIFIC": "true"
  }
}
```

#### Business Configuration (22 Tools)
```json
{
  "env": {
    "CALCULATOR_ENABLE_BUSINESS": "true",
    "CALCULATOR_ENABLE_CURRENCY_CONVERSION": "true"
  }
}
```

#### Engineering Configuration (38 Tools)
```json
{
  "env": {
    "CALCULATOR_ENABLE_ENGINEERING": "true"
  }
}
```

### Direct Execution

```bash
# Run with basic tools only (default)
p6plab-mcp-calculator

# Run with all tools enabled
CALCULATOR_ENABLE_ALL=true p6plab-mcp-calculator

# Run with scientific preset
CALCULATOR_ENABLE_SCIENTIFIC=true p6plab-mcp-calculator

# Run with custom precision
CALCULATOR_PRECISION=20 CALCULATOR_ENABLE_ALL=true p6plab-mcp-calculator
```

### Verification

Check your configuration with the health check:

```bash
# Test basic installation
uvx p6plab-mcp-calculator@latest --help

# Verify tool count (should show 8 for basic, 68 for all)
echo '{"method": "tools/list"}' | uvx p6plab-mcp-calculator@latest
```

## Configuration

### Environment Variables

The Scientific Calculator MCP Server can be configured using the following environment variables:

#### Core Configuration
- `CALCULATOR_PRECISION`: Decimal precision for calculations (default: `15`, range: 1-50)
- `CALCULATOR_LOG_LEVEL`: Logging verbosity level (default: `INFO`, options: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)
- `CALCULATOR_CACHE_SIZE`: Cache size for expensive operations (default: `1000`, range: 100-10000)

#### Performance & Resource Limits
- `CALCULATOR_MAX_COMPUTATION_TIME`: Maximum computation timeout in seconds (default: `30`, range: 1-300)
- `CALCULATOR_MAX_MEMORY_MB`: Memory limit in megabytes (default: `512`, range: 128-2048)
- `CALCULATOR_MAX_MATRIX_SIZE`: Maximum matrix dimension for operations (default: `1000`, range: 10-5000)
- `CALCULATOR_MAX_ARRAY_SIZE`: Maximum array size for statistical operations (default: `10000`, range: 100-100000)

#### Currency Conversion (Optional Feature)
- `CALCULATOR_ENABLE_CURRENCY_CONVERSION`: Enable currency conversion feature (default: `false`, options: `true`, `false`)
- `CALCULATOR_CURRENCY_API_KEY`: API key for premium currency conversion service (optional)
- `CALCULATOR_CURRENCY_CACHE_TTL`: Currency rate cache time-to-live in seconds (default: `3600`, range: 300-86400)
- `CALCULATOR_CURRENCY_FALLBACK_ENABLED`: Enable fallback to free currency API (default: `true`, options: `true`, `false`)

#### Security & Validation
- `CALCULATOR_STRICT_VALIDATION`: Enable strict input validation (default: `true`, options: `true`, `false`)
- `CALCULATOR_ALLOW_SYMBOLIC_COMPUTATION`: Allow symbolic math operations (default: `true`, options: `true`, `false`)
- `CALCULATOR_MAX_EXPRESSION_LENGTH`: Maximum length for mathematical expressions (default: `1000`, range: 10-10000)

#### Development & Debugging
- `CALCULATOR_DEBUG_MODE`: Enable debug mode with detailed logging (default: `false`, options: `true`, `false`)
- `CALCULATOR_PROFILE_PERFORMANCE`: Enable performance profiling (default: `false`, options: `true`, `false`)
- `CALCULATOR_DISABLE_CACHE`: Disable all caching for testing (default: `false`, options: `true`, `false`)

#### MCP Server Configuration
- `CALCULATOR_SERVER_NAME.*p6plab-mcp-calculator`)
- `CALCULATOR_SERVER_VERSION`: Override server version (default: auto-detected from package)
- `FASTMCP_LOG_LEVEL`: FastMCP framework log level (default: `ERROR`, options: `DEBUG`, `INFO`, `WARNING`, `ERROR`)

### Configuration Examples

#### Basic Configuration
```bash
# Minimal configuration for basic arithmetic
export CALCULATOR_PRECISION=10
export CALCULATOR_LOG_LEVEL=WARNING
export CALCULATOR_MAX_COMPUTATION_TIME=10
```

#### Scientific Configuration
```bash
# Configuration for advanced mathematical operations
export CALCULATOR_PRECISION=20
export CALCULATOR_LOG_LEVEL=INFO
export CALCULATOR_MAX_COMPUTATION_TIME=60
export CALCULATOR_MAX_MATRIX_SIZE=2000
export CALCULATOR_ALLOW_SYMBOLIC_COMPUTATION=true
```

#### Business/Financial Configuration
```bash
# Configuration with currency conversion enabled
export CALCULATOR_PRECISION=15
export CALCULATOR_ENABLE_CURRENCY_CONVERSION=true
export CALCULATOR_CURRENCY_API_KEY=your_api_key_here
export CALCULATOR_CURRENCY_CACHE_TTL=1800
export CALCULATOR_MAX_COMPUTATION_TIME=30
```

#### Development Configuration
```bash
# Configuration for development and testing
export CALCULATOR_DEBUG_MODE=true
export CALCULATOR_LOG_LEVEL=DEBUG
export CALCULATOR_PROFILE_PERFORMANCE=true
export CALCULATOR_STRICT_VALIDATION=true
export CALCULATOR_DISABLE_CACHE=true
export FASTMCP_LOG_LEVEL=DEBUG
```

#### Production Configuration
```bash
# Optimized configuration for production use
export CALCULATOR_PRECISION=15
export CALCULATOR_LOG_LEVEL=ERROR
export CALCULATOR_CACHE_SIZE=5000
export CALCULATOR_MAX_COMPUTATION_TIME=30
export CALCULATOR_MAX_MEMORY_MB=1024
export CALCULATOR_STRICT_VALIDATION=true
export CALCULATOR_ENABLE_CURRENCY_CONVERSION=false
export FASTMCP_LOG_LEVEL=ERROR
```

### MCP Client Configuration Examples

#### Claude Desktop Configuration
```json
{
  "mcpServers": {
    "p6plab-p6plab-mcp-calculator": {
      "command": "uvx",
      "args": ["p6plab-mcp-calculator@latest"],
      "env": {
        "CALCULATOR_PRECISION": "15",
        "CALCULATOR_LOG_LEVEL": "INFO",
        "CALCULATOR_ENABLE_CURRENCY_CONVERSION": "false",
        "CALCULATOR_MAX_COMPUTATION_TIME": "30",
        "CALCULATOR_CACHE_SIZE": "1000",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

#### Development MCP Configuration
```json
{
  "mcpServers": {
    "p6plab-p6plab-mcp-calculator-dev": {
      "command": "uvx",
      "args": ["--index-url", "https://test.pypi.org/simple/", "p6plab-mcp-calculator@latest"],
      "env": {
        "CALCULATOR_ENABLE_ALL": "true",
        "CALCULATOR_DEBUG_MODE": "true",
        "CALCULATOR_LOG_LEVEL": "DEBUG",
        "CALCULATOR_PRECISION": "20",
        "CALCULATOR_PROFILE_PERFORMANCE": "true",
        "FASTMCP_LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": ["health_check", "add", "subtract", "multiply", "divide"]
    }
  }
}
```

### Tool Group Configuration Examples

#### Individual Group Control
```json
{
  "env": {
    "CALCULATOR_ENABLE_ADVANCED": "true",
    "CALCULATOR_ENABLE_STATISTICS": "true",
    "CALCULATOR_ENABLE_MATRIX": "true"
  }
}
```

#### Mixed Configuration
```json
{
  "env": {
    "CALCULATOR_ENABLE_SCIENTIFIC": "true",
    "CALCULATOR_ENABLE_FINANCIAL": "true",
    "CALCULATOR_ENABLE_CURRENCY_CONVERSION": "true"
  }
}
```

## 🛠️ Available Tools

The MCP server provides **68 comprehensive mathematical tools** organized into **11 configurable tool groups**. By default, only the **Basic Arithmetic** group (8 tools) is enabled for security and performance.

### 🔢 Basic Arithmetic (8 tools) - **Always Enabled**
- `health_check()` - Server health verification and tool group status
- `add(a, b)` - Addition with high precision
- `subtract(a, b)` - Subtraction with high precision  
- `multiply(a, b)` - Multiplication with high precision
- `divide(a, b)` - Division with high precision
- `power(base, exponent)` - Exponentiation
- `square_root(value)` - Square root calculation
- `calculate(expression)` - Safe expression evaluation with SymPy

**Enable with**: Always enabled (no configuration needed)

### 📊 Advanced Mathematics (5 tools) - **Optional**
- `trigonometric(function, value, unit)` - Sin, cos, tan, sec, csc, cot, arcsin, arccos, arctan
- `logarithm(value, base)` - Natural log, log10, custom base logarithms
- `exponential(base, exponent)` - Exponential functions (e^x, custom base)
- `hyperbolic(function, value)` - Sinh, cosh, tanh functions
- `convert_angle(value, from_unit, to_unit)` - Radians ↔ degrees conversion

**Enable with**: `CALCULATOR_ENABLE_ADVANCED=true`

### 📈 Statistics (5 tools) - **Optional**
- `descriptive_stats(data, sample)` - Mean, median, mode, std dev, variance, quartiles
- `probability_distribution(distribution, ...)` - Normal, binomial, Poisson, uniform, exponential
- `correlation_analysis(x_data, y_data)` - Pearson correlation coefficients
- `regression_analysis(x_data, y_data)` - Linear regression with R-squared
- `hypothesis_test(test_type, ...)` - One-sample t-test, two-sample t-test, chi-square

**Enable with**: `CALCULATOR_ENABLE_STATISTICS=true`

### 🔢 Matrix Operations (8 tools) - **Optional**
- `matrix_multiply(matrix_a, matrix_b)` - Matrix multiplication
- `matrix_determinant(matrix_data)` - Determinant calculation
- `matrix_inverse(matrix_data)` - Matrix inversion
- `matrix_eigenvalues(matrix_data)` - Eigenvalues and eigenvectors
- `solve_linear_system(coefficient_matrix, constants)` - Linear system solving
- `matrix_operations(operation, matrix_data, norm_type)` - Transpose, trace, rank, norms
- `matrix_arithmetic(operation, matrix_a, matrix_b, scalar)` - Add, subtract, scalar multiply
- `create_matrix(matrix_type, size, rows, cols)` - Identity and zero matrices

**Enable with**: `CALCULATOR_ENABLE_MATRIX=true`

### 🔄 Complex Numbers (6 tools) - **Optional**
- `complex_arithmetic(operation, z1, z2)` - Add, subtract, multiply, divide, power
- `complex_magnitude(z)` - Absolute value/magnitude
- `complex_phase(z, unit)` - Phase/argument calculation
- `complex_conjugate(z)` - Complex conjugate
- `polar_conversion(operation, z, magnitude, phase, unit)` - Rectangular ↔ polar
- `complex_functions(function, z, base)` - Complex exp, log, sqrt, sin, cos, tan

**Enable with**: `CALCULATOR_ENABLE_COMPLEX=true`

### 📏 Unit Conversion (7 tools) - **Optional**
- `convert_units(value, from_unit, to_unit, unit_type)` - Convert between units
- `get_available_units(unit_type)` - List available units by type
- `validate_unit_compatibility(from_unit, to_unit, unit_type)` - Check compatibility
- `get_conversion_factor(from_unit, to_unit, unit_type)` - Get conversion factors
- `convert_multiple_units(value, from_unit, to_units, unit_type)` - Convert to multiple units
- `find_unit_by_name(unit_name)` - Find unit type by name
- `get_unit_info(unit_name, unit_type)` - Detailed unit information

**Enable with**: `CALCULATOR_ENABLE_UNITS=true`

### ∫ Calculus (9 tools) - **Optional**
- `derivative(expression, variable, order)` - Symbolic derivatives
- `integral(expression, variable, lower_bound, upper_bound)` - Symbolic integration
- `numerical_derivative(expression, variable, point, order, dx)` - Numerical derivatives
- `numerical_integral(expression, variable, lower_bound, upper_bound, method)` - Numerical integration
- `calculate_limit(expression, variable, approach_value, direction)` - Limit calculations
- `taylor_series(expression, variable, center, order)` - Taylor series expansion
- `find_critical_points(expression, variable)` - Critical point analysis
- `gradient(expression, variables)` - Gradient calculation
- `evaluate_expression(expression, variable_values)` - Expression evaluation

**Enable with**: `CALCULATOR_ENABLE_CALCULUS=true`

### 🔍 Equation Solving (6 tools) - **Optional**
- `solve_linear(equation, variable)` - Linear equation solving
- `solve_quadratic(equation, variable)` - Quadratic equations with analysis
- `solve_polynomial(equation, variable)` - Polynomial equations of any degree
- `solve_system(equations, variables)` - Systems of equations
- `find_roots(expression, variable, initial_guess, method)` - Numerical root finding
- `analyze_equation(equation, variable)` - Equation type and properties analysis

**Enable with**: `CALCULATOR_ENABLE_SOLVER=true`

### 💰 Financial Mathematics (7 tools) - **Optional**
- `compound_interest(principal, rate, time, compounding_frequency)` - Compound interest
- `loan_payment(principal, rate, periods, payment_type)` - Loan payment calculation
- `net_present_value(cash_flows, discount_rate, initial_investment)` - NPV calculation
- `internal_rate_of_return(cash_flows, initial_investment)` - IRR calculation
- `present_value(future_value, rate, periods)` - Present value calculation
- `future_value_annuity(payment, rate, periods, payment_type)` - Annuity future value
- `amortization_schedule(principal, rate, periods, max_periods_display)` - Loan amortization

**Enable with**: `CALCULATOR_ENABLE_FINANCIAL=true`

### 💱 Currency Conversion (4 tools) - **Optional & Privacy-Controlled**
- `convert_currency(amount, from_currency, to_currency)` - Currency conversion
- `get_exchange_rate(from_currency, to_currency)` - Exchange rate lookup
- `get_supported_currencies()` - List supported currencies
- `get_currency_info()` - Currency system configuration

**Enable with**: `CALCULATOR_ENABLE_CURRENCY=true` + `CALCULATOR_ENABLE_CURRENCY_CONVERSION=true`

### 📚 Constants & References (3 tools) - **Optional**
- `get_constant(name, precision)` - Mathematical/physical constants (π, e, c, h, etc.)
- `list_constants(category)` - List available constants by category
- `search_constants(query)` - Search constants database

**Enable with**: `CALCULATOR_ENABLE_CONSTANTS=true`

### 📋 Tool Group Summary

| Group | Tools | Default | Enable With |
|-------|-------|---------|-------------|
| **Basic** | 8 | ✅ Always | No configuration needed |
| **Advanced** | 5 | ❌ | `CALCULATOR_ENABLE_ADVANCED=true` |
| **Statistics** | 5 | ❌ | `CALCULATOR_ENABLE_STATISTICS=true` |
| **Matrix** | 8 | ❌ | `CALCULATOR_ENABLE_MATRIX=true` |
| **Complex** | 6 | ❌ | `CALCULATOR_ENABLE_COMPLEX=true` |
| **Units** | 7 | ❌ | `CALCULATOR_ENABLE_UNITS=true` |
| **Calculus** | 9 | ❌ | `CALCULATOR_ENABLE_CALCULUS=true` |
| **Solver** | 6 | ❌ | `CALCULATOR_ENABLE_SOLVER=true` |
| **Financial** | 7 | ❌ | `CALCULATOR_ENABLE_FINANCIAL=true` |
| **Currency** | 4 | ❌ | `CALCULATOR_ENABLE_CURRENCY=true` |
| **Constants** | 3 | ❌ | `CALCULATOR_ENABLE_CONSTANTS=true` |
| **TOTAL** | **68** | **8** | `CALCULATOR_ENABLE_ALL=true` |

### 🎯 Preset Combinations

| Preset | Groups | Tools | Use Case |
|--------|--------|-------|----------|
| **Scientific** | Basic + Advanced + Statistics + Matrix + Complex + Calculus | 42 | Research, analysis, scientific computing |
| **Business** | Basic + Financial + Currency + Units | 22 | Finance, accounting, business analysis |
| **Engineering** | Basic + Advanced + Matrix + Complex + Calculus + Units + Constants | 38 | Engineering calculations, physics |
| **All** | All 11 groups | 68 | Complete mathematical capabilities |

## 💬 Example Prompts

The Scientific Calculator MCP Server integrates seamlessly with AI assistants, allowing you to perform complex mathematical operations through natural language. Here are examples of how to interact with each tool category:

### 🤖 How It Works
Simply ask your AI assistant mathematical questions in natural language. The assistant will automatically:
1. **Understand** your request and identify the appropriate mathematical operation
2. **Select** the right tool from the 68 available mathematical functions  
3. **Execute** the calculation using the MCP server
4. **Explain** the results in a clear, understandable format

### 📝 Prompt Examples by Category

### 🔢 Basic Arithmetic
```
"Add 15.7 and 23.8"
"What's 144 divided by 12?"
"Calculate 2 to the power of 10"
"Find the square root of 169"
"Evaluate the expression: (3 + 4) * 2 - 1"
"What's 25% of 80?"
```

### 📊 Advanced Mathematics
```
"Calculate sin(π/4) in radians"
"What's the cosine of 60 degrees?"
"Find log base 10 of 1000"
"Calculate the natural logarithm of e²"
"What's e to the power of 2?"
"Find sinh(1)"
"Convert 90 degrees to radians"
```

### 📈 Statistics & Probability
```
"Calculate descriptive statistics for the dataset: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
"What's the mean and standard deviation of [23, 45, 67, 89, 12, 34, 56]?"
"Calculate the probability density for a normal distribution with mean 0, std dev 1, at x=1.96"
"Find the correlation coefficient between [1,2,3,4,5] and [2,4,6,8,10]"
"Perform linear regression on x=[1,2,3,4] and y=[2,4,6,8]"
"Do a one-sample t-test on [1,2,3,4,5] with population mean 3"
```

### 🔢 Matrix Operations
```
"Multiply matrices [[1,2],[3,4]] and [[5,6],[7,8]]"
"Find the determinant of [[1,2],[3,4]]"
"Calculate the inverse of [[2,1],[1,3]]"
"Find eigenvalues of [[4,-2],[1,1]]"
"Solve the linear system Ax=b where A=[[2,1],[1,3]] and b=[5,6]"
"Calculate the transpose of [[1,2,3],[4,5,6]]"
```

### 🔄 Complex Numbers
```
"Add (3+4i) and (1+2i)"
"Find the magnitude of 3+4i"
"Calculate the phase of 1+i in degrees"
"Find the complex conjugate of 2-3i"
"Convert 3+4i to polar form"
"Calculate e^(iπ)"
```

### 📏 Unit Conversions
```
"Convert 100 kilometers to miles"
"How many feet are in 2 meters?"
"Convert 32 degrees Fahrenheit to Celsius"
"What's 1000 joules in calories?"
"Convert 5 gallons to liters"
"How many seconds are in 2.5 hours?"
```

### ∫ Calculus Operations
```
"Find the derivative of x³ + 2x² + x with respect to x"
"Calculate the second derivative of sin(x)"
"Integrate x² from 0 to 3"
"Find the indefinite integral of cos(x)"
"Calculate the limit of (sin(x)/x) as x approaches 0"
"Find the Taylor series of e^x around x=0 up to order 5"
"Find critical points of x³ - 3x² + 2"
"Calculate the gradient of x² + y² + z²"
```

### 🔍 Equation Solving
```
"Solve 2x + 3 = 7 for x"
"Solve the quadratic equation x² - 5x + 6 = 0"
"Find roots of x³ - 6x² + 11x - 6 = 0"
"Solve the system: 2x + y = 5, x + 3y = 6"
"Find where f(x) = x² - 4 equals zero"
"Analyze the equation x² + 4x + 4 = 0"
```

### 💰 Financial Mathematics
```
"Calculate compound interest on $1000 at 5% annual rate for 10 years"
"What's the monthly payment on a $200,000 loan at 4.5% for 30 years?"
"Find the NPV of cash flows [-1000, 300, 400, 500] at 10% discount rate"
"Calculate the IRR for an investment of $1000 with returns [300, 400, 500, 600]"
"What's the present value of $1000 received in 5 years at 6% discount rate?"
"Generate an amortization schedule for a $100,000 loan at 6% for 15 years"
```

### 💱 Currency Conversion
```
"Convert 100 USD to EUR"
"What's the current exchange rate from GBP to JPY?"
"How much is 50 CAD in USD?"
"List all supported currencies"
"Convert 1000 EUR to multiple currencies: USD, GBP, JPY"
```

### 📚 Constants & References
```
"What's the value of π (pi) to 10 decimal places?"
"Give me the speed of light in m/s"
"What's Planck's constant?"
"List all mathematical constants"
"Search for constants related to 'gravity'"
"What's Avogadro's number?"
"Show me all physical constants"
```

### 🔬 Advanced Scientific Examples
```
"Calculate the kinetic energy of a 2kg object moving at 10 m/s using KE = ½mv²"
"Find the period of a pendulum with length 1 meter using T = 2π√(L/g)"
"Calculate the wavelength of light with frequency 5×10¹⁴ Hz using λ = c/f"
"Determine the half-life from decay constant 0.693 using t₁/₂ = ln(2)/λ"
"Find the escape velocity from Earth using v = √(2GM/r)"
```

### 📊 Data Analysis Examples
```
"Analyze this dataset for outliers: [1,2,3,4,5,100,6,7,8,9]"
"Calculate confidence intervals for sample mean of [23,25,27,29,31]"
"Test if two datasets have significantly different means: [1,2,3,4,5] vs [3,4,5,6,7]"
"Find the best-fit line for points (1,2), (2,4), (3,6), (4,8)"
"Calculate R-squared for the regression"
```

### 🏗️ Engineering Examples
```
"Calculate stress in a beam: Force = 1000N, Area = 0.01 m²"
"Find the resonant frequency: L = 0.1H, C = 1μF using f = 1/(2π√LC)"
"Calculate power dissipation: V = 12V, R = 4Ω using P = V²/R"
"Determine the moment of inertia for a solid cylinder: m = 5kg, r = 0.2m"
"Find the critical buckling load for a column"
```

### 💼 Business Analysis Examples
```
"Calculate ROI: Initial investment $10,000, Final value $12,000"
"Find break-even point: Fixed costs $5000, Variable cost per unit $10, Price per unit $25"
"Calculate depreciation using straight-line method: Cost $50,000, Salvage $5,000, Life 10 years"
"Determine optimal order quantity: Demand 1000 units/year, Order cost $50, Holding cost $2/unit/year"
"Calculate present value of annuity: $1000/year for 10 years at 8%"
```

### ⚙️ Configuration-Specific Examples

#### Basic Configuration (8 tools)
```
"Add 25 and 17"
"What's 144 divided by 12?"
"Calculate 2³"
"Find √64"
"Evaluate: (5 + 3) × 2"
```

#### Scientific Configuration (42+ tools)
```
"Calculate the derivative of x² + 3x + 2"
"Find the correlation between these datasets: [1,2,3,4,5] and [2,4,6,8,10]"
"What's the eigenvalue of this matrix: [[3,1],[0,2]]?"
"Solve the quadratic equation: x² - 5x + 6 = 0"
"Calculate sin(π/3) and convert the result to degrees"
```

#### Business Configuration (22+ tools)
```
"Convert 1000 USD to EUR at current rates"
"Calculate monthly payment for $300,000 mortgage at 4.2% for 30 years"
"What's the NPV of cash flows [-50000, 15000, 20000, 25000, 30000] at 8% discount?"
"Convert 50 kilometers to miles for my business trip"
"Find the IRR for this investment opportunity"
```

#### Engineering Configuration (38+ tools)
```
"Calculate the moment of inertia for a solid disk: mass=5kg, radius=0.3m"
"Find the natural frequency: spring constant=1000 N/m, mass=2kg"
"What's the stress in this beam: force=5000N, cross-sectional area=0.02m²?"
"Calculate the derivative of the displacement function: s(t) = 4.9t²"
"Convert 100 PSI to Pascals"
```

### 🎯 Pro Tips for Better Prompts

#### ✅ **Good Prompts:**
- **Be specific**: "Calculate the derivative of x³ + 2x² with respect to x"
- **Include units**: "Convert 100 kilometers to miles"
- **Provide context**: "Find the monthly payment for a $200,000 loan at 4.5% APR for 30 years"
- **Specify precision**: "Calculate π to 10 decimal places"

#### ❌ **Avoid:**
- Vague requests: "Do some math"
- Missing parameters: "Calculate compound interest" (missing principal, rate, time)
- Ambiguous units: "Convert 100 degrees" (Celsius to Fahrenheit? Degrees to radians?)

#### 🔧 **Configuration Hints:**
- If you get "tool not available" errors, you may need to enable additional tool groups
- Use `health_check` to see which tools are currently available
- Check the configuration guide for enabling specific mathematical capabilities

## 🛠️ Development

### Prerequisites
- Python 3.8+ (tested on 3.8, 3.9, 3.10, 3.11, 3.12)
- Virtual environment (venv)
- Git

### Development Setup
```bash
# Clone the repository
git clone https://github.com/peepeepopapapeepeepo/mcp-calculator.git
cd p6plab-mcp-calculator

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

# Verify installation
python -c "import calculator; print(calculator.__version__)"
```

### Project Structure
```
p6plab-mcp-calculator/
├── calculator/                 # Main package
│   ├── __init__.py            # Version and package info
│   ├── server.py              # FastMCP server implementation
│   ├── core/                  # Core mathematical modules
│   │   ├── basic.py           # Basic arithmetic operations
│   │   ├── advanced.py        # Advanced mathematical functions
│   │   ├── statistics.py      # Statistical analysis tools
│   │   ├── matrix.py          # Matrix operations
│   │   ├── complex.py         # Complex number operations
│   │   ├── units.py           # Unit conversion system
│   │   ├── calculus.py        # Calculus operations
│   │   ├── solver.py          # Equation solving
│   │   ├── financial.py       # Financial mathematics
│   │   ├── currency.py        # Currency conversion
│   │   ├── constants.py       # Mathematical constants
│   │   ├── tool_groups.py     # Tool group management
│   │   ├── tool_filter.py     # Tool filtering system
│   │   └── validators.py      # Input validation
│   ├── models/                # Data models
│   └── utils/                 # Utility functions
├── tests/                     # Test suite (216+ tests)
├── scripts/                   # Build and deployment scripts
├── docs/                      # Documentation
├── pyproject.toml            # Project configuration
├── README.md                 # This file
├── CHANGELOG.md              # Version history
└── LICENSE                   # MIT License
```

### Running Tests
```bash
# Run all tests with coverage
./scripts/run-tests.sh

# Run specific test categories
pytest tests/test_basic.py -v                    # Basic arithmetic tests
pytest tests/test_tool_groups.py -v              # Tool group management tests
pytest tests/test_server.py -v                   # MCP server tests
pytest -m "not slow" -v                          # Skip slow tests
pytest -k "matrix" -v                            # Run matrix-related tests

# Run tests with specific tool group configurations
CALCULATOR_ENABLE_ALL=true pytest tests/ -v     # Test with all tools
CALCULATOR_ENABLE_SCIENTIFIC=true pytest tests/ -v  # Test scientific preset
```

### Code Quality
```bash
# Linting and formatting
ruff check calculator/ tests/                    # Check code style
ruff format calculator/ tests/                   # Format code

# Type checking
pyright calculator/                              # Static type analysis

# Security scanning
bandit -r calculator/                            # Security analysis
```

### Building and Publishing

The project includes automated scripts for building and publishing:

```bash
# Build uvx-compatible package
./scripts/build-uvx-package.sh

# Test uvx package locally
./scripts/test-uvx-package.sh

# Test uvx installation from Test PyPI
./scripts/test-uvx-install.sh testpypi

# Publish to Test PyPI
./scripts/publish-test-pypi.sh

# Publish to production PyPI
./scripts/publish-pypi.sh

# Clean build artifacts
./scripts/clean.sh
```

### Development Workflow
1. **Create Feature Branch**: `git checkout -b feature/new-tool-group`
2. **Implement Changes**: Add new mathematical tools or improve existing ones
3. **Add Tests**: Ensure comprehensive test coverage (target: 95%+)
4. **Run Quality Checks**: `ruff check`, `pyright`, test suite
5. **Test Tool Groups**: Verify tool filtering and configuration works
6. **Update Documentation**: Update README, docstrings, and examples
7. **Submit Pull Request**: Include description of changes and test results

### Adding New Mathematical Tools

1. **Create Core Function**: Add to appropriate module in `calculator/core/`
2. **Register Tool**: Add to tool group in `calculator/core/tool_groups.py`
3. **Add Server Endpoint**: Register in `calculator/server.py` with `@filtered_tool`
4. **Write Tests**: Add comprehensive tests in `tests/`
5. **Update Documentation**: Add to README tool list and examples

### Environment Variables for Development
```bash
# Enable debug mode
export CALCULATOR_DEBUG_MODE=true
export CALCULATOR_LOG_LEVEL=DEBUG
export FASTMCP_LOG_LEVEL=DEBUG

# Enable all tools for testing
export CALCULATOR_ENABLE_ALL=true

# Performance profiling
export CALCULATOR_PROFILE_PERFORMANCE=true

# Disable caching for testing
export CALCULATOR_DISABLE_CACHE=true
```

## ⚡ Performance

The calculator is optimized for high-performance mathematical computation:

### Response Time Targets
- **Basic operations**: < 10ms response time
- **Advanced functions**: < 100ms response time  
- **Statistical operations**: < 500ms response time
- **Matrix operations**: < 1s response time (up to 1000×1000 matrices)
- **Unit conversions**: < 50ms response time
- **Currency conversion**: < 2s response time (with caching)

### Performance Features
- **Efficient Algorithms**: NumPy and SciPy optimized implementations
- **Smart Caching**: Configurable cache for expensive operations
- **Resource Limits**: Configurable memory and computation time limits
- **Lazy Loading**: Tool groups loaded only when enabled
- **Optimized Parsing**: SymPy integration for safe expression evaluation

### Benchmarks (on modern hardware)
- **Matrix multiplication** (100×100): ~5ms
- **Eigenvalue calculation** (50×50): ~15ms
- **Statistical analysis** (10,000 data points): ~50ms
- **Symbolic derivative**: ~20ms
- **Numerical integration**: ~100ms

## 🔒 Security

Security is built into every aspect of the calculator:

### Input Security
- **Comprehensive Validation**: All inputs validated with Pydantic models
- **Safe Expression Parsing**: Uses SymPy - no `eval()` or code execution
- **Type Safety**: Strong typing with Python 3.8+ type hints
- **Sanitization**: Mathematical expressions sanitized before processing

### Resource Protection
- **Computation Limits**: Configurable timeout (default: 30s)
- **Memory Limits**: Configurable memory usage (default: 512MB)
- **Matrix Size Limits**: Prevents memory exhaustion attacks
- **Array Size Limits**: Protects against large dataset attacks

### Privacy Controls
- **Local-First**: All core mathematical operations run locally
- **External APIs Disabled**: Currency conversion disabled by default
- **No Data Persistence**: No user data stored or logged
- **Minimal Network**: Only currency APIs when explicitly enabled

### Tool Group Security
- **Principle of Least Privilege**: Only basic tools enabled by default
- **Selective Enablement**: Enable only needed mathematical capabilities
- **Access Monitoring**: Track attempts to access disabled tools
- **Configuration Validation**: Comprehensive environment variable validation

### Error Handling
- **Safe Error Messages**: No sensitive information in error responses
- **Structured Errors**: Consistent error format with actionable suggestions
- **Logging Controls**: Configurable logging levels
- **No Stack Traces**: Production-safe error responses

## 🤝 Contributing

We welcome contributions to the Scientific Calculator MCP Server! Whether you're fixing bugs, adding new mathematical tools, improving documentation, or enhancing performance, your contributions are valued.

### Ways to Contribute
- **Bug Reports**: Report issues with detailed reproduction steps
- **Feature Requests**: Suggest new mathematical tools or capabilities
- **Code Contributions**: Implement new features or fix existing issues
- **Documentation**: Improve README, docstrings, or examples
- **Testing**: Add test cases or improve test coverage
- **Performance**: Optimize algorithms or improve efficiency

### Development Workflow
1. **Fork the Repository**: Create your own fork on GitHub
2. **Create Feature Branch**: `git checkout -b feature/your-feature-name`
3. **Set Up Development Environment**: Follow the development setup guide
4. **Make Your Changes**: Implement your feature or fix
5. **Add Tests**: Ensure comprehensive test coverage (target: 95%+)
6. **Run Quality Checks**: 
   ```bash
   ./scripts/run-tests.sh          # Run test suite
   ruff check calculator/ tests/   # Code style
   pyright calculator/             # Type checking
   ```
7. **Update Documentation**: Update README, docstrings, and examples
8. **Submit Pull Request**: Include clear description and test results

### Code Standards
- **Python 3.8+**: Compatible with Python 3.8 through 3.12
- **Type Hints**: Use comprehensive type annotations
- **Docstrings**: Google-style docstrings for all functions
- **Code Style**: Follow ruff formatting (line length: 99 characters)
- **Testing**: pytest with asyncio support, 95%+ coverage target
- **Security**: No `eval()`, comprehensive input validation

### Adding New Mathematical Tools
1. **Core Implementation**: Add to appropriate module in `calculator/core/`
2. **Tool Registration**: Add to tool group in `calculator/core/tool_groups.py`
3. **Server Integration**: Register in `calculator/server.py` with `@filtered_tool`
4. **Comprehensive Testing**: Add tests covering edge cases and error conditions
5. **Documentation**: Update README with tool description and examples

### Pull Request Guidelines
- **Clear Description**: Explain what your PR does and why
- **Test Coverage**: Include tests for new functionality
- **Documentation Updates**: Update relevant documentation
- **Breaking Changes**: Clearly mark any breaking changes
- **Performance Impact**: Note any performance implications

### Getting Help
- **Issues**: [GitHub Issues](https://github.com/peepeepopapapeepeepo/mcp-calculator/issues)
- **Discussions**: [GitHub Discussions](https://github.com/peepeepopapapeepeepo/mcp-calculator/discussions)
- **Documentation**: Check README and inline documentation

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

**Copyright (c) 2025 MCP Calculator Team**

## 📞 Support & Resources

### Getting Help
- **📋 Issues**: [GitHub Issues](https://github.com/peepeepopapapeepeepo/mcp-calculator/issues) - Bug reports and feature requests
- **💬 Discussions**: [GitHub Discussions](https://github.com/peepeepopapapeepeepo/mcp-calculator/discussions) - Questions and community support
- **📖 Documentation**: This README and inline code documentation
- **🔍 Troubleshooting**: Check the configuration examples and error messages

### Project Links
- **🏠 Homepage**: [GitHub Repository](https://github.com/peepeepopapapeepeepo/mcp-calculator)
- **📦 PyPI Package**: [p6plab-mcp-calculator](https://pypi.org/project/p6plab-mcp-calculator)
- **📋 Test PyPI**: [p6plab-mcp-calculator (Test)](https://test.pypi.org/project/p6plab-mcp-calculator)
- **📝 Changelog**: [CHANGELOG.md](CHANGELOG.md) - Detailed version history
- **⚖️ License**: [LICENSE](LICENSE) - MIT License terms

### Quick Links
- **Installation**: `uvx p6plab-mcp-calculator@latest`
- **All Tools**: Add `CALCULATOR_ENABLE_ALL=true` to environment
- **Health Check**: Use `health_check()` tool to verify configuration
- **Tool Count**: 8 tools (basic) to 68 tools (all groups enabled)

---

**Version**: 1.0.1 | **Status**: Production/Stable | **Python**: 3.8+ | **License**: MIT

Made with 👻 Kiro, an agentic IDE.