@cyanheads/sanctions-screening-mcp-server

Публичный размещённый сервер: https://sanctions-screening.caseyjhand.com/mcp

[!ВАЖНО] Это вспомогательное средство для проверки, а не юридическое или комплаенс-подтверждение. Каждый инструмент возвращает потенциальные совпадения с прозрачной оценкой и указанием источника — никогда не вердикт. Совпадение означает «проверьте этого кандидата по официальному источнику»; пустой результат никогда не означает «проверен». Реальное соблюдение санкционных требований — это юридический процесс: он требует проверки человеком и квалифицированного комплаенс-заключения. Этот сервер питает этот процесс; он не выполняет его, и его вывод не является комплаенс-записью.

Обзор

sanctions-screening-mcp-server превращает открытые данные о санкциях мира плюс глобальный реестр юридических лиц в единый рабочий процесс проверки и сопоставления, отвечая офлайн и с нечётким сопоставлением. Он проверяет имя по консолидированным спискам США (OFAC), ЕС, Великобритании и ООН одновременно и сопоставляет юридические лица с базой данных 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

Инструменты

Шесть инструментов, организованных вокруг двух рабочих процессов — проверьте имя по стоп-листам и сопоставьте юридическое лицо с его глобальным идентификатором и графом владения:

sanctions_screen_name

Точка входа на 80% — «находится ли эта организация в стоп-листе?»

• Разворачивается по всем четырём санкционным спискам (OFAC SDN + Consolidated, ЕС, Великобритания, ООН) за один вызов; источник отображается только как происхождение каждого совпадения

• С учётом псевдонимов: сопоставляется с каждым опубликованным основным именем, также известным как (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 уровня 1: юридическое название, другие/торговые названия, юридический и головной адреса, статус регистрации, юрисдикция, регистрационный орган и ID, дата последнего обновления

• Перекрёстно проверяет юридическое название организации по всем загруженным стоп-листам (только строгое совпадение — автоматический нечёткий поиск по общему юридическому названию затопил бы результат ложными срабатываниями с одним общим токеном)

• screeningStatus сообщает, действительно ли эта перекрёстная проверка выполнялась: пустой список совпадений при not_ready означает, что санкционное зеркало было недоступно, а не то, что ничего не совпало

• Проверенная организация несёт sanctionsScreen — totalAvailable, totalAvailableBasis, hasMore — поскольку список совпадений ограничен двадцатью пятью; повторно проверьте юридическое название с помощью sanctions_screen_name для полного набора

• Ввод LEI проверяется регулярным выражением (20 символов: 18 буквенно-цифровых + 2 контрольные цифры)

sanctions_trace_ownership

Проверка бенефициарного владения — межведомственный рабочий процесс, который не могут выполнить инструменты для одного списка.

• Обходит граф владения GLEIF уровня 2 в ширину до ограниченной глубины (1–5)

• direction: обход parents (кто владеет), children (чем владеет) или both

• Возвращает узлы (с ролью и глубиной) и направленные рёбра владения с типом отношения

• screenNodes: true проверяет каждую организацию в графе по всем стоп-листам — «есть ли кто-то в этой цепочке владения под санкциями?»

• Проверка каждого узла — только строгая и сообщает screenedNodeCount / flaggedNodeCount, чтобы вызывающий мог видеть покрытие с первого взгляда

• Сообщает, является ли граф полной известной картиной: complete, truncated (дальнейшие отношения существуют за пределами запрошенной глубины) и missingEntityLeis (узлы без записи GLEIF уровня 1, которые несут свой LEI там, где должно быть юридическое название)

• screeningStatus отделяет завершённую проверку узлов от той, которая никогда не запрашивалась, и от той, которую санкционное зеркало не смогло выполнить; каждый проверенный узел несёт sanctionsScreen — totalAvailable, totalAvailableBasis, hasMore — поскольку его список совпадений ограничен десятью

Ресурсы и подсказки

Все данные ресурсов также доступны через инструменты, которые являются основным путём для MCP-клиентов, работающих только с инструментами. Ресурсы — это удобство для клиентов, поддерживающих ресурсы.

Списки источников

Сервер агрегирует пять внешних источников за поверхностью скрининга. Все они — массовые, без ключей и свободны для распространения.

Источник Великобритании — это Санкционный список Великобритании (UKSL), единственный авторитетный источник Великобритании с момента закрытия Консолидированного списка OFSI 28 января 2026 года.

Первый запуск: заполнение зеркала

Зеркало не входит в комплект — санкционные списки и эталонная копия GLEIF загружаются и нормализуются при первом запуске. Запустите сценарий жизненного цикла инициализации вне пути запросов перед скринингом:

bun run mirror:init

Это потоково загружает все пять санкционных списков полностью, перестраивает индекс имён по псевдонимам, затем потоково загружает эталонную копию GLEIF (сущности уровня 1 + отношения собственности уровня 2). Процесс возобновляем и предназначен для однократного запуска вне пути запросов.

Установите SANCTIONS_INIT_SKIP_GLEIF=1 для mirror:init, чтобы загрузить только санкционные списки и пропустить GLEIF.

Примечание о памяти: каждый этап mirror:init работает в потоковом режиме. Санкционные документы в сумме составляют примерно 172 МБ, из которых OFAC SDN_ADVANCED.XML — около 120 МБ сам по себе; эталонная копия GLEIF уровня 1 — примерно 3,3 млн записей LEI (~892 МБ в сжатом виде, несколько ГБ в распакованном). Каждый источник сканируется по одной записи за раз и загружается ограниченными пакетами, поэтому пиковая резидентная память соответствует размеру пакета, а не размеру документа источника. Соответственно рассчитывайте диск под зеркало — GLEIF здесь доминирует — или пропустите GLEIF с SANCTIONS_INIT_SKIP_GLEIF=1, если вам нужен только скрининг по сторожевому списку.

Возможности

Построено на @cyanheads/mcp-ts-core:

• Декларативные определения инструментов, ресурсов и промптов — один файл на примитив, фреймворк обрабатывает регистрацию и валидацию

• Унифицированная обработка ошибок — обработчики выбрасывают, фреймворк перехватывает, классифицирует и форматирует

• Типизированные контракты ошибок с подсказками по восстановлению (mirror_not_ready, designation_not_found, lei_not_found)

• Подключаемая аутентификация: none, jwt, oauth (по умолчанию none — все данные публичны)

• Структурированное логирование с опциональной трассировкой OpenTelemetry

• Транспорты STDIO и Streamable HTTP

Специфично для санкций:

• Многоисточниковая поверхность, организованная по рабочим процессам — один экран внутренне распределяет запросы по OFAC, ЕС, Великобритании и ООН; источники проявляются только как происхождение данных

• Локальное зеркало SQLite + FTS5 через фреймворковый MirrorService — офлайн, без живого API-ключа, без лимита запросов в единицу времени

• Нормализованная общая схема для четырёх санкционных списков с денормализованным индексом имён по псевдонимам (одна строка на имя и на псевдоним), чтобы запрос сопоставлялся с любым из имён сущности за одно FTS-сканирование

• Строгое, затем нечёткое сопоставление: точное-нормализованное → все-токены-присутствуют (FTS5) → Jaro-Winkler + Double-Metaphone, с ограничением работы для коротких запросов

• Приём данных GLEIF уровня 1 и уровня 2 для разрешения сущностей и трассировки бенефициарной собственности

Вывод, удобный для агентов:

• Реальный сигнал, а не синтетическая уверенность — приблизительные совпадения несут сырое сходство Jaro-Winkler (0–1) и буквальный подсчёт покрытия токенов запроса, два отдельных измерения вместо одного смешанного вердикта; строгие совпадения несут match_type (exact / strong), никогда не сфабрикованный процент

• Ранжирование, которое вызывающая сторона может учесть — совпадения упорядочиваются по типу совпадения, затем по оценке, затем по покрытию, затем по стабильному идентификатору, и покрытие, решившее спор, указано на самом совпадении

• Происхождение данных на каждом совпадении — список источника, санкционная программа, дата включения в список, точное имя/псевдоним, по которому произошло совпадение, и его тип (primary / aka / fka / low-quality-aka)

• Оговорка о поддержке принятия решений в выводе каждого инструмента скрининга — совпадение — это кандидат для проверки, пустой результат — не подтверждение отсутствия ограничений

• Актуальность отображается через sanctions_list_sources — количество записей каждого источника и временная метка зеркала, чтобы агент мог оценить устаревание

Начало работы

Публичный размещённый экземпляр

Публичный экземпляр доступен по адресу https://sanctions-screening.caseyjhand.com/mcp — установка не требуется. Направьте любой MCP-клиент на него через Streamable HTTP со следующей конфигурацией клиента:

{
  "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 по умолчанию указывают на проверенные официальные конечные точки; переопределения существуют для тестирования и для закрепления зеркала в ограниченных средах. «Токен» ЕС — это статический публичный компонент пути, а не учётные данные.

Полный список дополнительных переопределений см. в .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 Sanctions List — Управление по делам иностранных дел, Содружества и развития Великобритании, лицензировано по Open Government Licence v3.0 (требуется указание авторства).

• UN — Консолидированный список Совета Безопасности ООН — Совет Безопасности ООН (свободно распространяется).

• GLEIF — данные LEI — Фонд глобальных идентификаторов юридических лиц, CC0 1.0 Universal.

Участие в разработке

Приветствуются issues и pull request'ы. Перед отправкой запустите проверки и тесты:

bun run devcheck
bun run test

Лицензия

Apache-2.0 — подробности см. в LICENSE.