CalcMCP/README.md

# Scientific Calculator MCP Server

> A Model Context Protocol (MCP) server providing advanced mathematical calculation capabilities for AI models. Supports symbolic math (SymPy), numerical computing (NumPy/SciPy), data analysis (pandas), and image processing.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **Fork notice** — this is a patched fork of
> [thinkitpossible/CalcMCP](https://github.com/thinkitpossible/CalcMCP).
> Changes relative to upstream:
>
> - **MCP compliance**: tools are published with a proper `inputSchema` (upstream used a
>   non-standard `params` key, so clients saw no parameters at all); JSON-RPC notifications
>   (`notifications/initialized`) are no longer answered with an error; tool failures set
>   `isError: true` on the result.
> - **Tool descriptions rewritten in English**, with per-parameter docs and inline examples.
> - **Security**: removed all raw `eval()` of tool arguments (matrix inputs now parse via
>   `json.loads`/`ast.literal_eval`, the numeric-ODE right-hand side via `sympy.lambdify`).
> - **Bug fixes**: eigenvalue/eigenvector results with complex values no longer crash JSON
>   serialization (rendered as `a+bi` strings); `solve` accepts equations written with `=`;
>   one-sample t-test accepts `params` as `{"popmean": ...}` or a bare number.
> - **New**: `symbolic_tool` operation `dsolve` — symbolic ODE solving
>   (e.g. `Derivative(y(x), x, 2) + y(x) = 0` → `y(x) = C1*sin(x) + C2*cos(x)`).

## Quick Start

### 1. Install Dependencies
```bash
pip install sympy numpy scipy pandas
```

### 2. Server Configuration

Add to your MCP client config (e.g., Claude Desktop `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "scientific-calculator": {
      "command": "python",
      "args": ["-u", "path/to/mcp_server.py"],
      "env": {}
    }
  }
}
```

**Windows Example:**
```json
{
  "mcpServers": {
    "scientific-calculator": {
      "command": "python",
      "args": ["-u", "F:\\AAchengguoofAI\\cuz_caculat\\mcp_server.py"]
    }
  }
}
```

**macOS/Linux Example:**
```json
{
  "mcpServers": {
    "scientific-calculator": {
      "command": "python3",
      "args": ["-u", "/path/to/mcp_server.py"]
    }
  }
}
```

## Features

- **3 Unified Tools** covering:
  - **symbolic_tool**: Symbolic algebra, calculus, equation solving (SymPy)
  - **numpy_tool**: Linear algebra, matrix decompositions, data analysis (NumPy/pandas), image processing
  - **scipy_tool**: Numerical integration, optimization, ODE/PDE solving, statistics, FFT
- **10 University-Level Math Problems** with validated step-by-step solutions
- **100% Calculation Accuracy** (validated against analytical solutions)
- **MCP Protocol Compliant** (STDIO transport, JSON-RPC 2.0)
- **Zero Configuration** - Works out-of-the-box with Claude Desktop

## Core Files

| File | Purpose |
|------|---------|
| `calculator.py` | Pure function library with 22 mathematical tools |
| `mcp_server.py` | MCP-compliant server (STDIO-based, JSON-RPC 2.0) |
| `advanced_math_problems.py` | 10 complex math problems with solutions |
| `advanced_math_problems.json` | Problem data (auto-generated) |

## Supported Operations (via consolidated tools)

### `symbolic_tool`
- Operations: simplify, expand, factor, derivative, integral, limit, solve, taylor, matrix (determinant/inverse/rank/trace via `matrix_data`).

-### `numpy_tool`
- Array reductions: sum, mean, std, max, min (with optional axis).
- Linear algebra & decompositions: eigenvalues/eigenvectors (aliases eig/eigvals), determinant, inverse, solve, norm, rank, trace, matmul/dot/hadamard (needs `matrix_a` & `matrix_b`), SVD, QR, Cholesky (use `matrix_a`, optional `matrix_b`).
- Polynomials: poly_eval, poly_derivative, poly_integral.
- Trigonometry: sin/cos/tan/arcsin/arccos/arctan/sinh/cosh/tanh (optional degrees input).
- Pandas (data analysis via pandas_* operations): describe, corr, value_counts (requires `columns`), group_sum (`columns` JSON with group/agg). Input as dataframe JSON.
- Image (numpy-based): image_stats, image_normalize, image_threshold (input `image_data` JSON array, optional `threshold`).
- Trigonometry: sin, cos, tan, arcsin, arccos, arctan, sinh, cosh, tanh (use `values`, optional `use_degrees`).
- Polynomials: poly_eval, poly_derivative, poly_integral (use `coefficients`, optional `x_values`).

### `scipy_tool`
- Integrate: integrate_function (operation=`integrate`).
- Optimization: optimize_minimize, optimize_root.
- Interpolation: interpolate_linear / interpolate_cubic / interpolate_spline.
- Special functions: special (function + parameters).
- ODE: solve_ode (expression, initial_conditions, t_values).
- Statistics: statistics/mean/std/describe/ttest/pearsonr via `operation` + `data` (+ `params`).
- FFT: fft, rfft.
- Matrix eigensystem: matrix_eigensystem (uses `matrix_a`).

## Usage Examples

```python
from calculator import CALCULATOR_TOOLS

# Derivative: d(x³)/dx = 3x²
result = CALCULATOR_TOOLS['symbolic_derivative']('x**3', 'x')

# Solve: x² - 4 = 0
result = CALCULATOR_TOOLS['solve_equation']('x**2 - 4', 'x')

# Eigenvalues of matrix
import numpy as np
A = [[1, 2], [3, 4]]
result = CALCULATOR_TOOLS['numpy_linear_algebra'](A, 'eigenvalues')

# Integrate: ∫ x² dx from 0 to 1
result = CALCULATOR_TOOLS['symbolic_integral']('x**2', 'x', 0, 1)
```

## Model Usage Policy

- Every numeric or symbolic calculation must be delegated to the tools (via MCP `tools/call` or direct `CALCULATOR_TOOLS[...]`), never hand-compute inside the model response.
- Reasoning flow: pick the right tool → prepare JSON-safe inputs → call the tool → present the tool output (with minimal post-processing only for formatting).
- If a step would require arithmetic, call a tool instead (e.g., use `numpy_linear_algebra` for matrices, `symbolic_*` for algebra, `scipy_*` for calculus/optimization).
- Avoid approximations unless the tool returns them; do not estimate values manually.

### Prompting Playbook (Advanced Problems)
- Restate the task, list the required sub-calculations, and map each to a tool.
- For matrices, always supply `matrix_a` (and `matrix_b` when needed) as JSON arrays to `numpy_linear_algebra`.
- For calculus/ODE/PDE, convert expressions to plain strings (SymPy-compatible) before calling `symbolic_*` or `scipy_*` tools.
- After each tool call, reuse its exact output for subsequent steps—no manual arithmetic in between.
- When summing or solving, prefer tool outputs as inputs to the next tool (e.g., eigenvalues → use in later steps instead of recomputing).
- If the user asks for a result, return: the tool(s) called, inputs used, and the tool outputs; avoid “mental math.”

## Problem Set

10 complex university-level problems demonstrating the tool capabilities:

1. **2nd Order ODE**: y'' + 4y' + 4y = e^x (7 steps)
2. **Eigenvalues & Eigenvectors**: Matrix analysis (5 steps)
3. **Fourier Series & Basel Problem**: Series expansion (6 steps)
4. **Lagrange Multipliers**: Constrained optimization (7 steps)
5. **Residue Theorem**: Complex integration (6 steps)
6. **Heat Equation**: PDE solving (7 steps)
7. **Surface Geometry**: Tangent planes (7 steps)
8. **ODE Systems**: Linear systems (7 steps)
9. **Green's Theorem**: Line integrals (8 steps)
10. **Calculus of Variations**: Euler-Lagrange (10 steps)

## Performance

| Metric | Value |
|--------|-------|
| Calculation Accuracy | 100% |
| MCP Compliance | 100% (16/16 checks) |
| Tools Available | 3 (consolidated) |
| Problems Included | 10 |
| Solution Steps | 69 |
| Startup Time | <1 second |
| Response Time | <100ms |

## Technical Details

- **Transport**: STDIO (standard for MCP)
- **Protocol**: JSON-RPC 2.0
- **Language**: Python 3.10+
- **Dependencies**: SymPy, NumPy, SciPy, FastMCP
- **Size**: ~70 KB (core code only)

## Status

✅ **Production Ready**
- 3 consolidated tools tested and working
- MCP specification verified
- Deployed and tested with Claude Desktop
- Ready for production use

## Support

For issues or questions, refer to the MCP specification at: https://modelcontextprotocol.io/docs/develop/build-server