# Math Reasoning MCP

[![Tests](https://github.com/TeleEng/math-reasoning-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/TeleEng/math-reasoning-mcp/actions/workflows/ci.yml)

![Math-Aware AI Engine](banner.jpg)

**A Model Context Protocol (MCP) server that gives AI agents a deterministic mathematical brain.** Instead of hallucinating algebra, the agent delegates symbolic computation to a SymPy engine over JSON-RPC — getting exact, verifiable results every time.

Built for engineers, researchers, and students working in **Algebra, Calculus, Signals & Systems, and Digital Signal Processing (DSP).**

---

## Why This Exists

Large Language Models are statistical text predictors. They can *describe* a Laplace transform, but when asked to *execute* one — especially a multi-step derivation involving chain rules, frequency shifts, and polynomial expansion — they routinely:

- Drop negative signs
- Hallucinate polynomial terms
- Produce plausible-looking but **wrong** final answers

Models with built-in code execution (like Gemini) work around this by writing and running Python scripts in a proprietary sandbox. This MCP provides the same deterministic SymPy power as a **universal, open standard** — pluggable into any AI agent, no proprietary sandbox required.

---

## Proof of Value

**Problem:** Compute the Laplace Transform of $f(t) = t^2 e^{-3t} \sin(2t)$ and find the system poles.

| | Raw LLM (no tools) | With Math MCP |
|---|---|---|
| **Accuracy** | ❌ Fails on the 2nd-derivative chain rule. Wrong poles. | ✅ Exact: $\frac{4(3(s+3)^2 - 4)}{((s+3)^2 + 4)^3}$, poles at $-3 \pm 2i$ |
| **Tokens** | ~800+ (lengthy, incorrect derivation) | ~150 (two tool calls + final answer) |
| **Time** | Slow (multi-step generation) | < 2 seconds |

---

## 21 Tools

### 📐 Core Algebra & Calculus

| Tool | Description | Example |
|------|-------------|---------|
| `parse_latex_to_sympy` | Convert LaTeX → SymPy | `\frac{d}{dx} x^2` → `Derivative(x**2, x)` |
| `simplify_expression` | Simplify expressions | `sin(x)**2 + cos(x)**2` → `1` |
| `solve_equation` | Solve for a variable | `s**2 + 6*s + 13` → `[-3-2i, -3+2i]` |
| `evaluate_expression` | Numeric evaluation | `sqrt(2) + pi` → `4.55...` |
| `differentiate` | Symbolic derivative (nth-order) | `x**3, order=2` → `6*x` |
| `integrate_expression` | Symbolic integral | `exp(-x)` → `-exp(-x)` |
| `partial_fraction_decomposition` | Partial fractions | `1/((s+1)*(s+2))` → `1/(s+1) - 1/(s+2)` |

### 📡 Signals & Continuous Transforms

| Tool | Description | Example |
|------|-------------|---------|
| `laplace_transform_signal` | $f(t) \to F(s)$ | `t**2 * exp(-3*t)` → `2/(s+3)**3` |
| `inverse_laplace_transform_signal` | $F(s) \to f(t)$ | `1/(s+3)` → `exp(-3*t)` |
| `fourier_transform_signal` | $f(t) \to F(\omega)$ | `exp(-a*t**2)` → `sqrt(pi)*exp(-w²/(4a))/sqrt(a)` |
| `inverse_fourier_transform_signal` | $F(\omega) \to f(t)$ | Inverse of the above |
| `continuous_convolution` | $(f * g)(t)$ with Heaviside support | Causal signals handled automatically |

### 💻 Discrete-Time & DSP

| Tool | Description | Example |
|------|-------------|---------|
| `z_transform_signal` | One-sided Z-transform | `a**n` → `z/(z - a)` |
| `dtft_signal` | Discrete-Time Fourier Transform | `0.5**n` → `1/(1 - 0.5*exp(-jW))` |
| `compute_fft` | Numerical FFT (numpy) | `[1,1,0,0]` → `[2+0j, 1-1j, 0+0j, 1+1j]` |
| `uniform_quantization` | ADC quantization simulation | `3.14V, 4-bit, 0–5V` → `Δ=0.3125, SQNR=25.84 dB` |

### ⚙️ System Analysis

| Tool | Description | Example |
|------|-------------|---------|
| `poles_and_zeros` | Poles & zeros of $H(s)$ or $H(z)$ | `(s-2)/((s+1)*(s+3))` → Zeros: `[2]`, Poles: `[-3,-1]` |
| `check_linearity` | Prove/disprove linearity | `x**2` → `Linear: False` with symbolic proof |
| `check_time_invariance` | Prove/disprove TI | `t*x` → `Time-Invariant: False` with reasoning |

Both `check_linearity` and `check_time_invariance` support:
- **Memoryless systems**: expressions in `x` and `t` (e.g., `x**2`, `t*x + 5`)
- **Difference equations**: expressions in `x_n`, `x_n1`, `x_n2`, `n` (e.g., `x_n + x_n1`)

`check_linearity` also detects **affine systems** (constant offset makes it non-linear).

### 🧮 Step-by-Step Solvers

| Tool | Description |
|------|-------------|
| `step_by_step_laplace` | Derives the Laplace transform showing each property applied (linearity, frequency shift, time multiplication) with verification |
| `step_by_step_algebra` | Solves equations showing expansion, factoring, discriminant analysis, and verification of each root |

These tools don't just return the answer — they show the *derivation*, making them ideal for education and debugging.

---

## Testing

55 tests covering all 21 tools, edge cases, and error handling:

```bash
uv run pytest tests/ -v
```

```
tests/test_tools.py   55 passed in 4.38s
```

Tests cover:
- All core algebra operations (simplify, solve, differentiate, integrate)
- All transform tools (Laplace, Fourier, Z-transform, FFT)
- System analysis (linearity, time-invariance) for both memoryless and memory systems
- Affine vs. linear detection
- Step-by-step output structure
- Structured error handling for malformed input

---

## Installation

Requires [`uv`](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/TeleEng/math-reasoning-mcp.git
cd math-reasoning-mcp
uv sync
```

## Usage

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "math-reasoning": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "<absolute-path-to-this-repository>",
        "math-reasoning-mcp"
      ]
    }
  }
}
```

Compatible with any MCP client: Claude Desktop, Cursor, Windsurf, Antigravity, custom agents, etc.

## Architecture

```
┌──────────────┐     JSON-RPC      ┌──────────────────┐
│   AI Agent   │ ◄──── MCP ──────► │  Math MCP Server │
│  (any LLM)   │   (stdio/SSE)     │   (SymPy+NumPy)  │
└──────────────┘                   └──────────────────┘
       │                                    │
  Reads files,                        Deterministic
  understands                         symbolic math
  context                             engine
```

## Tech Stack

- **[SymPy](https://www.sympy.org/)** — Symbolic mathematics engine
- **[NumPy](https://numpy.org/)** — Numerical computation (FFT, quantization)
- **[MCP SDK](https://modelcontextprotocol.io/)** — Model Context Protocol server framework
- **[uv](https://docs.astral.sh/uv/)** — Fast, reproducible Python dependency management
- **[pytest](https://pytest.org/)** — Test framework (55 tests)

## License

MIT