@cyanheads/sanctions-screening-mcp-server

公開ホスト型サーバー: https://sanctions-screening.caseyjhand.com/mcp

[!IMPORTANT] これはスクリーニング支援ツールであり、法的・コンプライアンス上の認定ではありません。 各ツールは潜在的な一致候補を、透明性のあるスコアと出典の来歴とともに返します — 判定結果を返すことは決してありません。ヒットは「この候補を公式ソースと照合して確認してください」を意味し、空の結果が「クリア」を意味することは決してありません。実際の制裁コンプライアンスは法的プロセスです — 人間によるレビューと、資格のあるコンプライアンス判定が必要です。本サーバーはそのプロセスに情報を提供するものであり、プロセス自体を実行するものではなく、その出力はコンプライアンス記録ではありません。

概要

sanctions-screening-mcp-server は、世界のオープンな制裁データとグローバルな法人レジストリを、1つのスクリーニング・特定ワークフローに統合し、オフラインかつファジーマッチで応答します。米国（OFAC）、EU、英国、UNの統合制裁リストに対して氏名を一度にスクリーニングし、GLEIF Legal Entity Identifier（LEI）データベースに対して法人を特定し、企業所有権のトレースも行います。

すべてのソースは一括ダウンロード可能で、キー不要、再配布も明確に許可されています。サーバーはこれらをローカルのSQLite + FTS5インデックスにミラーリングし、そのミラーから一致結果を提供します — ライブAPIキーも、ホットパスでのリクエストごとのレート制限も不要です。エージェントにはスクリーニング動詞（screen_name、resolve_entity、trace_ownership）が見えます。どのリストがクエリに応答したかは、各ヒットの来歴としてのみ表面化します。

マッチングモデルは設計上透明です。まず厳密なトークンマッチング（正規化完全一致、次にFTS5による全トークン存在）を行い、スコア化されたJaro-Winkler + 音声学的ファジーフォールバックを実行します。近似ヒットには**生のJaro-Winkler類似度（0〜1）**が付与されます — これは実際の測定値であり、決して捏造された「信頼度パーセンテージ」ではありません。

Related MCP server: Sanctions Screening MCP Server

ツール

2つのワークフローを中心に6つのツールを構成 — ウォッチリストに対する氏名スクリーニングと、法人のグローバル識別子・所有権グラフへの特定です：

sanctions_screen_name

80%のエントリーポイント — 「このエンティティはウォッチリストに載っているか？」

• 4つの制裁リストすべて（OFAC SDN + Consolidated、EU、UK、UN）に1回の呼び出しで展開。ソースはヒットごとの来歴としてのみ表面化します

• エイリアス対応：公開されているすべての正式名称、a.k.a.、f.k.a.に対してマッチングします。正規名のみではありません

• 厳密モード（デフォルト）：正規化完全一致、次にFTS5による全トークン存在 — 語順の入れ替えや中間語の欠落を、ファジーライブラリなしで処理します

• ファジーモード（オプトイン、または厳密で何も見つからない場合に自動）：Jaro-Winkler類似度とDouble-Metaphone音声学的マッチングを追加し、翻字クラスのミスに対応します

• ヒットはexact / strong / approximateにラベル付け。近似ヒットには生のJaro-Winklerスコア（0〜1）に加えてqueryTokenCoverage — 候補が説明するクエリトークンの数 — が付与され、1つの共有完全一致トークンで同スコアに固定された候補の順位付けに使われます

• エンティティタイプ、ソースリストのサブセット、類似度下限（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つの上流ソースを集約します。すべて一括取得・キーレス・再配布可能です。

英国のソースはUK Sanctions List (UKSL) であり、2026年1月28日にOFSI Consolidated Listが閉鎖されて以降、英国の唯一の権威あるソースです。

初回実行：ミラーの構築

ミラーはバンドルされていません — 制裁リストとGLEIFゴールデンコピーは初回実行時にダウンロードされ正規化されます。スクリーニングの前に、帯域外で初期化ライフサイクルスクリプトを実行してください：

bun run mirror:init

これにより、5つの制裁リストがすべて完全にストリーミングされ、エイリアスごとの名前インデックスが再構築され、その後GLEIFゴールデンコピー（レベル1エンティティ + レベル2所有関係）がストリーミングされます。再開可能であり、リクエスト経路の外で一度だけ実行することを想定しています。

mirror:init に SANCTIONS_INIT_SKIP_GLEIF=1 を設定すると、制裁リストのみをロードしてGLEIFをスキップします。

メモリに関する注意： mirror:init の各段はストリーミングです。制裁ドキュメントは合計で約172 MBであり、そのうちOFACの SDN_ADVANCED.XML だけで約120 MBです。GLEIFレベル1ゴールデンコピーは約330万件のLEIレコード（圧縮で約892 MB、展開で数GB）です。各ソースは一度に1レコードずつスキャンされ、境界付きバッチで取り込まれるため、ピーク時の常駐メモリはソースドキュメントのサイズではなくバッチサイズに追従します。ミラー用のディスクをそれに応じて確保してください — GLEIFがそこを支配します — または、ウォッチリストのスクリーニングのみが必要な場合は SANCTIONS_INIT_SKIP_GLEIF=1 でGLEIFをスキップしてください。

機能

@cyanheads/mcp-ts-core 上に構築：

• 宣言的なツール・リソース・プロンプト定義 — プリミティブごとに単一ファイル、フレームワークが登録と検証を処理

• 統合されたエラーハンドリング — ハンドラーがスローし、フレームワークが捕捉・分類・整形

• リカバリヒント付きの型付きエラー契約（mirror_not_ready、designation_not_found、lei_not_found）

• プラグ可能な認証：none、jwt、oauth（デフォルトは none — すべてのデータは公開）

• オプションのOpenTelemetryトレーシング付き構造化ロギング

• STDIOおよびStreamable HTTPトランスポート

制裁固有：

• マルチソース・ワークフロー編成のサーフェス — 1つのスクリーニングが内部でOFAC、EU、UK、UNにファンアウト。ソースは出典としてのみ表面化

• フレームワークの MirrorService によるローカルSQLite + FTS5ミラー — オフライン、ライブAPIキー不要、リクエストごとのレート制限なし

• 4つの制裁リストにわたる正規化された共通スキーマ。非正規化されたエイリアスごとの名前インデックス（名前とエイリアスごとに1行）により、クエリがエンティティのいずれかの名前に1回のFTSスキャンで一致

• 厳密→ファジーのマッチング：完全正規化 → 全トークン存在（FTS5） → Jaro-Winkler + Double-Metaphone。短いクエリでの作業量を制限するために上限付き

• エンティティ解決と受益所有権トレーシングのためのGLEIFレベル1 + レベル2取り込み

エージェントに優しい出力：

• 合成の信頼度ではなく実際のシグナル — 近似ヒットは生のJaro-Winkler類似度（0〜1）とリテラルなクエリトークンカバレッジ件数を保持。これは1つのブレンドされた判定ではなく2つの別々の測定値。厳密ヒットは match_type（exact / strong）を保持し、捏造されたパーセンテージは決して含まない

• 呼び出し側が考慮できるランキング — ヒットはマッチタイプ、次にスコア、次にカバレッジ、次に安定した識別子の順に並び、同点を決めたカバレッジはヒット自体に含まれる

• すべてのヒットに出典 — ソースリスト、制裁プログラム、指定日、一致した正確な名前/エイリアス、およびその型（primary / aka / fka / low-quality-aka）

• すべてのスクリーニングツールの出力に含まれる意思決定支援の注意事項 — ヒットは検証すべき候補であり、空の結果はクリアランスではない

• sanctions_list_sources による鮮度の表面化 — 各ソースのレコード件数とミラーのas-ofタイムスタンプにより、エージェントが陳腐化を判断可能

はじめに

公開ホステッドインスタンス

公開インスタンスは 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レベル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（自由に再配布可能）。

• UK制裁リスト — 英国外務・英連邦・開発省、Open Government Licence v3.0の下でライセンス（帰属表示が必要）。

• UN安全保障理事会統合リスト — 国際連合安全保障理事会（自由に再配布可能）。

• GLEIF LEIデータ — Global Legal Entity Identifier Foundation、CC0 1.0 Universal。

貢献

Issueとプルリクエストを歓迎します。提出前にチェックとテストを実行してください：

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細はLICENSEを参照してください。