rubensgomes-org/math-ai-agent：基于 calculator_mcp 的算术智能体 Web 应用

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 as built-in tools (for example, web search and file search) and function 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_CONFIG for calculator-mcp running locally

export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_local.yaml"

Launch calculator-mcp locally 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_CONFIG for calculator-mcp running remotely

export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_remote.yaml"

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. If Ctrl+C does 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.

Important

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

Author: Rubens Gomes