@cyanheads/sanctions-screening-mcp-server

Öffentlich gehosteter Server: https://sanctions-screening.caseyjhand.com/mcp

[!WICHTIG] Dies ist eine Screening-Hilfe, keine Rechts- oder Compliance-Zertifizierung. Jedes Tool gibt potenzielle Treffer mit einem transparenten Score und Quellen-Herkunft zurück – niemals ein Urteil. Ein Treffer bedeutet „prüfen Sie diesen Kandidaten gegen die offizielle Quelle"; ein leeres Ergebnis bedeutet niemals „freigegeben". Echte Sanktions-Compliance ist ein rechtlicher Prozess – sie erfordert menschliche Prüfung und eine qualifizierte Compliance-Feststellung. Dieser Server speist diesen Prozess; er führt ihn nicht aus, und seine Ausgabe ist kein Compliance-Nachweis.

Überblick

sanctions-screening-mcp-server verwandelt die offenen Sanktionsdaten der Welt plus das globale Register juristischer Personen in einen einzigen Screening- und Auflösungs-Workflow, der offline beantwortet und Fuzzy-gematcht wird. Er prüft einen Namen gleichzeitig gegen die konsolidierten US- (OFAC), EU-, UK- und UN-Sanktionslisten und löst juristische Personen gegen die GLEIF Legal Entity Identifier (LEI)-Datenbank mit Nachverfolgung von Unternehmenseigentümern auf.

Alle Quellen sind als Bulk-Download verfügbar, schlüssellos und für die Weiterverbreitung freigegeben. Der Server spiegelt sie in einen lokalen SQLite- + FTS5-Index und liefert Treffer aus diesem Spiegel – kein Live-API-Schlüssel, keine Rate-Limitierung pro Anfrage auf dem heißen Pfad. Der Agent sieht Screening-Verben (screen_name, resolve_entity, trace_ownership); welche Liste eine Abfrage beantwortet hat, erscheint nur als Herkunft auf jedem Treffer.

Das Matching-Modell ist von Design her transparent: zuerst strikter Token-Match (exakt-normalisiert, dann alle-Token-vorhanden über FTS5), mit einem bewerteten Jaro-Winkler- + phonetischen Fuzzy-Fallback. Näherungstreffer tragen die rohe Jaro-Winkler-Ähnlichkeit (0–1) – eine echte Messung, niemals ein erfundener „Konfidenzprozentsatz".

Related MCP server: sanctionwise

Tools

Sechs Tools, organisiert um zwei Workflows – prüfen Sie einen Namen gegen die Watchlists und lösen Sie eine juristische Person zu ihrer globalen Kennung und ihrem Eigentümer-Graphen auf:

sanctions_screen_name

Der 80-%-Einstiegspunkt – „ist diese Entität auf einer Watchlist?"

• Fächert in einem einzigen Aufruf über alle vier Sanktionslisten (OFAC SDN + Consolidated, EU, UK, UN) auf; die Quelle erscheint nur als Herkunft pro Treffer

• Alias-bewusst: matcht gegen jeden veröffentlichten Primärnamen, a.k.a. und f.k.a., nicht nur den kanonischen Namen

• Strikter Modus (Standard): exakt-normalisierte Gleichheit, dann alle-Token-vorhanden über FTS5 – behandelt Wortreihenfolge-Vertauschungen und fehlende Binnenwörter ohne Fuzzy-Bibliothek

• Fuzzy-Modus (opt-in oder automatisch, wenn strikt nichts findet): fügt Jaro-Winkler-Ähnlichkeit und Double-Metaphone-Phonetik-Matching für Transliterationsklassen-Fehltreffer hinzu

• Treffer als exact / strong / approximate gekennzeichnet; Näherungstreffer tragen den rohen Jaro-Winkler-Score (0–1) plus queryTokenCoverage – wie viele Abfrage-Tokens der Kandidat erklärt, was Kandidaten einstuft, die ein einziges gemeinsames exaktes Token auf denselben Score pinnt

• Filter nach Entitätstyp, Teilmengen der Quellenliste, Ähnlichkeitsuntergrenze (min_score) und Ergebnislimit

• Paginiert: totalAvailable und hasMore melden Treffer jenseits der zurückgegebenen Seite, und nextOffset ruft sie ab, wobei totalAvailableBasis diese Zahl als exakt (strikt) oder als Untergrenze des gescannten Satzes (Fuzzy) kennzeichnet

• Bei einem leeren Ergebnis gibt es Hinweise zur Verbreiterung der Suche zurück – und stellt ausdrücklich klar, dass ein fehlender Treffer keine Freigabe ist

sanctions_get_designation

Der Drill-in, nachdem sanctions_screen_name einen Kandidaten aufgespürt hat.

• Vollständiger normalisierter Datensatz nach source + entry_id (die sourceEntryId aus einem Screen-Treffer)

• Alle veröffentlichten Aliase, strukturierten Kennungen (Reisepass / Personalausweis / Steuer / Registrierung), Adressen, Geburtsdaten und -orte, Staatsangehörigkeiten, sanktionierendes Programm, Rechtsgrundlage und Designationsdatum

• Bewahrt die Sparsamkeit der Quelle – fehlende Felder bedeuten, dass die Quelle sie weggelassen hat; der Datensatz wird niemals mit erfundenen Daten aufgefüllt

sanctions_resolve_entity

Die Brücke von einem Freitext-Gegenparteinamen zu einer stabilen LEI, auf die die Entitäts-Tools aufbauen.

• Löst einen Unternehmens-/Organisationsnamen zu eingestuften GLEIF-LEI-Kandidaten auf

• Optionaler ISO-3166-1-alpha-2-Gerichtsbarkeitsfilter und Registrierungsstatus-Filter (issued Standard, lapsed oder any)

• Dasselbe strikt-dann-fuzzy-Matching-Modell wie beim Namens-Screening; Näherungstreffer tragen den rohen Jaro-Winkler-Score und dieselbe queryTokenCoverage-Zählung

• Matcht gegen Rechtsnamen und veröffentlichte andere/Handelsnamen

• Paginiert nach demselben Vertrag wie sanctions_screen_name – totalAvailable, totalAvailableBasis, hasMore, nextOffset

sanctions_get_entity

Wer ist diese juristische Person – plus eine Watchlist-Kreuzreferenz im selben Aufruf.

• Vollständiger GLEIF-Level-1-Datensatz: Rechtsname, andere/Handelsnamen, Rechts- und Hauptsitzadressen, Registrierungsstatus, Gerichtsbarkeit, Registrierungsbehörde und -ID, Datum der letzten Aktualisierung

• Kreuzreferenziert den Rechtsnamen der Entität gegen alle geladenen Watchlists (nur strikter Match – Auto-Fuzzy bei einem generischen Rechtsnamen würde das Ergebnis mit False Positives aus einem einzigen gemeinsamen Token überfluten)

• screeningStatus sagt aus, ob diese Kreuzreferenz tatsächlich gelaufen ist: eine leere Trefferliste unter not_ready bedeutet, dass der Sanktionsspiegel nicht verfügbar war, nicht dass nichts gematcht hat

• Eine geprüfte Entität trägt sanctionsScreen – totalAvailable, totalAvailableBasis, hasMore – da die Trefferliste auf fünfundzwanzig begrenzt ist; prüfen Sie den Rechtsnamen für den vollständigen Satz erneut mit sanctions_screen_name

• LEI-Eingabe ist Regex-validiert (20 Zeichen: 18 alphanumerische + 2 Prüfziffern)

sanctions_trace_ownership

Screening wirtschaftlicher Eigentümer – der quellenübergreifende Workflow, den Einzel-Listen-Tools nicht leisten können.

• Durchläuft den GLEIF-Level-2-Eigentümergraphen breitenzuerst bis zu einer begrenzten Tiefe (1–5)

• direction: geht zu parents (wer besitzt es), children (was es besitzt) oder both

• Gibt Knoten (mit Rolle und Tiefe) und gerichtete Eigentumskanten mit Beziehungstyp zurück

• screenNodes: true prüft jede Entität im Graphen gegen alle Watchlists – „ist irgendjemand in dieser Eigentumskette sanktioniert?"

• Die Prüfung pro Knoten ist nur-strikt und meldet screenedNodeCount / flaggedNodeCount, damit ein Aufrufer die Abdeckung auf einen Blick sieht

• Meldet, ob der Graph das vollständige bekannte Bild ist: complete, truncated (weitere Beziehungen existieren jenseits der angeforderten Tiefe) und missingEntityLeis (Knoten ohne GLEIF-Level-1-Datensatz, die ihre LEI dort tragen, wo ein Rechtsname stünde)

• screeningStatus trennt eine abgeschlossene Knotenprüfung von einer nie angeforderten und einer, die der Sanktionsspiegel nicht ausführen konnte; jeder geprüfte Knoten trägt sanctionsScreen – totalAvailable, totalAvailableBasis, hasMore – da seine Trefferliste auf zehn begrenzt ist

Ressourcen und Prompts

Alle Ressourcendaten sind auch über die Tools erreichbar, die der primäre Pfad für reine Tool-MCP-Clients sind. Die Ressourcen sind ein Komfort für ressourcenfähige Clients.

Quellenlisten

Der Server aggregiert fünf vorgelagerte Quellen hinter der Screening-Oberfläche. Alle sind Bulk-Daten, schlüssellos und für die Weiterverbreitung freigegeben.

Die britische Quelle ist die UK Sanctions List (UKSL), die einzige maßgebliche britische Quelle, seit die OFSI Consolidated List am 28. Januar 2026 geschlossen wurde.

Erster Start: Spiegel befüllen

Der Spiegel ist nicht gebündelt — die Sanktionslisten und die GLEIF-Goldkopie werden beim ersten Start heruntergeladen und normalisiert. Führen Sie das Init-Lifecycle-Skript außerhalb des Request-Pfads aus, bevor Sie screenen:

bun run mirror:init

Dies streamt alle fünf Sanktionslisten vollständig, baut den Namensindex pro Alias neu auf und streamt dann die GLEIF-Goldkopie (Level-1-Entitäten + Level-2-Eigentumsbeziehungen). Es ist fortsetzbar und für einen einmaligen Lauf außerhalb des Request-Pfads gedacht.

Setzen Sie SANCTIONS_INIT_SKIP_GLEIF=1 bei mirror:init, um nur die Sanktionslisten zu laden und GLEIF zu überspringen.

Hinweis zum Speicher: Jeder Abschnitt von mirror:init streamt. Die Sanktionsdokumente umfassen insgesamt etwa 172 MB, wovon OFAC SDN_ADVANCED.XML allein etwa 120 MB ausmacht; die GLEIF-Level-1-Goldkopie umfasst etwa 3,3 Mio. LEI-Datensätze (~892 MB komprimiert, mehrere GB dekomprimiert). Jede Quelle wird Datensatz für Datensatz gescannt und in begrenzten Batches übernommen, sodass der Spitzenspeicher der Batch-Größe folgt und nicht der Größe eines Quelldokuments. Dimensionieren Sie den Plattenplatz für den Spiegel entsprechend — GLEIF dominiert dort — oder überspringen Sie GLEIF mit SANCTIONS_INIT_SKIP_GLEIF=1, wenn Sie nur Watchlist-Screening benötigen.

Funktionen

Basiert auf @cyanheads/mcp-ts-core:

• Deklarative Tool-, Ressourcen- und Prompt-Definitionen — eine Datei pro Primitive, das Framework übernimmt Registrierung und Validierung

• Vereinheitlichte Fehlerbehandlung — Handler werfen, das Framework fängt, klassifiziert und formatiert

• Typisierte Fehlerverträge mit Wiederherstellungshinweisen (mirror_not_ready, designation_not_found, lei_not_found)

• Plug-in-fähige Authentifizierung: none, jwt, oauth (Standard ist none — alle Daten sind öffentlich)

• Strukturierte Protokollierung mit optionalem OpenTelemetry-Tracing

• STDIO- und Streamable-HTTP-Transports

Sanktionsspezifisch:

• Multi-Quellen-, workflow-organisierte Oberfläche — ein Screen fächert intern über OFAC, EU, UK und UN auf; Quellen erscheinen nur als Herkunft

• Lokaler SQLite- + FTS5-Spiegel über den Framework-MirrorService — offline, kein Live-API-Schlüssel, kein Rate-Limit pro Anfrage

• Normalisiertes gemeinsames Schema über die vier Sanktionslisten, mit einem denormalisierten Namensindex pro Alias (eine Zeile pro Name und pro Alias), sodass eine Abfrage jeden Namen einer Entität in einem einzigen FTS-Scan findet

• Streng-dann-Fuzzy-Matching: exakt-normalisiert → alle Token vorhanden (FTS5) → Jaro-Winkler + Double-Metaphone, begrenzt, um den Aufwand bei kurzen Abfragen zu beschränken

• GLEIF-Level-1- + Level-2-Ingest für Entitätsauflösung und Nachverfolgung wirtschaftlicher Eigentümer

Agentenfreundliche Ausgabe:

• Echtes Signal, keine synthetische Konfidenz — ungefähre Treffer tragen die rohe Jaro-Winkler-Ähnlichkeit (0–1) und eine wörtliche Abfrage-Token-Abdeckungszahl, zwei getrennte Messungen statt eines vermischten Urteils; strenge Treffer tragen einen match_type (exact / strong), nie einen erfundenen Prozentsatz

• Rangfolge, die ein Aufrufer berücksichtigen kann — Treffer sortieren nach Matchentyp, dann Punktzahl, dann Abdeckung, dann einer stabilen Kennung, und die Abdeckung, die das Gleichgewicht gebrochen hat, steht auf dem Treffer selbst

• Herkunft auf jedem Treffer — Quellenliste, Sanktionsprogramm, Benennungsdatum, der exakte Name/Alias, der gematcht hat, und sein Typ (primary / aka / fka / low-quality-aka)

• Entscheidungshinweis in der Ausgabe jedes Screening-Tools — ein Treffer ist ein Kandidat zur Verifizierung, ein leeres Ergebnis ist keine Freigabe

• Aktualität über sanctions_list_sources sichtbar — Datensatzzahl jeder Quelle und der As-of-Zeitstempel des Spiegels, damit ein Agent Veraltung beurteilen kann

Erste Schritte

Öffentlich gehostete Instanz

Eine öffentliche Instanz ist unter https://sanctions-screening.caseyjhand.com/mcp verfügbar — keine Installation erforderlich. Richten Sie einen beliebigen MCP-Client per Streamable HTTP darauf aus, mit dieser Client-Konfiguration:

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

Selbst gehostet / lokal

Fügen Sie Folgendes zu Ihrer MCP-Client-Konfigurationsdatei hinzu. Der Server ist offline-first — befüllen Sie den Spiegel mit bun run mirror:init, bevor Sie screenen (siehe Quellenlisten).

{
  "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"
      }
    }
  }
}

Oder mit npx (kein Bun erforderlich):

{
  "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"
      }
    }
  }
}

Für Streamable HTTP setzen Sie den Transport und starten den Server:

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

Voraussetzungen

• Bun v1.3 oder höher (oder Node.js v24+).

• Plattenplatz für den lokalen Spiegel (die befüllten SQLite-Dateien; GLEIF Level 1 dominiert). Kein API-Schlüssel für irgendeine Quelle.

Installation

1. Repository klonen:

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

2. In das Verzeichnis wechseln:

cd sanctions-screening-mcp-server

3. Abhängigkeiten installieren:

bun install

4. Umgebung konfigurieren:

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

5. Spiegel befüllen:

bun run mirror:init

Konfiguration

Alle Quellen sind schlüssellos — es gibt keinen erforderlichen API-Schlüssel. Jede der folgenden Variablen ist optional und hat einen sinnvollen Standardwert.

Quell-URLs standardmäßig auf die verifizierten offiziellen Endpunkte; Überschreibungen existieren für Tests und zum Festlegen eines Spiegels in eingeschränkten Umgebungen. Das EU-„Token“ ist eine statische öffentliche Pfadkomponente, keine Anmeldeinformation.

Siehe .env.example für die vollständige Liste optionaler Überschreibungen.

Ausführen des Servers

Lokale Entwicklung

• Erstellen und ausführen:

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

• Prüfungen und Tests ausführen:

  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

Das Dockerfile verwendet standardmäßig HTTP-Transport, zustandslosen Sitzungsmodus und protokolliert nach /var/log/sanctions-screening-mcp-server. Das Image läuft unter Bun, daher verwendet der Spiegel bun:sqlite (kein nativer Build). Mounten Sie ein Volume am Spiegelpfad (standardmäßig /usr/src/app/data), damit der befüllte Spiegel Container-Neustarts übersteht, und führen Sie bun run mirror:init im Container (docker exec) aus, um ihn zu befüllen. OpenTelemetry-Peer-Abhängigkeiten werden standardmäßig installiert – bauen Sie mit --build-arg OTEL_ENABLED=false, um sie wegzulassen.

Projektstruktur

Entwicklungsleitfaden

Siehe CLAUDE.md/AGENTS.md für Entwicklungsrichtlinien und Architekturregeln. Die Kurzfassung:

• Handler werfen, Framework fängt – kein try/catch in der Tool-Logik

• Verwenden Sie ctx.log für anforderungsbezogenes Logging, ctx.state für mandantenbezogenen Speicher

• Registrieren Sie neue Tools und Ressourcen über die Barrels in src/mcp-server/*/definitions/index.ts

• Externe Quellen umschließen: Rohdaten validieren → auf das gemeinsame Schema normalisieren → das Ausgabeschema zurückgeben; niemals Felder erfinden, die eine Quelle weglässt, und niemals einen Konfidenzwert synthetisieren

Namensnennung

Dieser Server verteilt offene Daten aus den folgenden Quellen weiter, die hier gemäß ihren Bedingungen zitiert werden:

• OFAC-SDN- und -Konsolidierte Listen – US-Finanzministerium, Office of Foreign Assets Control (Public Domain der US-Regierung).

• EU-Konsolidierte Finanzsanktionsliste – Europäische Kommission / EAD (frei weiterverbreitbar).

• UK-Sanktionsliste – britisches Außen-, Commonwealth- und Entwicklungsministerium, lizenziert unter der Open Government Licence v3.0 (Namensnennung erforderlich).

• UN-Konsolidierte Liste des Sicherheitsrats – Sicherheitsrat der Vereinten Nationen (frei weiterverbreitbar).

• GLEIF-LEI-Daten – Global Legal Entity Identifier Foundation, CC0 1.0 Universal.

Mitwirken

Issues und Pull-Requests sind willkommen. Führen Sie vor dem Einreichen Prüfungen und Tests aus:

bun run devcheck
bun run test

Lizenz

Apache-2.0 – siehe LICENSE für Details.