redflag-mcp
redflag-mcp
MCP-Server, der AML-Warnsignalwissen als abfragbare Tools bereitstellt. Compliance-Beauftragte stellen Fragen in natürlicher Sprache; der Server liefert relevante, mit Quellen belegte Warnsignale aus einer lokalen Vektordatenbank.
Übersicht
Drei verschiedene Arbeitsabläufe:
Extraktion — AML-Warnsignale mithilfe eines LLM aus PDFs oder Webseiten extrahieren und als YAML speichern
Ingestion — Die YAML-Dateien einbetten und in die lokale Vektordatenbank laden
Abfrage — MCP-Server beantwortet semantische Suchanfragen gegen diese Datenbank
Related MCP server: Financial Intelligence MCP Server
Extraktions-Pipeline
scripts/extract.py nimmt ein regulatorisches Dokument (PDF-Datei oder URL), sendet dessen Text an ein OpenAI-Modell und schreibt eine strukturierte YAML-Datei in data/source/. Jeder extrahierte Eintrag enthält eine source_url, die auf das Originaldokument zurückverweist.
Voraussetzungen
uv sync --extra dev
export OPENAI_API_KEY=sk-...PDFs in großen Mengen hinzufügen (empfohlener Arbeitsablauf)
Schritt-für-Schritt:
Die Quell-URL zu
red_flag_sources/pdflinks.txthinzufügen — eine URL pro Zeile, in serieller Reihenfolge. Zeile 1 → Schlüssel001, Zeile 2 →002, usw.Das PDF herunterladen und unter dem Namen
NNN_kurzer_beschreibender_name.pdfinred_flag_sources/pdf/speichern, wobeiNNNder Zeilenposition inpdflinks.txtentspricht.Das Register neu generieren:
uv run python scripts/build_sources_registry.pyExtraktion ausführen:
uv run python scripts/extract.py --parallel
Wichtige Einschränkung: Das
NNN_-Präfix im Dateinamen muss mit der Zeilennummer inpdflinks.txtübereinstimmen. Zeile 1 =001_*.pdf, Zeile 2 =002_*.pdf, usw. Auf diese Weise verknüpft der Extraktor jedes PDF mit seiner öffentlichen Quell-URL.
PDFs werden in red_flag_sources/pdf/ gespeichert und müssen mit einem mit Nullen aufgefüllten seriellen Präfix benannt werden:
red_flag_sources/pdf/
001_fincen_alert_russian_sanctions_evasion.pdf
002_ffiec_bsa_aml_examination_manual.pdf
003_fatf_guidance_virtual_assets.pdfJede Seriennummer verweist auf eine öffentliche URL für das Quelldokument. Pflegen Sie diese Zuordnung in red_flag_sources/pdflinks.txt — eine URL pro Zeile, in serieller Reihenfolge:
# FinCEN Russian Sanctions Evasion Alert
https://fincen.gov/sites/default/files/2022-06/Alert%20FIN-2022-Alert001_508C.pdf
# FFIEC BSA/AML Examination Manual
https://bsaaml.ffiec.gov/manual
# FATF Guidance on Virtual Assets
https://www.fatf-gafi.org/...Leerzeilen und Zeilen, die mit # beginnen, werden ignoriert. Nachdem Sie pdflinks.txt bearbeitet haben, generieren Sie sources.yaml neu:
uv run python scripts/build_sources_registry.pyFühren Sie dann die Batch-Extraktion aus:
uv run python scripts/extract.py --parallelNur neue (nicht verarbeitete) PDFs werden extrahiert — zuvor verarbeitete Quellen werden automatisch übersprungen.
Batch-Extraktionsbefehle
# Sequential batch
uv run python scripts/extract.py
# Parallel batch (4 workers by default)
uv run python scripts/extract.py --parallel
# Parallel batch with custom worker count
uv run python scripts/extract.py --parallel 8
# Force re-extract everything
uv run python scripts/extract.py --force --parallel
# Process only PDFs in a serial range (e.g. 001 through 005)
uv run python scripts/extract.py --range 001-005
# Range + parallel
uv run python scripts/extract.py --range 001-005 --parallel
# Force re-extract a range
uv run python scripts/extract.py --force --range 001-005 --parallelHinweis:
--rangegilt nur für nummerierte PDFs. Web-URLs inWeblinks.mdwerden ausgeschlossen, wenn ein Bereich aktiv ist.
Einzelquelle (ad hoc)
# Extract from a local PDF
uv run python scripts/extract.py red_flag_sources/pdf/001_fincen_alert.pdf
# Extract from a URL
uv run python scripts/extract.py https://example.com/regulatory-guidance
# Re-extract a source that was already processed
uv run python scripts/extract.py --force red_flag_sources/pdf/001_fincen_alert.pdfFür PDFs aus Einzelquellen fügen Sie die URL zu pdflinks.txt hinzu und führen Sie zuerst build_sources_registry.py aus, damit der Extraktor source_url in der Ausgabe ausfüllen kann.
Was es tut
Dokument abrufen — lädt die Webseite herunter (entfernt Navigation/Fußzeile/Skripte) oder liest Text aus dem PDF via pdfplumber
An OpenAI senden — fordert
gpt-4o-mini(überschreibbar mitOPENAI_EXTRACTION_MODEL) auf, jeden einzelnen AML-Warnsignalindikator als strukturiertes JSON zu extrahierenValidieren — jedes zurückgegebene Signal wird gegen das
RedFlagSource-Schema geprüft; ungültige Einträge werden mit einer Warnung übersprungenYAML schreiben — speichert in
data/source/<slug>.yaml, ein Eintrag pro WarnsignalManifest aktualisieren — protokolliert die Quelle in
data/source/.extracted_sources.yaml, um eine erneute Verarbeitung zu verhindern
Ausgabeschema
Jeder Eintrag in der YAML-Datei hat die folgenden Felder:
Feld | Typ | Erforderlich | Beschreibung |
| string | ja | Eindeutige Kennung, z. B. |
| string | ja | Eigenständige Beschreibung des Warnsignalindikators |
| string | nein | Öffentliche URL des Quelldokuments |
| list[string] | nein | Finanzprodukte, auf die dies zutrifft (z. B. |
| list[string] | nein | Kundenbranchen oder Sektoren, auf die dies zutrifft (z. B. |
| list[string] | nein | Kundenarchetypen, auf die dies zutrifft (z. B. |
| list[string] | nein | Relevante Regionen oder Korridore (z. B. |
| string | nein | Name des Quelldokuments oder Behörde (z. B. |
| string | nein |
|
| string | nein | AML-Typologie (z. B. |
| string | nein | Optionaler Code für Simulationskomplexität (z. B. |
Deduplizierung
data/source/.extracted_sources.yaml verfolgt jede verarbeitete Quelle anhand ihres kanonischen Pfads oder ihrer URL. Quellen, die bereits im Manifest enthalten sind, werden sowohl im Batch- als auch im Einzelquellenmodus übersprungen. Verwenden Sie --force, um eine Quelle ungeachtet dessen erneut zu extrahieren.
Ingestion
Nach der Extraktion betten Sie die YAML-Dateien ein und laden sie in die Vektordatenbank:
uv run python scripts/ingest.pyFür das anfängliche lokale Korpus sollten nur die drei Zieldateien aufgenommen werden:
uv run python scripts/ingest.py \
data/source/001_federal_child_nutrition_fraud.yaml \
data/source/002_oil_smuggling_cartels.yaml \
data/source/003_bulk_cash_smuggling_repatriation.yamlDies generiert Einbettungen mit nomic-embed-text-v1.5 und fügt Datensätze in LanceDB unter data/vectors/ ein. Führen Sie die Ingestion aus, bevor Sie den MCP-Server mit einem Desktop-Client verbinden; das Einbettungsmodell wird bei der ersten Verwendung heruntergeladen und während der Ingestion besser zwischengespeichert als während des Serverstarts.
OPENAI_API_KEY ist für die Ingestion optional. Wenn er gesetzt ist, kann die Ingestion fehlende Metadaten automatisch in die abgeleiteten LanceDB-Datensätze taggen. Wenn er nicht gesetzt ist, behält die Ingestion die verfügbaren YAML-Metadaten bei und lässt fehlende Rich-Consultation-Felder leer. Quell-YAML-Dateien werden durch die Ingestion nicht überschrieben.
MCP-Server
# Start server (stdio mode, for Claude Desktop / Claude Code)
uv run python -m redflag_mcp
# Start in MCP inspector
uv run mcp dev src/redflag_mcp/server.py
# Start as HTTP server (for OpenAI agents or other HTTP clients)
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8000 uv run python -m redflag_mcpDer Server stellt drei Tools bereit: search_red_flags, get_red_flag und list_filters. Er ist nach der Ingestion vollständig offline — zur Abfragezeit sind keine API-Schlüssel erforderlich.
Verwendung von Codex
Für lokale Codex-Threads bevorzugen Sie stdio, damit Codex den MCP-Server automatisch startet:
codex mcp add redflag-mcp -- zsh -lc 'cd /Users/learningmachine/Documents/Python-dev/redflag-mcp && HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 uv run python -m redflag_mcp'Überprüfen Sie die Registrierung:
codex mcp list
codex mcp get redflag-mcpStarten Sie dann einen neuen Codex-Thread und fragen Sie nach dem Server beim Namen, zum Beispiel:
Use the redflag-mcp MCP server. List the available AML red flag filters.Wenn der HTTP-Server bereits läuft, können Sie stattdessen diesen registrieren:
codex mcp add redflag-mcp-http --url http://127.0.0.1:8000/mcpLokale Smoke-Tests
Überprüfen Sie nach dem Einlesen der drei Zieldateien die Tools mit:
list_filters
search_red_flags(query="federal child nutrition program sponsor receives reimbursements inconsistent with its profile", product_types=["depository"])
search_red_flags(query="southwest border oil company wires for waste oil or hazardous materials")
search_red_flags(query="bulk cash moved by armored car service to Mexico")
get_red_flag(red_flag_id="001_federal_child_nutrition_fraud-01")Bei einer vagen Anfrage wie "Worauf sollte ich bei Geschäftskonten achten?" sollte der aufrufende Agent zuerst eine kurze Beratungsfrage stellen, die Produkt/Kanal, Branche, Kundenprofil, Geografie und Transaktionskanal oder -volumen abdeckt. Bei einer spezifischen Anfrage sollte er direkt suchen.
Entwicklung
uv sync --extra dev # Install dependencies
uv run pytest tests/ # Run tests
uv run ruff check src/ # Lint
uv run mypy src/ # Type checkAvailable Tools
7 toolsclassify_red_flag_requestA
Classify an AML red flag request before searching when the user asks which red flags apply to a product, customer, geography, industry, scenario, transaction pattern, or institution profile. Returns one route: needs_more_context, metadata_filter, filtered_relevance_search, or direct_relevance_search, plus the recommended next tool and arguments. Use it for ambiguous 'what red flags apply' requests; skip it when the user already gives specific metadata filters or a concrete scenario.
Inputs: query (required), limit, category, subjects, +6 more. Returns: object
filter_red_flagsA
Return AML red flags for exact metadata criteria without ranked relevance search. Use this for exact metadata requests, broad investigative subjects, and broad industry groups, such as high-risk depository structuring red flags, FINTRAC human trafficking red flags with subjects, trade logistics red flags with industry_groups, or red flags from regulators in France. category is the primary record classification; subjects is a broader eligibility layer that catches cross-category flags; typology_family is a broader proceeds or typology grouping. For example, a human-trafficking-relevant darknet crypto flag can have category="virtual_currency" while matching subjects=["human_trafficking"]. Paginate with next_cursor whenever truncated is true; search_red_flags is ranked and limit-based, with no cursor. For country or jurisdiction requests, translate names to ISO-style regulator_jurisdiction codes before filtering: France -> FR, Singapore -> SG, Australia -> AU, United Kingdom/UK -> GB, United States/US -> US, and European Union/EU regulators -> EU. Prefer filter_red_flags(regulator_jurisdiction="FR") for requests like "red flags from regulators in France." regulator_jurisdiction describes issuer jurisdiction; geographic_footprints describes affected geography or typology geography. Use search_red_flags instead for open-ended relevance questions. Successful responses include table-ready display hints in display and a portable Markdown fallback in markdown_table; clients decide how to render them.
Inputs: limit, cursor, detail, category, +16 more. Returns: object
get_red_flagB
Return one AML red flag by id, including source and citation metadata.
Inputs: red_flag_id (required). Returns: object
get_sourceA
Return bounded detail for one source by source_id, including citations, aggregate metadata, related red flag IDs, and short snippets. Use get_red_flag when full text for one red flag is needed.
Inputs: source_id (required). Returns: object
list_filtersA
List available filter values for product_types, industry_types, industry_groups, customer_profiles, geographic_footprints, subjects, typology_family, transaction_patterns, category, risk_level, regulator, and regulator_jurisdiction. Agents should call this before or during consultation when they need valid local filter values. category is the primary record classification; subjects is the broad investigative eligibility layer; typology_family is a broader proceeds or typology grouping. regulator_jurisdiction describes issuer jurisdiction; geographic_footprints describes affected geography or typology geography.
Inputs: no named parameters. Returns: object
list_sourcesA
List ingested AML red flag source coverage with citation URLs, source counts, aggregate metadata, and red flag IDs. Use when users ask what sources or citations the corpus covers.
Inputs: no named parameters. Returns: object
search_red_flagsA
Search AML red flags using natural-language context and optional filters.
Successful responses include table-ready display hints in display and a portable Markdown fallback in markdown_table; clients decide how to render them.
Agent guidance: use classify_red_flag_request before searching for ambiguous "what red flags apply" requests; skip that extra call when the user already gives specific metadata filters or a concrete scenario. If the user's request is vague, briefly ask for product/channel, industry, customer profile, geography, and transaction channel or volume before searching. If the request already names those details or has a specific scenario, search directly. Call list_filters when you need valid filter values. Use filter_red_flags for exact metadata requests and exhaustive enumeration; use search_red_flags for ranked relevance questions and increase limit for more ranked results because search has no cursor. For broad investigative topics such as human trafficking red flags, use subjects as an eligibility filter. Category is the primary record classification; subjects is a broader eligibility layer that catches cross-category flags; typology_family is a broader proceeds or typology grouping. For example, a human-trafficking-relevant darknet crypto flag can have category="virtual_currency" while matching subjects=["human_trafficking"]. For broad sector requests such as trade logistics red flags, use industry_groups as an eligibility filter. regulator_jurisdiction describes issuer jurisdiction; geographic_footprints describes affected geography or typology geography. For country or jurisdiction requests about issuing regulators, translate names to regulator_jurisdiction codes before filtering, such as France -> FR, Singapore -> SG, Australia -> AU, United Kingdom/UK -> GB, United States/US -> US, and European Union/EU regulators -> EU.
Inputs: query (required), limit, category, subjects, +7 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: classification, exact filtering, single retrieval, source retrieval, listing filters, listing sources, and semantic search. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (classify_red_flag_request, filter_red_flags, etc.), with predictable verbs like get_, list_, search_.
7 tools is well-scoped for the AML red flag domain, covering classification, filtering, retrieval, and metadata browsing without unnecessary bloat.
The tool set provides a complete read-only surface: routing ambiguous requests, exact filtering, single record lookup, source detail, filter values, source coverage, and full-text search. No obvious gaps.
Maintenance
Related MCP Connectors
MCP server for FCA Handbook compliance analysis with verbatim citations.
The CustomGPT.ai MCP server is a fully managed, RAG-powered endpoint that connects large language models with private knowledge bases and external data sources. It provides tools for retrieval-augmented generation queries (send_message), data ingestion (upload_file), and source listing, enabling AI agents to query private documents like PDFs with high accuracy and real-time citations.
AI governance MCP server for EU AI Act compliance and jurisdiction verification
MCP server for VC pitch-deck scoring, thesis-fit matching, and deal-flow management.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA production-grade MCP server that automates financial compliance audits by combining LLMs with structured analysis, enabling policy validation, risk profiling, and automated reporting.-
- FlicenseNot gradedqualityDmaintenanceA production-grade MCP server that provides financial ML tools including RAG search, anomaly detection, contract summarization, vendor graph analysis, and model drift monitoring using entirely free, open-source components.1-

yaml-ai-mcpofficial
AlicenseAqualityCmaintenanceAn MCP server for anti-money laundering (AML) compliance, including customer due diligence, transaction monitoring, and SAR filing, compliant with 6AMLD, UK MLR 2017, and FinCEN.4MIT- FlicenseNot gradedqualityDmaintenanceA Retrieval Augmented Generation MCP server that ingests documents into a local vector database and enables semantic search queries.9-