Mom's AI-powered Mandates Assistant
A retrieval-augmented regulatory consultant for the EU gas & hydrogen Distribution System Operator (DSO) framework — exposed to Claude as a set of Model Context Protocol (MCP) tools over a 48,775-chunk vector index of EU law.
MAMA answering inside Claude. The cited Article 71 text, the metadata badges (empowerment · DSO-relevance · in force) and the dates are real output from its MCP tools.
I built MAMA for my mother — a regulatory officer at the EU DSO Entity, the body that represents Europe's electricity distribution grid operators. Her job in 2025–2026 is to take the mature electricity DSO framework (expert groups, network codes, cooperation agreements) and replicate it for gas and hydrogen as the EU's new Gas Package comes into force.
That work means living inside a dense web of regulations — Regulation (EU) 2024/1789, Directive (EU) 2024/1788, the Electricity Market Regulation, the ACER Regulation, network codes — and constantly asking "what does the electricity side already do here, and what is the gas equivalent?"
MAMA turns that corpus into something she can simply ask in plain language, right inside her Claude subscription. It is not a chatbot wrapper — it is an MCP tool server that gives Claude precise, cited retrieval over the actual legal texts, plus a hand-curated metadata layer that prevents the classic RAG failure modes (confusing a Regulation with a Directive, inventing a network code that doesn't exist yet, missing an act entirely).
It runs locally and needs no API key for everyday use — Claude Desktop or Claude Code is the brain; MAMA is the retrieval + domain-knowledge layer it calls.
flowchart LR
subgraph Ingest["Build pipeline (offline)"]
A[Scraper<br/>EUR-Lex · ACER · ENTSOG · ENNOH · DSO Entity] --> B[PDF text<br/>extraction]
B --> C[DSO-relevance<br/>filter]
C --> D[Legal-aware<br/>chunker]
D --> E[Embedder<br/>all-MiniLM-L6-v2]
E --> F[(ChromaDB<br/>48,775 vectors)]
end
subgraph Curated["Curated knowledge layer"]
G[act_metadata.json<br/>31 acts]
H[relationships.json<br/>536 legal links]
end
subgraph Serve["Runtime"]
F --> I[MCP server<br/>mcp_server.py]
G --> I
H --> I
I -. stdio .-> J[Claude Desktop /<br/>Claude Code]
J --> K((User asks a<br/>question))
end
The retrieval layer is deliberately paired with a curated layer that encodes distinctions a pure embedding search keeps getting wrong:
- Regulation vs Directive — the Regulation creates the DSO Entity mandate; the Directive creates obligations on individual DSOs. MAMA labels every act so Claude never conflates the two.
- Adopted vs empowerment vs speculation — an article that empowers a future network code is tagged differently from one that is already binding, so the assistant doesn't describe a not-yet-drafted gas network code as if it existed.
- Completeness —
list_actsenumerates the full 31-act index with filters, so a topical mapping can be proven complete instead of trusting that semantic search surfaced everything.
The server (mcp_server.py) exposes five tools over stdio:
| Tool | What it does | Needs vector DB? |
|---|---|---|
search_regulations |
Semantic search over the corpus; filter by chunk_type (article / definition / recital / …) or restrict to a single act by CELEX. |
✅ |
get_article |
Exact text of a specific article (e.g. get_article("32024R1789", "41")) with its structural path and provision role. |
✅ |
list_acts |
Enumerate the 31-act metadata index with filters (sector_tag, act_type, dso_relevance, workstream, time_relevance). |
— |
get_act_metadata |
Full metadata for one act: official title, type, status, entry-into-force / application / transposition dates, DSO-relevance labels, amendments. | — |
get_legal_relationships |
What an act or article amends / repeals / references (act-level by CELEX, article-level by CELEX + article number). | — |
Three of the five work the moment you clone the repo (they read the committed
data/*.json); the two retrieval tools light up once you drop in the vector DB.
A companion CLAUDE.md ships in the repo as the consultant persona + tool-use
protocol — when the project is opened in Claude Code it loads automatically and
tells the model how to act as a senior DSO regulatory consultant (search both the
Regulation and Directive side, cite CELEX + article, never invent a network code,
etc.).
| Chunks indexed | 48,775 |
| Source documents | ~1,700 (EUR-Lex, ACER, ENTSOG, ENNOH, EU DSO Entity) |
| Acts with article-level structure | 31 legislative acts (Regulations & Directives) |
| Curated legal relationships | 536 (repeals / amends / supplements / references) |
| Embedding model | all-MiniLM-L6-v2 (sentence-transformers) |
| Vector store | ChromaDB (persistent) |
Article-level chunks carry a structural path (CHAPTER IV > Article 72), a
provision role (obligation / empowerment / governance / transitional / …) and
DSO-relevance labels, so citations are precise and the model can reason about
what an article does, not just what it says.
git clone https://github.com/KongFuzi1/MAMA.git
cd MAMA
python setup_mama.py # creates .venv, installs deps, writes .mcp.json + runners
setup_mama.pyis cross-platform (Windows / macOS / Linux). ChromaDB + sentence-transformers pull in PyTorch (~2 GB), so the first install takes a few minutes.
The index is ~1.4 GB and ships as a GitHub Release asset rather than in git.
# Download mama-vectordb-chroma_v2.zip from the latest Release, then:
unzip mama-vectordb-chroma_v2.zip -d data/
# result: data/chroma_v2/ (this is what search_regulations / get_article use)→ Releases
(You can skip this step and still use list_acts, get_act_metadata and
get_legal_relationships, which read the committed metadata.)
Claude Code — setup_mama.py already wrote a project .mcp.json. Just run
claude from inside the MAMA/ folder and the mama server connects
automatically (and CLAUDE.md loads the consultant persona).
Claude Desktop — add this to your claude_desktop_config.json:
Then ask, in natural language:
"What obligations does the Gas Market Regulation create for the DSO Entity, and how do they differ from the electricity framework?" "What does Article 41 of Regulation 2024/1789 say about additional tasks?" "List every gas-sector act in the index and flag which ones bind DSOs."
The MCP server is the main product, but the repo also includes:
source .venv/bin/activate
# Plain semantic search, no LLM — just retrieve the relevant chunks
python search.py "cybersecurity gas DSO network code" --top 10
# Ask via the Claude Code CLI as backend (no API key needed)
python -m app.ask "How do gas network codes get developed?"
# Local web UI (chat + PDF upload + doc browser) on http://localhost:7860
python -m app.web
# Classic API-key path (uses the Anthropic API directly)
export ANTHROPIC_API_KEY=... # only this path needs a key
python -m app.cliThe whole pipeline is reproducible from source. Heavy inputs/outputs
(data/raw/, data/text/, the Chroma stores) are gitignored.
source .venv/bin/activate
python -m scraper.main # fetch documents (EUR-Lex, ACER, ENTSOG, ENNOH, DSO Entity)
python -m scripts.extract_text # PDF → text
python -m rag.filter # score & keep DSO-relevant documents
python -m rag.chunker # legal-aware chunking
python -m rag.embedder # embed → ChromaDB
# Curated layers
python -m scripts.build_act_metadata
python -m scripts.build_relationshipsMAMA/
├── mcp_server.py # MCP tool server (stdio) — the product surface
├── search.py # standalone semantic-search CLI
├── setup_mama.py # cross-platform installer (venv, .mcp.json, runners)
├── CLAUDE.md # consultant persona + tool-use protocol (auto-loaded)
├── SPEC.md # full project specification
├── rag/ # RAG pipeline
│ ├── config.py # paths, model, system prompt, key regulations
│ ├── legal_parser.py # article/recital structure extraction
│ ├── chunker.py # legal-aware chunking with overlap
│ ├── embedder.py # sentence-transformers → ChromaDB
│ ├── filter.py # DSO-relevance scoring
│ ├── query.py # retrieval + (optional) Claude API
│ └── relationships.py # legal-graph lookup
├── scraper/ # document fetchers
│ └── sources/ # eurlex · acer · entsog · ec_energy
├── scripts/ # metadata / relationship / coverage builders
├── app/ # cli · ask (Claude CLI backend) · web (Gradio)
├── build/ + Makefile # docs/*.md → PDF via Typst (local doc toolchain)
└── data/
├── act_metadata.json # ✅ committed — 31-act metadata index
└── relationships.json # ✅ committed — 536 legal relationships
Python · ChromaDB (vector store) · sentence-transformers / all-MiniLM-L6-v2 (embeddings) · Model Context Protocol (stdio tool server) · pdfplumber (extraction) · BeautifulSoup / requests (scraping) · Gradio (optional web UI) · Typst (document rendering).
- Move the scraper to Oracle Cloud Infrastructure (OCI) — run document ingestion on a scheduled cloud worker instead of a laptop, so the index stays current as ACER/ENTSOG/ENNOH publish, and the refreshed vector DB is pushed automatically.
- Upgrade embeddings to a larger model for higher retrieval precision.
- Add conversation memory across questions.
Source code: MIT (see LICENSE).
The indexed legal texts and third-party publications remain under their own terms. EU legislative texts are © European Union via EUR-Lex; reuse is permitted under Commission Decision 2011/833/EU with acknowledgement of the source. Reference PDFs from ENTSOG, ENNOH, ACER and the EU DSO Entity are not redistributed in this repository.
{ "mcpServers": { "mama": { "command": "/absolute/path/to/MAMA/.venv/bin/python", "args": ["/absolute/path/to/MAMA/mcp_server.py"] } } }