Skip to main content
Glama

redflag-mcp

AMLのレッドフラグに関する知識をクエリ可能なツールとして公開するMCPサーバーです。コンプライアンス担当者が自然言語で質問すると、ローカルのベクトルデータベースから関連するソース付きのレッドフラグ情報を返します。

概要

3つの異なるワークフローがあります:

  1. 抽出 (Extraction) — LLMを使用してPDFやWebページからAMLレッドフラグを抽出し、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. red_flag_sources/pdflinks.txt にソースURLを追加する — 1行に1つのURLを順番に記述します。1行目はキー 001、2行目は 002 となります。

  2. PDFをダウンロードし、red_flag_sources/pdf/ に NNN_short_descriptive_name.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 で管理し、1行に1つの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 内のWeb URLは除外されます。

単一ソース(アドホック)

# 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. 文書の取得 — Webページをダウンロード(ナビゲーション、フッター、スクリプトを除去)するか、pdfplumberを介してPDFからテキストを読み取ります

  2. OpenAIへの送信 — gpt-4o-mini(OPENAI_EXTRACTION_MODEL で上書き可能)をプロンプトし、各AMLレッドフラグ指標を構造化JSONとして抽出します

  3. 検証 — 返された各フラグを RedFlagSource スキーマと照合し、無効なエントリは警告付きでスキップします

  4. YAMLの書き込み — data/source/<slug>.yaml に保存します(レッドフラグごとに1エントリ)

  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

初期のローカルコーパスについては、3つのターゲットファイルのみを取り込んでください:

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 を使用して埋め込みが生成され、data/vectors/ のLanceDBにレコードがアップサートされます。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 の3つのツールを公開します。取り込み後は完全にオフラインで動作し、クエリ時に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

ローカルの動作確認

3つのターゲットファイルを取り込んだ後、以下のツールで確認します:

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…

    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
    ResponsivenessOutdated data

    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
      -