# SanctionList Microservice

> Autonomous multi-jurisdiction sanctions screening microservice with OpenSanctions compatibility and Model Context Protocol (MCP) support.

## Overview
SanctionList is a high-performance compliance microservice that aggregates, normalizes, and screens against 63,000+ designated individuals, corporate entities, vessels, and aircraft across global sanctions, Politically Exposed Persons (PEPs), transnational crime notices, and multilateral debarment lists.

### Regimes & Ingested Datasets
- **US**: United States Consolidated Screening List (OFAC SDN, BIS DPL, State Dept Nonproliferation)
- **EU**: European Union Consolidated Financial Sanctions Files (EEAS)
- **UN**: United Nations Security Council Consolidated Sanctions List
- **UK**: United Kingdom OFSI & FCDO Consolidated Sanctions
- **CH**: Swiss SECO Sanctions, Swiss Federal Assembly PEPs & FIAA Asset Freezes
- **CA**: Canada Autonomous Sanctions (SEMA & JVCFOA)
- **AU**: Australia Department of Foreign Affairs and Trade (DFAT) Autonomous Sanctions
- **INT**: INTERPOL Red Notices (Wanted Fugitives) & World Bank Debarred Firms/Entities
- **OpenSanctions**: Global Consolidated Sanctions & PEPs (FollowTheMoney v3)

### Matching Engine Architecture
- **Multi-Signal Scorecard**: Name similarity (70%), Date of Birth distance (20%), Country/Nationality match (10%).
- **Phonetic & Trigram Indexing**: PostgreSQL `pg_trgm` trigram similarity combined with Double Metaphone phonetic equivalence.
- **Sparse Data Re-normalization**: When auxiliary attributes (DOB, Country) are omitted in query or feed, weights are dynamically re-allocated to the active name signal to prevent false negatives.
- **DOB Distance Penalty**: Exponential decay penalties for chronological contradiction (-0.15 for generational gaps).
- **Cross-Jurisdiction Clustering**: Canonical entity resolution deduplicating entities designated across multiple regulatory bodies into unified canonical profiles.
- **Delta Tombstoning**: Automated soft-deactivation (`is_active = FALSE`, `delisted_at = NOW()`) for delisted entities with immediate exclusion from screening.

---

## Model Context Protocol (MCP) Server

SanctionList natively exposes its compliance engine as an MCP server (Spec `2024-11-05`), allowing LLMs and AI coding assistants to execute live screening, entity matching, and dossier lookups.

### MCP Connectivity
- **HTTP Transport (Direct JSON-RPC 2.0)**:
  - URL: `http://localhost:8010/mcp`
  - Method: `POST`
  - Headers: `Content-Type: application/json`
- **SSE Transport (Server-Sent Events)**:
  - SSE URL: `http://localhost:8010/mcp/sse`
  - Message Endpoint: `http://localhost:8010/mcp/message?sessionId={sessionId}`
- **Stdio Transport (CLI Desktop Hosts)**:
  - Command: `node`
  - Arguments: `["/path/to/sanctionList/src/mcp_server.js"]`

### Client Configuration Examples

#### Cursor (`mcp.json` or `.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "sanction-list": {
      "url": "http://localhost:8010/mcp"
    }
  }
}
```

#### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "sanction-list": {
      "command": "node",
      "args": ["/path/to/sanctionList/src/mcp_server.js"]
    }
  }
}
```

#### Docker Stdio Execution
```json
{
  "mcpServers": {
    "sanction-list": {
      "command": "docker",
      "args": ["exec", "-i", "sanctionlist-app", "node", "src/mcp_server.js"]
    }
  }
}
```

### Available MCP Tools

1. `screen_entity`
   - **Description**: Screen an individual or corporate entity against all 63,000+ designated records using multi-signal fuzzy matching.
   - **Arguments**:
     - `name` (string, required): Full name or alias of the target (e.g., "Vladimir Putin", "PAO Sberbank").
     - `birth_date` (string, optional): ISO date of birth (YYYY-MM-DD or YYYY).
     - `country` (string, optional): ISO two-letter country code (e.g., "RU", "IR", "CN").
     - `threshold` (number, optional, default: 0.60): Minimum confidence score (0.0 to 1.0).
     - `limit` (integer, optional, default: 10): Max candidate matches.

2. `match_sanctions`
   - **Description**: Execute batch queries using OpenSanctions FollowTheMoney v3 schema.
   - **Arguments**:
     - `queries` (object, required): Map of query objects containing `schema` and `properties`.

3. `search_records`
   - **Description**: Query sanctions records with pagination, jurisdiction, and category filters.
   - **Arguments**:
     - `search` (string, optional): Search keyword.
     - `jurisdiction` (string, optional): "US", "EU", "UN", "UK", "CH", "CA", "AU", "INT", or "ALL".
     - `category` (string, optional): "sanctions", "pep", "crime", "debarment", or "ALL".
     - `page` (integer, optional, default: 1).
     - `limit` (integer, optional, default: 10).
     - `status` (string, optional, default: "active"): "active", "delisted", or "all".

4. `get_record_details`
   - **Description**: Retrieve comprehensive dossier for a specific record including all indexed aliases.
   - **Arguments**:
     - `id` (string, required): Record UUID or source_id (e.g., "US-CSL-12345").

5. `get_watchlist_stats`
   - **Description**: Retrieve live statistics on total records, aliases, canonical clusters, and last sync.
   - **Arguments**: none.

---

## Public HTTP REST API

Base URL: `http://localhost:8010`

### 1. OpenSanctions Drop-In Matcher
- **Endpoint**: `POST /match/default` (also mirrored at `POST /api/match`)
- **Headers**: `Content-Type: application/json`
- **Payload**:
```json
{
  "queries": {
    "q1": {
      "schema": "Person",
      "properties": {
        "name": ["Vladimir Putin"],
        "birthDate": ["1952-10-07"],
        "nationality": ["RU"]
      }
    }
  }
}
```
- **Response**: OpenSanctions FollowTheMoney v3 compliance format with candidate `score`, `features`, `properties`, and `datasets`.

### 2. Ad-hoc Entity Screening
- **Endpoint**: `GET /api/screen`
- **Query Parameters**:
  - `name` (required): Full name or alias
  - `dob` (optional): Date of birth (YYYY-MM-DD)
  - `country` (optional): Two-letter country code
  - `threshold` (optional, default: 0.60): Score threshold
  - `limit` (optional, default: 10): Max results

### 3. Record Search & Pagination
- **Endpoint**: `GET /api/records`
- **Query Parameters**: `page`, `limit`, `search`, `jurisdiction`, `category`, `status`

### 4. Telemetry & Health
- **Endpoint**: `GET /api/stats`: Aggregate database metrics and last ingestion log.
- **Endpoint**: `GET /health`: PostgreSQL liveness probe (`{"status":"healthy","service":"sanctionList"}`).

---

## Confidence Scoring Thresholds
- **Score >= 0.95 (Exact Match)**: Deterministic identification or exact normalized alias hit with matching corroborating attributes. Mandatory compliance block.
- **Score 0.85 - 0.94 (High Confidence)**: High phonetic and token overlap with consistent corroborating data. Manual compliance review recommended.
- **Score 0.70 - 0.84 (Medium Confidence)**: Partial name similarity or transliteration variation. Enhanced due diligence required.
- **Score < 0.60 (False Positive)**: Insufficient similarity; automatically cleared.