Dam Levels Data, Ontology and MCP Server

What it is

DamLevels-Data reconstructs the daily state of Tunisia’s 36 large dams from the bulletins Situation des barrages that the Direction Générale des Barrages et des Grands Travaux Hydrauliques (DGBGTH) publishes through the Observatoire National de l’Agriculture (ONAGRI) (onagri.nat.tn). The bulletins are public but only exist as three-page PDFs whose layout changed over the years. The archive covers 2 July 2014 to 10 October 2025: 3,985 bulletin dates, 11,927 PDF pages and 129,390 daily storage values, each traced to the file, page, column and printed characters it was read from. On 10 October 2025, the last date of the archive, the 36 dams held 649.3 million m³, 27.4% of their capacity, and 18 of them were less than a quarter full; on the same day in 2019, the 33 dams then printed held 1,392.8 million m³.

It ships as an open package — tables, provenance, quality indicators, GIS layers and the DamLevels Ontology (DLO 0.3) — and as a read-only MCP server through which an AI assistant can answer questions from the archive. This is an independent, unofficial project, not affiliated with or endorsed by the DGBGTH, ONAGRI or the Ministry of Agriculture.

From a PDF bulletin to an AI assistant

The work follows the five-star open data model, from a document on the web towards linked data, and adds one step on top: an MCP server that AI assistants can query.

How it works

Deterministic engines read the PDF text layer and the drawn table lines — no OCR, no manual retyping — so the same file always gives the same values. Dam names, printed in French and Arabic with varying spellings, are mapped to stable identifiers (dam_id). Missing values stay missing: nothing is interpolated, forward-filled or set to zero. The ontology writes down what each printed column really means and which day it describes: flows printed on the bulletin of day D cover day D−1, and one of the two “release of the day” columns is in fact the release one year earlier.

The MCP server exposes ten read-only tools — find_dam, list_dams, get_storage, get_fill, national_storage, compare_years, get_source, get_transfers, describe_variable and dataset_info. It refuses dates outside the record and malformed input with an explicit error rather than an empty answer, uses the capacity in force on each date, marks Page 3 transfers as PROBABLE, returns every candidate when a name or a term is ambiguous, and attaches its coverage, the source attribution and its caveats to every answer.

Use cases

• Hydrology and climate research — compare a dam’s storage on the same calendar day across eleven years, with missing days reported as missing.
• Journalism — check a figure quoted in the press against the bulletin it came from, down to the page, the column and the printed characters.
• Public policy — follow the national reserve: 649 million m³, 27% of capacity, on 10 October 2025, with 18 of 36 dams below a quarter full.

Demo — illustrative example

{
"dam": { "dam_id": "sidisalem", "name_fr": "Sidi Salem" },
"date": "2025-10-10",
"storage_mm3": 137.196,
"capacity": { "status": "KNOWN", "capacity_mm3": 580.35 },
"fill_pct": 23.6, "printed_fill_pct": 23.6,
"source": {
  "source_file": "10-10-2025_1.pdf", "page": "1",
  "printed_text": "137,196",
  "bulletin_url": "https://www.onagri.nat.tn/uploads/barrages/BARRAGES-10-10-2025.pdf"
}
}

Status and roadmap

DamLevels-Data is open source and self-hosted: the MCP server runs as a local stdio process from a clone of the repository, with no hosted endpoint. Release 1.1.2 is archived on Zenodo. The GitHub repository is the single source for the data, the installation and the code. Planned next steps: register the ontology namespace and publish the full instance graph, link dams and catchments to external datasets, publish the watershed climate layer (rainfall, meteorology, soil moisture), and resolve with the publisher the open questions on Page 3 transfers.

Technical report

Technical report TD-TR-2026-04 documents each stage, from the PDF bulletin to linked data and the MCP server, with its evidence and its limitations, under a CC BY 4.0 license.

Citable archival version of record: Nasfi, M. H., Boulaares, S., & Gasmi, T. (2026). DamLevels-Data: From PDF Bulletins to Linked, AI-Queryable Open Data on Tunisia’s Large Dams, 2014–2025. Technical report TD-TR-2026-04. tanitdata, Tunis. https://doi.org/10.5281/zenodo.23305079

Data and software (release 1.1.2): Nasfi, M. H., Boulaares, S., & Gasmi, T. (2026). DamLevels-Data: daily storage of Tunisia’s 36 large dams, 2014–2025. Zenodo. https://doi.org/10.5281/zenodo.23304326

Source code and data: github.com/tanitdata/DamLevels-Data