@cyanheads/sanctions-screening-mcp-server 0.1.0

package/dist/mcp-server/tools/definitions/list-sources.tool.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview `sanctions_list_sources` — provenance and freshness for any
+ * result. Lists the sanctions watchlists and GLEIF datasets currently loaded in
+ * the local mirror, each with its record count, source URL, license, and the
+ * mirror's readiness + as-of timestamp. Lets an agent judge staleness before
+ * trusting (or distrusting) a screen.
+ * @module mcp-server/tools/definitions/list-sources.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { DEFAULT_SOURCE_URLS, getServerConfig } from '../../../config/server-config.js';
+import { getScreeningService } from '../../../services/screening/screening-service.js';
+import { SOURCE_LABELS } from '../../../services/screening/types.js';
+const LICENSES = {
+    ofac_sdn: 'US Government public domain',
+    ofac_consolidated: 'US Government public domain',
+    eu: 'EU consolidated list — freely redistributable',
+    uk: 'Open Government Licence v3.0 (attribution required)',
+    un: 'Freely redistributable',
+};
+/** GLEIF golden copy is CC0 — cited but no attribution required. */
+const GLEIF_LICENSE = 'CC0 1.0 Universal (public domain)';
+export const listSourcesTool = tool('sanctions_list_sources', {
+    title: 'sanctions-screening-mcp-server: list sources',
+    description: "List the sanctions watchlists (OFAC SDN + Consolidated, EU, UK, UN) and GLEIF datasets currently loaded in the local mirror, each with its record count, source URL, license, and the mirror's readiness and as-of timestamp. Use this for provenance and freshness on any result — results are only as current as the last mirror refresh, and a not-ready mirror means screening cannot run yet. Attribution: UK data is under the Open Government Licence v3.0; all sources are cited here.",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    input: z.object({}),
+    output: z.object({
+        sanctionsReady: z
+            .boolean()
+            .describe('True once the sanctions mirror has completed at least one full sync.'),
+        sanctionsAsOf: z
+            .string()
+            .optional()
+            .describe('ISO 8601 timestamp of the last completed sanctions sync, when available.'),
+        leiReady: z
+            .boolean()
+            .describe('True once the GLEIF (LEI) mirror has completed at least one full sync.'),
+        leiAsOf: z
+            .string()
+            .optional()
+            .describe('ISO 8601 timestamp of the last completed GLEIF sync, when available.'),
+        sources: z
+            .array(z
+            .object({
+            code: z.string().describe('Source code (ofac_sdn, eu, …, or gleif).'),
+            label: z.string().describe('Human-readable source name.'),
+            recordCount: z.number().describe('Records currently loaded for this source.'),
+            url: z.string().describe('Upstream source URL the mirror harvests from.'),
+            license: z.string().describe('Redistribution license / terms for this source.'),
+        })
+            .describe('One loaded source with count, provenance, and license.'))
+            .describe('All loaded sources, sanctions lists then the GLEIF dataset.'),
+    }),
+    async handler(_input, ctx) {
+        const svc = getScreeningService();
+        const cfg = getServerConfig();
+        const [counts, sanctions, lei] = await Promise.all([
+            svc.sourceCounts(),
+            svc.sanctionsReadiness(),
+            svc.leiReadiness(),
+        ]);
+        const urlFor = {
+            ofac_sdn: cfg.ofacSdnUrl,
+            ofac_consolidated: cfg.ofacConsolidatedUrl,
+            eu: cfg.euFsfUrl,
+            uk: cfg.ukSanctionsUrl,
+            un: cfg.unScUrl,
+        };
+        const sources = counts.map((s) => ({
+            code: s.code,
+            label: SOURCE_LABELS[s.code],
+            recordCount: s.recordCount,
+            url: urlFor[s.code],
+            license: LICENSES[s.code],
+        }));
+        sources.push({
+            code: 'gleif',
+            label: 'GLEIF LEI (Level 1 entities + Level 2 ownership)',
+            recordCount: lei.entityCount,
+            url: `${cfg.gleifGoldenCopyBaseUrl.replace(/\/$/, '')} (golden copy) — default ${DEFAULT_SOURCE_URLS.gleifGoldenCopyBase}`,
+            license: GLEIF_LICENSE,
+        });
+        ctx.log.debug('Listed sources', { sanctionsReady: sanctions.ready, leiReady: lei.ready });
+        return {
+            sanctionsReady: sanctions.ready,
+            ...(sanctions.completedAt ? { sanctionsAsOf: sanctions.completedAt } : {}),
+            leiReady: lei.ready,
+            ...(lei.completedAt ? { leiAsOf: lei.completedAt } : {}),
+            sources,
+        };
+    },
+    format: (r) => {
+        const lines = ['# Loaded sources', ''];
+        lines.push(`**Sanctions mirror:** ${r.sanctionsReady ? 'ready' : 'NOT ready'}${r.sanctionsAsOf ? ` (as of ${r.sanctionsAsOf})` : ''}`);
+        lines.push(`**GLEIF mirror:** ${r.leiReady ? 'ready' : 'NOT ready'}${r.leiAsOf ? ` (as of ${r.leiAsOf})` : ''}`);
+        lines.push('');
+        for (const s of r.sources) {
+            lines.push(`### ${s.label} (\`${s.code}\`)`);
+            lines.push(`**Records:** ${s.recordCount} | **License:** ${s.license}`);
+            lines.push(`**Source:** ${s.url}`);
+            lines.push('');
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=list-sources.tool.js.map

package/dist/mcp-server/tools/definitions/list-sources.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-sources.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/list-sources.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/resolve-entity.tool.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview `sanctions_resolve_entity` — resolves a company/organization
+ * name (+ optional jurisdiction) to candidate GLEIF LEIs, ranked. The bridge
+ * from a free-text counterparty name to a stable global identifier other tools
+ * key off. Decision support: candidates to confirm, not an authoritative
+ * identification.
+ * @module mcp-server/tools/definitions/resolve-entity.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const resolveEntityTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    name: z.ZodString;
+    jurisdiction: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
+    matchMode: z.ZodDefault<z.ZodEnum<{
+        strict: "strict";
+        fuzzy: "fuzzy";
+    }>>;
+    status: z.ZodDefault<z.ZodEnum<{
+        any: "any";
+        issued: "issued";
+        lapsed: "lapsed";
+    }>>;
+    minScore: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    matches: z.ZodArray<z.ZodObject<{
+        lei: z.ZodString;
+        legalName: z.ZodString;
+        matchedName: z.ZodString;
+        matchType: z.ZodEnum<{
+            exact: "exact";
+            strong: "strong";
+            approximate: "approximate";
+        }>;
+        score: z.ZodOptional<z.ZodNumber>;
+        jurisdiction: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "mirror_not_ready";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The GLEIF (LEI) mirror has never completed an initial sync.";
+    readonly retryable: true;
+    readonly recovery: "Run the mirror:init lifecycle script to load the GLEIF golden copy, then retry; check sanctions_list_sources for readiness.";
+}], {
+    readonly normalizedQuery: z.ZodString;
+    readonly matchModeUsed: z.ZodString;
+    readonly totalCount: z.ZodNumber;
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=resolve-entity.tool.d.ts.map

package/dist/mcp-server/tools/definitions/resolve-entity.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/resolve-entity.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6J5B,CAAC"}

package/dist/mcp-server/tools/definitions/resolve-entity.tool.js

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview `sanctions_resolve_entity` — resolves a company/organization
+ * name (+ optional jurisdiction) to candidate GLEIF LEIs, ranked. The bridge
+ * from a free-text counterparty name to a stable global identifier other tools
+ * key off. Decision support: candidates to confirm, not an authoritative
+ * identification.
+ * @module mcp-server/tools/definitions/resolve-entity.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getScreeningService } from '../../../services/screening/screening-service.js';
+export const resolveEntityTool = tool('sanctions_resolve_entity', {
+    title: 'sanctions-screening-mcp-server: resolve entity',
+    description: 'Resolve a company or organization name (with an optional ISO 3166-1 alpha-2 jurisdiction) to candidate GLEIF Legal Entity Identifiers (LEIs), ranked. This turns a free-text counterparty name into a stable global identifier that sanctions_get_entity and sanctions_trace_ownership key off. Strict mode (default) matches exact-normalized then all-tokens-present; fuzzy mode (or auto when strict is empty) adds Jaro-Winkler scoring labeled approximate with a raw 0–1 score. Returns potential matches to confirm against the GLEIF record — name resolution is a candidate ranking, not an authoritative identification.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    input: z.object({
+        name: z.string().min(1).describe('The company / organization name to resolve to an LEI.'),
+        jurisdiction: z
+            .union([
+            z.literal(''),
+            z
+                .string()
+                .regex(/^[A-Za-z]{2}$/, 'ISO 3166-1 alpha-2 code (e.g. US, GB)')
+                .describe('ISO 3166-1 alpha-2 jurisdiction code (e.g. US, GB).'),
+        ])
+            .optional()
+            .describe('Optional ISO 3166-1 alpha-2 jurisdiction filter (e.g. "US", "GB"). Empty string disables it.'),
+        matchMode: z
+            .enum(['strict', 'fuzzy'])
+            .default('strict')
+            .describe('strict (default): exact then all-tokens-present. fuzzy: also scored Jaro-Winkler.'),
+        status: z
+            .enum(['any', 'issued', 'lapsed'])
+            .default('issued')
+            .describe('Registration status filter: issued (default), lapsed, or any.'),
+        minScore: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("Jaro-Winkler floor for fuzzy hits (0–1); defaults to the server's configured floor."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .default(10)
+            .describe('Maximum LEI candidates to return.'),
+    }),
+    output: z.object({
+        matches: z
+            .array(z
+            .object({
+            lei: z.string().describe('20-character GLEIF Legal Entity Identifier.'),
+            legalName: z.string().describe('Registered legal name of the entity.'),
+            matchedName: z
+                .string()
+                .describe('The name (legal or other/trading) that matched the query.'),
+            matchType: z
+                .enum(['exact', 'strong', 'approximate'])
+                .describe('exact = normalized equality; strong = all tokens present; approximate = fuzzy.'),
+            score: z
+                .number()
+                .optional()
+                .describe('Raw Jaro-Winkler similarity (0–1) for approximate hits only — a real measurement.'),
+            jurisdiction: z
+                .string()
+                .optional()
+                .describe('Legal jurisdiction (ISO code), when published.'),
+            status: z.string().optional().describe('Registration status (e.g. ISSUED, LAPSED).'),
+        })
+            .describe('One LEI candidate — confirm against the GLEIF record before relying on it.'))
+            .describe('Ranked LEI candidates, highest-confidence first.'),
+    }),
+    enrichment: {
+        normalizedQuery: z.string().describe('The name as the server folded it for matching.'),
+        matchModeUsed: z
+            .string()
+            .describe('The match mode actually applied (strict may upgrade to fuzzy).'),
+        totalCount: z.number().describe('Number of LEI candidates returned.'),
+        notice: z.string().optional().describe('Guidance when no LEI matched and how to broaden.'),
+    },
+    errors: [
+        {
+            reason: 'mirror_not_ready',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'The GLEIF (LEI) mirror has never completed an initial sync.',
+            retryable: true,
+            recovery: 'Run the mirror:init lifecycle script to load the GLEIF golden copy, then retry; check sanctions_list_sources for readiness.',
+        },
+    ],
+    async handler(input, ctx) {
+        const svc = getScreeningService();
+        if (!(await svc.leiReady())) {
+            throw ctx.fail('mirror_not_ready', 'The local GLEIF (LEI) mirror is not yet populated.', {
+                ...ctx.recoveryFor('mirror_not_ready'),
+            });
+        }
+        const jurisdiction = input.jurisdiction ? input.jurisdiction.toUpperCase() : undefined;
+        const result = await svc.resolveEntity({
+            query: input.name,
+            ...(jurisdiction ? { jurisdiction } : {}),
+            matchMode: input.matchMode,
+            status: input.status,
+            ...(input.minScore !== undefined ? { minScore: input.minScore } : {}),
+            limit: input.limit,
+        }, ctx);
+        ctx.enrich({ normalizedQuery: result.normalizedQuery, matchModeUsed: result.modeUsed });
+        ctx.enrich.total(result.matches.length);
+        if (result.matches.length === 0) {
+            ctx.enrich.notice(`No LEI candidate for "${input.name}"${jurisdiction ? ` in ${jurisdiction}` : ''} (mode: ${result.modeUsed}). ` +
+                'Try matchMode:"fuzzy", drop the jurisdiction/status filter, or set status:"any" — an unmatched name is not proof the entity has no LEI.');
+        }
+        return {
+            matches: result.matches.map((m) => ({
+                lei: m.lei,
+                legalName: m.legalName,
+                matchedName: m.matchedName,
+                matchType: m.matchType,
+                ...(m.score !== undefined ? { score: m.score } : {}),
+                ...(m.jurisdiction ? { jurisdiction: m.jurisdiction } : {}),
+                ...(m.status ? { status: m.status } : {}),
+            })),
+        };
+    },
+    format: (r) => {
+        if (r.matches.length === 0)
+            return [{ type: 'text', text: '**No LEI candidates found.**' }];
+        const lines = [`**${r.matches.length} LEI candidate(s)** — confirm before relying on:\n`];
+        for (const m of r.matches) {
+            const scoreStr = m.score !== undefined ? ` · score ${m.score.toFixed(3)}` : '';
+            lines.push(`### ${m.legalName} — ${m.matchType}${scoreStr}`);
+            lines.push(`**LEI:** \`${m.lei}\``);
+            lines.push(`**Matched on:** "${m.matchedName}"`);
+            const meta = [
+                m.jurisdiction ? `Jurisdiction: ${m.jurisdiction}` : null,
+                m.status ? `Status: ${m.status}` : null,
+            ]
+                .filter(Boolean)
+                .join(' | ');
+            if (meta)
+                lines.push(`**${meta}**`);
+            lines.push('');
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=resolve-entity.tool.js.map

package/dist/mcp-server/tools/definitions/resolve-entity.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-entity.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/resolve-entity.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAEhF,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,0BAA0B,EAAE;IAChE,KAAK,EAAE,gDAAgD;IACvD,WAAW,EACT,omBAAomB;IACtmB,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAC/E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,uDAAuD,CAAC;QACzF,YAAY,EAAE,CAAC;aACZ,KAAK,CAAC;YACL,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;YACb,CAAC;iBACE,MAAM,EAAE;iBACR,KAAK,CAAC,eAAe,EAAE,uCAAuC,CAAC;iBAC/D,QAAQ,CAAC,qDAAqD,CAAC;SACnE,CAAC;aACD,QAAQ,EAAE;aACV,QAAQ,CACP,8FAA8F,CAC/F;QACH,SAAS,EAAE,CAAC;aACT,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;aACzB,OAAO,CAAC,QAAQ,CAAC;aACjB,QAAQ,CACP,mFAAmF,CACpF;QACH,MAAM,EAAE,CAAC;aACN,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;aACjC,OAAO,CAAC,QAAQ,CAAC;aACjB,QAAQ,CAAC,+DAA+D,CAAC;QAC5E,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CACP,qFAAqF,CACtF;QACH,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,EAAE,CAAC;aACP,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CAAC,mCAAmC,CAAC;KACjD,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,OAAO,EAAE,CAAC;aACP,KAAK,CACJ,CAAC;aACE,MAAM,CAAC;YACN,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;YACvE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;YACtE,WAAW,EAAE,CAAC;iBACX,MAAM,EAAE;iBACR,QAAQ,CAAC,2DAA2D,CAAC;YACxE,SAAS,EAAE,CAAC;iBACT,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;iBACxC,QAAQ,CACP,gFAAgF,CACjF;YACH,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,mFAAmF,CACpF;YACH,YAAY,EAAE,CAAC;iBACZ,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,gDAAgD,CAAC;YAC7D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;SACrF,CAAC;aACD,QAAQ,CAAC,4EAA4E,CAAC,CAC1F;aACA,QAAQ,CAAC,kDAAkD,CAAC;KAChE,CAAC;IACF,UAAU,EAAE;QACV,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;QACtF,aAAa,EAAE,CAAC;aACb,MAAM,EAAE;aACR,QAAQ,CAAC,gEAAgE,CAAC;QAC7E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QACrE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;KAC3F;IACD,MAAM,EAAE;QACN;YACE,MAAM,EAAE,kBAAkB;YAC1B,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,6DAA6D;YACnE,SAAS,EAAE,IAAI;YACf,QAAQ,EACN,6HAA6H;SAChI;KACF;IAED,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC;YAC5B,MAAM,GAAG,CAAC,IAAI,CAAC,kBAAkB,EAAE,oDAAoD,EAAE;gBACvF,GAAG,GAAG,CAAC,WAAW,CAAC,kBAAkB,CAAC;aACvC,CAAC,CAAC;QACL,CAAC;QAED,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACvF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,aAAa,CACpC;YACE,KAAK,EAAE,KAAK,CAAC,IAAI;YACjB,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrE,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,EACD,GAAG,CACJ,CAAC;QAEF,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE,aAAa,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxF,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChC,GAAG,CAAC,MAAM,CAAC,MAAM,CACf,yBAAyB,KAAK,CAAC,IAAI,IAAI,YAAY,CAAC,CAAC,CAAC,OAAO,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,MAAM,CAAC,QAAQ,KAAK;gBAC7G,yIAAyI,CAC5I,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAClC,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpD,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3D,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC1C,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;QACZ,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,8BAA8B,EAAE,CAAC,CAAC;QAC5F,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,oDAAoD,CAAC,CAAC;QAC1F,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YAC1B,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/E,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,SAAS,GAAG,QAAQ,EAAE,CAAC,CAAC;YAC7D,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC;YACjD,MAAM,IAAI,GAAG;gBACX,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI;gBACzD,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI;aACxC;iBACE,MAAM,CAAC,OAAO,CAAC;iBACf,IAAI,CAAC,KAAK,CAAC,CAAC;YACf,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QACD,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/screen-name.tool.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview `sanctions_screen_name` — the 80% entry point. Screens a name
+ * against all loaded watchlists (OFAC SDN + Consolidated, EU, UK, UN) at once,
+ * alias- and fuzzy-aware, and returns scored potential matches with source
+ * provenance. This is decision support, NOT a compliance determination: a hit is
+ * a candidate to verify against the official source, and an empty result is
+ * never a clearance.
+ * @module mcp-server/tools/definitions/screen-name.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const screenNameTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    name: z.ZodString;
+    entityType: z.ZodDefault<z.ZodEnum<{
+        any: "any";
+        person: "person";
+        organization: "organization";
+        vessel: "vessel";
+        aircraft: "aircraft";
+    }>>;
+    matchMode: z.ZodDefault<z.ZodEnum<{
+        strict: "strict";
+        fuzzy: "fuzzy";
+    }>>;
+    minScore: z.ZodOptional<z.ZodNumber>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        ofac_sdn: "ofac_sdn";
+        ofac_consolidated: "ofac_consolidated";
+        eu: "eu";
+        uk: "uk";
+        un: "un";
+    }>>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    hits: z.ZodArray<z.ZodObject<{
+        source: z.ZodEnum<{
+            ofac_sdn: "ofac_sdn";
+            ofac_consolidated: "ofac_consolidated";
+            eu: "eu";
+            uk: "uk";
+            un: "un";
+        }>;
+        sourceLabel: z.ZodString;
+        sourceEntryId: z.ZodString;
+        entityType: z.ZodEnum<{
+            unknown: "unknown";
+            person: "person";
+            organization: "organization";
+            vessel: "vessel";
+            aircraft: "aircraft";
+        }>;
+        primaryName: z.ZodString;
+        matchedName: z.ZodString;
+        matchedNameType: z.ZodEnum<{
+            primary: "primary";
+            aka: "aka";
+            fka: "fka";
+            "low-quality-aka": "low-quality-aka";
+        }>;
+        matchType: z.ZodEnum<{
+            exact: "exact";
+            strong: "strong";
+            approximate: "approximate";
+        }>;
+        score: z.ZodOptional<z.ZodNumber>;
+        program: z.ZodOptional<z.ZodString>;
+        designationDate: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    caveat: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "mirror_not_ready";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The sanctions mirror has never completed an initial sync.";
+    readonly retryable: true;
+    readonly recovery: "Run the mirror:init lifecycle script to load the sanctions lists, then retry; check sanctions_list_sources for readiness.";
+}], {
+    readonly normalizedQuery: z.ZodString;
+    readonly matchModeUsed: z.ZodString;
+    readonly totalCount: z.ZodNumber;
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=screen-name.tool.d.ts.map

package/dist/mcp-server/tools/definitions/screen-name.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-name.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/screen-name.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA4CjE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgJzB,CAAC"}

package/dist/mcp-server/tools/definitions/screen-name.tool.js

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview `sanctions_screen_name` — the 80% entry point. Screens a name
+ * against all loaded watchlists (OFAC SDN + Consolidated, EU, UK, UN) at once,
+ * alias- and fuzzy-aware, and returns scored potential matches with source
+ * provenance. This is decision support, NOT a compliance determination: a hit is
+ * a candidate to verify against the official source, and an empty result is
+ * never a clearance.
+ * @module mcp-server/tools/definitions/screen-name.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getScreeningService } from '../../../services/screening/screening-service.js';
+import { SOURCE_CODES, SOURCE_LABELS } from '../../../services/screening/types.js';
+import { SCREENING_CAVEAT } from './_shared.js';
+const SOURCE_ENUM = z.enum(['ofac_sdn', 'ofac_consolidated', 'eu', 'uk', 'un']);
+const HitSchema = z
+    .object({
+    source: SOURCE_ENUM.describe('Which watchlist this candidate is on — its provenance.'),
+    sourceLabel: z.string().describe('Human-readable name of the source list.'),
+    sourceEntryId: z
+        .string()
+        .describe("The list's own entry ID — pass to sanctions_get_designation for the full record."),
+    entityType: z
+        .enum(['person', 'organization', 'vessel', 'aircraft', 'unknown'])
+        .describe('Entity classification as published by the source.'),
+    primaryName: z.string().describe('Primary published name of the designated entity.'),
+    matchedName: z.string().describe('The specific name or alias string that matched the query.'),
+    matchedNameType: z
+        .enum(['primary', 'aka', 'fka', 'low-quality-aka'])
+        .describe('Provenance of the matched name: primary, a.k.a., f.k.a., or a low-quality a.k.a.'),
+    matchType: z
+        .enum(['exact', 'strong', 'approximate'])
+        .describe('exact = normalized name equality; strong = all query tokens present; approximate = fuzzy/phonetic.'),
+    score: z
+        .number()
+        .optional()
+        .describe('Raw Jaro-Winkler similarity (0–1) for approximate hits only — a real measurement, not a confidence verdict. Absent for exact/strong hits.'),
+    program: z
+        .string()
+        .optional()
+        .describe('Sanctioning program / regime, when published by the source.'),
+    designationDate: z
+        .string()
+        .optional()
+        .describe('Designation date as published, when available.'),
+})
+    .describe('One potential match — a candidate to verify, never a determination.');
+export const screenNameTool = tool('sanctions_screen_name', {
+    title: 'sanctions-screening-mcp-server: screen name',
+    description: 'Screen a name (person, company, vessel, aircraft) against all loaded sanctions watchlists at once — OFAC SDN + Consolidated, EU, UK, and UN — alias- and fuzzy-aware. Returns scored potential matches with the source list, sanctioning program, designation date, and the matched alias. Strict mode (default) matches exact-normalized then all-tokens-present; fuzzy mode (or auto when strict is empty) adds Jaro-Winkler and phonetic matching and labels hits approximate with a raw 0–1 similarity score. This is a screening AID for a human/compliance review, NOT a compliance determination: a hit means "review this candidate against the official source," and an empty result never means "cleared."',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    input: z.object({
+        name: z
+            .string()
+            .min(1)
+            .describe('The name to screen (person, organization, vessel, or aircraft).'),
+        entityType: z
+            .enum(['any', 'person', 'organization', 'vessel', 'aircraft'])
+            .default('any')
+            .describe('Restrict to one entity class, or "any" (default) to screen across all.'),
+        matchMode: z
+            .enum(['strict', 'fuzzy'])
+            .default('strict')
+            .describe('strict (default): exact-normalized then all-tokens-present. fuzzy: also scored Jaro-Winkler + phonetic. Strict auto-falls-back to fuzzy when it finds nothing.'),
+        minScore: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("Jaro-Winkler similarity floor for fuzzy hits (0–1). Applies to fuzzy mode only; defaults to the server's configured floor."),
+        sources: z
+            .array(SOURCE_ENUM)
+            .optional()
+            .describe('Restrict to specific source lists. Omit to screen all loaded lists.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(25)
+            .describe('Maximum number of potential matches to return.'),
+    }),
+    output: z.object({
+        hits: z.array(HitSchema).describe('Scored potential matches, highest-confidence first.'),
+        caveat: z
+            .string()
+            .describe('Decision-support caveat — this is a screening aid, not a compliance determination.'),
+    }),
+    enrichment: {
+        normalizedQuery: z.string().describe('The name as the server folded it for matching.'),
+        matchModeUsed: z
+            .string()
+            .describe('The match mode actually applied (strict may auto-upgrade to fuzzy on empty).'),
+        totalCount: z.number().describe('Number of potential matches returned.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Guidance when no candidate matched — how to broaden, and what an empty result does NOT mean.'),
+    },
+    errors: [
+        {
+            reason: 'mirror_not_ready',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'The sanctions mirror has never completed an initial sync.',
+            retryable: true,
+            recovery: 'Run the mirror:init lifecycle script to load the sanctions lists, then retry; check sanctions_list_sources for readiness.',
+        },
+    ],
+    async handler(input, ctx) {
+        const svc = getScreeningService();
+        if (!(await svc.sanctionsReady())) {
+            throw ctx.fail('mirror_not_ready', 'The local sanctions mirror is not yet populated.', {
+                ...ctx.recoveryFor('mirror_not_ready'),
+            });
+        }
+        const sources = input.sources && input.sources.length > 0 ? input.sources : [...SOURCE_CODES];
+        const result = await svc.screenName({
+            query: input.name,
+            entityType: input.entityType,
+            matchMode: input.matchMode,
+            ...(input.minScore !== undefined ? { minScore: input.minScore } : {}),
+            sources,
+            limit: input.limit,
+        }, ctx);
+        ctx.enrich({ normalizedQuery: result.normalizedQuery, matchModeUsed: result.modeUsed });
+        ctx.enrich.total(result.hits.length);
+        if (result.hits.length === 0) {
+            ctx.enrich.notice(`No potential match for "${input.name}" across the selected lists (mode: ${result.modeUsed}). ` +
+                'This is NOT a clearance — the entity may be listed under a name variant the mirror does not index, ' +
+                'or under a transliteration. Try matchMode:"fuzzy", a broader name, or verify directly against the official source.');
+        }
+        return {
+            hits: result.hits.map((h) => ({
+                source: h.source,
+                sourceLabel: SOURCE_LABELS[h.source],
+                sourceEntryId: h.sourceEntryId,
+                entityType: h.entityType,
+                primaryName: h.primaryName,
+                matchedName: h.matchedName,
+                matchedNameType: h.matchedNameType,
+                matchType: h.matchType,
+                ...(h.score !== undefined ? { score: h.score } : {}),
+                ...(h.program ? { program: h.program } : {}),
+                ...(h.designationDate ? { designationDate: h.designationDate } : {}),
+            })),
+            caveat: SCREENING_CAVEAT,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        if (result.hits.length === 0) {
+            lines.push('**No potential matches found.**');
+        }
+        else {
+            lines.push(`**${result.hits.length} potential match(es)** — candidates to verify, not determinations:\n`);
+            for (const h of result.hits) {
+                const scoreStr = h.score !== undefined ? ` · score ${h.score.toFixed(3)}` : '';
+                lines.push(`### ${h.primaryName} — ${h.matchType}${scoreStr}`);
+                lines.push(`**List:** ${h.sourceLabel} (\`${h.source}\`) | **Entry ID:** ${h.sourceEntryId} | **Type:** ${h.entityType}`);
+                lines.push(`**Matched on:** "${h.matchedName}" (${h.matchedNameType})`);
+                if (h.program)
+                    lines.push(`**Program:** ${h.program}`);
+                if (h.designationDate)
+                    lines.push(`**Designated:** ${h.designationDate}`);
+                lines.push('');
+            }
+        }
+        lines.push(`> ${result.caveat}`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=screen-name.tool.js.map

package/dist/mcp-server/tools/definitions/screen-name.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-name.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/screen-name.tool.ts"],"names":[],"mappings":"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"}