mcp3

Building Calculon: Enforcing LLM Precision with the Modular Calculation Protocol (MCP)

Large Language Models (LLMs) are phenomenal at reasoning and language generation, but they notoriously struggle with complex, precise arithmetic. The goal of the Calculon project was to architect a system where the AI is intentionally and strictly forbidden from performing its own calculations. Instead, it is forced to delegate all arithmetic tasks to a highly reliable, external tool, demonstrating secure, verifiable, and transparent tool usage in a real-time streaming environment.

Architectural Design

Calculon employs a three-part architecture orchestrated primarily by Python:

1. Tool Server (FastMCP/MCP): A dedicated, independent Python server exposes basic arithmetic functions (`add`, `subtract`, `multiply`, `divide`) via the Modular Calculation Protocol (MCP). Running this service separately ensures robustness and strict computation integrity.
2. API/Relay Server (FastAPI): This Python backend handles the core logic. It manages WebSocket connections from the frontend and acts as the crucial intermediary, feeding user prompts to the Gemini client and routing tool calls to the MCP server.
3. Frontend (Vanilla JS/HTML): A clean, dependency-free chat interface connects via WebSockets. It is responsible for dynamically parsing and displaying the streamed responses, differentiating between normal text, internal AI thoughts, and explicit tool interactions.

The Power of Enforced Tool Orchestration

The core innovation lies in the integration of the MCP library with the Gemini API. In backend/mcp_client_logic.py, we initialize the Gemini client, passing the MCP ClientSession directly into the `GenerateContentConfig` as a tool. A detailed system instruction is applied, creating the personality "Calculon," who is explicitly commanded to break down complex expressions using PEMDAS/BODMAS and **MUST** delegate every single arithmetic step to the provided calculator tools.

When a user asks a math question, the transaction follows this strict, delegated flow:

1. Gemini streams its *thought* (e.g., "I must first calculate the value inside the parentheses...").
2. Gemini generates a *function_call* object (e.g., `add(a=5, b=3)`).
3. The FastAPI backend intercepts this call and routes it via the MCP client session to the separate MCP server.
4. The MCP server executes the precise calculation and returns the result.
5. The result is streamed back to Gemini as a *function_response*.
6. Gemini uses the tool result (e.g., 8) to stream the next thought and tool call, repeating the process until the final answer is obtained.

Real-time Transparency via WebSockets

To provide a highly transparent user experience, we implemented real-time, chunked streaming using WebSockets (`/ws/chat`). The `process_user_message_stream` function asynchronously iterates over the Gemini stream. As it receives chunks (whether they are text, thoughts, or tool events), it serializes them into distinct JSON payloads (`text_chunk`, `thought`, `tool_call`, `tool_response`) and sends them instantly to the client. The Vanilla JavaScript frontend (static/js/app.js) dynamically handles these different message types, creating visually distinct message bubbles for internal thoughts and tool usage, greatly enhancing user trust and insight into the LLM's decision-making process.

Conclusion

Calculon serves as a strong demonstration of how modern LLMs should be integrated into precision-required systems. By leveraging the Modular Calculation Protocol, FastAPI, and asynchronous streaming, we successfully decoupled reasoning from computation, resulting in a powerful, entertaining, and verifiably accurate AI assistant.