@cyanheads/sanctions-screening-mcp-server

公共托管服务器： https://sanctions-screening.caseyjhand.com/mcp

[!IMPORTANT] 这是一项筛查辅助工具，而非法律或合规认证。 每个工具返回的都是潜在匹配，并附有透明的评分和来源出处——绝不给出裁决。命中意味着"请对照官方来源审查该候选对象"；空结果也绝不意味着"已通过"。真正的制裁合规是一个法律流程——它需要人工审查和合格的合规判定。本服务器为该流程提供输入；它不执行该流程，其输出也不构成合规记录。

概述

sanctions-screening-mcp-server 将全球开放的制裁数据与全球法律实体注册库整合为一个筛查与解析工作流，可离线运行并支持模糊匹配。它可一次性对合并后的美国（OFAC）、欧盟、英国和联合国制裁名单进行姓名筛查，并对照 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 + 合并名单、欧盟、英国、联合国）；来源仅作为每条命中的出处信息呈现

• 别名感知：匹配所有已发布的主名称、又名（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）获取完整归一化记录

• 所有已发布的别名、结构化标识符（护照/国民身份证/税务/注册号）、地址、出生日期和地点、国籍、制裁计划、法律依据和指定日期

• 保留来源数据的稀疏性——字段缺失意味着来源未提供；记录绝不用编造的数据填充

sanctions_resolve_entity

从自由文本的交易对手名称到稳定 LEI 的桥梁，实体工具以该 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 一级记录：法定名称、其他/经营名称、法定地址和总部地址、注册状态、司法辖区、注册机构和 ID、最后更新日期

• 将该实体的法定名称与所有已加载的观察名单进行交叉引用（仅严格匹配——对通用法定名称自动启用模糊匹配会因单一常见令牌而产生大量误报）

• screeningStatus 表明该交叉引用是否实际执行：not_ready 状态下的空命中列表意味着制裁镜像不可用，而非无匹配

• 已筛查的实体携带 sanctionsScreen——totalAvailable、totalAvailableBasis、hasMore——因为命中列表上限为二十五条；如需完整结果，请使用 sanctions_screen_name 重新筛查法定名称

• LEI 输入经过正则验证（20 个字符：18 个字母数字 + 2 个校验位）

sanctions_trace_ownership

受益所有权筛查——单一名单工具无法完成的跨来源工作流。

• 以广度优先方式遍历 GLEIF 二级所有权图谱，深度有界（1–5）

• direction：遍历 parents（谁拥有它）、children（它拥有什么）或 both

• 返回节点（含角色和深度）以及带关系类型的有向所有权边

• screenNodes: true 对图谱中的每个实体对照所有观察名单进行筛查——"该所有权链中是否有人被制裁？"

• 每个节点的筛查仅限严格模式，并报告 screenedNodeCount / flaggedNodeCount，使调用方一眼即可看到覆盖情况

• 报告图谱是否为已知全貌：complete、truncated（在请求深度之外还存在更多关系）和 missingEntityLeis（没有 GLEIF 一级记录的节点，这些节点在法定名称位置携带其 LEI）

• screeningStatus 区分已完成的节点筛查、从未请求的筛查以及制裁镜像无法执行的筛查；每个已筛查节点携带 sanctionsScreen——totalAvailable、totalAvailableBasis、hasMore——因为其命中列表上限为十条

资源和提示词

所有资源数据也可通过工具访问，工具是仅支持工具的 MCP 客户端的主要路径。资源仅为支持资源的客户端提供便利。

来源名单

服务器在筛查表面之后聚合了五个上游来源。所有来源均为批量、无密钥、可自由再分发。

英国来源是 UK Sanctions List (UKSL)，自 OFSI Consolidated List 于 2026 年 1 月 28 日关闭以来，这是英国唯一的权威来源。

首次运行：填充镜像

镜像不随包附带 — 制裁名单和 GLEIF 黄金副本在首次运行时下载并规范化。在筛查之前，先在带外运行初始化生命周期脚本：

bun run mirror:init

这会完整流式加载全部五份制裁名单，重建按别名划分的名称索引，然后流式加载 GLEIF 黄金副本（Level 1 实体 + Level 2 所有权关系）。该过程可恢复，设计为在请求路径之外运行一次。

在 mirror:init 上设置 SANCTIONS_INIT_SKIP_GLEIF=1 可仅加载制裁名单并跳过 GLEIF。

内存说明： mirror:init 的每一段都是流式的。制裁文档总计约 172 MB，其中 OFAC SDN_ADVANCED.XML 单独约 120 MB；GLEIF Level 1 黄金副本约 330 万条 LEI 记录（压缩后约 892 MB，解压后数 GB）。每个来源逐条记录扫描，并以有界批次摄入，因此峰值常驻内存跟随批次大小而非任何来源文档的大小。请相应地为镜像规划磁盘空间 — 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 传输

制裁特定功能：

• 多来源、工作流组织的表面 — 一次筛查在内部扇出到 OFAC、EU、UK 和 UN；来源仅作为出处呈现

• 通过框架 MirrorService 的本地 SQLite + FTS5 镜像 — 离线、无需实时 API 密钥、无按请求速率限制

• 四个制裁名单的规范化通用模式，带反规范化的按别名名称索引（每个名称和别名一行），因此一次 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 呈现新鲜度 — 每个来源的记录数和镜像的 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 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 默认指向经核实的官方端点；覆盖项用于测试以及在受限环境中固定镜像。欧盟的“token”是静态公共路径组件，而非凭据。

完整的可选覆盖项列表请参阅 .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）挂载卷，以便已填充的镜像在容器重启后仍然存在，并在容器内（docker exec）运行 bun run mirror:init 来填充它。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 名单——美国财政部外国资产控制办公室（美国政府公有领域）。

• 欧盟合并金融制裁名单——欧盟委员会 / EEAS（可自由重新分发）。

• 英国制裁名单——英国外交、联邦及发展事务部，依据 Open Government Licence v3.0 许可（需注明出处）。

• 联合国安理会合并名单——联合国安理会（可自由重新分发）。

• GLEIF LEI 数据——全球法人机构识别编码基金会，CC0 1.0 Universal。

贡献

欢迎提交 Issue 和 Pull Request。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。