Skip to main content
Glama
Sign In
deenesjakoruzh
redflag-mcp

redflag-mcp

by govindgnair23
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

redflag-mcp

MCP-сервер, предоставляющий доступ к знаниям о «красных флагах» AML в виде инструментов для запросов. Специалисты по комплаенсу задают вопросы на естественном языке; сервер возвращает релевантные, подтвержденные источниками «красные флаги» из локальной векторной базы данных.

Обзор

Три отдельных рабочих процесса:

  1. Извлечение (Extraction) — извлечение «красных флагов» AML из PDF-файлов или веб-страниц с помощью LLM и сохранение их в формате YAML.

  2. Загрузка (Ingestion) — создание эмбеддингов для YAML-файлов и их загрузка в локальную векторную базу данных.

  3. Запрос (Query) — MCP-сервер отвечает на семантические поисковые запросы к этой базе данных.

Related MCP server: Financial Intelligence MCP Server

Конвейер извлечения

scripts/extract.py берет нормативный документ (PDF-файл или URL), отправляет его текст в модель OpenAI и записывает структурированный YAML-файл в data/source/. Каждая извлеченная запись включает source_url, ссылающийся на исходный документ.

Предварительные требования

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

Массовое добавление PDF-файлов (рекомендуемый рабочий процесс)

Пошаговая инструкция:

  1. Добавьте исходный URL в red_flag_sources/pdflinks.txt — по одному URL на строку, в последовательном порядке. Строка 1 → ключ 001, строка 2 → 002 и т. д.

  2. Скачайте PDF и сохраните его в red_flag_sources/pdf/ под именем NNN_краткое_описательное_имя.pdf, где NNN соответствует позиции строки в pdflinks.txt.

  3. Пересоздайте реестр: uv run python scripts/build_sources_registry.py

  4. Запустите извлечение: uv run python scripts/extract.py --parallel

Ключевое ограничение: префикс NNN_ в имени файла должен совпадать с номером строки в pdflinks.txt. Строка 1 = 001_*.pdf, строка 2 = 002_*.pdf и т. д. Именно так экстрактор связывает каждый PDF с его публичным исходным URL.

PDF-файлы хранятся в red_flag_sources/pdf/ и должны иметь имя с серийным префиксом, дополненным нулями:

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

Каждый серийный номер соответствует публичному URL исходного документа. Поддерживайте это соответствие в red_flag_sources/pdflinks.txt — по одному URL на строку, в последовательном порядке:

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

Пустые строки и строки, начинающиеся с #, игнорируются. После редактирования pdflinks.txt пересоздайте sources.yaml:

uv run python scripts/build_sources_registry.py

Затем запустите пакетное извлечение:

uv run python scripts/extract.py --parallel

Извлекаются только новые (необработанные) PDF-файлы — ранее обработанные источники пропускаются автоматически.

Команды пакетного извлечения

# 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

Примечание: --range применяется только к пронумерованным PDF-файлам. Веб-ссылки в Weblinks.md исключаются, когда активен диапазон.

Отдельный источник (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

Для отдельных PDF-файлов добавьте URL в pdflinks.txt и сначала запустите build_sources_registry.py, чтобы экстрактор мог заполнить source_url в выходных данных.

Что он делает

  1. Получает документ — скачивает веб-страницу (удаляет навигацию/футер/скрипты) или считывает текст из PDF через pdfplumber.

  2. Отправляет в OpenAI — запрашивает gpt-4o-mini (можно переопределить через OPENAI_EXTRACTION_MODEL) для извлечения каждого отдельного индикатора «красного флага» AML в виде структурированного JSON.

  3. Проверяет — каждый возвращенный флаг сверяется со схемой RedFlagSource; невалидные записи пропускаются с предупреждением.

  4. Записывает YAML — сохраняет в data/source/<slug>.yaml, по одной записи на «красный флаг».

  5. Обновляет манифест — записывает источник в data/source/.extracted_sources.yaml, чтобы предотвратить повторную обработку.

Схема выходных данных

Каждая запись в YAML-файле имеет следующие поля:

Поле

Тип

Обязательно

Описание

id

string

да

Уникальный идентификатор, например 001-fincen-alert-01

description

string

да

Самостоятельное описание индикатора «красного флага»

source_url

string

нет

Публичный URL исходного документа

product_types

list[string]

нет

Финансовые продукты, к которым это относится (например, depository, crypto, msb)

industry_types

list[string]

нет

Отрасли или секторы клиентов, к которым это относится (например, oil_and_gas, government_benefits)

customer_profiles

list[string]

нет

Типы клиентов, к которым это относится (например, small_business, charity_or_nonprofit)

geographic_footprints

list[string]

нет

Соответствующие географические регионы или коридоры (например, southwest_border, mexico)

regulatory_source

string

нет

Название исходного документа или органа (например, FinCEN Alert FIN-2022-Alert001)

risk_level

string

нет

high, medium или low

category

string

нет

Типология AML (например, structuring, sanctions_evasion, shell_company)

simulation_type

string

нет

Дополнительный код сложности симуляции (например, 1A, 2B)

Дедупликация

data/source/.extracted_sources.yaml отслеживает каждый обработанный источник по его каноническому пути или URL. Источники, уже имеющиеся в манифесте, пропускаются как в пакетном, так и в одиночном режиме. Используйте --force для принудительного повторного извлечения источника.

Загрузка (Ingestion)

После извлечения создайте эмбеддинги для YAML-файлов и загрузите их в векторную базу данных:

uv run python scripts/ingest.py

Для начального локального корпуса загрузите только три целевых файла:

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

Это генерирует эмбеддинги с помощью nomic-embed-text-v1.5 и добавляет записи в LanceDB по адресу data/vectors/. Запустите загрузку перед подключением MCP-сервера к настольному клиенту; модель эмбеддингов скачивается при первом использовании и лучше кэшируется во время загрузки, чем при запуске сервера.

OPENAI_API_KEY является необязательным для загрузки. Если он установлен, загрузка может автоматически добавлять недостающие метаданные в производные записи LanceDB. Если он не установлен, загрузка сохраняет доступные метаданные YAML и оставляет пустые поля для расширенной консультации. Исходные YAML-файлы при загрузке не перезаписываются.

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

Сервер предоставляет три инструмента: search_red_flags, get_red_flag и list_filters. После загрузки он полностью работает в автономном режиме — ключи API во время запроса не требуются.

Использование из Codex

Для локальных потоков Codex предпочтительнее использовать stdio, чтобы Codex запускал MCP-сервер автоматически:

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'

Проверьте регистрацию:

codex mcp list
codex mcp get redflag-mcp

Затем запустите новый поток Codex и запросите сервер по имени, например:

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

Если у вас уже запущен HTTP-сервер, вы можете зарегистрировать его:

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

Локальные проверки работоспособности

После загрузки трех целевых файлов проверьте инструменты с помощью:

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

Для расплывчатого запроса, такого как «на что мне следует обратить внимание в бизнес-счетах?», вызывающий агент должен сначала задать краткий уточняющий вопрос, охватывающий продукт/канал, отрасль, профиль клиента, географию и канал или объем транзакций. Для конкретного запроса он должен выполнять поиск напрямую.

Разработка

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…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    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.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Financial Intelligence MCP

      BharathiD9
      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
      -
    • yaml-ai-mcp

      yaml-ai-mcpofficial

      CSOAI-ORG
      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

    • RAG-MCP

      alejandro-ao
      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
      -