# advanced-math-mcp

MCP (Model Context Protocol) server for advanced mathematics — linear algebra, vector math, symbolic computation, and calculus. Designed for use with Claude and other MCP-compatible LLMs.

## Quick Start

```bash
npm install -g advanced-math-mcp
```

Then add to your MCP client configuration (e.g., `mcp_settings.json`):

```json
{
  "mcpServers": {
    "advanced-math-mcp": {
      "command": "advanced-math-mcp",
      "args": [],
      "alwaysAllow": [
        "evaluate",
        "set_variable",
        "get_variable",
        "list_variables",
        "clear_variables",
        "matrix_create",
        "matrix_identity",
        "matrix_zeros",
        "matrix_diagonal",
        "symbolic_simplify",
        "symbolic_substitute",
        "symbolic_derivative",
        "symbolic_expand",
        "symbolic_integrate",
        "symbolic_definite_integral",
        "symbolic_limit",
        "symbolic_partial_derivative"
      ]
    }
  }
}
```

## Tools (17 total)

### Unified Expression Evaluator

| Tool | Description |
|---|---|
| `evaluate` | Universal expression evaluator with natural math syntax. Supports matrices, vectors, scalars, decompositions, and custom functions. |
| `set_variable` | Define a named variable (matrix, vector, or scalar) for use in `evaluate` |
| `get_variable` | Retrieve a variable's value |
| `list_variables` | List all defined variables and their types |
| `clear_variables` | Reset all variables |

### Matrix Creation

| Tool | Description |
|---|---|
| `matrix_create` | Create a matrix from a 2D array of strings |
| `matrix_identity` | Create an n×n identity matrix |
| `matrix_zeros` | Create an m×n matrix of zeros |
| `matrix_diagonal` | Create a diagonal matrix from a vector of values |

### Symbolic Math

| Tool | Description |
|---|---|
| `symbolic_simplify` | Simplify algebraic expressions |
| `symbolic_expand` | Expand factored expressions |
| `symbolic_substitute` | Substitute variables with values or expressions |
| `symbolic_derivative` | Compute ordinary derivatives (single-variable) |
| `symbolic_partial_derivative` | Compute partial derivatives (multivariable) |
| `symbolic_integrate` | Compute indefinite integrals (antiderivatives) |
| `symbolic_definite_integral` | Compute definite integrals with bounds |
| `symbolic_limit` | Compute limits of expressions |

## `evaluate` — The Universal Evaluator

All matrix/vector operations use a single `evaluate` tool with natural expression syntax:

### Matrix Operations
```js
// Arithmetic
evaluate("A + B")           // addition
evaluate("A - B")           // subtraction
evaluate("A * B")           // matrix multiplication
evaluate("A ^ 3")           // matrix power

// Properties
evaluate("det(A)")          // determinant
evaluate("trace(A)")        // trace
evaluate("rank(A)")         // rank
evaluate("inv(A)")          // inverse
evaluate("transpose(A)")    // transpose

// Decompositions
evaluate("eig(A)")          // eigenvalues & eigenvectors
evaluate("charpoly(A)")     // characteristic polynomial (2×2, 3×3)
evaluate("lu(A)")           // LU decomposition
evaluate("qr(A)")           // QR decomposition
evaluate("svd(A)")          // singular value decomposition

// Linear systems
evaluate("solve(A, b)")     // solve Ax = b
```

### Vector Operations
```js
evaluate("dot([1,2,3], [4,5,6])")       // dot product → 32
evaluate("cross([1,2,3], [4,5,6])")     // cross product → [-3, 6, -3]
evaluate("norm([3,4])")                  // L2 norm → 5
evaluate("norm([3,4], \"1\")")           // L1 norm → 7
evaluate("project([3,4], [1,0])")        // vector projection → [3, 0]
```

### Inline Literals
```js
evaluate("[[1,2],[3,4]] * [[5,6],[7,8]]")  // → [[19,22],[43,50]]
evaluate("det([[4,1],[2,3]])")              // → 10
evaluate("inv([[4,7],[2,6]])")             // → [[0.6,-0.7],[-0.2,0.4]]
```

### Variable Workflow
```js
set_variable("A", "[[1,2],[3,4]]")
set_variable("B", "[[5,6],[7,8]]")
evaluate("A * B")          // uses stored variables
list_variables()           // see all defined variables
clear_variables()          // reset
```

## Symbolic Math

### Simplification & Expansion
```js
symbolic_simplify("x^2 + 2*x + 1 - (x+1)^2")  // → 0
symbolic_expand("(x+1)*(x-1)*(x+2)")           // → x^3 + 2x^2 - x - 2
```

### Substitution
```js
// Single variable
symbolic_substitute("x^2 + 2*x", { x: "3" })      // → 15

// Multi-variable
symbolic_substitute("x^2 + y*x + z", { x: "3", y: "2", z: "1" })  // → 16
```

### Calculus
```js
// Derivatives
symbolic_derivative("x^3 + 2*x^2", "x")              // → 3x^2 + 4x
symbolic_partial_derivative("x^2*y + sin(z)", "x", 2) // → 2y (second partial)

// Integration
symbolic_integrate("x^2 + sin(x)", "x")               // → 0.333x^3 - cos(x) + C
symbolic_definite_integral("x^2", "x", "0", "2")      // → 2.667 (∫₀² x² dx)

// Limits
symbolic_limit("sin(x)/x", "x", "0")                  // → 1
```

## Architecture

```
src/
├── index.ts              # Entry point, loads nerdamer plugins
├── server.ts             # MCP server setup, tool routing
├── types.ts              # Shared types and Zod schemas
├── engine/
│   ├── evaluator.ts      # Unified expression evaluator (mathjs + custom functions)
│   ├── symbolic.ts        # Symbolic engine (nerdamer + mathjs)
│   ├── math-engine.ts     # Low-level matrix operations
│   └── format.ts          # Output formatting utilities
└── tools/
    ├── evaluate.ts        # evaluate + variable management tools
    ├── matrix-create.ts   # matrix_create, identity, zeros, diagonal
    ├── symbolic.ts        # symbolic_simplify, substitute, derivative, expand
    └── calculus.ts        # symbolic_integrate, definite_integral, limit, partial_derivative
```

### Dependencies

| Package | Purpose |
|---|---|
| `@modelcontextprotocol/sdk` | MCP protocol implementation |
| `mathjs` v13 | Numeric matrix operations, expression parsing |
| `nerdamer` | Symbolic algebra, calculus (integrals, limits) |
| `zod` | Runtime input validation |

### Custom Functions in `evaluate`

The evaluator extends mathjs with these custom functions:

| Function | Implementation |
|---|---|
| `rank(A)` | Via eigenvalue count of AᵀA |
| `solve(A, b)` | Wraps `math.lusolve()` |
| `eig(A)` / `eigs(A)` | Wraps `math.eigs()` with formatted output |
| `svd(A)` | Via eigenvalue decomposition of AᵀA |
| `charpoly(A)` | Formula-based for 2×2 and 3×3 |
| `lu(A)` | Alias for `math.lup()` |
| `qr(A)` | Alias for `math.qr()` |
| `project(u, v)` | Vector projection formula |
| `norm(v, type)` | L1, L2 (default), L∞ |

## Development

```bash
git clone https://github.com/PsyWhat/advanced-math-mcp.git
cd advanced-math-mcp
npm install
npm run build        # compile TypeScript
npm run dev          # watch mode
npm link             # install globally for local testing
```

## Testing

```bash
npm test             # run all tests (vitest)
npm run test:watch   # watch mode
npm run typecheck    # TypeScript validation only
```

| Suite | Tests | Coverage |
|---|---|---|
| `evaluator.test.ts` | 36 | Matrix ops, vector ops, decompositions, eigenvalues, variable scope, error handling |
| `symbolic.test.ts` | 15 | Simplify, expand, substitute, ordinary derivatives |
| `calculus.test.ts` | 17 | Indefinite/definite integrals, limits, partial derivatives |

**All 68 tests pass.**

## Known Limitations

- **SVD**: The rank-deficient SVD gives zero vectors for nullspace columns (computed via AᵀA eigen-decomposition, not full Golub-Reinsch)
- **Cholesky**: Not available in mathjs v13; use `lu()` for general decomposition
- **`norm(v, inf)`**: Must use quoted `"inf"` (not bare `inf`) due to mathjs parsing
- **`charpoly`**: Numeric only, supports 2×2 and 3×3 matrices
- **`symbolic_limit`**: Some advanced limits (e.g., `(1+1/x)^x` as `x→∞`) may not fully resolve

## License

MIT