@pharmasync/mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AyeOnGo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @pharmasync/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [MCP](https://modelcontextprotocol.io) server that makes the **Pharmasync**
+UK medicine-supply data legible to AI agents.
+
+It is a **read-only client of the public [`pharmasync.xyz/api/v1`](https://pharmasync.xyz/api/v1)
+artefacts** — a static, open-licensed CDN feed. The server holds no API keys,
+opens no database, and stands up no infrastructure: every answer is computed
+from data any agent could fetch itself, over a single fixed origin. It exposes
+nothing that is not already public; it exists to turn an open contract into
+tools an agent can actually call.
+
+## Install & run
+
+Requires **Node.js ≥ 20**. No account, no key, no configuration.
+
+```bash
+npx @pharmasync/mcp
+```
+
+The server speaks MCP over **stdio**, so it is launched by an MCP client rather
+than run by hand.
+
+### Wire it into an MCP client
+
+Add it to your client's server config. For a Claude Desktop–style
+`mcpServers` block:
+
+```json
+{
+  "mcpServers": {
+    "pharmasync": {
+      "command": "npx",
+      "args": ["-y", "@pharmasync/mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+All five tools are **read-only** and answer from the public artefacts. Every
+severity tier is a citation of a public government act, reproducible without
+trusting Pharmasync.
+
+| Tool | What it returns |
+|---|---|
+| `lookup_product` | A UK medicine by exact dm+d code or a name substring: the product, its current severity tier (with the citing act), and its supply events (MSN / SSP / price concession), newest first. |
+| `current_shortages` | Medicines with a severity tier in force — **WATCH** (a Medicine Supply Notification), **CONCERN** (a restricted-export designation), or **CRITICAL** (a Serious Shortage Protocol) — ranked highest first, each with its citation. Optionally filtered to one tier. |
+| `changes_since` | Detected supply changes from the delta feed. Pass the `cursor` you last stored to get only newer changes; the response carries the next `latest_cursor` to store. |
+| `concessions_for` | The price-concession events for a medicine (by code or name substring), newest first — a financial-exposure and market-stress signal. |
+| `workforce_stats` | The Workforce Panel ledger — the second supply chain: medicines and the people who dispense them. Vacancy rate by role/region, GPhC registrant counts, pharmacy network change by region, and shortage designation status, newest period first. Optionally filtered by `metric`, `role` and/or `region`. Not a jobs board — observed aggregate data only. |
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `PHARMASYNC_API` | `https://pharmasync.xyz/api/v1` | The artefact origin the server reads. Every request is pinned to this one host; tool arguments only filter fetched data and never reach a URL. |
+
+## Data & provenance
+
+The underlying artefacts are published under an open licence and are fully
+disclosed at [`pharmasync.xyz/api/v1`](https://pharmasync.xyz/api/v1)
+(schemas, methodology, coverage, and freshness/status). Data is fetched live at
+tool-call time, so answers are as current as the feed — nothing is bundled or
+cached stale.
+
+## License
+
+[MIT](./LICENSE) © AyeOnGo

package/dist/api.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A read-only client of the public Pharmasync API (`/api/v1`), for the MCP server (S8).
+ *
+ * The whole security posture of this package lives here. Every fetch goes to a **single,
+ * fixed origin** (`PHARMASYNC_API`, defaulting to the production CDN). Tool arguments filter
+ * data that has already been fetched — they never contribute to a URL, a host, or a path.
+ * So there is no SSRF surface: an argument cannot redirect a request anywhere, because
+ * arguments do not reach `fetch` at all.
+ *
+ * The data it serves is the same boundary-clean, public logistics data the CDN publishes —
+ * no keys, no store, no credentials, nothing a `/api/v1` reader could not fetch itself. The
+ * MCP server is a convenience layer over the open contract, not a privileged path to it.
+ */
+import type { z } from 'zod';
+import { ARTEFACT_SCHEMAS, type ArtefactPath, type ChangeRecord, type ChangesIndex, type DmdProduct, type SupplyEvent, type Tier, type WorkforceStat } from './schemas.js';
+/** The one origin every request goes to. A URL like `https://pharmasync.xyz/api/v1`. */
+export declare const API_ORIGIN: string;
+/**
+ * Fetch a fixed artefact path relative to the API base, validate it, or throw.
+ *
+ * `relPath` is a key of `ARTEFACT_SCHEMAS` — a hard-coded literal, never derived from a tool
+ * argument. A failed fetch throws rather than returning stale or empty data, and so does a body
+ * that does not match the published schema: a tool that cannot read the contract says so, it does
+ * not hand an agent a shape it was never promised.
+ */
+export declare const getArtefact: <P extends ArtefactPath>(relPath: P) => Promise<z.infer<(typeof ARTEFACT_SCHEMAS)[P]>>;
+/**
+ * Fetch a segment listed in the change feed's own index (`segments[].path`), guarded.
+ *
+ * The path comes from *our own* published index, not from a tool argument — but it is still
+ * validated: it must be an absolute path under `/api/v1/changes/`, and the resolved URL must
+ * land on the pinned host. That rejects a protocol-relative `//evil.com/…` from ever being
+ * followed, even if a corrupted index somehow carried one. Defense in depth, per §2.3.
+ */
+export declare const getChangeSegment: (pathFromRoot: string) => Promise<ChangeRecord[]>;
+/**
+ * Validate a fetched body against its schema, or throw a message a tool can return verbatim.
+ *
+ * At most three issues are named, each with its JSON path, so an agent (or a human reading the
+ * tool error) can see *what* drifted without the message growing with the size of the corpus.
+ */
+export declare const parseArtefact: <S extends z.ZodType>(schema: S, body: unknown, url: string) => z.infer<S>;
+export type { ChangeRecord, ChangeSegmentRef, ChangesIndex, DmdProduct, SupplyEvent, Tier, TierLevel, WorkforceMetric, WorkforceStat, } from './schemas.js';
+export declare const getProducts: () => Promise<DmdProduct[]>;
+export declare const getTiers: () => Promise<Tier[]>;
+export declare const getEvents: () => Promise<SupplyEvent[]>;
+export declare const getChangesIndex: () => Promise<ChangesIndex>;
+export declare const getWorkforceStats: () => Promise<WorkforceStat[]>;

package/dist/api.js

@@ -0,0 +1,85 @@
+/**
+ * A read-only client of the public Pharmasync API (`/api/v1`), for the MCP server (S8).
+ *
+ * The whole security posture of this package lives here. Every fetch goes to a **single,
+ * fixed origin** (`PHARMASYNC_API`, defaulting to the production CDN). Tool arguments filter
+ * data that has already been fetched — they never contribute to a URL, a host, or a path.
+ * So there is no SSRF surface: an argument cannot redirect a request anywhere, because
+ * arguments do not reach `fetch` at all.
+ *
+ * The data it serves is the same boundary-clean, public logistics data the CDN publishes —
+ * no keys, no store, no credentials, nothing a `/api/v1` reader could not fetch itself. The
+ * MCP server is a convenience layer over the open contract, not a privileged path to it.
+ */
+import { ARTEFACT_SCHEMAS, ChangeSegmentSchema, } from './schemas.js';
+import { PACKAGE_VERSION } from './version.js';
+/** The one origin every request goes to. A URL like `https://pharmasync.xyz/api/v1`. */
+export const API_ORIGIN = (process.env.PHARMASYNC_API ?? 'https://pharmasync.xyz/api/v1').replace(/\/+$/, '');
+/** The scheme+host the whole package is pinned to — the SSRF allow-list, of size one. */
+const ORIGIN_ROOT = new URL(API_ORIGIN).origin;
+const FETCH_TIMEOUT_MS = 15_000;
+/**
+ * Fetch a fixed artefact path relative to the API base, validate it, or throw.
+ *
+ * `relPath` is a key of `ARTEFACT_SCHEMAS` — a hard-coded literal, never derived from a tool
+ * argument. A failed fetch throws rather than returning stale or empty data, and so does a body
+ * that does not match the published schema: a tool that cannot read the contract says so, it does
+ * not hand an agent a shape it was never promised.
+ */
+export const getArtefact = async (relPath) => {
+    const url = `${API_ORIGIN}/${relPath}`;
+    return parseArtefact(ARTEFACT_SCHEMAS[relPath], await fetchJson(url), url);
+};
+/**
+ * Fetch a segment listed in the change feed's own index (`segments[].path`), guarded.
+ *
+ * The path comes from *our own* published index, not from a tool argument — but it is still
+ * validated: it must be an absolute path under `/api/v1/changes/`, and the resolved URL must
+ * land on the pinned host. That rejects a protocol-relative `//evil.com/…` from ever being
+ * followed, even if a corrupted index somehow carried one. Defense in depth, per §2.3.
+ */
+export const getChangeSegment = async (pathFromRoot) => {
+    if (!/^\/api\/v1\/changes\/[A-Za-z0-9._-]+$/.test(pathFromRoot)) {
+        throw new Error(`refusing to fetch an unexpected change-segment path: ${pathFromRoot}`);
+    }
+    const url = new URL(pathFromRoot, `${ORIGIN_ROOT}/`);
+    if (url.origin !== ORIGIN_ROOT) {
+        throw new Error(`change-segment path resolved off-origin (${url.origin}); refusing`);
+    }
+    return parseArtefact(ChangeSegmentSchema, await fetchJson(url.toString()), url.toString());
+};
+/**
+ * Validate a fetched body against its schema, or throw a message a tool can return verbatim.
+ *
+ * At most three issues are named, each with its JSON path, so an agent (or a human reading the
+ * tool error) can see *what* drifted without the message growing with the size of the corpus.
+ */
+export const parseArtefact = (schema, body, url) => {
+    const result = schema.safeParse(body);
+    if (result.success)
+        return result.data;
+    const issues = result.error.issues;
+    const named = issues
+        .slice(0, 3)
+        .map((issue) => `${issue.path.length > 0 ? issue.path.join('.') : '(root)'}: ${issue.message}`)
+        .join('; ');
+    const more = issues.length > 3 ? ` (+${String(issues.length - 3)} more)` : '';
+    throw new Error(`GET ${url} returned a body that does not match the published schema — ${named}${more}`);
+};
+const fetchJson = async (url) => {
+    const response = await fetch(url, {
+        headers: { accept: 'application/json', 'user-agent': `pharmasync-mcp/${PACKAGE_VERSION} (+https://pharmasync.xyz)` },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new Error(`GET ${url} -> HTTP ${String(response.status)}`);
+    }
+    // `unknown`, deliberately: nothing reads this until `parseArtefact` has validated it.
+    const body = await response.json();
+    return body;
+};
+export const getProducts = () => getArtefact('products.json');
+export const getTiers = () => getArtefact('tiers.json');
+export const getEvents = () => getArtefact('events.json');
+export const getChangesIndex = () => getArtefact('changes/index.json');
+export const getWorkforceStats = () => getArtefact('workforce/stats.json');

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { API_ORIGIN, getChangeSegment, getChangesIndex, getEvents, getProducts, getTiers, getWorkforceStats, } from './api.js';
+import { MISSING_SELECTOR_MESSAGE, concessionsFor, currentShortages, filterWorkforceStats, hasSelector, lookupProducts, segmentsToFetch, } from './query.js';
+import { TIERS, WORKFORCE_METRICS } from './schemas.js';
+import { PACKAGE_VERSION } from './version.js';
+const ok = (value) => ({
+    content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+});
+const fail = (message) => ({
+    content: [{ type: 'text', text: `error: ${message}` }],
+    isError: true,
+});
+/** Wrap a tool body so a fetch/parse failure becomes an honest tool error, never a crash. */
+const guard = async (run) => {
+    try {
+        return await run();
+    }
+    catch (error) {
+        return fail(error.message);
+    }
+};
+const PRODUCT_SELECTOR = {
+    code: z.string().optional().describe('An exact dm+d code (VMP identifier), e.g. "42381011000001106".'),
+    name: z.string().optional().describe('A case-insensitive substring of the medicine name, e.g. "ramipril".'),
+};
+// Read from package.json (`version.ts`) — previously restated here by hand.
+const server = new McpServer({ name: 'pharmasync', version: PACKAGE_VERSION });
+server.registerTool('lookup_product', {
+    title: 'Look up a medicine',
+    description: 'Look up a UK medicine by exact dm+d code or by a substring of its name. Returns the dm+d ' +
+        'product, its current severity tier (the highest government act in force, with citation), and ' +
+        'its supply events (MSN / SSP / price concession), newest first. Provide `code` or `name`.',
+    inputSchema: PRODUCT_SELECTOR,
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ code, name }) => guard(async () => {
+    if (!hasSelector({ code, name }))
+        return fail(MISSING_SELECTOR_MESSAGE);
+    const [products, tiers, events] = await Promise.all([getProducts(), getTiers(), getEvents()]);
+    const results = lookupProducts(products, tiers, events, { code, name });
+    return ok({ query: { code, name }, count: results.length, results });
+}));
+server.registerTool('current_shortages', {
+    title: 'Current shortages by tier',
+    description: 'List the UK medicines with a government severity tier currently in force — WATCH (a Medicine ' +
+        'Supply Notification), CONCERN (a restricted-export designation) or CRITICAL (a Serious Shortage ' +
+        'Protocol) — ranked highest first, each with the citing act and its date. Optionally filter to one ' +
+        'tier. Every tier is a citation of a public act, reproducible without trusting Pharmasync.',
+    inputSchema: {
+        tier: z
+            .enum(TIERS)
+            .optional()
+            .describe('Restrict to a single tier. Omit for all tiers.'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ tier }) => guard(async () => {
+    const [tiers, products] = await Promise.all([getTiers(), getProducts()]);
+    const rows = currentShortages(tiers, products, tier);
+    return ok({ tier_filter: tier ?? null, count: rows.length, shortages: rows });
+}));
+server.registerTool('changes_since', {
+    title: 'Supply changes since a cursor',
+    description: 'Return detected supply changes from the delta feed. Pass the `cursor` you last stored to get only ' +
+        'newer changes; omit it for the full feed. Each response includes `latest_cursor` — store it and ' +
+        'pass it next time. The feed is not retrospective: events predating change detection carry no change ' +
+        'record (see the feed limitations).',
+    inputSchema: {
+        cursor: z
+            .string()
+            .optional()
+            .describe('The `latest_cursor` from a previous call (e.g. "2026-08"). Omit for all changes.'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ cursor }) => guard(async () => {
+    const index = await getChangesIndex();
+    const segments = segmentsToFetch(index, cursor);
+    const batches = await Promise.all(segments.map((s) => getChangeSegment(s.path)));
+    const changes = batches.flat();
+    return ok({
+        requested_cursor: cursor ?? null,
+        latest_cursor: index.latest_cursor,
+        cursor_protocol: index.cursor_protocol,
+        limitations: index.limitations,
+        count: changes.length,
+        changes,
+    });
+}));
+server.registerTool('concessions_for', {
+    title: 'Price concessions for a medicine',
+    description: 'Return the price-concession events for a medicine, by exact dm+d code or a substring of its name, ' +
+        'newest first. A concession is a financial-exposure and market-stress signal, published as the ' +
+        'source states it. Provide `code` or `name`.',
+    inputSchema: PRODUCT_SELECTOR,
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ code, name }) => guard(async () => {
+    if (!hasSelector({ code, name }))
+        return fail(MISSING_SELECTOR_MESSAGE);
+    const [products, events] = await Promise.all([getProducts(), getEvents()]);
+    const rows = concessionsFor(products, events, { code, name });
+    return ok({ query: { code, name }, count: rows.length, concessions: rows });
+}));
+server.registerTool('workforce_stats', {
+    title: 'The Workforce Panel ledger',
+    description: 'The second supply chain: medicines and the people who dispense them. Returns published ' +
+        'workforce indicators — vacancy rate by role and region, GPhC registrant counts, pharmacy ' +
+        'network change by region, and shortage designation status — newest period first. Optionally ' +
+        'filter by metric, role and/or region (filters combine; omit all for the full ledger). Not a ' +
+        'jobs board: no listings, no applications, no salary benchmarking — observed aggregate data ' +
+        'only, provenance on every row.',
+    inputSchema: {
+        metric: z
+            .enum(WORKFORCE_METRICS)
+            .optional()
+            .describe('Restrict to one indicator. Omit for every metric currently populated.'),
+        role: z.string().optional().describe('e.g. "PHARMACIST" or "PHARMACY_TECHNICIAN". Omit for every role.'),
+        region: z
+            .string()
+            .optional()
+            .describe('An exact ICS name (vacancy rate) or Health-and-Wellbeing-Board name (pharmacy count / network change). Omit for every region.'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ metric, role, region }) => guard(async () => {
+    const stats = await getWorkforceStats();
+    const rows = filterWorkforceStats(stats, { metric, role, region });
+    return ok({ query: { metric: metric ?? null, role: role ?? null, region: region ?? null }, count: rows.length, stats: rows });
+}));
+const main = async () => {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr only — stdout is the protocol channel.
+    process.stderr.write(`pharmasync MCP server ready — reading ${API_ORIGIN}\n`);
+};
+main().catch((error) => {
+    process.stderr.write(`pharmasync MCP server failed to start: ${error.message}\n`);
+    process.exitCode = 1;
+});

package/dist/query.d.ts

@@ -0,0 +1,71 @@
+import type { ChangeSegmentRef, ChangesIndex, DmdProduct, SupplyEvent, Tier, WorkforceStat } from './api.js';
+/**
+ * Pure query logic for the four MCP tools.
+ *
+ * Every function here takes already-fetched artefact arrays plus the tool arguments and
+ * returns a plain result — no I/O, no fetch, no MCP. That is deliberate: it keeps the
+ * matching, filtering and ranking testable in isolation, and it keeps `index.ts` a thin
+ * fetch-then-format wrapper. Arguments select and filter published data; they never reach
+ * a URL (see `api.ts`).
+ */
+/** Cap on rows returned by name-search tools, so a broad term can't return the whole corpus. */
+export declare const RESULT_CAP = 25;
+export interface ProductSelector {
+    readonly code?: string | undefined;
+    readonly name?: string | undefined;
+}
+/** Whether a selector names anything — `code` or `name` with non-whitespace content. */
+export declare const hasSelector: (selector: ProductSelector) => boolean;
+/** The refusal both product-selecting tools return when neither `code` nor `name` was given. */
+export declare const MISSING_SELECTOR_MESSAGE = "provide either `code` (exact dm+d code) or `name` (substring of the medicine name)";
+/**
+ * Products matching an exact dm+d code, or a case-insensitive substring of the name.
+ *
+ * Code match is exact and unbounded (a code identifies at most one product). Name match is a
+ * substring and capped, because a short term ("sol") would otherwise sweep the corpus. Neither
+ * branch builds a URL — the argument only ever filters the array already in memory.
+ */
+export declare const matchProducts: (products: readonly DmdProduct[], selector: ProductSelector) => DmdProduct[];
+export interface ProductLookup {
+    readonly product: DmdProduct;
+    /** The highest tier in force, or null when no rung applies (§7.2 — a concession is a signal, not a tier). */
+    readonly tier: Tier | null;
+    /** This product's supply events, newest first. */
+    readonly events: readonly SupplyEvent[];
+}
+/** `lookup_product`: a product plus its tier and its events. */
+export declare const lookupProducts: (products: readonly DmdProduct[], tiers: readonly Tier[], events: readonly SupplyEvent[], selector: ProductSelector) => ProductLookup[];
+export interface ShortageRow extends Tier {
+    /** The dm+d product name, when the corpus references it; null otherwise. */
+    readonly name: string | null;
+}
+/** `current_shortages`: the tier ladder, optionally filtered, joined with names, ranked highest first. */
+export declare const currentShortages: (tiers: readonly Tier[], products: readonly DmdProduct[], tierFilter?: Tier["tier"]) => ShortageRow[];
+export interface ConcessionRow extends SupplyEvent {
+    readonly name: string | null;
+}
+/** `concessions_for`: the price-concession events for the matched product(s), newest first. */
+export declare const concessionsFor: (products: readonly DmdProduct[], events: readonly SupplyEvent[], selector: ProductSelector) => ConcessionRow[];
+export interface WorkforceStatSelector {
+    readonly metric?: WorkforceStat['metric'] | undefined;
+    readonly role?: string | undefined;
+    readonly region?: string | undefined;
+}
+/**
+ * `workforce_stats`: the Workforce Panel ledger, optionally filtered by metric, role and/or
+ * region (all three combine with AND when given). Every filter here is an exact match against a
+ * small, closed or near-closed vocabulary (seven metrics; two roles; a stable-ish list of ICS/
+ * Health-and-Wellbeing-Board names) — unlike `matchProducts`' name substring search over an
+ * open-ended medicine corpus, there is no plausible query shape here that could sweep an
+ * unbounded result set, so this applies no `RESULT_CAP`. Newest period first, for a stable order
+ * a machine consumer can rely on.
+ */
+export declare const filterWorkforceStats: (rows: readonly WorkforceStat[], selector?: WorkforceStatSelector) => WorkforceStat[];
+/**
+ * `changes_since`: the segments to fetch for a given cursor.
+ *
+ * The feed is a cursor-in-a-published-list (D-045): fetch every segment whose `cursor` is
+ * ≥ the last cursor stored, ascending. Cursors are lexically ordered by construction
+ * (`2026-08`), so a string compare is the order. With no cursor, every segment is returned.
+ */
+export declare const segmentsToFetch: (index: ChangesIndex, cursor?: string) => ChangeSegmentRef[];

package/dist/query.js

@@ -0,0 +1,105 @@
+/**
+ * Pure query logic for the four MCP tools.
+ *
+ * Every function here takes already-fetched artefact arrays plus the tool arguments and
+ * returns a plain result — no I/O, no fetch, no MCP. That is deliberate: it keeps the
+ * matching, filtering and ranking testable in isolation, and it keeps `index.ts` a thin
+ * fetch-then-format wrapper. Arguments select and filter published data; they never reach
+ * a URL (see `api.ts`).
+ */
+/** Cap on rows returned by name-search tools, so a broad term can't return the whole corpus. */
+export const RESULT_CAP = 25;
+const norm = (value) => value.trim().toLowerCase();
+/** Newest first, by published date then id — a stable order for a machine consumer. */
+const byPublishedDesc = (a, b) => a.source_published_at !== b.source_published_at
+    ? a.source_published_at < b.source_published_at
+        ? 1
+        : -1
+    : a.id < b.id
+        ? 1
+        : a.id > b.id
+            ? -1
+            : 0;
+/** Whether a selector names anything — `code` or `name` with non-whitespace content. */
+export const hasSelector = (selector) => (selector.code ?? '').trim() !== '' || (selector.name ?? '').trim() !== '';
+/** The refusal both product-selecting tools return when neither `code` nor `name` was given. */
+export const MISSING_SELECTOR_MESSAGE = 'provide either `code` (exact dm+d code) or `name` (substring of the medicine name)';
+/**
+ * Products matching an exact dm+d code, or a case-insensitive substring of the name.
+ *
+ * Code match is exact and unbounded (a code identifies at most one product). Name match is a
+ * substring and capped, because a short term ("sol") would otherwise sweep the corpus. Neither
+ * branch builds a URL — the argument only ever filters the array already in memory.
+ */
+export const matchProducts = (products, selector) => {
+    const code = selector.code?.trim();
+    if (code !== undefined && code.length > 0) {
+        return products.filter((p) => p.dmd_code === code);
+    }
+    const name = selector.name?.trim();
+    if (name !== undefined && name.length > 0) {
+        const needle = norm(name);
+        return products.filter((p) => norm(p.name).includes(needle)).slice(0, RESULT_CAP);
+    }
+    return [];
+};
+/** `lookup_product`: a product plus its tier and its events. */
+export const lookupProducts = (products, tiers, events, selector) => {
+    const tierByCode = new Map(tiers.map((t) => [t.dmd_code, t]));
+    const eventsByCode = new Map();
+    for (const event of events) {
+        const bucket = eventsByCode.get(event.dmd_code);
+        if (bucket === undefined)
+            eventsByCode.set(event.dmd_code, [event]);
+        else
+            bucket.push(event);
+    }
+    return matchProducts(products, selector).map((product) => ({
+        product,
+        tier: tierByCode.get(product.dmd_code) ?? null,
+        events: [...(eventsByCode.get(product.dmd_code) ?? [])].sort(byPublishedDesc),
+    }));
+};
+const TIER_RANK = { CRITICAL: 3, CONCERN: 2, WATCH: 1 };
+/** `current_shortages`: the tier ladder, optionally filtered, joined with names, ranked highest first. */
+export const currentShortages = (tiers, products, tierFilter) => {
+    const nameByCode = new Map(products.map((p) => [p.dmd_code, p.name]));
+    return tiers
+        .filter((t) => tierFilter === undefined || t.tier === tierFilter)
+        .map((t) => ({ ...t, name: nameByCode.get(t.dmd_code) ?? null }))
+        .sort((a, b) => TIER_RANK[b.tier] - TIER_RANK[a.tier] || (a.dmd_code < b.dmd_code ? -1 : a.dmd_code > b.dmd_code ? 1 : 0));
+};
+/** `concessions_for`: the price-concession events for the matched product(s), newest first. */
+export const concessionsFor = (products, events, selector) => {
+    const codes = new Set(matchProducts(products, selector).map((p) => p.dmd_code));
+    const nameByCode = new Map(products.map((p) => [p.dmd_code, p.name]));
+    return events
+        .filter((e) => e.kind === 'CONCESSION' && codes.has(e.dmd_code))
+        .map((e) => ({ ...e, name: nameByCode.get(e.dmd_code) ?? null }))
+        .sort(byPublishedDesc);
+};
+/**
+ * `workforce_stats`: the Workforce Panel ledger, optionally filtered by metric, role and/or
+ * region (all three combine with AND when given). Every filter here is an exact match against a
+ * small, closed or near-closed vocabulary (seven metrics; two roles; a stable-ish list of ICS/
+ * Health-and-Wellbeing-Board names) — unlike `matchProducts`' name substring search over an
+ * open-ended medicine corpus, there is no plausible query shape here that could sweep an
+ * unbounded result set, so this applies no `RESULT_CAP`. Newest period first, for a stable order
+ * a machine consumer can rely on.
+ */
+export const filterWorkforceStats = (rows, selector = {}) => rows
+    .filter((r) => selector.metric === undefined || r.metric === selector.metric)
+    .filter((r) => selector.role === undefined || r.role === selector.role)
+    .filter((r) => selector.region === undefined || r.region === selector.region)
+    .sort((a, b) => (a.period < b.period ? 1 : a.period > b.period ? -1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+/**
+ * `changes_since`: the segments to fetch for a given cursor.
+ *
+ * The feed is a cursor-in-a-published-list (D-045): fetch every segment whose `cursor` is
+ * ≥ the last cursor stored, ascending. Cursors are lexically ordered by construction
+ * (`2026-08`), so a string compare is the order. With no cursor, every segment is returned.
+ */
+export const segmentsToFetch = (index, cursor) => {
+    const ordered = [...index.segments].sort((a, b) => a.cursor < b.cursor ? -1 : a.cursor > b.cursor ? 1 : 0);
+    return cursor === undefined ? ordered : ordered.filter((s) => s.cursor >= cursor);
+};

package/dist/schemas.d.ts

@@ -0,0 +1,407 @@
+import { z } from 'zod';
+/**
+ * Runtime schemas for every `/api/v1` artefact this package reads.
+ *
+ * **The source of truth is the pipeline, not this file.** Each entity schema mirrors the JSON
+ * Schema document the pipeline publishes at `/api/v1/schema/<Name>.json` (generated from the same
+ * declaration its ingestion gate enforces — `pipeline/src/artefacts/json-schema.ts`). The CI
+ * contract step (`test/contract-cli.ts`, run in check.yml against freshly built artefacts) fails
+ * if a property name, `required` entry, type or enum here drifts from that published document —
+ * so this file cannot silently fall out of step with the contract it claims to read.
+ *
+ * Two deliberate choices:
+ *   * `z.looseObject`, not `z.strictObject`. The pipeline emits `additionalProperties: false`, but
+ *     the frozen-contract rule (PROJECT_RULES §3) allows *additive* changes within `/v1`. A client
+ *     that rejected an added field would turn a non-breaking change into an outage. Unknown keys
+ *     pass through unchanged, exactly as the tool output did before validation existed.
+ *   * `format` (date, date-time, uri) is not enforced. The pipeline's gate enforces it before
+ *     persistence; re-checking it here would make a formatting nit an MCP outage. Types, enums
+ *     and required-ness — the things a tool's logic actually depends on — are enforced.
+ *
+ * Types are derived from these schemas (`z.infer`), so the TypeScript shape and the runtime
+ * check are one declaration rather than two that can disagree.
+ */
+/** The three rungs of the tier ladder (D-009/D-051), lowest first. Shared by the schema and the tool. */
+export declare const TIERS: readonly ["WATCH", "CONCERN", "CRITICAL"];
+/** The Workforce Panel's indicators (S15). Shared by the schema and the tool. */
+export declare const WORKFORCE_METRICS: readonly ["VACANCY_RATE", "REGISTRANTS", "PHARMACY_COUNT", "NET_CHANGE", "SHORTAGE_STATUS", "CONTEXT_VACANCIES", "DENSITY_PER_10K"];
+/** A dm+d product for a referenced code (D-042). Mirrors `/api/v1/schema/DmdProduct.json`. */
+export declare const DmdProductSchema: z.ZodObject<{
+    dmd_code: z.ZodString;
+    name: z.ZodString;
+    form: z.ZodOptional<z.ZodString>;
+    strength: z.ZodOptional<z.ZodString>;
+    retired: z.ZodBoolean;
+    dmd_release: z.ZodString;
+}, z.core.$loose>;
+/** The highest rung of government action in force for a medicine. Mirrors `Tier.json`. */
+export declare const TierSchema: z.ZodObject<{
+    dmd_code: z.ZodString;
+    tier: z.ZodEnum<{
+        WATCH: "WATCH";
+        CONCERN: "CONCERN";
+        CRITICAL: "CRITICAL";
+    }>;
+    triggering_act: z.ZodString;
+    source_url: z.ZodString;
+    source_date: z.ZodString;
+    in_force_until: z.ZodOptional<z.ZodString>;
+    market_stress: z.ZodBoolean;
+}, z.core.$loose>;
+/** One published supply event. Mirrors `SupplyEvent.json`. */
+export declare const SupplyEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    dmd_code: z.ZodString;
+    kind: z.ZodEnum<{
+        MSN: "MSN";
+        SSP: "SSP";
+        CONCESSION: "CONCESSION";
+    }>;
+    status: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    reason_code: z.ZodOptional<z.ZodEnum<{
+        manufacturing: "manufacturing";
+        api_supply: "api_supply";
+        discontinuation: "discontinuation";
+        shipping: "shipping";
+        demand: "demand";
+        unstated: "unstated";
+    }>>;
+    nations: z.ZodArray<z.ZodEnum<{
+        ENG: "ENG";
+        SCO: "SCO";
+        WAL: "WAL";
+        NIR: "NIR";
+    }>>;
+    effective_from: z.ZodString;
+    effective_from_basis: z.ZodEnum<{
+        published: "published";
+        first_observed: "first_observed";
+    }>;
+    effective_to: z.ZodOptional<z.ZodString>;
+    source_url: z.ZodString;
+    source_published_at: z.ZodString;
+    source_published_at_basis: z.ZodEnum<{
+        published: "published";
+        first_observed: "first_observed";
+        http_last_modified: "http_last_modified";
+    }>;
+    first_seen_at: z.ZodString;
+}, z.core.$loose>;
+/** A detected change in the delta feed. Mirrors `ChangeRecord.json`. */
+export declare const ChangeRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        SUPPLY: "SUPPLY";
+        WORKFORCE: "WORKFORCE";
+    }>;
+    dmd_code: z.ZodOptional<z.ZodString>;
+    change_type: z.ZodEnum<{
+        NEW: "NEW";
+        UPDATED: "UPDATED";
+        RESOLVED: "RESOLVED";
+        EXPIRED: "EXPIRED";
+    }>;
+    event_id: z.ZodOptional<z.ZodString>;
+    detected_at: z.ZodString;
+    headline: z.ZodString;
+}, z.core.$loose>;
+/** One row of the Workforce Panel's ledger (S15). Mirrors `WorkforceStat.json`. */
+export declare const WorkforceStatSchema: z.ZodObject<{
+    id: z.ZodString;
+    metric: z.ZodEnum<{
+        VACANCY_RATE: "VACANCY_RATE";
+        REGISTRANTS: "REGISTRANTS";
+        PHARMACY_COUNT: "PHARMACY_COUNT";
+        NET_CHANGE: "NET_CHANGE";
+        SHORTAGE_STATUS: "SHORTAGE_STATUS";
+        CONTEXT_VACANCIES: "CONTEXT_VACANCIES";
+        DENSITY_PER_10K: "DENSITY_PER_10K";
+    }>;
+    role: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    period: z.ZodString;
+    value: z.ZodNumber;
+    unit: z.ZodString;
+    nhwa_code: z.ZodOptional<z.ZodString>;
+    source_url: z.ZodString;
+    source_published_at: z.ZodString;
+    source_published_at_basis: z.ZodEnum<{
+        published: "published";
+        first_observed: "first_observed";
+    }>;
+    first_seen_at: z.ZodString;
+}, z.core.$loose>;
+/**
+ * One entry of the change feed's index. The pipeline publishes no JSON Schema document for the
+ * index (it is described in `openapi.json`), so this mirrors `FeedSegment` in
+ * `pipeline/src/artefacts/changes.ts` instead.
+ */
+export declare const ChangeSegmentRefSchema: z.ZodObject<{
+    cursor: z.ZodString;
+    path: z.ZodString;
+    count: z.ZodNumber;
+    closed: z.ZodBoolean;
+    from: z.ZodString;
+    to: z.ZodString;
+}, z.core.$loose>;
+/** `/api/v1/changes/index.json`. Mirrors `ChangeFeedIndex` in `pipeline/src/artefacts/changes.ts`. */
+export declare const ChangesIndexSchema: z.ZodObject<{
+    api_version: z.ZodString;
+    generated_at: z.ZodString;
+    latest_cursor: z.ZodNullable<z.ZodString>;
+    total_changes: z.ZodNumber;
+    segments: z.ZodArray<z.ZodObject<{
+        cursor: z.ZodString;
+        path: z.ZodString;
+        count: z.ZodNumber;
+        closed: z.ZodBoolean;
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$loose>>;
+    cursor_protocol: z.ZodArray<z.ZodString>;
+    limitations: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+export type Tier = z.infer<typeof TierSchema>;
+export type TierLevel = (typeof TIERS)[number];
+export type DmdProduct = z.infer<typeof DmdProductSchema>;
+export type SupplyEvent = z.infer<typeof SupplyEventSchema>;
+export type ChangeRecord = z.infer<typeof ChangeRecordSchema>;
+export type WorkforceStat = z.infer<typeof WorkforceStatSchema>;
+export type WorkforceMetric = (typeof WORKFORCE_METRICS)[number];
+export type ChangeSegmentRef = z.infer<typeof ChangeSegmentRefSchema>;
+export type ChangesIndex = z.infer<typeof ChangesIndexSchema>;
+/**
+ * The entity schemas that have a published JSON Schema counterpart, keyed by its title — the
+ * registry the contract check walks. Adding a schema here without a published document (or the
+ * reverse, for a document this package reads) fails that check.
+ */
+export declare const PUBLISHED_ENTITY_SCHEMAS: {
+    readonly DmdProduct: z.ZodObject<{
+        dmd_code: z.ZodString;
+        name: z.ZodString;
+        form: z.ZodOptional<z.ZodString>;
+        strength: z.ZodOptional<z.ZodString>;
+        retired: z.ZodBoolean;
+        dmd_release: z.ZodString;
+    }, z.core.$loose>;
+    readonly Tier: z.ZodObject<{
+        dmd_code: z.ZodString;
+        tier: z.ZodEnum<{
+            WATCH: "WATCH";
+            CONCERN: "CONCERN";
+            CRITICAL: "CRITICAL";
+        }>;
+        triggering_act: z.ZodString;
+        source_url: z.ZodString;
+        source_date: z.ZodString;
+        in_force_until: z.ZodOptional<z.ZodString>;
+        market_stress: z.ZodBoolean;
+    }, z.core.$loose>;
+    readonly SupplyEvent: z.ZodObject<{
+        id: z.ZodString;
+        dmd_code: z.ZodString;
+        kind: z.ZodEnum<{
+            MSN: "MSN";
+            SSP: "SSP";
+            CONCESSION: "CONCESSION";
+        }>;
+        status: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+        reason_code: z.ZodOptional<z.ZodEnum<{
+            manufacturing: "manufacturing";
+            api_supply: "api_supply";
+            discontinuation: "discontinuation";
+            shipping: "shipping";
+            demand: "demand";
+            unstated: "unstated";
+        }>>;
+        nations: z.ZodArray<z.ZodEnum<{
+            ENG: "ENG";
+            SCO: "SCO";
+            WAL: "WAL";
+            NIR: "NIR";
+        }>>;
+        effective_from: z.ZodString;
+        effective_from_basis: z.ZodEnum<{
+            published: "published";
+            first_observed: "first_observed";
+        }>;
+        effective_to: z.ZodOptional<z.ZodString>;
+        source_url: z.ZodString;
+        source_published_at: z.ZodString;
+        source_published_at_basis: z.ZodEnum<{
+            published: "published";
+            first_observed: "first_observed";
+            http_last_modified: "http_last_modified";
+        }>;
+        first_seen_at: z.ZodString;
+    }, z.core.$loose>;
+    readonly ChangeRecord: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            SUPPLY: "SUPPLY";
+            WORKFORCE: "WORKFORCE";
+        }>;
+        dmd_code: z.ZodOptional<z.ZodString>;
+        change_type: z.ZodEnum<{
+            NEW: "NEW";
+            UPDATED: "UPDATED";
+            RESOLVED: "RESOLVED";
+            EXPIRED: "EXPIRED";
+        }>;
+        event_id: z.ZodOptional<z.ZodString>;
+        detected_at: z.ZodString;
+        headline: z.ZodString;
+    }, z.core.$loose>;
+    readonly WorkforceStat: z.ZodObject<{
+        id: z.ZodString;
+        metric: z.ZodEnum<{
+            VACANCY_RATE: "VACANCY_RATE";
+            REGISTRANTS: "REGISTRANTS";
+            PHARMACY_COUNT: "PHARMACY_COUNT";
+            NET_CHANGE: "NET_CHANGE";
+            SHORTAGE_STATUS: "SHORTAGE_STATUS";
+            CONTEXT_VACANCIES: "CONTEXT_VACANCIES";
+            DENSITY_PER_10K: "DENSITY_PER_10K";
+        }>;
+        role: z.ZodOptional<z.ZodString>;
+        region: z.ZodOptional<z.ZodString>;
+        period: z.ZodString;
+        value: z.ZodNumber;
+        unit: z.ZodString;
+        nhwa_code: z.ZodOptional<z.ZodString>;
+        source_url: z.ZodString;
+        source_published_at: z.ZodString;
+        source_published_at_basis: z.ZodEnum<{
+            published: "published";
+            first_observed: "first_observed";
+        }>;
+        first_seen_at: z.ZodString;
+    }, z.core.$loose>;
+};
+/**
+ * Every data artefact this package fetches, by path under `/api/v1`, with the schema its body
+ * must satisfy. Change segments (`changes/<cursor>.json`) are validated as `ChangeRecord[]`.
+ */
+export declare const ARTEFACT_SCHEMAS: {
+    readonly 'products.json': z.ZodArray<z.ZodObject<{
+        dmd_code: z.ZodString;
+        name: z.ZodString;
+        form: z.ZodOptional<z.ZodString>;
+        strength: z.ZodOptional<z.ZodString>;
+        retired: z.ZodBoolean;
+        dmd_release: z.ZodString;
+    }, z.core.$loose>>;
+    readonly 'tiers.json': z.ZodArray<z.ZodObject<{
+        dmd_code: z.ZodString;
+        tier: z.ZodEnum<{
+            WATCH: "WATCH";
+            CONCERN: "CONCERN";
+            CRITICAL: "CRITICAL";
+        }>;
+        triggering_act: z.ZodString;
+        source_url: z.ZodString;
+        source_date: z.ZodString;
+        in_force_until: z.ZodOptional<z.ZodString>;
+        market_stress: z.ZodBoolean;
+    }, z.core.$loose>>;
+    readonly 'events.json': z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        dmd_code: z.ZodString;
+        kind: z.ZodEnum<{
+            MSN: "MSN";
+            SSP: "SSP";
+            CONCESSION: "CONCESSION";
+        }>;
+        status: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+        reason_code: z.ZodOptional<z.ZodEnum<{
+            manufacturing: "manufacturing";
+            api_supply: "api_supply";
+            discontinuation: "discontinuation";
+            shipping: "shipping";
+            demand: "demand";
+            unstated: "unstated";
+        }>>;
+        nations: z.ZodArray<z.ZodEnum<{
+            ENG: "ENG";
+            SCO: "SCO";
+            WAL: "WAL";
+            NIR: "NIR";
+        }>>;
+        effective_from: z.ZodString;
+        effective_from_basis: z.ZodEnum<{
+            published: "published";
+            first_observed: "first_observed";
+        }>;
+        effective_to: z.ZodOptional<z.ZodString>;
+        source_url: z.ZodString;
+        source_published_at: z.ZodString;
+        source_published_at_basis: z.ZodEnum<{
+            published: "published";
+            first_observed: "first_observed";
+            http_last_modified: "http_last_modified";
+        }>;
+        first_seen_at: z.ZodString;
+    }, z.core.$loose>>;
+    readonly 'changes/index.json': z.ZodObject<{
+        api_version: z.ZodString;
+        generated_at: z.ZodString;
+        latest_cursor: z.ZodNullable<z.ZodString>;
+        total_changes: z.ZodNumber;
+        segments: z.ZodArray<z.ZodObject<{
+            cursor: z.ZodString;
+            path: z.ZodString;
+            count: z.ZodNumber;
+            closed: z.ZodBoolean;
+            from: z.ZodString;
+            to: z.ZodString;
+        }, z.core.$loose>>;
+        cursor_protocol: z.ZodArray<z.ZodString>;
+        limitations: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+    readonly 'workforce/stats.json': z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        metric: z.ZodEnum<{
+            VACANCY_RATE: "VACANCY_RATE";
+            REGISTRANTS: "REGISTRANTS";
+            PHARMACY_COUNT: "PHARMACY_COUNT";
+            NET_CHANGE: "NET_CHANGE";
+            SHORTAGE_STATUS: "SHORTAGE_STATUS";
+            CONTEXT_VACANCIES: "CONTEXT_VACANCIES";
+            DENSITY_PER_10K: "DENSITY_PER_10K";
+        }>;
+        role: z.ZodOptional<z.ZodString>;
+        region: z.ZodOptional<z.ZodString>;
+        period: z.ZodString;
+        value: z.ZodNumber;
+        unit: z.ZodString;
+        nhwa_code: z.ZodOptional<z.ZodString>;
+        source_url: z.ZodString;
+        source_published_at: z.ZodString;
+        source_published_at_basis: z.ZodEnum<{
+            published: "published";
+            first_observed: "first_observed";
+        }>;
+        first_seen_at: z.ZodString;
+    }, z.core.$loose>>;
+};
+export declare const ChangeSegmentSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        SUPPLY: "SUPPLY";
+        WORKFORCE: "WORKFORCE";
+    }>;
+    dmd_code: z.ZodOptional<z.ZodString>;
+    change_type: z.ZodEnum<{
+        NEW: "NEW";
+        UPDATED: "UPDATED";
+        RESOLVED: "RESOLVED";
+        EXPIRED: "EXPIRED";
+    }>;
+    event_id: z.ZodOptional<z.ZodString>;
+    detected_at: z.ZodString;
+    headline: z.ZodString;
+}, z.core.$loose>>;
+export type ArtefactPath = keyof typeof ARTEFACT_SCHEMAS;

package/dist/schemas.js

@@ -0,0 +1,145 @@
+import { z } from 'zod';
+/**
+ * Runtime schemas for every `/api/v1` artefact this package reads.
+ *
+ * **The source of truth is the pipeline, not this file.** Each entity schema mirrors the JSON
+ * Schema document the pipeline publishes at `/api/v1/schema/<Name>.json` (generated from the same
+ * declaration its ingestion gate enforces — `pipeline/src/artefacts/json-schema.ts`). The CI
+ * contract step (`test/contract-cli.ts`, run in check.yml against freshly built artefacts) fails
+ * if a property name, `required` entry, type or enum here drifts from that published document —
+ * so this file cannot silently fall out of step with the contract it claims to read.
+ *
+ * Two deliberate choices:
+ *   * `z.looseObject`, not `z.strictObject`. The pipeline emits `additionalProperties: false`, but
+ *     the frozen-contract rule (PROJECT_RULES §3) allows *additive* changes within `/v1`. A client
+ *     that rejected an added field would turn a non-breaking change into an outage. Unknown keys
+ *     pass through unchanged, exactly as the tool output did before validation existed.
+ *   * `format` (date, date-time, uri) is not enforced. The pipeline's gate enforces it before
+ *     persistence; re-checking it here would make a formatting nit an MCP outage. Types, enums
+ *     and required-ness — the things a tool's logic actually depends on — are enforced.
+ *
+ * Types are derived from these schemas (`z.infer`), so the TypeScript shape and the runtime
+ * check are one declaration rather than two that can disagree.
+ */
+/** The three rungs of the tier ladder (D-009/D-051), lowest first. Shared by the schema and the tool. */
+export const TIERS = ['WATCH', 'CONCERN', 'CRITICAL'];
+/** The Workforce Panel's indicators (S15). Shared by the schema and the tool. */
+export const WORKFORCE_METRICS = [
+    'VACANCY_RATE',
+    'REGISTRANTS',
+    'PHARMACY_COUNT',
+    'NET_CHANGE',
+    'SHORTAGE_STATUS',
+    'CONTEXT_VACANCIES',
+    'DENSITY_PER_10K',
+];
+/** A dm+d product for a referenced code (D-042). Mirrors `/api/v1/schema/DmdProduct.json`. */
+export const DmdProductSchema = z.looseObject({
+    dmd_code: z.string(),
+    name: z.string(),
+    form: z.string().optional(),
+    strength: z.string().optional(),
+    retired: z.boolean(),
+    dmd_release: z.string(),
+});
+/** The highest rung of government action in force for a medicine. Mirrors `Tier.json`. */
+export const TierSchema = z.looseObject({
+    dmd_code: z.string(),
+    tier: z.enum(TIERS),
+    triggering_act: z.string(),
+    source_url: z.string(),
+    source_date: z.string(),
+    in_force_until: z.string().optional(),
+    market_stress: z.boolean(),
+});
+/** One published supply event. Mirrors `SupplyEvent.json`. */
+export const SupplyEventSchema = z.looseObject({
+    id: z.string(),
+    dmd_code: z.string(),
+    kind: z.enum(['MSN', 'SSP', 'CONCESSION']),
+    status: z.string(),
+    detail: z.string().optional(),
+    reason_code: z
+        .enum(['manufacturing', 'api_supply', 'discontinuation', 'shipping', 'demand', 'unstated'])
+        .optional(),
+    nations: z.array(z.enum(['ENG', 'SCO', 'WAL', 'NIR'])),
+    effective_from: z.string(),
+    effective_from_basis: z.enum(['published', 'first_observed']),
+    effective_to: z.string().optional(),
+    source_url: z.string(),
+    source_published_at: z.string(),
+    source_published_at_basis: z.enum(['published', 'http_last_modified', 'first_observed']),
+    first_seen_at: z.string(),
+});
+/** A detected change in the delta feed. Mirrors `ChangeRecord.json`. */
+export const ChangeRecordSchema = z.looseObject({
+    id: z.string(),
+    kind: z.enum(['SUPPLY', 'WORKFORCE']),
+    dmd_code: z.string().optional(),
+    change_type: z.enum(['NEW', 'UPDATED', 'RESOLVED', 'EXPIRED']),
+    event_id: z.string().optional(),
+    detected_at: z.string(),
+    headline: z.string(),
+});
+/** One row of the Workforce Panel's ledger (S15). Mirrors `WorkforceStat.json`. */
+export const WorkforceStatSchema = z.looseObject({
+    id: z.string(),
+    metric: z.enum(WORKFORCE_METRICS),
+    role: z.string().optional(),
+    region: z.string().optional(),
+    period: z.string(),
+    value: z.number(),
+    unit: z.string(),
+    nhwa_code: z.string().optional(),
+    source_url: z.string(),
+    source_published_at: z.string(),
+    source_published_at_basis: z.enum(['published', 'first_observed']),
+    first_seen_at: z.string(),
+});
+/**
+ * One entry of the change feed's index. The pipeline publishes no JSON Schema document for the
+ * index (it is described in `openapi.json`), so this mirrors `FeedSegment` in
+ * `pipeline/src/artefacts/changes.ts` instead.
+ */
+export const ChangeSegmentRefSchema = z.looseObject({
+    cursor: z.string(),
+    path: z.string(),
+    count: z.number(),
+    closed: z.boolean(),
+    from: z.string(),
+    to: z.string(),
+});
+/** `/api/v1/changes/index.json`. Mirrors `ChangeFeedIndex` in `pipeline/src/artefacts/changes.ts`. */
+export const ChangesIndexSchema = z.looseObject({
+    api_version: z.string(),
+    generated_at: z.string(),
+    latest_cursor: z.string().nullable(),
+    total_changes: z.number(),
+    segments: z.array(ChangeSegmentRefSchema),
+    cursor_protocol: z.array(z.string()),
+    limitations: z.array(z.string()),
+});
+/**
+ * The entity schemas that have a published JSON Schema counterpart, keyed by its title — the
+ * registry the contract check walks. Adding a schema here without a published document (or the
+ * reverse, for a document this package reads) fails that check.
+ */
+export const PUBLISHED_ENTITY_SCHEMAS = {
+    DmdProduct: DmdProductSchema,
+    Tier: TierSchema,
+    SupplyEvent: SupplyEventSchema,
+    ChangeRecord: ChangeRecordSchema,
+    WorkforceStat: WorkforceStatSchema,
+};
+/**
+ * Every data artefact this package fetches, by path under `/api/v1`, with the schema its body
+ * must satisfy. Change segments (`changes/<cursor>.json`) are validated as `ChangeRecord[]`.
+ */
+export const ARTEFACT_SCHEMAS = {
+    'products.json': z.array(DmdProductSchema),
+    'tiers.json': z.array(TierSchema),
+    'events.json': z.array(SupplyEventSchema),
+    'changes/index.json': ChangesIndexSchema,
+    'workforce/stats.json': z.array(WorkforceStatSchema),
+};
+export const ChangeSegmentSchema = z.array(ChangeRecordSchema);

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The package version, read once from `package.json`.
+ *
+ * Previously restated by hand in two places (the MCP server's `version` and the fetch
+ * user-agent), and the two had already disagreed (`0.2.0` vs `0.0.0`). `package.json` sits one
+ * directory above both `src/` (run via tsx) and `dist/` (the published build), and npm always
+ * ships it, so the same relative URL resolves in development and in the installed package.
+ */
+export declare const PACKAGE_VERSION: string;

package/dist/version.js

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+/**
+ * The package version, read once from `package.json`.
+ *
+ * Previously restated by hand in two places (the MCP server's `version` and the fetch
+ * user-agent), and the two had already disagreed (`0.2.0` vs `0.0.0`). `package.json` sits one
+ * directory above both `src/` (run via tsx) and `dist/` (the published build), and npm always
+ * ships it, so the same relative URL resolves in development and in the installed package.
+ */
+export const PACKAGE_VERSION = z
+    .object({ version: z.string().min(1) })
+    .parse(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))).version;

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@pharmasync/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "mcpName": "io.github.ayeongo/pharmasync",
+  "description": "MCP server for the Pharmasync public API (S8). A read-only client of the static /api/v1 artefacts — no keys, no store, no server infrastructure.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pharmasync",
+    "medicine-supply",
+    "dmd",
+    "nhs",
+    "pharmacy",
+    "drug-shortage"
+  ],
+  "license": "MIT",
+  "author": "AyeOnGo (https://github.com/ayeongo)",
+  "homepage": "https://github.com/ayeongo/Pharmasync/tree/main/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ayeongo/Pharmasync.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/ayeongo/Pharmasync/issues"
+  },
+  "type": "module",
+  "bin": {
+    "pharmasync-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24 <26",
+    "npm": ">=11.16.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "check": "npm run lint && npm run typecheck && npm run test",
+    "contract": "tsx test/contract-cli.ts",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "eslint": "^10.11.0",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.71.0",
+    "vitest": "^5.0.2"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "zod": "^4.6.5"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true,
+    "fsevents@2.3.3": true
+  }
+}