@cyanheads/sanctions-screening-mcp-server

Servidor público alojado: https://sanctions-screening.caseyjhand.com/mcp

[!IMPORTANT] Esto es una ayuda de cribado, no una certificación legal o de cumplimiento. Cada herramienta devuelve posibles coincidencias con una puntuación transparente y la procedencia de la fuente — nunca un veredicto. Una coincidencia significa "revisa este candidato contra la fuente oficial"; un resultado vacío nunca significa "exento". El cumplimiento real de sanciones es un proceso legal — requiere revisión humana y una determinación de cumplimiento cualificada. Este servidor alimenta ese proceso; no lo realiza, y su salida no es un registro de cumplimiento.

Resumen

sanctions-screening-mcp-server convierte los datos abiertos de sanciones del mundo más el registro global de entidades legales en un único flujo de trabajo de cribado y resolución, respondido sin conexión y con coincidencia difusa. Examina un nombre contra las listas consolidadas de sanciones de EE. UU. (OFAC), UE, Reino Unido y ONU a la vez, y resuelve entidades legales contra la base de datos de Identificadores de Entidades Legales (LEI) de GLEIF con trazado de propiedad corporativa.

Todas las fuentes son descargables en bloque, sin clave y claras para redistribución. El servidor las refleja en un índice local SQLite + FTS5 y sirve coincidencias desde ese espejo — sin clave de API en vivo, sin límite de tasa por solicitud en la ruta crítica. El agente ve verbos de cribado (screen_name, resolve_entity, trace_ownership); qué lista respondió a una consulta aparece solo como procedencia en cada coincidencia.

El modelo de coincidencia es transparente por diseño: primero coincidencia estricta de tokens (normalización exacta, luego todos los tokens presentes vía FTS5), con un respaldo difuso puntuado de Jaro-Winkler + fonético. Las coincidencias aproximadas llevan la similitud bruta de Jaro-Winkler (0–1) — una medición real, nunca un "porcentaje de confianza" inventado.

Related MCP server: sanctionwise

Herramientas

Seis herramientas organizadas en torno a dos flujos de trabajo — examinar un nombre contra las listas de vigilancia, y resolver una entidad legal a su identificador global y grafo de propiedad:

sanctions_screen_name

El punto de entrada del 80% — "¿está esta entidad en una lista de vigilancia?"

• Se expande a través de las cuatro listas de sanciones (OFAC SDN + Consolidada, UE, Reino Unido, ONU) en una sola llamada; la fuente aparece solo como procedencia por coincidencia

• Con conocimiento de alias: coincide con cada nombre primario publicado, a.k.a., y f.k.a., no solo el nombre canónico

• Modo estricto (predeterminado): igualdad normalizada exacta, luego todos los tokens presentes vía FTS5 — maneja intercambios de orden de palabras y palabras interiores faltantes sin biblioteca difusa

• Modo difuso (opt-in, o automático cuando el estricto no encuentra nada): añade similitud de Jaro-Winkler y coincidencia fonética Double-Metaphone para fallos de clase de transliteración

• Coincidencias etiquetadas exact / strong / approximate; las coincidencias aproximadas llevan la puntuación bruta de Jaro-Winkler (0–1) más queryTokenCoverage — cuántos tokens de consulta explica el candidato, lo que clasifica candidatos que un solo token exacto compartido fija en la misma puntuación

• Filtra por tipo de entidad, subconjunto de lista fuente, umbral de similitud (min_score) y límite de resultados

• Paginado: totalAvailable y hasMore informan coincidencias más allá de la página devuelta y nextOffset las recupera, con totalAvailableBasis marcando ese recuento como exacto (estricto) o un mínimo del conjunto escaneado (difuso)

• En un resultado vacío, devuelve orientación sobre cómo ampliar — y establece explícitamente que ninguna coincidencia no es una exención

sanctions_get_designation

El detalle después de que sanctions_screen_name muestre un candidato.

• Registro completo normalizado por source + entry_id (el sourceEntryId de una coincidencia de cribado)

• Todos los alias publicados, identificadores estructurados (pasaporte / ID nacional / impuestos / registro), direcciones, fechas y lugares de nacimiento, nacionalidades, programa sancionador, base legal y fecha de designación

• Preserva la escasez de la fuente — los campos faltantes significan que la fuente los omitió; el registro nunca se rellena con datos fabricados

sanctions_resolve_entity

El puente desde un nombre de contraparte en texto libre a un LEI estable del que dependen las herramientas de entidad.

• Resuelve un nombre de empresa / organización a candidatos LEI de GLEIF clasificados

• Filtro opcional de jurisdicción ISO 3166-1 alfa-2 y filtro de estado de registro (issued predeterminado, lapsed, o any)

• Mismo modelo de coincidencia estricto-luego-difuso que el cribado de nombres; las coincidencias aproximadas llevan la puntuación bruta de Jaro-Winkler y el mismo recuento de queryTokenCoverage

• Coincide contra nombres legales y otros nombres comerciales publicados

• Paginado en el mismo contrato que sanctions_screen_name — totalAvailable, totalAvailableBasis, hasMore, nextOffset

sanctions_get_entity

Quién es esta entidad legal — más una referencia cruzada de lista de vigilancia en la misma llamada.

• Registro completo de Nivel 1 de GLEIF: nombre legal, otros nombres comerciales, direcciones legal y de sede, estado de registro, jurisdicción, autoridad de registro e ID, fecha de última actualización

• Referencia cruzada del nombre legal de la entidad contra todas las listas de vigilancia cargadas (solo coincidencia estricta — el difuso automático en un nombre legal genérico inundaría el resultado con falsos positivos de un solo token común)

• screeningStatus indica si esa referencia cruzada realmente se ejecutó: una lista de coincidencias vacía bajo not_ready significa que el espejo de sanciones no estaba disponible, no que nada coincidió

• Una entidad examinada lleva sanctionsScreen — totalAvailable, totalAvailableBasis, hasMore — ya que la lista de coincidencias está limitada a veinticinco; vuelve a examinar el nombre legal con sanctions_screen_name para el conjunto completo

• La entrada LEI se valida con regex (20 caracteres: 18 alfanuméricos + 2 dígitos de verificación)

sanctions_trace_ownership

Cribado de propiedad beneficiaria — el flujo de trabajo entre fuentes que las herramientas de lista única no pueden hacer.

• Recorre el grafo de propiedad de Nivel 2 de GLEIF en anchura hasta una profundidad limitada (1–5)

• direction: camina parents (quién lo posee), children (qué posee), o both

• Devuelve nodos (con rol y profundidad) y aristas de propiedad dirigidas con tipo de relación

• screenNodes: true examina cada entidad en el grafo contra todas las listas de vigilancia — "¿está alguien en esta cadena de propiedad sancionado?"

• El cribado por nodo es solo estricto e informa screenedNodeCount / flaggedNodeCount para que un llamador vea la cobertura de un vistazo

• Informa si el grafo es la imagen completa conocida: complete, truncated (existen más relaciones más allá de la profundidad solicitada), y missingEntityLeis (nodos sin registro de Nivel 1 de GLEIF, que llevan su LEI donde estaría un nombre legal)

• screeningStatus separa un cribado de nodo completado de uno nunca solicitado y de uno que el espejo de sanciones no pudo ejecutar; cada nodo examinado lleva sanctionsScreen — totalAvailable, totalAvailableBasis, hasMore — ya que su lista de coincidencias está limitada a diez

Recursos y prompts

Todos los datos de recursos también son accesibles a través de las herramientas, que son la vía principal para clientes MCP solo de herramientas. Los recursos son una conveniencia solo para clientes con capacidad de recursos.

Listas de fuentes

El servidor agrega cinco fuentes upstream detrás de la superficie de screening. Todas son masivas, sin clave y claras para redistribución.

La fuente del Reino Unido es la Lista de Sanciones del Reino Unido (UKSL), la única fuente autoritativa del Reino Unido desde que la Lista Consolidada de OFSI cerró el 28 de enero de 2026.

Primera ejecución: poblar el espejo

El espejo no está incluido — las listas de sanciones y la copia dorada de GLEIF se descargan y normalizan en la primera ejecución. Ejecute el script del ciclo de vida de init fuera de banda antes del screening:

bun run mirror:init

Esto transmite las cinco listas de sanciones completas, reconstruye el índice de nombres por alias y luego transmite la copia dorada de GLEIF (entidades de Nivel 1 + relaciones de propiedad de Nivel 2). Es reanudable y está diseñado para ejecutarse una vez, fuera de la ruta de solicitudes.

Establezca SANCTIONS_INIT_SKIP_GLEIF=1 en mirror:init para cargar solo las listas de sanciones y omitir GLEIF.

Nota de memoria: cada tramo de mirror:init transmite. Los documentos de sanciones suman aproximadamente 172 MB, de los cuales SDN_ADVANCED.XML de OFAC es de unos 120 MB por sí solo; la copia dorada de GLEIF de Nivel 1 es de aproximadamente 3,3 millones de registros LEI (~892 MB comprimidos, varios GB descomprimidos). Cada fuente se escanea un registro a la vez y se ingiere en lotes acotados, por lo que la memoria residente máxima sigue el tamaño del lote en lugar del tamaño de cualquier documento fuente. Dimensione el disco para el espejo en consecuencia — GLEIF domina allí — u omita GLEIF con SANCTIONS_INIT_SKIP_GLEIF=1 si solo necesita screening de listas de vigilancia.

Características

Construido sobre @cyanheads/mcp-ts-core:

• Definiciones declarativas de herramientas, recursos y prompts — un archivo por primitiva, el framework maneja el registro y la validación

• Manejo de errores unificado — los handlers lanzan, el framework captura, clasifica y formatea

• Contratos de error tipados con sugerencias de recuperación (mirror_not_ready, designation_not_found, lei_not_found)

• Autenticación conectable: none, jwt, oauth (por defecto none — todos los datos son públicos)

• Registro estructurado con trazado opcional de OpenTelemetry

• Transportes STDIO y HTTP Streamable

Específico de sanciones:

• Superficie multi-fuente organizada por flujo de trabajo — una pantalla se expande internamente a OFAC, UE, RU y ONU; las fuentes aparecen solo como procedencia

• Espejo local SQLite + FTS5 a través del MirrorService del framework — sin conexión, sin clave API en vivo, sin límite de tasa por solicitud

• Esquema común normalizado en las cuatro listas de sanciones, con un índice de nombres por alias desnormalizado (una fila por nombre y por alias) para que una consulta coincida con cualquiera de los nombres de una entidad en un solo escaneo FTS

• Coincidencia estricta-luego-difusa: normalizado exacto → todos los tokens presentes (FTS5) → Jaro-Winkler + Double-Metaphone, con límite para acotar el trabajo en consultas cortas

• Ingesta de GLEIF Nivel 1 + Nivel 2 para resolución de entidades y rastreo de propiedad beneficiaria

Salida amigable para agentes:

• Señal real, no confianza sintética — los aciertos aproximados llevan la similitud bruta de Jaro-Winkler (0–1) y un recuento literal de cobertura de tokens de consulta, dos mediciones separadas en lugar de un veredicto combinado; los aciertos estrictos llevan un match_type (exact / strong), nunca un porcentaje fabricado

• Clasificación que el llamador puede tener en cuenta — los aciertos se ordenan por tipo de coincidencia, luego puntuación, luego cobertura, luego un identificador estable, y la cobertura que rompió el empate está en el propio acierto

• Procedencia en cada acierto — lista de fuentes, programa de sanciones, fecha de designación, el nombre/alias exacto que coincidió y su tipo (primary / aka / fka / low-quality-aka)

• Advertencia de apoyo a la decisión incluida en la salida de cada herramienta de screening — un acierto es un candidato a verificar, un resultado vacío no es una exención

• Frescura expuesta a través de sanctions_list_sources — el recuento de registros de cada fuente y la marca de tiempo del espejo, para que un agente pueda juzgar la obsolescencia

Primeros pasos

Instancia pública alojada

Hay una instancia pública disponible en https://sanctions-screening.caseyjhand.com/mcp — sin necesidad de instalación. Apunte cualquier cliente MCP a ella a través de HTTP Streamable, con esta configuración de cliente:

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

Autoalojado / local

Añada lo siguiente a su archivo de configuración del cliente MCP. El servidor es offline-first — pueble el espejo con bun run mirror:init antes del screening (consulte Listas de fuentes).

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

O con npx (sin necesidad de 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"
      }
    }
  }
}

Para HTTP Streamable, configure el transporte e inicie el servidor:

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

Requisitos previos

• Bun v1.3 o superior (o Node.js v24+).

• Disco para el espejo local (los archivos SQLite poblados; GLEIF Nivel 1 domina). Sin clave API para ninguna fuente.

Instalación

1. Clone el repositorio:

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

2. Navegue al directorio:

cd sanctions-screening-mcp-server

3. Instale las dependencias:

bun install

4. Configure el entorno:

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

5. Pueble el espejo:

bun run mirror:init

Configuración

Todas las fuentes no requieren clave — no hay clave API obligatoria. Cada variable a continuación es opcional con un valor predeterminado sensato.

Las URL de origen tienen como valor predeterminado los endpoints oficiales verificados; existen anulaciones para pruebas y para fijar un espejo en entornos restringidos. El "token" de la UE es un componente de ruta público estático, no una credencial.

Consulte .env.example para obtener la lista completa de anulaciones opcionales.

Ejecución del servidor

Desarrollo local

• Compilar y ejecutar:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

• Ejecutar comprobaciones y pruebas:

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

El Dockerfile tiene como valores predeterminados el transporte HTTP, el modo de sesión sin estado y los registros en /var/log/sanctions-screening-mcp-server. La imagen se ejecuta bajo Bun, por lo que el espejo usa bun:sqlite (sin compilación nativa). Monte un volumen en la ruta del espejo (/usr/src/app/data por defecto) para que el espejo poblado sobreviva a los reinicios del contenedor, y ejecute bun run mirror:init dentro del contenedor (docker exec) para poblarlo. Las dependencias de pares de OpenTelemetry se instalan por defecto; compile con --build-arg OTEL_ENABLED=false para omitirlas.

Estructura del proyecto

Guía de desarrollo

Consulte CLAUDE.md/AGENTS.md para obtener las pautas de desarrollo y las reglas arquitectónicas. La versión breve:

• Los manejadores lanzan excepciones, el marco las captura: no hay try/catch en la lógica de las herramientas

• Use ctx.log para el registro con ámbito de solicitud, ctx.state para el almacenamiento con ámbito de inquilino

• Registre nuevas herramientas y recursos mediante los barriles en src/mcp-server/*/definitions/index.ts

• Envuelva las fuentes externas: valide los datos sin procesar → normalícelos al esquema común → devuelva el esquema de salida; nunca invente campos que una fuente omita y nunca sintetice una puntuación de confianza

Atribución

Este servidor redistribuye datos abiertos de las siguientes fuentes, citadas aquí según sus términos:

• OFAC listas SDN y Consolidadas — Departamento del Tesoro de EE. UU., Oficina de Control de Activos Extranjeros (dominio público del Gobierno de EE. UU.).

• UE Lista Consolidada de Sanciones Financieras — Comisión Europea / SEAE (redistribuible libremente).

• Lista de Sanciones del Reino Unido — Oficina de Asuntos Exteriores, Commonwealth y Desarrollo del Reino Unido, bajo la Licencia de Gobierno Abierto v3.0 (se requiere atribución).

• ONU Lista Consolidada del Consejo de Seguridad — Consejo de Seguridad de las Naciones Unidas (redistribuible libremente).

• GLEIF datos LEI — Global Legal Entity Identifier Foundation, CC0 1.0 Universal.

Contribuciones

Se aceptan problemas y solicitudes de extracción. Ejecute comprobaciones y pruebas antes de enviar:

bun run devcheck
bun run test

Licencia

Apache-2.0 — consulte LICENSE para obtener detalles.