redflag-mcp
redflag-mcp
AML 적신호 지식을 쿼리 가능한 도구로 제공하는 MCP 서버입니다. 컴플라이언스 담당자가 자연어로 질문하면 서버가 로컬 벡터 데이터베이스에서 관련 출처가 포함된 적신호 정보를 반환합니다.
개요
세 가지 주요 워크플로우:
추출(Extraction) — LLM을 사용하여 PDF나 웹 페이지에서 AML 적신호를 추출하고 YAML로 저장
수집(Ingestion) — YAML 파일을 임베딩하여 로컬 벡터 데이터베이스에 로드
쿼리(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 대량 추가 (권장 워크플로우)
단계별 안내:
red_flag_sources/pdflinks.txt에 원본 URL 추가 — 줄당 하나의 URL을 순차적으로 입력합니다. 1번 줄은 키001, 2번 줄은002등으로 매핑됩니다.PDF 다운로드 —
red_flag_sources/pdf/에NNN_short_descriptive_name.pdf형식으로 저장합니다. 여기서NNN은pdflinks.txt의 줄 번호와 일치해야 합니다.레지스트리 재생성:
uv run python scripts/build_sources_registry.py추출 실행:
uv run python scripts/extract.py --parallel
핵심 제약 사항: 파일 이름의
NNN_접두사는pdflinks.txt의 줄 번호와 일치해야 합니다. 1번 줄 =001_*.pdf, 2번 줄 =002_*.pdf등. 추출기는 이 방식을 통해 각 PDF를 공개 원본 URL에 연결합니다.
PDF는 red_flag_sources/pdf/에 저장되며, 0으로 채워진 일련번호 접두사를 사용하여 이름을 지정해야 합니다:
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의 웹 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을 채울 수 있도록 하십시오.
기능 설명
문서 가져오기 — 웹 페이지를 다운로드(탐색/푸터/스크립트 제거)하거나 pdfplumber를 통해 PDF에서 텍스트를 읽습니다.
OpenAI로 전송 —
gpt-4o-mini(또는OPENAI_EXTRACTION_MODEL로 재정의 가능)를 사용하여 모든 개별 AML 적신호 지표를 구조화된 JSON으로 추출합니다.검증 — 반환된 각 적신호는
RedFlagSource스키마에 따라 확인되며, 유효하지 않은 항목은 경고와 함께 건너뜁니다.YAML 작성 — 적신호당 하나의 항목으로
data/source/<slug>.yaml에 저장합니다.매니페스트 업데이트 — 재처리를 방지하기 위해
data/source/.extracted_sources.yaml에 소스를 기록합니다.
출력 스키마
YAML 파일의 각 항목은 다음 필드를 가집니다:
필드 | 타입 | 필수 | 설명 |
| string | 예 | 고유 식별자, 예: |
| string | 예 | 적신호 지표에 대한 독립적인 설명 |
| string | 아니오 | 원본 문서의 공개 URL |
| list[string] | 아니오 | 적용되는 금융 상품 (예: |
| list[string] | 아니오 | 적용되는 고객 산업 또는 부문 (예: |
| list[string] | 아니오 | 적용되는 고객 유형 (예: |
| list[string] | 아니오 | 관련 지역 또는 경로 (예: |
| string | 아니오 | 원본 문서 이름 또는 기관 (예: |
| string | 아니오 |
|
| string | 아니오 | AML 유형 (예: |
| string | 아니오 | 선택적 시뮬레이션 복잡도 코드 (예: |
중복 제거
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를 사용하여 임베딩을 생성하고 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 세 가지 도구를 제공합니다. 수집 후에는 완전히 오프라인으로 작동하며 쿼리 시 API 키가 필요하지 않습니다.
Codex에서 사용
로컬 Codex 스레드의 경우, Codex가 MCP 서버를 자동으로 시작할 수 있도록 stdio를 선호합니다:
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 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.
Hosted MCP server for pre-action AI governance verdicts, model routing, and evidence verification.
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
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-