Skip to main content
Glama

redflag-mcp

Servidor MCP que expone conocimientos sobre señales de alerta AML como herramientas consultables. Los oficiales de cumplimiento realizan preguntas en lenguaje natural; el servidor devuelve señales de alerta relevantes y con sus fuentes desde una base de datos vectorial local.

Descripción general

Tres flujos de trabajo distintos:

  1. Extracción: extraer señales de alerta AML de archivos PDF o páginas web utilizando un LLM y guardarlas como YAML.

  2. Ingesta: integrar (embed) los archivos YAML y cargarlos en la base de datos vectorial local.

  3. Consulta: el servidor MCP responde a consultas de búsqueda semántica contra esa base de datos.


Related MCP server: Financial Intelligence MCP Server

Pipeline de extracción

scripts/extract.py toma un documento regulatorio (archivo PDF o URL), envía su texto a un modelo de OpenAI y escribe un archivo YAML estructurado en data/source/. Cada entrada extraída incluye una source_url que enlaza con el documento original.

Requisitos previos

uv sync --extra dev
export OPENAI_API_KEY=sk-...

Agregar archivos PDF de forma masiva (flujo de trabajo recomendado)

Paso a paso:

  1. Agregar la URL de origen a red_flag_sources/pdflinks.txt: una URL por línea, en orden secuencial. Línea 1 → clave 001, línea 2 → 002, etc.

  2. Descargar el PDF y guardarlo en red_flag_sources/pdf/ con el nombre NNN_nombre_descriptivo_corto.pdf, donde NNN coincide con su posición de línea en pdflinks.txt.

  3. Regenerar el registro: uv run python scripts/build_sources_registry.py

  4. Ejecutar la extracción: uv run python scripts/extract.py --parallel

Restricción clave: el prefijo NNN_ en el nombre del archivo debe coincidir con el número de línea en pdflinks.txt. Línea 1 = 001_*.pdf, línea 2 = 002_*.pdf, etc. Así es como el extractor vincula cada PDF con su URL de origen pública.


Los archivos PDF se almacenan en red_flag_sources/pdf/ y deben nombrarse con un prefijo serial con ceros a la izquierda:

red_flag_sources/pdf/
  001_fincen_alert_russian_sanctions_evasion.pdf
  002_ffiec_bsa_aml_examination_manual.pdf
  003_fatf_guidance_virtual_assets.pdf

Cada número de serie se asigna a una URL pública para el documento de origen. Mantenga este mapeo en red_flag_sources/pdflinks.txt — una URL por línea, en orden secuencial:

# 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/...

Las líneas en blanco y las líneas que comienzan con # se ignoran. Después de editar pdflinks.txt, regenere sources.yaml:

uv run python scripts/build_sources_registry.py

Luego ejecute la extracción por lotes:

uv run python scripts/extract.py --parallel

Solo se extraen los archivos PDF nuevos (no procesados); las fuentes procesadas anteriormente se omiten automáticamente.

Comandos de extracción por lotes

# 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 --parallel

Nota: --range se aplica solo a los archivos PDF numerados. Las URLs web en Weblinks.md se excluyen cuando un rango está activo.

Fuente única (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.pdf

Para archivos PDF de fuente única, agregue la URL a pdflinks.txt y ejecute build_sources_registry.py primero para que el extractor pueda completar la source_url en la salida.

Qué hace

  1. Obtiene el documento: descarga la página web (elimina navegación/pie de página/scripts) o lee el texto del PDF a través de pdfplumber.

  2. Envía a OpenAI: solicita a gpt-4o-mini (sobrescribir con OPENAI_EXTRACTION_MODEL) que extraiga cada indicador de señal de alerta AML distinto como JSON estructurado.

  3. Valida: cada señal devuelta se verifica contra el esquema RedFlagSource; las entradas no válidas se omiten con una advertencia.

  4. Escribe YAML: guarda en data/source/<slug>.yaml, una entrada por señal de alerta.

  5. Actualiza el manifiesto: registra la fuente en data/source/.extracted_sources.yaml para evitar el reprocesamiento.

Esquema de salida

Cada entrada en el archivo YAML tiene los siguientes campos:

Campo

Tipo

Requerido

Descripción

id

string

sí

Identificador único, ej. 001-fincen-alert-01

description

string

sí

Descripción independiente del indicador de señal de alerta

source_url

string

no

URL pública del documento de origen

product_types

list[string]

no

Productos financieros a los que aplica (ej. depository, crypto, msb)

industry_types

list[string]

no

Industrias o sectores de clientes a los que aplica (ej. oil_and_gas, government_benefits)

customer_profiles

list[string]

no

Arquetipos de clientes a los que aplica (ej. small_business, charity_or_nonprofit)

geographic_footprints

list[string]

no

Geografías o corredores relevantes (ej. southwest_border, mexico)

regulatory_source

string

no

Nombre del documento de origen o autoridad (ej. FinCEN Alert FIN-2022-Alert001)

risk_level

string

no

high, medium, o low

category

string

no

Tipología AML (ej. structuring, sanctions_evasion, shell_company)

simulation_type

string

no

Código de complejidad de simulación opcional (ej. 1A, 2B)

Deduplicación

data/source/.extracted_sources.yaml rastrea cada fuente procesada por su ruta canónica o URL. Las fuentes que ya están en el manifiesto se omiten tanto en el modo por lotes como en el de fuente única. Use --force para volver a extraer una fuente independientemente.


Ingesta

Después de la extracción, integre los archivos YAML y cárguelos en la base de datos vectorial:

uv run python scripts/ingest.py

Para el corpus local inicial, ingiera solo los tres archivos objetivo:

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.yaml

Esto genera embeddings con nomic-embed-text-v1.5 y realiza upsert de registros en LanceDB en data/vectors/. Ejecute la ingesta antes de conectar el servidor MCP a un cliente de escritorio; el modelo de embedding se descarga en el primer uso y se almacena mejor en caché durante la ingesta que durante el inicio del servidor.

OPENAI_API_KEY es opcional para la ingesta. Cuando está configurada, la ingesta puede etiquetar automáticamente metadatos faltantes en los registros derivados de LanceDB. Cuando no está configurada, la ingesta conserva los metadatos YAML disponibles y deja vacíos los campos de consulta enriquecidos faltantes. Los archivos YAML de origen no se sobrescriben mediante la ingesta.


Servidor MCP

# 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_mcp

El servidor expone tres herramientas: search_red_flags, get_red_flag y list_filters. Está completamente fuera de línea después de la ingesta; no se requieren claves API en el momento de la consulta.

Uso desde Codex

Para hilos locales de Codex, prefiera stdio para que Codex inicie el servidor MCP automáticamente:

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'

Verifique el registro:

codex mcp list
codex mcp get redflag-mcp

Luego inicie un nuevo hilo de Codex y solicite el servidor por su nombre, por ejemplo:

Use the redflag-mcp MCP server. List the available AML red flag filters.

Si ya tiene el servidor HTTP ejecutándose, puede registrar ese en su lugar:

codex mcp add redflag-mcp-http --url http://127.0.0.1:8000/mcp

Verificaciones locales (smoke checks)

Después de ingerir los tres archivos objetivo, verifique las herramientas con:

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")

Para una consulta vaga como "¿qué debo buscar en las cuentas comerciales?", el agente que realiza la llamada primero debe hacer una breve pregunta de consulta que cubra el producto/canal, la industria, el perfil del cliente, la geografía y el canal o volumen de transacciones. Para una consulta específica, debe buscar directamente.


Desarrollo

uv sync --extra dev              # Install dependencies
uv run pytest tests/             # Run tests
uv run ruff check src/           # Lint
uv run mypy src/                 # Type check

Available Tools

7 tools
classify_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

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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_.

    Tool Count5/5

    7 tools is well-scoped for the AML red flag domain, covering classification, filtering, retrieval, and metadata browsing without unnecessary bloat.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -
    • A
      license
      A
      quality
      C
      maintenance
      An 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.
      4
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A Retrieval Augmented Generation MCP server that ingests documents into a local vector database and enables semantic search queries.
      9
      -