Math AI Agent
A prompt chat webapp that drives an LLM call inside an agentic loop using
the calculator_mcp MCP server for arithmetic operations. The key constraint is
that the LLM is given explicit system instructions to use calculator_mcp for
any arithmetic operations.
Features
- FastAPI web UI — simple form-based interface for submitting prompts
- MCP client — connects to a remote calculator MCP server with optional OAuth authentication
- Configurable — MCP server URL, OAuth settings, LLM endpoint and model,
and logging are all driven by
config.yaml - Plain-text answers — the model is instructed to reply without LaTeX or
Markdown, since the web UI renders answers in a plain
<textarea>
Unsupported Features
- Server-sent events (SSE) are not supported for either LLM or MCP communication.
- Streaming communication channels, such as Streamable HTTP, are not supported. In other words, both the LLM model and the MCP server are expected to generate the entire output before sending it.
- Stateful Responses API communication may not be supported, depending on the LLM model selected in the configuration.
- Input types such as images and videos are not supported. Only text input is supported.
- Tools available to the LLM are limited to
calculator_mcp. Other tool types, such asbuilt-in tools(for example, web search and file search) andfunction calls, are not supported.
Bear in mind that support for the features listed above also depends on the capabilities of the selected LLM model. For example, the default configured model, NVIDIA Nemotron 3 Super, does not support storing conversation history and supports only text input.
AI Disclaimer
This project includes code and documentation created with the assistance of AI tools. For details on usage, limits, and review practices, please see the AI Disclaimer.
Prerequisites
- Python 3.14+
- pip
Installation
- Install using
pip
pip install math-ai-agent
- Confirm the installed version matches the latest GitHub release at math-ai-agent/releases
math-ai-agent --version
pip show math-ai-agent
Uninstall
pip uninstall math-ai-agent
pip cache purge
Configuration
calculator-mcp Running Locally
-
Copy the file config_local.yaml to
${HOME}/cfg/math-ai-agent/config_local.yaml -
Set
MATHAIAGENT_CONFIGforcalculator-mcprunning locally
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_local.yaml"
- Launch
calculator-mcplocally following the instructions at calculator-mcp
calculator-mcp Running Remotely
Note: This requires OAuth authentication using a GitHub account. Currently, only the project author is authorized.
-
Copy the file config_remote.yaml to
${HOME}/cfg/math-ai-agent/config_remote.yaml -
Set
MATHAIAGENT_CONFIGforcalculator-mcprunning remotely
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_remote.yaml"
Overriding the calculator-mcp URL
A non-empty CALCULATOR_MCP_URL overrides server.calculator_mcp.url.
Usage
- Simply run
math-ai-agent
- Health check
curl -v http://localhost:9090/health
# Expect: OK
- To stop, go to the running terminal and press
Ctrl+C. IfCtrl+Cdoes not work you can try the following:
PID="$(pgrep -f math-ai-agent)"
kill -15 "${PID}"
Open Source Project Information
This project is open source and publicly hosted on GitHub at rubensgomes-org. It is published under an OSI-approved open-source license.
Note: Public availability and the use of an OSI-approved license are requirements for eligibility to use SonarQube Cloud under its free plan for open-source projects.
License
The project is licensed under the MIT License.
Links
- GitHub Project
- Agent, LLM, MCP Diagram
- Class Diagram
- Development Setup
- Docker
- LangChain Notes
- LLM Models
- LLM Tool Calls and the MCP Server
- MCP Client Sequence Diagram
- OAuth Authentication Diagram
- Ollama LLM Models
- PyCharm
- Python Coroutines
- Python Execution
- Release Process
- Tests
Author: Rubens Gomes
1 maintainer
Metadata
1 maintainer
Release files for math-ai-agent 0.0.30
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| math_ai_agent-0.0.30.tar.gz | 26.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| math_ai_agent-0.0.30-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 69.9 kB
Release files / math_ai_agent-0.0.30.tar.gz
| Download URL | math_ai_agent-0.0.30.tar.gz |
|---|---|
| Size | 26.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d8ad2317eda2c47f91b95081bd7e46ad1bc1199db91f84ff4d8bccf733076494
|
|
BLAKE2b-256 checksum How to use checksums |
2b1cf0704cf4fbd9e38861ed52451b0a1aadb21f405d2bb2ac2bb3d6d90a5502
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.3 CPython/3.14.7 Linux/6.17.0-1022-azure
|
Release files / math_ai_agent-0.0.30-py3-none-any.whl
| Download URL | math_ai_agent-0.0.30-py3-none-any.whl |
|---|---|
| Size | 43.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d4f69c54891cea7ae8bdf97f2c985f55bf4b125078d12aa0735f34ebc98b25ed
|
|
BLAKE2b-256 checksum How to use checksums |
05ed03571f3bec5ba99c909bf5a642d0445b1f4e0c3c15bc39b0682e985a320d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.3 CPython/3.14.7 Linux/6.17.0-1022-azure
|
