# Mathematical MCP Server

A small, secure Model Context Protocol (MCP) server that exposes 6 basic mathematical tools to
any MCP-compatible AI client (e.g., Claude Desktop, Cursor, VS Code).

Built using Python, FastMCP, Pydantic, and SymPy, this server performs basic arithmetic and safe
symbolic expression evaluation.

---

## Features

- **Standardized Structured Responses:** Returns structured JSON responses containing `success`, `result` (properly serialized to JSON-friendly types), `error`, and `execution_time_ms`.
- **Input Validation:** Enforces strict type checking using Pydantic.
- **Safe Expression Evaluation:** Parses and evaluates string equations (e.g., `(5+7)*9/3`) using a secure whitelist-based SymPy AST walker.
- **Robust Error Handling:** Intercepts and formats errors like division-by-zero and complex roots.
- **Strict I/O Logging:** Automatically logs incoming requests, runtime arguments, execution speeds, and errors strictly to `stderr` to preserve stdout for MCP JSON-RPC protocol transport.

---

## Folder Structure

```
Calculator_MCP_Server/
├── config.py                 # Computational boundaries and whitelists
├── schemas.py                # Pydantic response models
├── utils.py                  # Logging configurations and tool execution wrappers
├── calculator.py             # Pure mathematical algorithms
├── tools.py                  # MCP tools definitions and binding using FastMCP
├── server.py                 # Application entry point
├── requirements.txt          # Python dependencies
├── pyproject.toml            # Formatter (black/ruff) and pytest config
├── .gitignore                # Git files pattern exclusions
└── tests/
    ├── test_calculator.py    # Unit tests for core algorithms
    └── test_tools.py         # Integration tests for tool wrappers
```

---

## Installation & Setup

### 1. Prerequisites
- **Python 3.12+**
- **pip** (Python package installer)

### 2. Set Up Virtual Environment
Clone this repository and navigate into the folder:
```bash
cd Calculator_MCP_Server
```

Create a virtual environment:
```bash
# On Windows
python -m venv .venv
.venv\Scripts\activate

# On macOS/Linux
python3 -m venv .venv
source .venv/bin/activate
```

### 3. Install Dependencies
```bash
pip install -r requirements.txt
```

---

## Running the MCP Server

The server communicates via standard I/O (`stdio`) by default, making it ideal for local LLM integrations.

```bash
# Run server
python server.py
```

To run with live reloading and access the **MCP Inspector** web interface (ideal for testing tools in the browser):
```bash
fastmcp dev server.py
```

---

## Connecting to MCP Clients

### Claude Desktop
To integrate this mathematical server with Claude Desktop, add it to your configuration file:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the following to the `mcpServers` object:

```json
{
  "mcpServers": {
    "math-server": {
      "command": "python",
      "args": [
        "c:/Users/Admin/OneDrive/Documents/Projects/Calculator_MCP_Server/server.py"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "MAX_FACTORIAL_N": "10000"
      }
    }
  }
}
```
*Note: Make sure to specify the absolute path to your Python executable if it's not globally available in your environment's PATH.*

---

## Available Tools

- `add(a, b)`: Returns $a + b$.
- `subtract(a, b)`: Returns $a - b$.
- `multiply(a, b)`: Returns $a \times b$.
- `divide(a, b)`: Returns $a / b$ (raises division-by-zero errors).
- `power(base, exponent)`: Returns $base^{exponent}$ (handles negative bases/exponent calculations).
- `evaluate_expression(expression)`: Safely parses and evaluates mathematical expression strings (e.g. `(5+7)*9/3`). Supports basic math operators and trigonometric/root functions.

---

## Example AI Prompts

You can write naturally to any MCP client equipped with this server:
- *"What is 567 × 897?"* (calls `multiply`)
- *"What is 2 raised to the power of 10?"* (calls `power`)
- *"Calculate (12 + 8) * 3 / 2"* (calls `evaluate_expression`)
- *"What is sin(0) + cos(0)?"* (calls `evaluate_expression`)

---

## Testing

To run the automated tests:
```bash
pytest
```

To run with coverage or verbose mode:
```bash
pytest -v
```

---

## Future Improvements

1. **Caching Layer:** Cache expensive symbolic evaluations and factorial queries.
2. **Extended Solvers:** Implement solvers for cubic equations and system of linear equations (using SymPy's `linsolve`).
3. **Advanced Matrix Algorithms:** Eigenvalue and eigenvector calculations using NumPy/SciPy.
4. **Calculus Tools:** Symbolic derivative and integration tools.

---

## License

This project is licensed under the MIT License - see the LICENSE file for details.