Metadata-Version: 2.5
Name: math-mcp-ay
Version: 0.3.0
Summary: A Model Context Protocol (MCP) server exposing safe math tools.
Project-URL: Homepage, https://github.com/AbderY/math-mcp
Project-URL: Issues, https://github.com/AbderY/math-mcp/issues
Author: AbderY
License: MIT License
        
        Copyright (c) 2026 AbderY
        
        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: llm,math,mcp,model-context-protocol,tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2.0
Requires-Dist: sympy>=1.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# math-mcp

[![CI](https://github.com/AbderY/math-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/AbderY/math-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/math-mcp-ay.svg)](https://pypi.org/project/math-mcp-ay/)

A small [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server
that gives an LLM a set of reliable math tools — expression evaluation,
statistics, number theory, linear algebra, and symbolic math — instead of
asking it to do arithmetic in its head.

Every tool runs real, deterministic code. The expression evaluator is
**sandboxed**: it parses input into an AST and only allows a whitelist of
operators, constants, and functions. It never calls Python's `eval`. Symbolic
tools parse input with SymPy's tokenizing parser (also no `eval`).

## Tools

### Numeric & number theory

| Tool | Description |
| --- | --- |
| `evaluate` | Evaluate an expression like `sqrt(2) * sin(pi / 4)`. Supports `+ - * / // % **`, parentheses, constants (`pi`, `e`, `tau`) and functions (`sqrt`, `sin`, `log`, `factorial`, `gcd`, `hypot`, …). |
| `descriptive_statistics` | Count, sum, min, max, mean, median, variance and standard deviation (population and sample) of a list of numbers. |
| `is_prime` | Test whether an integer is prime. |
| `prime_factorization` | Factor a positive integer into primes with exponents. |
| `gcd_lcm` | Greatest common divisor and least common multiple of two or more integers. |
| `solve_quadratic` | Roots of `a·x² + b·x + c = 0`, real or complex, with the discriminant. |
| `convert_base` | Convert an integer between bases 2–36. |

### Linear algebra

Matrices are lists of rows, e.g. `[[1, 2], [3, 4]]`.

| Tool | Description |
| --- | --- |
| `matrix_multiply` | Matrix product `A @ B`. |
| `matrix_transpose` | Transpose of a matrix. |
| `matrix_determinant` | Determinant of a square matrix. |
| `matrix_inverse` | Inverse of a square, non-singular matrix. |
| `solve_linear_system` | Solve `A x = b` for `x`. |

### Symbolic (SymPy)

| Tool | Description |
| --- | --- |
| `simplify_expression` | Simplify, e.g. `sin(x)**2 + cos(x)**2` → `1`. |
| `expand_expression` | Expand, e.g. `(x + 1)**2` → `x**2 + 2*x + 1`. |
| `factor_expression` | Factor, e.g. `x**2 - 1` → `(x - 1)*(x + 1)`. |
| `differentiate` | Derivative w.r.t. a variable (any order). |
| `integrate` | Indefinite integral w.r.t. a variable. |
| `definite_integral` | Definite integral over `[lower, upper]` (bounds may be `oo`). |
| `limit` | Limit as a variable approaches a point (`oo` allowed; left/right/two-sided). |
| `taylor_series` | Taylor series about a point, up to N terms. |
| `solve_symbolic_equation` | Solve an equation, e.g. `x**2 = 4` → `["-2", "2"]`. |

## Resources & prompts

Beyond tools, the server exposes:

- **Resources** — mathematical constants to 50 digits: `math://constants`
  (an index) and `math://constants/{name}` for `pi`, `e`, `tau`, `phi`
  (golden ratio) and `gamma` (Euler–Mascheroni).
- **Prompts** — reusable templates a client can offer to the user:
  `solve_step_by_step` and `solve_linear_system_prompt`.

## Install

Requires Python 3.10+.

Once published to PyPI (distribution name `math-mcp-ay`):

```bash
pip install math-mcp-ay
```

The import package is `math_mcp` and the command is `math-mcp` regardless of
the distribution name.

From source (for development):

```bash
git clone https://github.com/AbderY/math-mcp.git
cd math-mcp
pip install -e ".[dev]"
```

## Run

The server speaks MCP over stdio:

```bash
math-mcp
# or
python -m math_mcp
```

### Use with an MCP client

Add it to your client's MCP configuration. For example (Claude Desktop /
`claude_desktop_config.json`, or any MCP client that launches servers):

```json
{
  "mcpServers": {
    "math": {
      "command": "math-mcp"
    }
  }
}
```

If `math-mcp` is not on your `PATH`, use the interpreter form instead:

```json
{
  "mcpServers": {
    "math": {
      "command": "python",
      "args": ["-m", "math_mcp"]
    }
  }
}
```

## Examples

- `evaluate("2 ** 10 + factorial(5)")` → `1144.0`
- `descriptive_statistics([2, 4, 4, 4, 5, 5, 7, 9])` → mean `5.0`, `pstdev` `2.0`
- `prime_factorization(360)` → `2³ · 3² · 5`
- `solve_quadratic(1, -3, 2)` → roots `1.0` and `2.0`
- `convert_base("ff", 16, 2)` → `"11111111"`
- `matrix_inverse([[4, 7], [2, 6]])` → `[[0.6, -0.7], [-0.2, 0.4]]`
- `solve_linear_system([[1, 1], [1, -1]], [3, 1])` → `[2.0, 1.0]`
- `differentiate("x**3", "x", 2)` → `"6*x"`
- `definite_integral("exp(-x)", "x", "0", "oo")` → `"1"`
- `limit("sin(x)/x", "x", "0")` → `"1"`
- `taylor_series("exp(x)", "x", "0", 4)` → `"x**3/6 + x**2/2 + x + 1"`
- `solve_symbolic_equation("x**2 = 4")` → `["-2", "2"]`

## Development

```bash
pip install -e ".[dev]"
pytest
```

## Releasing to PyPI

Publishing is automated via GitHub Actions using
[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC),
so no API token is stored in the repo.

One-time setup on [pypi.org](https://pypi.org):

1. Create (or claim) the project name `math-mcp-ay`.
2. Under the project's *Publishing* settings, add a **trusted publisher**:
   - Owner: `AbderY`, repository: `math-mcp`
   - Workflow: `publish.yml`
   - Environment: `pypi`

Then, to release: bump the version in `pyproject.toml` and
`src/math_mcp/__init__.py`, tag it, and publish a GitHub Release. The
`publish.yml` workflow builds the sdist + wheel and uploads them to PyPI.

## License

[MIT](LICENSE)
