Mango Client: a ReAct agent that runs Julia reservoir simulations and retrieval over your documents

What Mango Client is aimed at

Mango Client is a geothermal analytics agent. The pitch in the README is short: ask it questions, hand it documents, and have it run real reservoir simulations, all from one chat window. What sits behind that chat window is not a language model with a prompt wrapped around it. There is a Next.js front end, a FastAPI backend running a ReAct-style loop, and two Model Context Protocol tool servers behind the loop. One drives an actual Julia reservoir simulator, Fimbul.jl, for geothermal cases such as ATES, EGS and doublets. The other runs hybrid retrieval over a LanceDB knowledge base built from the documents you upload. The intended reader is somebody doing geothermal work who already has documents and cases and does not want to hand-translate a question into a simulation script.

Two MCP servers, and why they are separate processes

The two tool servers are deliberately separate processes, and the README gives the reason in architectural terms: the model is an orchestration and reasoning layer, and domain capability is exposed through tool interfaces rather than embedded in that layer. The simulator side is fimbul_server.py, an MCP server over stdio that talks to fimbul_sim.jl, which runs as a persistent Julia subprocess. Retrieval is rag_server.py, also MCP over stdio, which calls ingest.py as a fresh subprocess per file. That difference in process model is not decoration. A reservoir simulation is long-lived and expensive to start, so it is kept alive, while document ingestion is a per-file job with heavy dependencies, so it is spawned and discarded. The README states the retrieval server's dependencies, Docling, transformers and pix2tex, are kept out of the main environment on purpose.

How a request travels through the stack

A request travels through four layers. The client is Next.js using useChat, and it receives server-sent events typed as metadata, thought, token, error and done, so the interface can show the agent reasoning separately from its final answer. Those events come from src/term.py, a FastAPI app holding the ReAct loop. The loop may reason about the problem, invoke one or more tools, observe the outputs and refine its response, which the README describes as decomposing complex analytical tasks into a sequence of explicit computational operations instead of compressing them into a single model call. The full request lifecycle and a sequence diagram live in arch.md, and examples/sim.md shows what each simulation case's output looks like.

Installing it across three runtimes

The install is spread across three runtimes, which is the main cost of adopting this. You need Python 3.11 or newer for the backend and the simulator, a separate Python 3.13 environment for rag_server, Julia installed through juliaup, and Node.js with pnpm for the front end.

pip install .

Create a .env file at the repository root. The README lists three variables as the minimum, and points at src/config.py for every setting and its default.

OPENAI_API_KEY=...
LLM_MODEL=YOUR_MODEL_NAME
WEB_SEARCH_API_KEY=...

The Julia side is a one-time step. This script clones Fimbul.jl into packages/, dev-links it into the julia/ project and precompiles it, and later edits to packages/Fimbul.jl are picked up on the next run.

./fimbul.bash

The retrieval server gets its own virtual environment because of those heavy dependencies.

cd src/server/rag_server
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Then the front end, whose env file needs at minimum MANGO_CLIENT_API_URL, which defaults to http://localhost:8000, AUTH_SECRET and POSTGRES_URL.

cd client
pnpm install
cp .env.example .env.local

Running it takes two terminals. The backend also spawns fimbul_server and rag_server as MCP subprocesses.

cd src
python -m uvicorn term:app --host 127.0.0.1 --port 8000

cd client
pnpm dev

Open http://localhost:3000 for the chat interface. The backend health check is at http://localhost:8000/mango_client/health, which is the first thing to hit when the agent answers with nothing.

What a simulation answer comes back with

The examples directory is the clearest statement of scope, because it is a list of the cases the simulator has been pointed at. Alongside examples/sim.md, there are curve images for ags, analytical_1d, ates, ates_simple, btes, coaxial_bhe, doublet, egg_ates, egg_geothermal, egg_geothermal_doublet, egs and ftes. The README names ATES, EGS and doublets explicitly and adds "and more". Charts come from Plotly, and the 3D site map, whose preview image shows the Utah FORGE site, uses CesiumJS. So the output of a question is not only prose: it is meant to come back with curves and a spatial context.

The setup surface is the real cost

The honest limitation is the setup surface. Three language runtimes, two Python environments with a hard version split, a Julia package that gets cloned and precompiled, and a Postgres URL in the front end config is a lot of machinery before the first answer, and the README does not document memory or runtime requirements for a simulation, so you will be finding those out yourself. The project also has exactly one release, v1.0.0 published on 2026-08-09 with empty release notes, and the last push was on 2026-08-10, so there is no release history to read for signal about stability. The pyproject pins one dependency to an exact version, mcp==1.27.1, while everything else is a minimum range, which means a change in the MCP protocol needs a manual bump here.

Writing JutulDarcy scripts yourself is the alternative

The alternative is to skip the agent and work with JutulDarcy.jl directly, which is the same reservoir simulation library Fimbul.jl is built on. Writing your own Julia scripts gives you full control over the case setup, reproducibility you can commit, and no language model between your question and the numbers. What it does not give you is the retrieval layer over your documents, the conversational interface, or a fixed tool contract the model has to use. Mango Client is the opposite bet: it accepts an orchestration layer it does not fully control in exchange for not having to write a script per question. If your cases are few and well defined, scripts win. If your questions arrive in natural language and reference a pile of PDFs, the agent is the point.

Licence, provenance and dependencies

Mango Client is MIT licensed, but the repository is assembled from parts with their own provenance, and the acknowledgements section names them. The chat front end is adapted from Vercel's ai-chatbot template. Simulation is powered by SINTEF's Fimbul.jl, built on JutulDarcy.jl. The UI layout is adapted from the GAIA work of Harsuko, Bi, Chen and Nakata (2026), which the README cites with a Zenodo DOI. Tool orchestration follows the Model Context Protocol specification. The backend dependencies are conventional for this kind of service: FastAPI with uvicorn, pydantic, the openai SDK, httpx, duckdb, numpy, pandas and both plotly and matplotlib, with ruff in the dev group and hatchling as the build backend.

Editorial conclusion

Pick Mango Client if your geothermal questions arrive in natural language, reference documents you already have, and end in a reservoir case you would otherwise script by hand, because that is exactly the gap the ReAct loop and the two MCP servers fill. Do not pick it if you want repeatable, reviewable case definitions, since a model decides which tool runs and the README does not document how to pin that behaviour. Before committing, budget for the setup: Python 3.11 or newer, a separate Python 3.13 environment for the retrieval server, Julia through juliaup, Node.js with pnpm, and a Postgres URL for the front end.

Frequently asked questions

Official sources

1. Issues
2. Jokerwoo780/Mango_Client on GitHub
3. License: MIT
4. README
5. Releases