uae-aml-rag
by mathu619
README.md
# UAE AML/CFT Regulations RAG
A local retrieval tool over UAE anti-money laundering and counter-terrorist financing
(AML/CFT) regulations, exposed as an [MCP](https://modelcontextprotocol.io) server. Claude
Desktop uses it to search the actual texts, so Claude can answer compliance questions
with citations to document, article and page, such as `[CR134-2025 – Article 16 – p. 22]`.
**Why:** compliance answers have to rest on the current texts. The UAE replaced its AML law
in 2025 (Federal Decree-Law No. 10 of 2025 repealed Decree-Law No. 20 of 2018), so a
model's general knowledge can cite repealed provisions or the wrong article. This tool
lets Claude look the rules up instead and show where each point comes from.
- **Local retrieval.** Extraction, embeddings, the vector store and search all run on your
machine, on CPU. No API key, no paid services and no network calls at query time.
- **Citations.** Every passage carries its source, article or section, and pages.
- **Legal-structure chunking.** Chunks follow articles, sections and FATF Recommendations,
and are sized to the embedding model's token limit.
- **Measured.** A small retrieval eval compares the two supported embedding models.
## How it works
```mermaid
flowchart LR
subgraph ING["Ingest: python -m uae_aml_rag.ingest"]
pdfs["PDFs in docs/<br/>listed in sources.yaml"] --> extract["Text extraction<br/>pypdf, pdfplumber fallback"]
extract --> chunk["Chunking by legal structure<br/>Article, Section, Recommendation"]
chunk --> embed["Embeddings on CPU<br/>MiniLM or bge-small"]
end
embed --> db[("ChromaDB in ./db<br/>one collection per model")]
subgraph SRV["Query time: no network"]
server["MCP server<br/>python -m uae_aml_rag.server"]
end
server -->|"embed query, cosine top-k"| db
claude["Claude Desktop"] -->|"MCP over stdio"| server
```
1. **Extraction.**
- pypdf reads each page, with pdfplumber as a fallback for pages that come out garbled.
- Repeated headers and footers, table-of-contents lines and stray glyphs are removed, and hyphenated line breaks are joined.
2. **Chunking.**
- Headings split the text into units:
- `Article (16)` and `Division Five`;
- numbered sections such as `6.4.1`;
- chapters in capitals such as `7 CUSTOMER DUE DILIGENCE`;
- `Annex 2. Red Flag Indicators`;
- FATF's `10. Customer due diligence`.
Chapters in capitals, annexes and FATF's numbered headings count only while their numbers run 1, 2, 3, …, which skips leftover table-of-contents lines and repeated lists.
- Long units are split at sentence boundaries, with abbreviations and numbered lists handled, into chunks measured with the model's own tokenizer:
- MiniLM: ~220 tokens, ~40 overlap.
- bge-small: ~450 tokens, ~60 overlap.
- Each chunk is embedded with a short context header naming the document and the article.
3. **Storage.**
- ChromaDB with cosine distance, one collection per embedding model.
- The collection records which model built it, and searching with another model is refused.
- Chunk ids are deterministic, so re-running ingest only embeds what changed and deletes stale chunks.
4. **Serving.**
- Claude Desktop starts the server with stdio transport and calls its three tools.
- The model loads lazily from the local cache, with `HF_HUB_OFFLINE=1`.
- Chroma keeps each vector index in memory and does not see writes from another process, so the server reopens the store whenever ingest has left a new stamp in `db/`.
- Nothing but the protocol is ever written to stdout, and logs go to stderr.
| Tool | What it does |
|---|---|
| `search_regulations(query, k=6, issuer=None, source=None)` | Top-k passages (k is limited to 1–20) with citation headers and similarity scores. The results can be limited to one issuer or one document. |
| `get_article(source, article)` | One full article or section, rebuilt from its chunks with the overlap removed. Accepts `16`, `Art. 16`, `Article Sixteen`, `6.4` or `R.10`, and suggests close matches when the reference doesn't exist. |
| `list_sources()` | The indexed documents, their versions and official URLs, and the embedding model. |
Built with the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk),
ChromaDB, sentence-transformers, pypdf and pdfplumber. It doesn't use LangChain or LlamaIndex.
## Indexed documents
Download the PDFs from the official sources and save them in `docs/` under the file names
below. They are public documents, but this repository does not redistribute them:
`docs/*.pdf` is git-ignored. [`docs/sources.yaml`](docs/sources.yaml) maps each file to its
metadata.
| File in `docs/` | Source id | Document | Version |
|---|---|---|---|
| `uae_fdl_10_2025_aml.pdf` | DL10-2025 | [Federal Decree-Law No. 10 of 2025 on AML/CFT/CPF](https://rulebook.centralbank.ae/sites/default/files/en_net_file_store/CBUAE_EN_6471_VER1.pdf) | 2025 |
| `uae_cr_134_2025_exec_regs.pdf` | CR134-2025 | [Cabinet Resolution No. 134 of 2025, Executive Regulations](https://rulebook.centralbank.ae/sites/default/files/en_net_file_store/CBUAE_EN_6843_VER1.pdf) | 2025 |
| `cbuae_aml_guidelines_fis.pdf` | CBUAE-AMLG | [CBUAE AML/CFT Guidelines for Financial Institutions](https://rulebook.centralbank.ae/sites/default/files/en_net_file_store/CBUAE_EN_3945_VER2.pdf) | 2023 |
| `cbuae_tfs_guidance.pdf` | CBUAE-TFS | [CBUAE Guidance on Targeted Financial Sanctions](https://rulebook.centralbank.ae/sites/default/files/en_net_file_store/CBUAE_EN_996_VER1.pdf) | 2021 |
| `cbuae_str_guidance.pdf` | CBUAE-STR | [CBUAE Guidance on Suspicious Transaction Reporting](https://rulebook.centralbank.ae/sites/default/files/en_net_file_store/CBUAE_EN_418_VER2.pdf) | 2021 |
| `fatf_recommendations.pdf` | FATF-REC | [The FATF Recommendations](https://www.fatf-gafi.org/content/dam/fatf-gafi/recommendations/fatf-recommendations-2012.pdf) | June 2026 |
| `dfsa_aml_module.pdf` | DFSA-AML | [DFSA Rulebook, AML Module (DIFC)](https://dfsaen.thomsonreuters.com/sites/default/files/net_file_store/DFSA1547_20015_VER300426.pdf) | VER30/04-26 |
| `fsra_aml_rules.pdf` | FSRA-AML | [FSRA AML and Sanctions Rules and Guidance (ADGM)](https://en.adgm.thomsonreuters.com/sites/default/files/net_file_store/ADGM1547_5692_VER11210526.pdf) | VER11.210526 |
The URLs were checked on 2026-11-09. The FATF site blocks scripted downloads, so use a
browser. The two free-zone rulebooks (DFSA, FSRA) are optional, and missing files are
reported and skipped.
Only index public regulatory documents: the passages Claude retrieves become part of your
conversation with Claude.
## Setup (Windows, PowerShell)
You need Python 3.10 or newer. It was tested with Python 3.12 and 3.13 on Windows 11, CPU only.
Clone the repository, then:
```powershell
cd UAE_Regulations_RAG
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
```
If PowerShell blocks `Activate.ps1`, skip it and type `.\.venv\Scripts\python.exe`
wherever these instructions say `python`.
Put the PDFs in `docs/` (see above), then build the index:
```powershell
python -m uae_aml_rag.ingest
```
The first run downloads the embedding model from Hugging Face (all-MiniLM-L6-v2, about
90 MB, into `~/.cache/huggingface`). After that, ingest, search and the tests all run offline.
Ingest prints a summary table per document and lists any pages without a text layer.
Check it from a terminal before connecting Claude Desktop:
```powershell
python -m uae_aml_rag.server --selftest "record retention period"
python -m pytest
```
**macOS / Linux:**
- Create and activate the venv with `python3 -m venv .venv` and `source .venv/bin/activate`; the other commands are the same.
- On Linux, PyPI's default torch wheel includes CUDA. For a CPU-only install, first run `pip install torch --index-url https://download.pytorch.org/whl/cpu`.
- Claude Desktop is available for Windows and macOS.
## Connect Claude Desktop
Open the config file from Claude Desktop: **Settings → Developer → Edit Config**.
| Platform | Usual location |
|---|---|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
The Microsoft Store build may keep the file somewhere else; Edit Config always opens the
right one.
Print the venv's Python path, already escaped for JSON:
```powershell
.\.venv\Scripts\python.exe -c "import json, sys; print(json.dumps(sys.executable))"
```
Add the server under `mcpServers`, keeping any servers already there:
```json
{
"mcpServers": {
"uae-aml-rag": {
"command": "C:\\path\\to\\UAE_Regulations_RAG\\.venv\\Scripts\\python.exe",
"args": ["-m", "uae_aml_rag.server"]
}
}
}
```
- **macOS:** the command is `/path/to/UAE_Regulations_RAG/.venv/bin/python`.
- **No `env` block needed.** The server switches itself to offline mode and finds `./db` from its own location, not from the working directory.
- **To use bge-small instead of MiniLM,** add `"env": {"UAE_AML_RAG_MODEL": "bge"}` and build that index first (see [Configuration](#configuration)).
Then restart Claude Desktop properly:
1. Quit it from the system tray, or with Cmd+Q on macOS. Closing the window isn't enough.
2. Reopen it. **Settings → Developer** should show `uae-aml-rag` as running, and the
connectors menu under the chat box should list its three tools.
3. Ask a question. Approve the tool when asked.
- The first search can take up to 20 seconds while the model loads; later ones are fast.
- The server uses about 600 MB of RAM once loaded.
You can re-run ingest while Claude Desktop is open. Every ingest leaves a stamp in `db/`,
and the server reopens the index on its next request. A search made while an ingest is
still running may come back asking Claude to search again.
**Troubleshooting.** The server's log is `mcp-server-uae-aml-rag.log`. It sits in
`%APPDATA%\Claude\logs\`, or `%LOCALAPPDATA%\Claude\Logs\` for the Microsoft Store build,
and in `~/Library/Logs/Claude/` on macOS. Near the top it should show
`Starting MCP server: db=… model=…`.
| Symptom | Fix |
|---|---|
| Server missing or "failed", `spawn … ENOENT` in the logs | The `command` path is wrong. Use the printed path; JSON needs doubled backslashes. |
| Tool says the embedding model is not downloaded | Run `python -m uae_aml_rag.ingest` once to fill the model cache. |
| Tool says the index is empty | Run ingest, with `--model bge` if you configured bge. |
| Tool says the index was built with another model | Rebuild it with `python -m uae_aml_rag.ingest --rebuild`, adding `--model bge` for bge. |
| JSON parse errors in the logs | Something wrote to stdout. The server never does, so check any wrapper script. |
## Example
The question:
> What do we have to do before taking on a foreign politically exposed person as a customer?
Claude first calls `search_regulations`. Each result starts with a citation header:
```text
--- Result 1 ---
[CR134-2025 – Article 16 – p. 22] similarity 0.59
Cabinet Resolution No. (134) of 2025 Regarding the Executive Regulations of Federal Decree by Law No. (10) of 2025 … (UAE Federal, 2025)
Article (16)
1. In addition to applying Customer Due Diligence measures, Financial Institutions, …
```
The next results are FATF Recommendation 12 and the DFSA's guidance on PEPs. Claude then
calls `get_article("CR134-2025", "Art. 16")` for the full article and answers (abridged):
> In addition to normal customer due diligence, the Executive Regulations require four
> measures for a foreign PEP [CR134-2025 – Article 16 – p. 22]:
>
> 1. risk management systems to determine whether the customer or the beneficial owner is a PEP;
> 2. senior management approval before establishing the relationship, or before continuing
> it with an existing customer;
> 3. reasonable measures to identify the source of funds and the source of wealth;
> 4. enhanced ongoing monitoring of the relationship.
>
> For domestic PEPs and people with a prominent function in an international organisation,
> you must take adequate measures to identify them, and measures 2–4 apply when the
> relationship is high-risk [CR134-2025 – Article 16 – p. 22]. Life insurers must also check
> whether a beneficiary is a PEP before paying out [CR134-2025 – Article 16 – p. 22].
> These rules mirror FATF Recommendation 12 [FATF-REC – Recommendation 12 – p. 17]. In the
> DIFC, the DFSA's guidance adds that the risk extends to PEPs' family members and close
> associates [DFSA-AML – Section 7.3 – p. 38].
## Adding documents
1. Save the PDF in `docs/`.
2. Add an entry to `docs/sources.yaml` with these fields:
- `source`: a short id used in citations;
- `title`;
- `issuer`: one of `UAE Federal`, `CBUAE`, `FATF`, `DFSA`, `FSRA`;
- `year`;
- `url`.
Add `numbered_headings: Recommendation` (or another label) for documents whose
headings are plain numbered lines such as `10. Customer due diligence`.
3. Run `python -m uae_aml_rag.ingest`. Only new or changed chunks are embedded.
Useful flags:
- `--only DL10-2025` ingests one document.
- `--rebuild` starts the collection from scratch.
- `--model bge` builds the bge-small index.
Ingest warns about PDFs that aren't listed in `sources.yaml` and about listed files that are missing.
## Configuration
| Environment variable | Default | Meaning |
|---|---|---|
| `UAE_AML_RAG_MODEL` | `minilm` | Embedding model: `minilm` (sentence-transformers/all-MiniLM-L6-v2, ~90 MB) or `bge` (BAAI/bge-small-en-v1.5, ~130 MB). Each has its own index. bge-small gets its query instruction prepended to queries only. |
| `UAE_AML_RAG_DB` | `./db` | Chroma directory. A relative path is resolved against the project root. |
## Evaluation
`scripts/eval.py` runs the 10 questions in [`eval_questions.yaml`](eval_questions.yaml)
through the same retrieval the server uses. The topics are CDD, EDD for PEPs, STRs,
record retention, targeted financial sanctions, DNFBPs, beneficial ownership, wire
transfers, the risk-based approach and tipping off. Each question names the provision
that answers it, chosen by reading the documents. The script prints the top 3 passages per
question and **hit@3**: how many questions have their expected article among the top 3.
```powershell
python -m uae_aml_rag.ingest --model bge # build the bge-small index once
python scripts/eval.py --model minilm bge # all documents
python scripts/eval.py --model minilm bge --issuer "UAE Federal"
```
The results below were measured on 2026-11-10 with the eight documents above. The MiniLM
index has 1,935 chunks and the bge-small index 942. A number is the rank of the expected
article, and "–" means it was not in the top 3.
| Question | MiniLM | bge-small |
|---|---|---|
| CDD | 1 | 1 |
| EDD / PEPs | 1 | 2 |
| STR | – | – |
| Record retention | 2 | 2 |
| Targeted financial sanctions | – | – |
| DNFBPs | – | 1 |
| Beneficial ownership | 2 | – |
| Wire transfers | – | 2 |
| Risk-based approach | – | – |
| Tipping off | 3 | – |
| **hit@3, all documents** | **5/10** | **5/10** |
| **hit@3, federal questions searched in UAE Federal documents only** | **8/9** | **9/9** |
How to read this:
- **The metric is strict.** Only one provision counts per question. For example, Decree-Law Article 18 states the same reporting duty as the Executive Regulations' Article 18 but does not count for the STR question.
- **Most misses still return the right topic.** The FATF Recommendations, the DFSA rulebook or CBUAE guidance outrank the UAE article, such as FATF Recommendation 1 for the risk-based approach. Limited to UAE federal documents, almost every expected article reaches the top 3. That is why the tools take `issuer` and `source` filters, and why their descriptions tell Claude to search again with a filter.
- **Wording matters.** The sanctions question misses for both models, even though CBUAE-TFS Section 3.7 answers it (freeze the funds within 24 hours). The question's terms, such as "name screening" and "UN Consolidated List", are repeated in the screening sections, which rank higher. Keyword-aware (hybrid) search or a reranker would address this; this project uses plain embedding search.
- **MiniLM stays the default.** On all documents the two models tie, MiniLM is smaller, and a one-question gap on ten questions is noise.
## Limitations
- **Not legal advice.** Check every point against the official text before relying on it.
- **Laws change.** The index is a snapshot of the versions in `sources.yaml`.
- The CBUAE guidance (2021, 2023) still refers to the repealed Decree-Law No. 20 of 2018 and Cabinet Decision No. 10 of 2019.
- Re-download and re-ingest documents when they are amended.
- **Translations.** The UAE federal texts are English versions; the official text is the Arabic one published in the Official Gazette.
- **PDF quality.**
- Text extraction leaves artifacts such as `risk -based` or `t he`.
- FATF's group titles, such as "D. PREVENTIVE MEASURES", are not detected as headings, so each one ends up at the end of the previous Recommendation.
- Repeated labels, such as Recommendations restated in the FATF annex, make `get_article` return the first occurrence and say so.
- **No OCR.** Pages without a text layer (scanned documents) are skipped and listed by ingest.
- **Retrieval can miss.** Semantic search ranks similar passages, not legal authority, and a passage that answers in different words can rank below passages that repeat the question's terms (see the evaluation). Asking about UAE federal law specifically helps Claude filter.
## Project layout
```text
docs/sources.yaml document list; the PDFs go here but are not committed
src/uae_aml_rag/
config.py paths, model settings, environment variables
pdf_extract.py PDF text extraction and cleanup
chunking.py legal-structure chunking (pure functions)
store.py ChromaDB and embedding helpers
ingest.py ingest CLI
server.py MCP server and --selftest
scripts/eval.py retrieval eval
eval_questions.yaml eval questions with their expected provisions
tests/ pytest suite: chunking, extraction, ingest, tools, stdio session, eval
```
The tests build a tiny PDF and a temporary index, so they never touch `./db`. They run
offline once MiniLM is cached.
## License
The code is under the [MIT License](LICENSE). The regulatory documents belong to their
issuers and are not included in this repository.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues