# Developer Protocol

**Server:** sanctions-screening-mcp-server
**Version:** 0.6.1
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
**Engines:** Bun ≥1.4.4, Node ≥24.0.0
**MCP SDK:** `@modelcontextprotocol/server` ^2.4.0 (via the framework)
**Zod:** ^4.6.7

> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

---

## What This Server Is

Entity screening and resolution over eleven sanctions and export-control lists plus the GLEIF legal-entity registry, served offline. The lists are OFAC SDN/Consolidated, EU, UK, UN, BIS Entity/Denied Persons/Unverified/Military End User, and State ITAR Debarred/Nonproliferation Sanctions. Name and exact-identifier screening share this corpus; GLEIF supplies accounting-consolidation relationship tracing.

**Screening aid, not a compliance determination.** Every tool returns *potential matches* with a transparent score and source provenance — never a verdict. This framing is load-bearing: it lives in `SCREENING_CAVEAT` (`src/mcp-server/tools/definitions/_shared.ts`), in every screening tool's description, and in its output. A hit is a candidate to verify against the official source; an empty result is never a clearance. Preserve it in any edit to the surface.

**The data path is a local mirror, not a live API.** All eleven watchlists and GLEIF use keyless bulk downloads. The six BIS/State lists share one CSL download per sync; skip CSL Treasury copies, preserve provider id verbatim, and retain missing type as unknown. They are normalized into two local SQLite + FTS5 mirrors via the framework `MirrorService` — a sanctions `designation` mirror with a per-alias `name` index (Double-Metaphone phonetic keys) and a per-identifier `designation_identifier` index, and a GLEIF `lei_entity` mirror with a per-name `lei_name` index (legal, other, and transliterated names, typed) and a `lei_relationship` ownership table. The real corpus loads out-of-band via `bun run mirror:init`; the read path gates on mirror readiness. **Do not commit or modify the populated `data/` mirrors** — they are environment state, not source.

**Match signal is the raw Jaro-Winkler value (0–1) — never a fabricated confidence percentage.** Strict matching (exact-normalized → all-tokens-present via FTS5) is the default and the ~90% path; fuzzy (Jaro-Winkler + phonetic) is opt-in, or runs on its own over each selected list a strict screen found nothing on (all of them when strict found nothing anywhere). Surface only real signal: `matchType` (`exact`/`strong`/`approximate`), the matched name and its type, the raw score for approximate hits, and `queryTokenCoverage` — a literal count of the query tokens a candidate explains. Coverage ranks candidates the score ties (one shared exact token pins several at 1.0) and is surfaced so a caller can account for that order; it is a second measurement beside the score, never a term blended into it.

---

## Core Rules

- Source membership derives from `SOURCE_CODES`; keep default screens, cross-references, source listings, and schemas aligned automatically. OFAC grouping remains limited to its two direct feeds. CSL restrictions, notices, end dates, and provenance URLs remain labeled features, never inferred legal status.
- Ownership traces page nodes, then edges, then boundaries (50 default, 100 maximum records; soft 64-KiB target with intact oversized records). Drain a segment before same-side boundary re-rooting; deduplicate branch roots and edges. Topology fingerprints invalidate changed graphs; entity and screening values remain current rather than frozen. Completeness covers loaded accounting-consolidation data only.
- `sanctionsAsOf` is the last successful local all-list sync, not upstream publication freshness. Existing mirrors need `mirror:refresh` to load newly supported sources; configured source rows can have zero stored records before that refresh.

- **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
- **Use `ctx.log`** for request-scoped logging. No `console` calls.
- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
- **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler. (No tool here does — every read is answered from the mirror.)
- **Secrets in env vars only** — never hardcoded.
- **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.
- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.

---

## Patterns

### Tool

Real example: `sanctions_screen_name` (trimmed). Note the typed error contract (`errors[]` + `ctx.fail`), the load-bearing caveat in the output, and the `enrichment` block for non-result metadata (normalized query, mode used, empty-result notice).

```ts
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';

export const screenNameTool = tool('sanctions_screen_name', {
  title: 'sanctions-screening-mcp-server: screen name',
  description: 'Screen a name against all loaded sanctions watchlists at once … a screening AID, not a compliance determination.',
  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).'),
    matchMode: z.enum(['strict', 'fuzzy']).default('strict').describe('strict: exact then all-tokens-present. fuzzy: also Jaro-Winkler + phonetic.'),
    limit: z.number().int().min(1).max(100).default(25).describe('Maximum number of potential matches to return.'),
    // … entityType, minScore, sources
  }),
  output: z.object({
    hits: z.array(HitSchema).describe('Scored potential matches, highest-confidence first.'),
    caveat: z.string().describe('Decision-support caveat — 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('fuzzy when every selected list was fuzzy-searched; strict otherwise, including a strict screen whose strict-empty lists were completed.'),
    totalCount: z.number().describe('Number of potential matches returned.'),
    notice: z.string().optional().describe('Guidance when no candidate matched.'),
  },
  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.' },
  ],

  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.');
    }
    const sources = input.sources?.length ? input.sources : [...SOURCE_CODES];
    const result = await svc.screenName({ query: input.name, matchMode: input.matchMode, sources, limit: input.limit }, ctx);
    ctx.enrich({ normalizedQuery: result.normalizedQuery, matchModeUsed: result.modeUsed });
    ctx.enrich.total(result.hits.length);
    return { hits: result.hits.map((h) => ({ ...h, sourceLabel: SOURCE_LABELS[h.source] })), caveat: SCREENING_CAVEAT };
  },

  // format() populates content[] — the markdown twin of structuredContent. Both
  // surfaces must carry the same data (lint-enforced). The caveat renders last.
  format: (result) => [{ type: 'text', text: renderHits(result) }],
});
```

### Resource

Real example: `sanctions://entity/{lei}` — a URI mirror of `sanctions_get_entity`'s entity payload (the screening cross-reference is tool-only). Resources mirror tool data for resource-capable clients; tools are the primary path.

```ts
import { resource, z } from '@cyanheads/mcp-ts-core';
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
import { canonicalLei, LeiInputSchema } from '@/mcp-server/normalize-inputs.js';
import { getScreeningService } from '@/services/screening/screening-service.js';

export const entityResource = resource('sanctions://entity/{lei}', {
  name: 'sanctions-screening-mcp-server: entity',
  title: 'sanctions-screening-mcp-server: entity',
  description: "Fetch one GLEIF Level 1 legal-entity record by LEI — a read-only URI mirror of sanctions_get_entity's entity payload.",
  mimeType: 'application/json',
  params: z.object({
    lei: LeiInputSchema.describe('The 20-character GLEIF Legal Entity Identifier.'),
  }),
  errors: [
    { reason: 'lei_not_found', code: JsonRpcErrorCode.NotFound,
      when: 'No GLEIF entity exists for the given LEI in the mirror.',
      recovery: 'Resolve the entity name with sanctions_resolve_entity to obtain a valid LEI first.' },
  ],
  async handler(params, ctx) {
    const lei = canonicalLei(params.lei, 'sanctions://entity/{lei}', ctx);
    const entity = await getScreeningService().getLeiEntity(lei);
    if (!entity) throw ctx.fail('lei_not_found', `No GLEIF entity with LEI "${lei}".`);
    return entity;
  },
});
```

### Prompt

Real example: `sanctions_vet_counterparty` — sequences the existing tools into a due-diligence workflow. No new capability; a reusable framing.

```ts
import { prompt, z } from '@cyanheads/mcp-ts-core';

export const vetCounterpartyPrompt = prompt('sanctions_vet_counterparty', {
  title: 'sanctions-screening-mcp-server: vet counterparty',
  description: 'Structure a full counterparty due-diligence pass: resolve the name to an LEI, pull its GLEIF ownership graph, screen the named entity and every parent and subsidiary in that graph, and summarize hits with provenance and the decision-support caveat.',
  args: z.object({
    name: z.string().describe('The counterparty name to vet (person or organization).'),
    jurisdiction: z.string().optional().describe('Optional jurisdiction: a country code, which includes its subdivisions ("US"), or an ISO 3166-2 subdivision code ("US-DE").'),
  }),
  generate: (args) => [
    { role: 'user', content: { type: 'text', text: `Run a counterparty due-diligence pass on "${args.name}". Screen the name, resolve it to an LEI, trace ownership with screenNodes:true, then summarize every potential match as a candidate to verify — never a determination.` } },
  ],
});
```

### Server config

```ts
// src/config/server-config.ts — lazy-parsed, separate from framework config.
// All sources are keyless; there are no secret values here. Every field is
// optional with a default — the mirror path, the fuzzy score floor, the refresh
// cron, and per-source URL overrides.
import { z } from '@cyanheads/mcp-ts-core';
import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';

const ServerConfigSchema = z.object({
  mirrorPath: z.string().default('./data/sanctions.db').describe('Filesystem path for the SQLite mirror.'),
  refreshCron: z.string().default('0 4 * * *').describe('Cron for the scheduled refresh (HTTP only).'),
  fuzzyMinScore: z.coerce.number().min(0).max(1).default(0.85).describe('Default Jaro-Winkler floor for fuzzy matches.'),
  // … per-source URL overrides (ofacSdnUrl, euFsfUrl, ukSanctionsUrl, unScUrl, gleifGoldenCopyBaseUrl)
});

let _config: z.infer<typeof ServerConfigSchema> | undefined;
export function getServerConfig() {
  _config ??= parseEnvConfig(ServerConfigSchema, {
    mirrorPath: 'SANCTIONS_MIRROR_PATH',
    refreshCron: 'SANCTIONS_REFRESH_CRON',
    fuzzyMinScore: 'SANCTIONS_FUZZY_MIN_SCORE',
    // … OFAC_SDN_URL, EU_FSF_URL, UK_SANCTIONS_URL, UN_SC_URL, GLEIF_GOLDEN_COPY_BASE_URL
  });
  return _config;
}
```

`parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`SANCTIONS_MIRROR_PATH`) not the path (`mirrorPath`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.

For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.

### Server identity and instructions

`createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`):

```ts
await createApp({
  name: 'my-mcp-server',
  title: 'My Server',                         // human-readable display name
  websiteUrl: 'https://github.com/owner/repo', // canonical homepage URL
  description: 'One-line description.',        // wins over MCP_SERVER_DESCRIPTION
  icons: [{ src: 'https://example.com/icon.png', sizes: ['48x48'], mimeType: 'image/png' }],
  instructions: 'Use shortcut alpha for the most common case.', // session-level context
});
```

`instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.

`createApp({ cacheHints })` sets what a 2026-07-28 client may cache per operation. This server declares an hour on the listing operations (`tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`, `server/discover`), scoped `public` because the same listings are already served unauthenticated. Per-record read lifetimes live on the resource definitions as `cacheHint`: an hour, `private`, on the designation and entity records; `ttlMs: 0` on `sanctions://sources`, whose payload IS the mirror's freshness.

### Session posture and shutdown

Two more `createApp()` options shape how the server runs rather than how it presents itself:

```ts
await createApp({
  sessionMode: 'stateless',
  async setup() { initScreeningService(); await scheduleSanctionsRefresh(); },
  async teardown() {
    await stopSanctionsRefresh();
    await getScreeningService().close();
  },
});
```

`sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). This server declares `stateless`: every read is answered from the mirror and no tool calls `ctx.requestInput`, so nothing needs a session to come back to. A server whose tools do would add `require: 'stateful'`, failing startup with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused.

`teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. Here it first stops refresh cron ticks, cancels and awaits the child (five-second grace, then SIGKILL), then closes both serving mirrors and their prepared statements. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling). The framework destroys cron registrations; the server owns and reaps its child.

---

## Context

Handlers receive a unified `ctx` object. Key properties:

| Property | Description |
|:---------|:------------|
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
| `ctx.fail` | Typed error contract — `ctx.fail(reason, msg, …)` against the definition's `errors[]` union; the framework puts the declared `recovery` on the wire. Used by every read tool to throw `mirror_not_ready` / `*_not_found`. |
| `ctx.enrich` | Attach non-result metadata to the response — `ctx.enrich({ … })`, `ctx.enrich.total(n)`, `ctx.enrich.notice(text)`. Used by `screen_name` / `resolve_entity` for the normalized query, the mode actually applied, and the empty-result guidance. |
| `ctx.requestInput` / `ctx.inputs` | Suspend and ask the caller for more input — `return ctx.requestInput(...)`, then read `ctx.inputs.accepted(key, schema)` on re-entry; `ctx.inputs` holds only responses the client's declared capabilities cover. Unused here; every read is answered from the mirror. |
| `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context; never a reason to skip a consent prompt. Unused here. |
| `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
| `ctx.signal` | `AbortSignal` for cancellation (propagated into the mirror sync on the refresh path). |
| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |

This server's persistence is the local SQLite mirror, owned by the screening service and reached via `getScreeningService()` — not `ctx.state`. The data is a shared global corpus, not tenant-scoped KV, so the service-accessor pattern replaces `ctx.state` here.

---

## Errors

Handlers throw — the framework catches, classifies, and formats.

**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.

```ts
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';

errors: [
  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
    when: 'No item matched the query',
    recovery: 'Broaden the query or check the spelling and try again.' },
],
async handler(input, ctx) {
  const item = await db.find(input.id);
  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
  return item;
}
```

**Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.

**Fallback (no contract entry fits):** throw via factories or plain `Error`.

```ts
// Error factories — explicit code
import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
throw notFound('Item not found', { itemId });
throw serviceUnavailable('API unavailable', { url }, { cause: err });

// Plain Error — framework auto-classifies from message patterns
throw new Error('Item not found');           // → NotFound
throw new Error('Invalid query format');     // → ValidationError

// McpError — when no factory exists for the code
import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });
```

See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.

---

## Structure

```text
src/
  index.ts                              # createApp() entry point; schedules HTTP mirror refresh
  config/
    server-config.ts                    # Server-specific env vars (Zod schema) — mirror path, fuzzy tuning, source URLs
  services/
    screening/
      screening-service.ts              # Owns the local mirrors + matching engine (init/accessor pattern)
      schema.ts                         # Normalized designation/name/identifier/lei_entity/lei_name/lei_relationship schema + MirrorService defs + each spec's v2 migration
      sanctions-ingest.ts               # OFAC/EU/UK/UN streaming ingesters (record-at-a-time XML → normalized designations)
      csl-ingest.ts                     # Shared trade.gov download and per-list spools for six BIS/State lists
      gleif-ingest.ts                   # GLEIF files — publication index, header-first streaming of L1/L2/reporting-exception files, deletion markers
      gleif-sync.ts                     # GLEIF lifecycles — golden-copy load + checkpointed delta refresh (window per dataset, one commit)
      ingest-validation.ts              # Shared drop predicate + per-source rejection tally — no source identity or no usable name means no row
      text-matching.ts                  # Fold/tokenize, Jaro-Winkler, Double-Metaphone, the fuzzy-admission stoplist (FUZZY_STOPLIST)
      candidate-pool.ts                 # Fuzzy blocking pool — whole blocks, smallest first, under one budget, then pair lookups
      cross-reference.ts                # get_entity / trace_ownership cross-reference — strict name screens + LEI and registration-number lookups, merged per designation
      country-codes.ts                  # Published country names → ISO 3166-1 alpha-2 (the registration-number country gate)
      lei-checksum.ts                   # ISO 17442 check digits — invalid_lei_checksum on a mirror miss
      identifier-matching.ts            # Identifier label → category table + per-category exact-match keys (IMO, BIC8, wallet case by shape)
      types.ts                          # Source codes, labels, domain types
      fixtures.ts                       # Synthetic fixture for mirror:seed / tests
      xml.ts                            # Attribute-preserving XML parser (fast-xml-parser wrapper)
      xml-stream.ts                     # UTF-8 stream decoder + record-boundary scanner (bounds every ingest) + root-close check
      source-fetch.ts                   # Streamed source download — 120 s headers bound, body bounded only by the run's signal
      sanctions-refresh.ts              # The refresh run (sanctions, then GLEIF deltas), its HTTP cron job, and the long-run time bound
      scheduled-refresh-process.ts      # Supervised compiled child, pipe drain, cancellation and teardown
      scheduled-refresh-job.ts          # Deltas-only scheduled entry, compiled into dist
  mcp-server/
    tools/definitions/
      *.tool.ts                         # Seven tools (screen-name, screen-identifier, get-designation, resolve-entity, get-entity, trace-ownership, list-sources)
      _shared.ts                        # SCREENING_CAVEAT (load-bearing decision-support caveat)
    resources/definitions/
      *.resource.ts                     # Three URI mirrors (designation, entity, sources)
    prompts/definitions/
      vet-counterparty.prompt.ts        # Counterparty due-diligence workflow prompt
scripts/
  mirror-init.ts / mirror-refresh.ts / mirror-verify.ts / mirror-seed.ts   # Mirror lifecycle CLI
  _mirror-context.ts                    # Shared bootstrap shim for the mirror scripts
```

---

## Naming

| What | Convention | Example |
|:-----|:-----------|:--------|
| Files | kebab-case with suffix | `search-docs.tool.ts` |
| Tool/resource/prompt names | snake_case | `search_docs` |
| Directories | kebab-case | `src/services/doc-search/` |
| Descriptions | Single string or template literal, no `+` concatenation | `'Search items by query and filter.'` |

---

## Skills

Two skill trees live at the project root, written for different readers:

| Tree | For | Written by |
|:-----|:----|:-----------|
| `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
| `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |

Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.

A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.

`skills/sanctions-screening-guide/SKILL.md` is the published consumer guide: identity confirmation, ownership continuation, capped cross-reference recovery, and screening uncertainty.

**Agent skill directory:** Copy `framework-skills/` into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.

Available skills:

| Skill | Purpose |
|:------|:--------|
| `setup` | Post-init project orientation |
| `design-mcp-server` | Design tool surface, resources, and services for a new server |
| `add-tool` | Scaffold a new tool definition |
| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
| `add-resource` | Scaffold a new resource definition |
| `add-prompt` | Scaffold a new prompt definition |
| `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
| `add-service` | Scaffold a new service integration |
| `add-test` | Scaffold test file for a tool, resource, or service |
| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
| `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
| `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
| `api-auth` | Auth modes, scopes, JWT/OAuth |
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
| `api-config` | AppConfig, parseConfig, env vars |
| `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
| `api-services` | LLM, Speech, Graph services |
| `api-testing` | createMockContext, test patterns |
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
| `api-workers` | Cloudflare Workers runtime |

**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.

When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).

---

## Commands

**Runtime:** Scripts use Bun's native TypeScript execution — `bun run <cmd>` is the standard invocation. `npm run <cmd>` also works (npm delegates to bun).

| Command | Purpose |
|:--------|:--------|
| `bun run build` | Compile TypeScript |
| `bun run rebuild` | Clean + build |
| `bun run clean` | Remove build artifacts |
| `bun run devcheck` | Lint + format + typecheck + security + changelog/skills/docs sync |
| `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
| `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile |
| `bun run tree` | Generate directory structure doc (`docs/tree.md`) |
| `bun run list-skills` | Print the skill registry |
| `bun run format` | Auto-fix formatting (safe fixes only) |
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
| `bun run lint:mcp` | Validate MCP definitions against the linter rule catalog |
| `bun run lint:packaging` | Validate `manifest.json` ↔ `server.json` env-var consistency |
| `bun run test` | Run the Vitest suite (use `bun run test`, not `bun test` — the bare subcommand bypasses Vitest) |
| `bun run test:coverage` | Run the Vitest suite with istanbul coverage |
| `bun run start:stdio` | Production mode (stdio) |
| `bun run start:http` | Production mode (HTTP) |
| `bun run mirror:init` | Full out-of-band initial load of all sources (sanctions lists + GLEIF golden copies, recording the GLEIF checkpoint). Hours-long and safe to re-run (an interrupted run starts over); never on the request path. |
| `bun run mirror:refresh` | Re-harvest sanctions lists, removing what a list's complete document no longer publishes, then apply the GLEIF delta windows the checkpoint calls for. Exits non-zero naming `mirror:init` when a GLEIF gap cannot be covered. The same run is the HTTP cron (GLEIF deltas only). |
| `bun run mirror:verify` | Report mirror readiness, per-source record counts, GLEIF counts, and the GLEIF checkpoint. |
| `bun run mirror:seed` | Load a small synthetic fixture for local smoke tests (no downloads). |
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
| `bun run release:github` | Create the GitHub release from the changelog/tag. |

**CI is one file.** `.github/workflows/codeql.yml` is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.

---

## Bundling

`bun run bundle` builds the stdio extension for Claude Desktop. `mcpb pack` uses `.mcpbignore`, so development files need root-anchored exclusions. Root `skills/` ships with the bundle. `scripts/clean-mcpb.ts` prunes dev dependencies, dependency-root agent docs, platform-specific bindings, and build-only files. Runtime modules such as the SDK’s nested `skills/` and compiled `better-sqlite3` addon remain. `lint:packaging` verifies the result.

**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.

**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.

---

## Changelog

Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `npm run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `npm run changelog:build` — devcheck hard-fails on drift; never hand-edit it.

Each per-version file opens with YAML frontmatter:

```markdown
---
summary: "One-line headline, ≤350 chars"  # required — powers the rollup index
breaking: false                            # optional — true flags breaking changes
security: false                            # optional — true ONLY for a source-code security fix, never a dependency CVE bump
---

# 0.1.0 — YYYY-MM-DD
...
```

`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.

`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.

**Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.

**Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.

---

## Publishing

**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.

---

## Imports

```ts
// Framework — z is re-exported, no separate zod import needed
import { tool, z } from '@cyanheads/mcp-ts-core';
import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';

// Server's own code — via path alias
import { getScreeningService } from '@/services/screening/screening-service.js';
import { SCREENING_CAVEAT } from '@/mcp-server/tools/definitions/_shared.js';
```

---

## Checklist

- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
- [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`.
- [ ] JSDoc `@fileoverview` + `@module` on every file
- [ ] `ctx.log` for logging, `ctx.state` for storage
- [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
- [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
- [ ] Source normalization reviewed against real upstream sparsity/nullability before finalizing required vs optional fields (the four sanctions XML shapes differ widely; UK XML is the messiest)
- [ ] Normalization and `format()` preserve uncertainty; never fabricate facts from missing source data
- [ ] Tests include at least one sparse payload case with omitted source fields
- [ ] **Screening-aid framing preserved** — `SCREENING_CAVEAT` in every screening tool's output; descriptions say "candidate to verify," empty result is "not a clearance"
- [ ] **No fabricated confidence** — approximate hits surface the raw Jaro-Winkler score (0–1); never a composite/synthesized percentage
- [ ] **Read path gates on mirror readiness** — `svc.sanctionsReady()` / `svc.leiReady()` before querying; throw `mirror_not_ready` otherwise
- [ ] Display identity is `sanctions-screening-mcp-server` everywhere (`name`/`title`, manifest, docs) — never Title Case
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
- [ ] `bun run devcheck` passes