@cyanheads/sanctions-screening-mcp-server

공개 호스팅 서버: https://sanctions-screening.caseyjhand.com/mcp

[!IMPORTANT] 이 도구는 스크리닝 보조 도구이지 법률 또는 컴플라이언스 인증이 아닙니다. 모든 도구는 투명한 점수와 출처 정보를 포함한 잠재적 매치를 반환할 뿐, 판정을 내리지 않습니다. 매치가 발생했다는 것은 "공식 출처에서 이 후보를 검토하라"는 의미이며, 결과가 비어 있다고 해서 "이상 없음"을 의미하지 않습니다. 실제 제재 컴플라이언스는 법적 절차입니다 — 인간의 검토와 자격을 갖춘 컴플라이언스 판정이 필요합니다. 이 서버는 그러한 절차를 지원할 뿐, 절차를 대신 수행하지 않으며, 그 출력물은 컴플라이언스 기록이 아닙니다.

개요

sanctions-screening-mcp-server는 전 세계의 공개 제재 데이터와 글로벌 법인 등록부를 하나의 스크리닝 및 식별 워크플로우로 통합하며, 오프라인에서 퍼지 매칭으로 응답합니다. 미국(OFAC), EU, UK, UN 통합 제재 명단에 대해 이름을 한 번에 스크리닝하고, GLEIF 법인식별코드(LEI) 데이터베이스에 대해 법인을 식별하며 기업 소유권 추적까지 제공합니다.

모든 소스는 대량 다운로드가 가능하고, 키가 필요 없으며, 재배포가 명확히 허용됩니다. 이 서버는 해당 소스를 로컬 SQLite + FTS5 인덱스로 미러링하고 그 미러에서 매치를 제공합니다 — 실시간 API 키도, 핫 경로의 요청별 속도 제한도 없습니다. 에이전트는 스크리닝 동사(screen_name, resolve_entity, trace_ownership)를 볼 수 있으며, 어떤 명단이 쿼리에 응답했는지는 각 히트의 출처 정보로만 표시됩니다.

매칭 모델은 설계상 투명합니다: 먼저 엄격한 토큰 매칭(정규화된 정확 일치, 그 다음 FTS5를 통한 전체 토큰 포함)을 수행하고, 점수가 매겨진 Jaro-Winkler + 음성학적 퍼지 폴백을 사용합니다. 근사 히트에는 원시 Jaro-Winkler 유사도(0–1) 가 포함됩니다 — 실제 측정값이며, 결코 조작된 "신뢰도 백분율"이 아닙니다.

Related MCP server: sanctionwise

도구

두 가지 워크플로우를 중심으로 구성된 여섯 가지 도구 — 워치리스트에 대해 이름을 스크리닝하고, 법인을 글로벌 식별자 및 소유권 그래프로 식별합니다:

sanctions_screen_name

80% 진입점 — "이 엔티티가 워치리스트에 있나?"

• 네 개의 제재 명단(OFAC SDN + Consolidated, EU, UK, UN) 전체에 한 번의 호출로 분산 실행됩니다. 소스는 각 히트의 출처 정보로만 표시됩니다

• 별칭 인식: 정식 이름뿐만 아니라 게시된 모든 기본 이름, a.k.a., f.k.a.에 대해 매칭합니다

• 엄격 모드(기본값): 정규화된 정확 일치, 그 다음 FTS5를 통한 전체 토큰 포함 — 퍼지 라이브러리 없이 단어 순서 변경과 내부 단어 누락을 처리합니다

• 퍼지 모드(옵트인, 또는 엄격 모드에서 결과가 없을 때 자동): 음역 계열 누락을 위해 Jaro-Winkler 유사도와 Double-Metaphone 음성학적 매칭을 추가합니다

• 히트는 exact / strong / approximate로 분류됩니다. 근사 히트에는 원시 Jaro-Winkler 점수(0–1)와 queryTokenCoverage — 후보가 설명하는 쿼리 토큰 수 — 가 포함되어, 동일한 점수에서 하나의 공유 정확 토큰으로 고정된 후보들의 순위를 매깁니다

• 엔티티 유형, 소스 목록 하위 집합, 유사도 하한(min_score), 결과 제한으로 필터링합니다

• 페이지네이션: totalAvailable과 hasMore가 반환된 페이지 너머의 매치를 보고하고 nextOffset으로 이를 검색합니다. totalAvailableBasis는 해당 수가 정확한 값(엄격)인지 스캔된 집합의 하한(퍼지)인지 표시합니다

• 결과가 비어 있으면 검색 범위를 넓히는 방법에 대한 안내를 반환하며, 매치가 없다는 것이 이상 없음이 아님을 명시적으로 밝힙니다

sanctions_get_designation

sanctions_screen_name이 후보를 표면화한 후의 상세 조회입니다.

• source + entry_id(스크린 히트의 sourceEntryId)로 전체 정규화 레코드를 가져옵니다

• 게시된 모든 별칭, 구조화된 식별자(여권/국가 ID/세금/등록), 주소, 생년월일 및 출생지, 국적, 제재 프로그램, 법적 근거, 지정 날짜

• 소스의 희소성을 보존합니다 — 누락된 필드는 소스가 해당 정보를 제공하지 않았음을 의미하며, 레코드는 결코 조작된 데이터로 채워지지 않습니다

sanctions_resolve_entity

자유 형식의 거래 상대방 이름에서 엔티티 도구가 키로 사용하는 안정적인 LEI로의 브리지입니다.

• 회사/조직 이름을 순위가 매겨진 GLEIF LEI 후보로 식별합니다

• 선택적 ISO 3166-1 alpha-2 관할권 필터와 등록 상태 필터(issued 기본값, lapsed, 또는 any)

• 이름 스크리닝과 동일한 엄격-후-퍼지 매칭 모델을 사용합니다. 근사 히트에는 원시 Jaro-Winkler 점수와 동일한 queryTokenCoverage 수가 포함됩니다

• 법적 이름과 게시된 기타/상호에 대해 매칭합니다

• sanctions_screen_name과 동일한 계약으로 페이지네이션됩니다 — totalAvailable, totalAvailableBasis, hasMore, nextOffset

sanctions_get_entity

이 법인은 누구인가 — 그리고 같은 호출에서 워치리스트 교차 참조까지 제공합니다.

• 전체 GLEIF Level 1 레코드: 법적 이름, 기타/상호, 법적 및 본사 주소, 등록 상태, 관할권, 등록 기관 및 ID, 최종 업데이트 날짜

• 엔티티의 법적 이름을 로드된 모든 워치리스트에 대해 교차 참조합니다(엄격 매칭만 — 일반적인 법적 이름에 자동 퍼지를 적용하면 단일 공통 토큰으로 인한 오탐이 넘쳐날 수 있습니다)

• screeningStatus는 해당 교차 참조가 실제로 실행되었는지 여부를 나타냅니다. not_ready 상태의 빈 히트 목록은 제재 미러를 사용할 수 없었음을 의미하지, 매치가 없었다는 의미가 아닙니다

• 스크리닝된 엔티티는 sanctionsScreen — totalAvailable, totalAvailableBasis, hasMore — 을 포함합니다. 히트 목록이 25개로 제한되므로, 전체 집합을 보려면 sanctions_screen_name으로 법적 이름을 다시 스크리닝하세요

• LEI 입력은 정규식으로 검증됩니다(20자: 영숫자 18자 + 체크 숫자 2자)

sanctions_trace_ownership

실소유자 스크리닝 — 단일 명단 도구로는 불가능한 교차 소스 워크플로우입니다.

• GLEIF Level 2 소유권 그래프를 제한된 깊이(1–5)까지 너비 우선으로 탐색합니다

• direction: parents(누가 소유하는지), children(무엇을 소유하는지), 또는 both 방향으로 탐색합니다

• 역할과 깊이가 포함된 노드와 관계 유형이 포함된 방향성 소유권 엣지를 반환합니다

• screenNodes: true는 그래프의 모든 엔티티를 모든 워치리스트에 대해 스크리닝합니다 — "이 소유권 체인에 제재 대상이 있나?"

• 노드별 스크리닝은 엄격 모드만 사용하며 screenedNodeCount / flaggedNodeCount를 보고하여 호출자가 적용 범위를 한눈에 확인할 수 있습니다

• 그래프가 알려진 전체 그림인지 보고합니다: complete, truncated(요청된 깊이 너머에 추가 관계가 존재), missingEntityLeis(GLEIF Level 1 레코드가 없는 노드 — 법적 이름 자리에 LEI가 표시됨)

• screeningStatus는 완료된 노드 스크리닝, 요청되지 않은 스크리닝, 제재 미러가 실행할 수 없었던 스크리닝을 구분합니다. 각 스크리닝된 노드는 sanctionsScreen — totalAvailable, totalAvailableBasis, hasMore — 을 포함합니다. 히트 목록이 10개로 제한되기 때문입니다

리소스 및 프롬프트

모든 리소스 데이터는 도구를 통해서도 접근할 수 있으며, 도구는 도구 전용 MCP 클라이언트의 기본 경로입니다. 리소스는 리소스 지원 클라이언트를 위한 편의 기능일 뿐입니다.

소스 리스트

서버는 스크리닝 표면 뒤에서 5개의 업스트림 소스를 집계합니다. 모두 대량, 키 없음, 재배포 가능입니다.

영국 소스는 영국 제재 목록 (UKSL) 으로, OFSI 통합 목록이 2026년 1월 28일에 종료된 이후 영국의 단일 공식 소스입니다.

첫 실행: 미러 채우기

미러는 번들로 포함되지 않습니다 — 제재 목록과 GLEIF 골든 카피는 첫 실행 시 다운로드되어 정규화됩니다. 스크리닝 전에 초기화 수명주기 스크립트를 대역 외로 실행하세요:

bun run mirror:init

이 명령은 5개 제재 목록 전체를 스트리밍하고, 별칭별 이름 인덱스를 재구축한 다음, GLEIF 골든 카피(Level 1 엔티티 + Level 2 소유권 관계)를 스트리밍합니다. 재개 가능하며 요청 경로 밖에서 한 번 실행하도록 설계되었습니다.

mirror:init에 SANCTIONS_INIT_SKIP_GLEIF=1을 설정하면 제재 목록만 로드하고 GLEIF를 건너뜁니다.

메모리 참고: mirror:init의 모든 구간은 스트리밍됩니다. 제재 문서는 총 약 172MB이며, 그중 OFAC SDN_ADVANCED.XML만 약 120MB입니다. GLEIF Level 1 골든 카피는 약 330만 개의 LEI 레코드(압축 시 약 892MB, 압축 해제 시 수 GB)입니다. 각 소스는 레코드 단위로 스캔되어 제한된 배치로 수집되므로, 최대 상주 메모리는 소스 문서 크기가 아닌 배치 크기를 따릅니다. 이에 따라 미러용 디스크를 계획하세요 — GLEIF가 지배적입니다 — 또는 감시 목록 스크리닝만 필요한 경우 SANCTIONS_INIT_SKIP_GLEIF=1로 GLEIF를 건너뛰세요.

기능

@cyanheads/mcp-ts-core 기반:

• 선언적 도구, 리소스, 프롬프트 정의 — 프리미티브당 단일 파일, 프레임워크가 등록 및 검증 처리

• 통합 오류 처리 — 핸들러가 throw하면 프레임워크가 포착, 분류, 포맷

• 복구 힌트가 포함된 타입화된 오류 계약(mirror_not_ready, designation_not_found, lei_not_found)

• 플러그형 인증: none, jwt, oauth(기본값 none — 모든 데이터는 공개)

• 선택적 OpenTelemetry 추적이 포함된 구조화 로깅

• STDIO 및 Streamable HTTP 전송

제재 특화:

• 다중 소스, 워크플로우 기반 표면 — 단일 스크린이 내부적으로 OFAC, EU, UK, UN에 걸쳐 팬아웃됩니다. 소스는 출처(provenance)로만 표시됩니다.

• 프레임워크 MirrorService를 통한 로컬 SQLite + FTS5 미러 — 오프라인, 라이브 API 키 불필요, 요청별 속도 제한 없음

• 4개 제재 목록에 걸친 정규화된 공통 스키마, 비정규화된 별칭별 이름 인덱스(이름 및 별칭당 한 행)로 단일 FTS 스캔에서 엔티티의 모든 이름을 매칭

• 엄격-후-퍼지 매칭: 정규화 정확 → 전체 토큰 존재(FTS5) → Jaro-Winkler + Double-Metaphone, 짧은 쿼리의 작업량을 제한

• 엔티티 해석 및 실소유권 추적을 위한 GLEIF Level 1 + Level 2 수집

에이전트 친화적 출력:

• 실제 신호, 합성 신뢰도 아님 — 근사 히트는 원시 Jaro-Winkler 유사도(0–1)와 리터럴 쿼리 토큰 커버리지 개수를 별도 측정값으로 전달합니다(단일 혼합 판정이 아닌 두 개의 별도 측정). 엄격 히트는 match_type(exact / strong)을 전달하며, 조작된 백분율을 전달하지 않습니다.

• 호출자가 고려할 수 있는 순위 — 히트는 매치 유형, 점수, 커버리지, 안정적 식별자 순으로 정렬되며, 동점을 깬 커버리지가 히트 자체에 포함됩니다.

• 모든 히트에 출처 포함 — 소스 목록, 제재 프로그램, 지정 날짜, 매칭된 정확한 이름/별칭 및 그 유형(primary / aka / fka / low-quality-aka)

• 모든 스크리닝 도구 출력에 의사결정 지원 주의사항 포함 — 히트는 검증할 후보이며, 빈 결과는 클리어런스가 아닙니다.

• sanctions_list_sources를 통해 신선도 표시 — 각 소스의 레코드 수와 미러의 기준 시점 타임스탬프로 에이전트가 오래된 정도를 판단할 수 있습니다.

시작하기

공개 호스팅 인스턴스

공개 인스턴스는 https://sanctions-screening.caseyjhand.com/mcp에서 사용할 수 있습니다 — 설치가 필요 없습니다. Streamable HTTP를 통해 모든 MCP 클라이언트를 이 주소로 연결하세요. 클라이언트 구성은 다음과 같습니다:

{
  "mcpServers": {
    "sanctions-screening-mcp-server": {
      "type": "streamable-http",
      "url": "https://sanctions-screening.caseyjhand.com/mcp"
    }
  }
}

자체 호스팅 / 로컬

MCP 클라이언트 구성 파일에 다음을 추가하세요. 서버는 오프라인 우선입니다 — 스크리닝 전에 bun run mirror:init으로 미러를 채우세요(소스 리스트 참조).

{
  "mcpServers": {
    "sanctions-screening-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/sanctions-screening-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

또는 npx 사용(Bun 불필요):

{
  "mcpServers": {
    "sanctions-screening-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/sanctions-screening-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Streamable HTTP의 경우 전송을 설정하고 서버를 시작하세요:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

사전 요구 사항

• Bun v1.3 이상(또는 Node.js v24+).

• 로컬 미러용 디스크(채워진 SQLite 파일, GLEIF Level 1이 지배적). 모든 소스에 API 키가 필요 없습니다.

설치

1. 저장소 클론:

git clone https://github.com/cyanheads/sanctions-screening-mcp-server.git

2. 디렉터리로 이동:

cd sanctions-screening-mcp-server

3. 의존성 설치:

bun install

4. 환경 구성:

cp .env.example .env
# edit .env if you need to override defaults (all optional)

5. 미러 채우기:

bun run mirror:init

구성

모든 소스는 키가 없습니다 — 필수 API 키가 없습니다. 아래 모든 변수는 선택 사항이며 합리적인 기본값이 있습니다.

소스 URL은 기본적으로 검증된 공식 엔드포인트를 사용하며, 재정의 값은 테스트 및 제한된 환경에서 미러를 고정하기 위해 존재합니다. EU "토큰"은 자격 증명이 아닌 정적 공개 경로 구성 요소입니다.

전체 선택적 재정의 목록은 .env.example을 참조하세요.

서버 실행

로컬 개발

• 빌드 및 실행:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• 검사 및 테스트 실행:

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t sanctions-screening-mcp-server .
docker run --rm -p 3010:3010 -v sanctions-data:/usr/src/app/data sanctions-screening-mcp-server

Dockerfile은 기본적으로 HTTP 전송, 무상태 세션 모드를 사용하며 로그는 /var/log/sanctions-screening-mcp-server에 기록합니다. 이미지는 Bun에서 실행되므로 미러는 bun:sqlite를 사용합니다 (네이티브 빌드 불필요). 미러 경로(/usr/src/app/data 기본값)에 볼륨을 마운트하여 채워진 미러가 컨테이너 재시작 후에도 유지되도록 하고, 컨테이너 내부에서 bun run mirror:init(docker exec)을 실행하여 미러를 채웁니다. OpenTelemetry 피어 의존성은 기본적으로 설치됩니다. 이를 제외하려면 --build-arg OTEL_ENABLED=false로 빌드하세요.

프로젝트 구조

개발 가이드

개발 지침 및 아키텍처 규칙은 CLAUDE.md/AGENTS.md를 참조하세요. 요약:

• 핸들러가 예외를 던지고 프레임워크가 처리합니다 — 도구 로직에 try/catch 없음

• 요청 범위 로깅에는 ctx.log를, 테넌트 범위 저장소에는 ctx.state를 사용하세요

• src/mcp-server/*/definitions/index.ts의 배럴을 통해 새 도구와 리소스를 등록하세요

• 외부 소스 래핑: 원시 데이터 검증 → 공통 스키마로 정규화 → 출력 스키마 반환. 소스가 생략한 필드를 임의로 만들지 말고, 신뢰도 점수를 합성하지 마세요

출처 표기

이 서버는 다음 출처의 공개 데이터를 재배포하며, 각각의 조건에 따라 인용합니다:

• OFAC SDN 및 Consolidated 목록 — 미국 재무부 해외자산통제국 (미국 정부 공공 영역).

• EU 통합 금융 제재 목록 — 유럽 위원회 / EEAS (자유 재배포 가능).

• 영국 제재 목록 — 영국 외무·영연방·개발부, Open Government Licence v3.0에 따라 라이선스 (출처 표기 필요).

• UN 안전보장이사회 통합 목록 — 유엔 안전보장이사회 (자유 재배포 가능).

• GLEIF LEI 데이터 — Global Legal Entity Identifier Foundation, CC0 1.0 Universal.

기여

이슈 및 풀 리퀘스트를 환영합니다. 제출 전에 검사와 테스트를 실행하세요:

bun run devcheck
bun run test

라이선스

Apache-2.0 — 자세한 내용은 LICENSE를 참조하세요.