onem-tunisia-mcp: A Qualifier-Aware MCP Server over Tunisia's National Energy Time-Series

onem-tunisia-mcp is a Model Context Protocol (MCP) server that makes Tunisia's national energy statistics directly queryable by LLM clients. The source data is not an API but a corpus of recurring PDF reports published by the Observatoire National de l'Energie et des Mines (ONEM) — the annual Bilan National de l'Energie, the Memento (Chiffres clés), and the periodic Conjoncture énergétique bulletins, spanning 2010 to 2026. The system's defining work is the discipline that carries a figure intact from a PDF table to an LLM's sentence. A coordinate-aware extractor lifts cells, with per-cell provenance, into a long-format DuckDB store whose schema makes every qualifier — calorific basis (PCI/PCS), period type (annual vs year-to-date), geography scope, aggregation role, and data status — a first-class column rather than a derivable afterthought. The serving layer is built on one principle: a category error should be hard to even express. The server refuses to compare a PCI figure with a PCS one, an annual figure with a year-to-date one, or a total with its own components; it distinguishes "out of scope" from "no data"; and it never returns a bare number. Cross-edition disagreements are retained and reconciled by a documented precedence rule rather than silently overwritten. A battery of fifteen arithmetic and relationship checks (including the physical relation PCI ≈ 0.9 × PCS and the energy-balance identity), a three-layer evaluation, and an adversarial multi-agent audit stand behind the store. This report documents the system as it ships today — a source-distributed local stdio server bundled with its built store — together with the rationale behind its principal design decisions and its candid limitations. The software is distributed under the MIT License; the data is derived and restructured from public ONEM reports. This is an independent, unofficial project, not affiliated with or endorsed by ONEM or the Ministry of Industry, Mines and Energy. Software repository: github.com