Ananyamorab/Math_Agent

Math Agent with MCP Server Integration

🎯 Overview

This project creates a Math Agent that uses Groq AI for understanding mathematical problems and real MCP server tools for performing calculations. The agent never uses internal LLM reasoning for mathematical operations - it always delegates to external MCP tools.

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   User Input    │ -> │   Groq AI       │ -> │  MCP Tools      │
│  Math Question  │    │   Analysis      │    │  (External)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │                       │
                              v                       v
                       Parse Problem            Execute Calculation
                       Extract Numbers         Return Precise Result
                       Identify Operations

📁 Project Structure

MathAgent/
├── math_agent.py         # Main agent with Groq AI integration
├── math_functions.py     # Mathematical functions (external tools)
├── main.py              # MCP server
├── .env                 # API keys (GROQ_API_KEY)
├── pyproject.toml       # Dependencies
└── README.md           # This file

🔧 Key Components

1. Math Agent (math_agent.py)

• Uses Groq AI to analyze mathematical problems
• Extracts operations and numbers from natural language
• Delegates calculations to real MCP server tools
• Returns error if MCP tools unavailable (no fallback)

2. Math Functions (math_functions.py)

• Pure mathematical functions that can be imported directly
• No server startup when imported
• Used by both MCP server and direct agent integration

3. MCP Server (main.py)

• FastMCP server exposing mathematical tools
• Can run standalone for external connections
• Provides 15 mathematical operations as MCP tools

🚀 Quick Start

1. Install Dependencies

pip install groq python-dotenv pydantic-ai fastmcp

2. Setup API Key

Create .env file:

GROQ_API_KEY=your_groq_api_key_here

3. Run Interactive Agent

python3 math_agent.py

4. Run MCP Server (Optional)

python3 main.py

📊 Available Mathematical Tools

🎮 Usage Examples

Interactive Mode

$ python3 math_agent.py

🧮 Math Agent - Production Mode
==================================================
I solve mathematical problems using external MCP tools.
Requires: math_functions.py for calculations

� Enter your math question: What is 156 + 244?
🎯 Solution: Using real MCP server tool 'add': 156 + 244 = 400

📝 Enter your math question: Calculate the square root of 625  
🎯 Solution: Using real MCP server tool 'square_root': √625 = 25.0

Programmatic Usage

from math_agent import MathAgent
import asyncio

async def solve_problem():
    agent = MathAgent()
    result = await agent.solve_math_problem("What is 7 factorial?")
    print(result)  # "Using real MCP server tool 'factorial': 7! = 5040"

asyncio.run(solve_problem())

🔍 How It Works

1. User asks a math question (natural language)
2. Groq AI analyzes the problem and extracts:
   • Required mathematical operations
   • Numbers involved
   • Solution approach
3. Agent uses real MCP tools:
   • Imports functions from math_functions.py
   • Executes calculations with external tools
   • Returns precise numerical results
4. Error handling if MCP tools unavailable (no simulation)

✅ Production Features

The system ensures external tool usage by:

• No fallback simulations - only real tool calls
• Never performing calculations in LLM context
• Always delegating to imported mathematical functions
• Clear error messages when tools unavailable
• Logging which tools are used for each operation

🎯 Key Benefits

• 🔒 Reliable: No LLM calculation errors
• 🎯 Precise: Uses real mathematical functions
• 🔧 External: All calculations via MCP tools
• 🧠 Smart: Natural language understanding via Groq AI
• ⚡ Fast: Direct function calls for calculations
• 🛡️ Safe: Proper error handling and validation
• 🏭 Production: No mock code or fallbacks

Production Math Agent using Groq AI + Real MCP Tools with MCP Tools

A sophisticated Math Agent that uses external Model Context Protocol (MCP) tools for all mathematical calculations instead of relying on LLM's internal reasoning. This ensures accurate calculations and provides transparency in the problem-solving process.

🎯 Project Overview

This project implements a Math Agent that:

• ✅ Uses external MCP tools for ALL mathematical operations
• ✅ Never relies on LLM internal calculations
• ✅ Provides step-by-step explanations
• ✅ Uses Groq API for fast and efficient LLM operations
• ✅ Supports interactive problem-solving sessions
• ✅ Includes comprehensive logging for debugging

🛠️ Architecture

Student Query → Math Agent → MCP Client → MCP Server (Tools) → Results → Student
                    ↓
              Standard Logging

Components

1. MCP Server (main.py) - Provides mathematical tools
2. Math Agent (math_agent.py) - Orchestrates problem solving using Groq API
3. MCP Client - Connects agent to tools
4. Standard Logging - Basic logging for debugging and monitoring

🧮 Available Mathematical Tools

Basic Operations

• add(a, b) - Addition
• subtract(a, b) - Subtraction
• multiply(a, b) - Multiplication
• divide(a, b) - Division
• modulus(a, b) - Modulus/Remainder

Advanced Operations

• power(a, b) - Exponentiation (a^b)
• square_root(a) - Square root
• log(a, base) - Logarithm with custom base
• factorial(n) - Factorial
• absolute_value(a) - Absolute value

Trigonometric Functions

• sin(a) - Sine (radians)
• cos(a) - Cosine (radians)
• tan(a) - Tangent (radians)
• degrees_to_radians(degrees) - Convert degrees to radians
• radians_to_degrees(radians) - Convert radians to degrees

🚀 Quick Start

1. Setup Environment

# Run setup script
python setup.py

# Or manual installation
pip install -e .

2. Configure Environment Variables

Edit .env file:

# Preferred: Groq API Key (fast and efficient)
GROQ_API_KEY=your_groq_api_key_here

# Fallback: OpenAI API Key
OPENAI_API_KEY=your_openai_api_key_here

3. Start MCP Server

# Terminal 1: Start the MCP server
python main.py

4. Run Math Agent

# Terminal 2: Run the interactive agent
python math_agent.py

# Or run examples
python examples.py

💡 Usage Examples

Interactive Mode

📝 Enter your math problem: What is 25 + 17?

🤔 Thinking...

✅ Solution:
I'll help you add 25 and 17 using the external addition tool.

Let me use the 'add' tool to calculate this:
- Adding 25 + 17 = 42

The answer is 42.

Complex Problems

📝 Enter your math problem: Calculate the area of a circle with radius 5

🤔 Thinking...

✅ Solution:
I'll calculate the area of a circle with radius 5 using the formula A = π × r².

Step 1: Calculate r² (radius squared)
Using the 'power' tool: 5² = 25

Step 2: Calculate π × r²
Using the 'multiply' tool: 3.14159 × 25 = 78.54

The area of the circle is approximately 78.54 square units.

🔍 Monitoring and Logging

The agent includes basic logging capabilities:

Operation Logging

• Mathematical operations performed
• Execution time tracking
• Error monitoring
• Basic performance insights

Setup Logging

The agent uses Python's standard logging module for monitoring operations and debugging. All logs are output to the console by default.

📁 Project Structure

MathAgent/
├── main.py              # MCP Server with math tools
├── math_agent.py        # Main Math Agent implementation
├── examples.py          # Example usage and demonstrations
├── setup.py             # Environment setup script
├── logfire_config.py    # Logfire monitoring configuration
├── pyproject.toml       # Project dependencies
├── README.md            # This file
├── .env                 # Environment variables (create from template)
└── logs/                # Log files directory

🔧 Advanced Configuration

Custom Model Selection

# Use different Groq models (recommended)
agent = MathAgent(model_name="llama3-8b-8192")      # Fast and efficient
agent = MathAgent(model_name="llama3-70b-8192")     # More capable  
agent = MathAgent(model_name="mixtral-8x7b-32768")  # Alternative option

# OpenAI models (fallback)
agent = MathAgent(model_name="gpt-3.5-turbo")       # If using OpenAI

Custom MCP Server Path

# Use custom MCP server
await agent.setup_mcp_client("/path/to/custom/server.py")

🚨 Key Features

1. No Internal LLM Calculations

The agent is designed with strict rules to prevent the LLM from performing any mathematical calculations internally. All math operations must use external tools.

2. Step-by-Step Solutions

Complex problems are broken down into smaller steps, each using appropriate tools, making the solution process transparent and educational.

3. Error Handling

Robust error handling for edge cases like division by zero, negative square roots, etc.

4. Performance Monitoring

Comprehensive logging and monitoring to track performance and optimize token usage.

5. Educational Focus

Designed specifically for helping students understand mathematical problem-solving processes.

🧪 Testing

Run the test examples:

python examples.py

Test specific scenarios:

from math_agent import MathAgent

async def test_agent():
    agent = MathAgent()
    await agent.setup_mcp_client()
    agent.create_agent()
    
    result = await agent.solve_math_problem("What is 15 × 23?")
    print(result)

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add new mathematical tools to main.py
4. Update documentation
5. Submit a pull request

📋 TODO

• Add more advanced mathematical functions
• Implement graph plotting capabilities
• Add support for symbolic mathematics
• Create web interface
• Add unit tests
• Performance benchmarking

🆘 Troubleshooting

Common Issues

1. MCP Connection Failed

   • Ensure main.py is running
   • Check file paths are correct
   • Verify Python environment

2. API Key Issues

   • Set GROQ_API_KEY in .env file (recommended)
   • Or set OPENAI_API_KEY as fallback
   • Check API key validity

3. Import Errors

   • Run python setup.py
   • Check Python version (3.8+)
   • Verify all dependencies installed

📄 License

This project is created for educational purposes. Please respect OpenAI's and Groq's usage policies and terms of service.

git clone https://github.com/ArjunKrish7356/MathAgent.git

2. Create an MCP server wrapper in your agent code (the name can be any unique id; args are the command used to start the server process):

from pydantic_ai.mcp import MCPServerStdio

mcp_server = MCPServerStdio(
    'uv'
    args=[
        "run",
        "MathAgent/main.py"
    ]
)

3. Register the MCP server with your Agent:

from pydantic_ai import Agent

agent = Agent(model="openai:gpt-4o", toolsets=[mcp_server])

Notes:

• Ensure the MathAgent/main.py path is correct relative to where the agent runs and that the script is runnable.
• The Stdio transport will spawn the configured process using the provided args; verify any required environment or dependencies are installed before launching.
• Test the connection locally before deploying.

More Resources

• Official MCP documentation: https://modelcontextprotocol.io/docs/getting-started/intro
• Introductory video on MCP: https://www.youtube.com/watch?v=N3vHJcHBS-w

Contributing

Thank you for your interest! Contributions are welcome—feel free to open issues or submit pull requests.