mcp_math_tool_gradio/README.md

---
title: MCP Math Calculator Tool
emoji: 🧮
colorFrom: purple
colorTo: pink
sdk: gradio
sdk_version: 4.44.1
app_file: app.py
pinned: false
license: mit
tags:
  - mcp-server-track
  - mcp
  - mathematics
  - calculator
  - computation
  - hackathon
  - gradio
python_version: 3.11.8
---

# 🧮 MCP Math Calculator Tool

An AI-powered mathematical computation tool that provides both a user-friendly Gradio interface and an MCP (Model Context Protocol) server endpoint for integration with AI assistants and other applications.

## ✨ Features

- **🔢 Advanced Calculations**: Support for complex mathematical expressions and operations
- **📊 Statistical Functions**: Mean, median, standard deviation, and statistical analysis
- **📈 Mathematical Functions**: Trigonometry, logarithms, exponentials, and more
- **🔌 MCP Server**: Compliant with Model Context Protocol for AI assistant integration
- **🎨 Interactive UI**: Modern Gradio interface with real-time calculation preview
- **⚡ Fast Processing**: Instant mathematical computation and validation

## 🚀 Quick Start

### Using the Web Interface

1. **Visit this Space** and interact with the web interface directly
2. **Enter your mathematical expression** in the input field
3. **Click Calculate** to get instant results
4. **View detailed breakdown** of complex calculations

### Supported Operations

- ➕ **Basic Arithmetic**: Addition, subtraction, multiplication, division
- 🔢 **Advanced Math**: Powers, roots, factorials, logarithms
- 📐 **Trigonometry**: sin, cos, tan, and inverse functions
- 📊 **Statistics**: Statistical functions for data analysis
- 🧮 **Constants**: π (pi), e (Euler's number), and mathematical constants

## 🔌 MCP Server Integration

This tool implements the Model Context Protocol (MCP) for integration with AI assistants, allowing programmatic mathematical computation capabilities.

### MCP Endpoint Details

- **Endpoint URL**: `https://[this-space-url]/gradio_api/mcp/sse`
- **HTTP Method**: `POST`
- **Content-Type**: `application/json`

### Request Format

Send a POST request with the following JSON payload:

```json
{
  "data": [
    "<mathematical_expression>"
  ]
}
```

**Parameters:**
- `data[0]` (string): Mathematical expression to evaluate (e.g., "2 + 3 * 4", "sin(pi/2)", "sqrt(16)")

### Response Format

Successful responses return:

```json
{
  "data": [
    {
      "expression": "2 + 3 * 4",
      "result": 14,
      "steps": "2 + (3 * 4) = 2 + 12 = 14",
      "type": "arithmetic"
    }
  ]
}
```

Error responses return:

```json
{
  "data": ["❌ Error: Invalid mathematical expression"]
}
```

### Example MCP Request

```bash
curl -X POST https://[space-url]/gradio_api/mcp/sse \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      "sqrt(144) + log(100) + sin(pi/6)"
    ]
  }'
```

### Integration Examples

#### Python Integration

```python
import requests

def call_mcp_calculator(expression):
    url = "https://[space-url]/gradio_api/mcp/sse"
    payload = {"data": [expression]}
    
    response = requests.post(url, json=payload)
    if response.status_code == 200:
        result = response.json()
        return result["data"][0]
    else:
        return f"Error: {response.status_code}"

# Example usage
result = call_mcp_calculator("2^8 + sqrt(81)")
print(f"Result: {result}")
```

#### Claude/AI Assistant Integration

When integrating with Claude or other AI assistants supporting MCP:

1. Configure the MCP client to point to this Space's `/gradio_api/mcp/sse` endpoint
2. Use the tool in conversations: "Calculate the area of a circle with radius 5"
3. The AI assistant will automatically format mathematical expressions

## 🛠️ Technical Details

### Supported Functions

- **Arithmetic**: `+`, `-`, `*`, `/`, `**` (power), `%` (modulo)
- **Trigonometry**: `sin()`, `cos()`, `tan()`, `asin()`, `acos()`, `atan()`
- **Logarithmic**: `log()`, `log10()`, `ln()`, `exp()`
- **Root Functions**: `sqrt()`, `cbrt()`, `nthroot()`
- **Statistical**: `mean()`, `median()`, `stdev()`, `variance()`
- **Constants**: `pi`, `e`, `tau`, `phi` (golden ratio)

### Input Validation

- **Expression parsing**: Safe evaluation of mathematical expressions
- **Error handling**: Comprehensive error messages for invalid inputs
- **Security**: Protected against code injection and unsafe operations
- **Precision**: High-precision decimal arithmetic for accurate results

### API Configuration

- **Timeout**: 30 seconds
- **Rate Limiting**: Standard Gradio Space limits
- **Memory Usage**: Optimized for complex calculations
- **Error Recovery**: Graceful handling of mathematical errors

## 🏆 Hackathon Submission

This tool is submitted for the **MCP Server Track** of the hackathon, demonstrating:

- ✅ **MCP Protocol Compliance**: Full implementation of MCP server specification
- ✅ **Production Ready**: Robust mathematical computation and error handling
- ✅ **User Experience**: Intuitive calculator interface with step-by-step solutions
- ✅ **Documentation**: Comprehensive API documentation and examples
- ✅ **Integration Ready**: Easy to integrate with AI assistants and applications

## 🎯 Use Cases for AI Assistants

When integrated with AI assistants via MCP, this tool enables:

1. **Mathematical Problem Solving**: "Calculate the compound interest for..."
2. **Scientific Calculations**: "Compute the trajectory using physics formulas"
3. **Statistical Analysis**: "Find the mean and standard deviation of these values"
4. **Engineering Calculations**: "Calculate the load capacity using these parameters"
5. **Educational Support**: "Solve this trigonometry problem step by step"

## 🔧 Local Development

### Prerequisites

- Python 3.11+
- Math libraries (numpy, scipy for advanced functions)

### Installation

```bash
# Clone this repository
git clone [repository-url]
cd mcp_math_tool_gradio

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py
```

### Testing MCP Endpoint Locally

```bash
# Test with curl
curl -X POST http://localhost:7860/gradio_api/mcp/sse \
  -H "Content-Type: application/json" \
  -d '{"data": ["(5^2 + 3^2)^0.5"]}'
```

## 📊 Performance & Limitations

### Strengths
- High-precision mathematical computation
- Wide range of supported functions
- Fast calculation processing
- MCP protocol compliance
- Step-by-step solution breakdown

### Limitations
- Limited to mathematical expressions (no symbolic algebra)
- Large number computations may timeout
- Complex statistical functions require proper input format
- Precision limited by floating-point arithmetic

## 📝 License

MIT License - Feel free to use and modify for your projects.

## 🤝 Contributing

This is a hackathon submission, but feedback and suggestions are welcome! Feel free to:

- Test complex mathematical expressions
- Try statistical functions with your data
- Report any calculation errors or edge cases
- Suggest additional mathematical functions

## 🏷️ Tags

`#mcp-server-track` `#mathematics` `#calculator` `#computation` `#gradio` `#ai-assistant` `#model-context-protocol`

---

**Built with ❤️ for the MCP Hackathon**