Math Agent (math-agent)

与MCP服务器集成的数学代理

🎯 概述

此项目创建了一个 数学代理 使用 希腊 AI 为了理解数学问题和 真正的MCP服务器工具 用于执行计算。代理从不使用内部LLM推理进行数学运算，它总是委托给外部MCP工具。

🏗️ 建筑

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

📁 项目结构

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

🔧 关键组件

1. 数学代理(math_agent.py)

• 使用Groq AI分析数学问题
• 从自然语言中提取运算和数字
• 将计算委托给真实的MCP服务器工具
• 如果MCP工具不可用，则返回错误（无回退）

2. 数学函数(math_functions.py)

• 可以直接导入的纯数学函数
• 导入时不启动服务器
• MCP服务器和直接代理集成都使用

3. MCP服务器(main.py)

• FastMCP服务器公开数学工具
• 可以独立运行以进行外部连接
• 提供15个数学运算作为MCP工具

🚀 快速开始

1.安装依赖项

pip install groq python-dotenv pydantic-ai fastmcp

2.设置API密钥

创建 .env 文件：

GROQ_API_KEY=your_groq_api_key_here

3.运行交互式代理

python3 math_agent.py

4.运行MCP服务器（可选）

python3 main.py

📊 可用的数学工具

🎮 使用示例

交互模式

$ 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

程序化使用

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())

🔍 运作原理

1. 用户提出一个数学问题 （自然语言）
2. Groq AI分析 问题和摘录：

- 所需的数学运算 - 涉及的数字 - 解决方案方法

1. Agent使用真正的MCP工具:

- 从导入函数 math_functions.py - 使用外部工具执行计算 - 返回精确的数值结果

1. 错误处理 如果MCP工具不可用（无模拟）

✅ 生产特点

该系统通过以下方式确保外部工具的使用：

• 无回退模拟 -只有真正的工具调用
• 从不在LLM环境中执行计算
• 始终委托给导入的数学函数
• 工具不可用时清除错误消息
• 记录每次操作使用的工具

🎯 关键利益

• 🔒 可靠的：无LLM计算错误
• 🎯 精确：使用实数数学函数
• 🔧 外部：所有计算均通过MCP工具进行
• 🧠 聪明的：通过Groq AI进行自然语言理解
• ⚡ 快速：直接函数调用进行计算
• 🛡️ Safe：正确的错误处理和验证
• 🏭 生产：没有模拟代码或回退

______________________________________________________________________

使用Groq AI+Real MCP工具制作数学代理 使用MCP工具

一个复杂的数学代理，它使用外部模型上下文协议（MCP）工具进行所有数学计算，而不是依赖LLM的内部推理。这确保了精确的计算，并在解决问题的过程中提供了透明度。

🎯 项目概述

此项目实现了一个数学代理，该代理：

• ✅ 使用外部MCP工具进行所有数学运算
• ✅ 从不依赖LLM内部计算
• ✅ 提供分步说明
• ✅ 使用Groq API实现快速高效的LLM操作
• ✅ 支持交互式问题解决会话
• ✅ 包括用于调试的全面日志记录

🛠️ 建筑

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

组件

1. MCP服务器 (main.py)-提供数学工具
2. 数学代理 (math_agent.py)-使用Groq API协调解决问题
3. MCP客户端 -将代理连接到工具
4. 标准测井 -调试和监控的基本日志记录

🧮 可用的数学工具

基本操作

• add(a, b) -补充
• subtract(a, b) -减法
• multiply(a, b) -乘法
• divide(a, b) -分部
• modulus(a, b) -模量/剩余量

高级操作

• power(a, b) -指数（a^b）
• square_root(a) -平方根
• log(a, base) -自定义基数的对数
• factorial(n) -保理
• absolute_value(a) -绝对值

三角函数

• sin(a) -正弦（弧度）
• cos(a) -余弦（弧度）
• tan(a) -切线（弧度）
• degrees_to_radians(degrees) -将度数转换为弧度
• radians_to_degrees(radians) -将弧度转换为度数

🚀 快速开始

1.设置环境

# Run setup script
python setup.py

# Or manual installation
pip install -e .

2.配置环境变量

编辑 .env 文件：

# 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.启动MCP服务器

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

4.运行Math Agent

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

# Or run examples
python examples.py

💡 使用示例

交互模式

📝 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.

复杂问题

📝 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.

🔍 监控和日志记录

该代理包括基本的日志记录功能：

操作日志

• 执行的数学运算
• 执行时间跟踪
• 误差监控
• 基本性能见解

安装日志记录

该代理使用Python的标准日志模块来监控操作和调试。默认情况下，所有日志都会输出到控制台。

📁 项目结构

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

🔧 高级配置

自定义模型选择

# 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

自定义MCP服务器路径

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

🚨 主要特点

1. 无内部LLM计算

该代理的设计有严格的规则，以防止LLM在内部执行任何数学计算。所有数学运算都必须使用外部工具。

2. 分步解决方案

复杂的问题被分解为更小的步骤，每个步骤都使用适当的工具，使解决方案过程透明且具有教育意义。

3. 错误处理

针对除零、负平方根等边缘情况的稳健错误处理。

4. 性能监控

全面的日志记录和监控，以跟踪性能并优化令牌使用。

5. 教育重点

专为帮助学生理解数学问题解决过程而设计。

🧪 测试

运行测试示例：

python examples.py

测试特定场景：

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)

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 添加新的数学工具 main.py
4. 更新文档
5. 提交拉取请求

📋 全部

• \[\]添加更高级的数学函数
• \[\]实现图形绘制功能
• \[\]添加对符号数学的支持
• \[\]创建web界面
• \[\]添加单元测试
• \[\]性能基准测试

🆘 故障排除

常见问题

1. MCP连接失败

- 确保 main.py 正在运行 - 检查文件路径是否正确 - 验证Python环境

1. API关键问题

- 集 GROQ_API_KEY 在……里面 .env 文件（推荐） - 或设置 OPENAI_API_KEY 作为后备 - 检查API密钥的有效性

1. 导入错误

- 跑 python setup.py - 检查Python版本（3.8+） - 验证已安装的所有依赖项

📄 许可证

这个项目是为了教育目的而创建的。请尊重OpenAI和Groq的使用政策和服务条款。

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

1. 在代理代码中创建MCP服务器包装器（ name 可以是任何唯一的id； args 是用于启动服务器进程的命令）：

from pydantic_ai.mcp import MCPServerStdio

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

1. 向您的代理注册MCP服务器：

from pydantic_ai import Agent

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

笔记：

• 确保 MathAgent/main.py 路径相对于代理运行的位置是正确的，并且脚本是可运行的。
• Stdio传输将使用提供的 args；在启动之前，请验证是否安装了任何所需的环境或依赖项。
• 部署前在本地测试连接。

更多资源

• MCP官方文件：https://modelcontextprotocol.io/docs/getting-started/intro
• MCP介绍视频：https://www.youtube.com/watch?v=N3vHJcHBSw

贡献

感谢您的关注！欢迎投稿——欢迎打开问题或提交pull请求。