@cyanheads/nist-nvd-mcp-server 0.1.14 → 0.1.16

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Developer Protocol
 
 **Server:** nist-nvd-mcp-server
-**Version:** 0.1.14
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.14`
+**Version:** 0.1.16
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.0`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
 **Zod:** ^4.4.3
@@ -35,7 +35,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **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.
-- **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
+- **Check `ctx.elicit`** for presence before calling.
 - **Secrets in env vars only** — never hardcoded.
 - **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.
 
@@ -67,12 +67,15 @@ export const nvdSearchCpes = tool('nvd_search_cpes', {
       title: z.string().optional().describe('Human-readable title.'),
       deprecated: z.boolean().describe('Whether this CPE is deprecated.'),
     })).describe('Matching CPE dictionary entries.'),
-    queryMeta: z.object({
-      totalResults: z.number().describe('Total matches before limit.'),
-      returned: z.number().describe('Entries returned.'),
-    }).describe('Pagination metadata.'),
   }),
 
+  // Pagination totals are agent-facing context, not domain payload — declare them as
+  // `enrichment` and populate via ctx.enrich so they reach structuredContent AND content[].
+  enrichment: {
+    totalCount: z.number().describe('Total matches before the limit was applied.'),
+    returned: z.number().describe('Entries returned.'),
+  },
+
   errors: [
     {
       reason: 'missing_search_input',
@@ -91,7 +94,9 @@ export const nvdSearchCpes = tool('nvd_search_cpes', {
     ctx.log.info('Searching CPE dictionary', { keyword: input.keyword, limit: input.limit });
     const service = getNvdCpeService();
     const result = await service.searchCpes({ keyword: input.keyword, cpeMatchString: input.cpeMatchString, limit: input.limit }, ctx);
-    return { cpes: result.cpes, queryMeta: { totalResults: result.totalResults, returned: result.returned } };
+    ctx.enrich({ returned: result.returned });
+    ctx.enrich.total(result.totalResults);
+    return { cpes: result.cpes };
   },
 
   format: (result) => [{ type: 'text', text: result.cpes.map(c => `**${c.title ?? c.cpeName}**: \`${c.cpeName}\``).join('\n') }],
@@ -162,10 +167,14 @@ 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. |
-| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
+| `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
+| `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
 | `ctx.signal` | `AbortSignal` for cancellation. Forwarded to NVD HTTP requests. |
+| `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
 | `ctx.requestId` | Unique request ID. |
-| `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
+| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
 
 ---
 
@@ -279,6 +288,7 @@ Available skills:
 | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
 | `release-and-publish` | 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 |
@@ -288,13 +298,12 @@ Available skills:
 | `api-context` | Context interface, logger, state, progress |
 | `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-mirror` | MirrorService: persistent local SQLite mirror of a bulk upstream dataset — defineMirror, sqliteMirrorStore, FTS5 |
 | `api-workers` | Cloudflare Workers runtime |
-| `orchestrations` | Chain task skills into a gated multi-phase pipeline (build-out, QA-fix, update-ship) when sub-agents are available |
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
 
@@ -310,16 +319,20 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run rebuild` | Clean + build |
 | `bun run clean` | Remove build artifacts |
 | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
-| `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
+| `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
+| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
+| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
+| `bun run list-skills` | Print the skill registry |
 | `bun run tree` | Generate directory structure doc |
-| `bun run format` | Auto-fix formatting |
-| `bun run test` | Run tests |
+| `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 test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
 | `bun run start:stdio` | Production mode (stdio) |
 | `bun run start:http` | Production mode (HTTP) |
 | `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 release:github` | Create GitHub Release — constructs title from tag, conditionally attaches `.mcpb` bundle |
-| `bun run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
+| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
 ---
 

package/CLAUDE.md

@@ -1,8 +1,8 @@
 # Developer Protocol
 
 **Server:** nist-nvd-mcp-server
-**Version:** 0.1.14
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.14`
+**Version:** 0.1.16
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.0`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
 **Zod:** ^4.4.3
@@ -35,7 +35,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **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.
-- **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
+- **Check `ctx.elicit`** for presence before calling.
 - **Secrets in env vars only** — never hardcoded.
 - **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.
 
@@ -67,12 +67,15 @@ export const nvdSearchCpes = tool('nvd_search_cpes', {
       title: z.string().optional().describe('Human-readable title.'),
       deprecated: z.boolean().describe('Whether this CPE is deprecated.'),
     })).describe('Matching CPE dictionary entries.'),
-    queryMeta: z.object({
-      totalResults: z.number().describe('Total matches before limit.'),
-      returned: z.number().describe('Entries returned.'),
-    }).describe('Pagination metadata.'),
   }),
 
+  // Pagination totals are agent-facing context, not domain payload — declare them as
+  // `enrichment` and populate via ctx.enrich so they reach structuredContent AND content[].
+  enrichment: {
+    totalCount: z.number().describe('Total matches before the limit was applied.'),
+    returned: z.number().describe('Entries returned.'),
+  },
+
   errors: [
     {
       reason: 'missing_search_input',
@@ -91,7 +94,9 @@ export const nvdSearchCpes = tool('nvd_search_cpes', {
     ctx.log.info('Searching CPE dictionary', { keyword: input.keyword, limit: input.limit });
     const service = getNvdCpeService();
     const result = await service.searchCpes({ keyword: input.keyword, cpeMatchString: input.cpeMatchString, limit: input.limit }, ctx);
-    return { cpes: result.cpes, queryMeta: { totalResults: result.totalResults, returned: result.returned } };
+    ctx.enrich({ returned: result.returned });
+    ctx.enrich.total(result.totalResults);
+    return { cpes: result.cpes };
   },
 
   format: (result) => [{ type: 'text', text: result.cpes.map(c => `**${c.title ?? c.cpeName}**: \`${c.cpeName}\``).join('\n') }],
@@ -162,10 +167,14 @@ 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. |
-| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
+| `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
+| `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
 | `ctx.signal` | `AbortSignal` for cancellation. Forwarded to NVD HTTP requests. |
+| `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
 | `ctx.requestId` | Unique request ID. |
-| `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
+| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
 
 ---
 
@@ -279,6 +288,7 @@ Available skills:
 | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
 | `release-and-publish` | 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 |
@@ -288,13 +298,12 @@ Available skills:
 | `api-context` | Context interface, logger, state, progress |
 | `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-mirror` | MirrorService: persistent local SQLite mirror of a bulk upstream dataset — defineMirror, sqliteMirrorStore, FTS5 |
 | `api-workers` | Cloudflare Workers runtime |
-| `orchestrations` | Chain task skills into a gated multi-phase pipeline (build-out, QA-fix, update-ship) when sub-agents are available |
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
 
@@ -310,16 +319,20 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run rebuild` | Clean + build |
 | `bun run clean` | Remove build artifacts |
 | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
-| `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
+| `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
+| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
+| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
+| `bun run list-skills` | Print the skill registry |
 | `bun run tree` | Generate directory structure doc |
-| `bun run format` | Auto-fix formatting |
-| `bun run test` | Run tests |
+| `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 test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
 | `bun run start:stdio` | Production mode (stdio) |
 | `bun run start:http` | Production mode (HTTP) |
 | `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 release:github` | Create GitHub Release — constructs title from tag, conditionally attaches `.mcpb` bundle |
-| `bun run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
+| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
 ---
 

package/Dockerfile

@@ -60,7 +60,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add @hono/otel \
+      bun add --omit=dev --ignore-scripts @hono/otel \
         @opentelemetry/instrumentation-http \
         @opentelemetry/exporter-metrics-otlp-http \
         @opentelemetry/exporter-trace-otlp-http \

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.14-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/nist-nvd-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/nist-nvd-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/nist-nvd-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.1.16-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/nist-nvd-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/nist-nvd-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/nist-nvd-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -49,8 +49,9 @@ The primary discovery tool for vulnerability surveillance and triage workflows.
 - CISA KEV filter — limit results to known-exploited vulnerabilities
 - Convenience date shorthands: `pubDays` and `lastModDays` for "last N days" queries
 - Explicit ISO 8601 date range parameters (`pubStartDate`/`pubEndDate`, etc.) with 120-day max span
-- Auto-clamps convenience date params that exceed 120 days and reports clamped values in `queryMeta`
+- Auto-clamps convenience date params that exceed 120 days and reports clamped values in the response enrichment
 - Pagination via `limit` (up to 2000) and `offset`
+- Every row carries a truncated description alongside the ID, so results are distinguishable without a follow-up fetch
 - Results are always brief; call `nvd_get_cve` for full detail
 
 ---
@@ -61,9 +62,10 @@ Fetch one or more CVEs by ID with full detail or brief summaries.
 
 - Batch up to 100 CVE IDs per call
 - Full mode: all CVSS scores across v2.0, v3.0, v3.1, and v4.0; CWE weaknesses; CPE configurations; CISA KEV fields; references
-- Brief mode (`brief: true`): ID, status, top severity, KEV name — recommended for batches larger than 10
+- Brief mode (`brief: true`): ID, status, top severity, KEV name, truncated description — recommended for batches larger than 10
 - `includeReferences: false` to strip the references array and reduce response size
-- Per-ID parity check: `queryMeta.missingIds` lists any requested IDs NVD didn't return
+- Per-ID parity check: the `missingIds` enrichment field lists any requested IDs NVD didn't return
+- Rendered text carries the affected-product criteria and references the record holds, capped with a `… N more` trailer; `allLanguages: true` renders every localized description, not just English
 
 ---
 
@@ -73,7 +75,7 @@ Look up product identifiers before auditing.
 
 - Keyword search (e.g., `"apache http server"`, `"openssl"`) or partial CPEv2.3 pattern
 - Returns full CPE name, human-readable title, deprecation status, and superseding CPEs
-- Pagination up to 10,000 entries — narrow the keyword when `totalResults > returned`
+- Pagination via `limit` (up to 10,000 per page) and `offset` — a vendor-level keyword can match tens of thousands of entries, so page with `offset` rather than trying to narrow further
 - Use this before `nvd_audit_cpe` — CPE names are arcane strings; guessing audits the wrong product
 
 ---
@@ -86,7 +88,8 @@ Full CVE audit for a specific product version.
 - Version range via `versionStart`/`versionEnd` with inclusive/exclusive type control
 - Client-side severity filter (`severityMin`) to strip low-signal entries
 - Returns full CVE records (ID, CVSS scores, CWE, CPE configurations, KEV fields, references)
-- Echoes the CPE identifier used in `queryMeta` so callers can verify the correct product was queried
+- Pagination via `limit` (up to 2000) and `offset` — page at a modest `limit` instead of raising it, since each result is a full record
+- Echoes the CPE identifier used in the response enrichment so callers can verify the correct product was queried
 
 ---
 
@@ -94,8 +97,9 @@ Full CVE audit for a specific product version.
 
 Track a CVE's lifecycle over time.
 
-- Returns change events in reverse-chronological order: CVSS revisions, status transitions, reference additions, CPE configuration updates
-- Paginated via `limit` and `offset`
+- Returns change events: CVSS revisions, status transitions, reference additions, CPE configuration updates
+- `order` picks which end to read from — `newest` (default) returns the most recent events first, `oldest` returns NVD's native oldest-first order
+- Paginated via `limit` and `offset`, where `offset` counts from the end `order` anchors to
 - Note: the NVD history endpoint is significantly slower without an API key — set `NVD_API_KEY` and raise `NVD_REQUEST_TIMEOUT_MS` for reliable operation
 
 ## Resource
@@ -127,9 +131,10 @@ NVD-specific:
 
 Agent-friendly output:
 
-- `queryMeta` on every response — total results, returned count, page offset, and any date-clamping events so agents can reason about what was actually queried
+- An `enrichment` block on every response, carried on both `structuredContent` and the rendered text — total results, returned count, page offset, the filters actually applied, and any date-clamping events, so agents can reason about what was really queried
 - `missingIds` in batch CVE lookups — per-ID parity check instead of a silent partial result
 - CPE echo in audit responses — `cpeName` or `virtualMatchString` reflected back so callers can verify the correct product was audited
+- Empty-result notices that name the cause — an unmatched query, a severity threshold that emptied the page, and an offset past the end of the result set are told apart rather than all reading as "nothing found"
 
 ## Getting started
 

package/changelog/0.1.x/0.1.15.md

@@ -0,0 +1,24 @@
+---
+summary: "nvd_get_cve_history gains an order input (newest/oldest) and no longer loses pages carrying Affected/SSVC change values; invalid_cve_id_format and cve_not_found now carry their declared recovery hints; nvd_search_cves' severity filter is documented as exact-band, not a floor."
+breaking: false
+security: false
+---
+
+# 0.1.15 — 2026-07-27
+
+## Added
+
+- **`order` input on `nvd_get_cve_history`** (`oldest` | `newest`, default `newest`) — pages change history from either end. `oldest` maps `offset` straight to NVD's native `startIndex` in one request; `newest` reverses it, adding a second tail-anchored request only when the history is longer than `limit`. The effective order is echoed in the `enrichment` block. ([#29](https://github.com/cyanheads/nist-nvd-mcp-server/issues/29))
+
+## Fixed
+
+- **`nvd_get_cve_history` failed output validation on pages carrying `Affected` or `SSVC` changes** — NVD emits an array for `Affected` details and an object for `SSVC` details, which the `oldValue`/`newValue` string schema rejected, losing the entire page. Non-string values now serialize to JSON strings during normalization. ([#27](https://github.com/cyanheads/nist-nvd-mcp-server/issues/27))
+- **`nvd_get_cve_history`'s `changes` output was documented as reverse-chronological but returned NVD's native oldest-first order** — the description now states the real ordering, resolved by the new `order` input above. ([#29](https://github.com/cyanheads/nist-nvd-mcp-server/issues/29))
+- **`invalid_cve_id_format` and `cve_not_found` shipped no recovery hint** — both were thrown from `NvdCveService` via bare `validationError()`/`notFound()` rather than `ctx.fail()`, so the recovery text declared on `nvd_get_cve`, `nvd_get_cve_history`, and the `nvd://cve/{cveId}` resource never reached the caller. Throw sites now resolve `ctx.recoveryFor(reason)` so each carries the calling definition's own hint. ([#33](https://github.com/cyanheads/nist-nvd-mcp-server/issues/33))
+- **`nvd_search_cves`' `severity` input described itself as "or above"** — NVD's severity parameters are exact-match, not a floor, so a `severity: "HIGH"` query silently dropped every `CRITICAL` result. The `severity` input and `filtersApplied.severity` enrichment now state the filter selects exactly one band and that covering several bands takes one call per band. ([#28](https://github.com/cyanheads/nist-nvd-mcp-server/issues/28))
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.10.14 → ^0.11.0
+- `@biomejs/biome` ^2.5.3 → ^2.5.5
+- `tsc-alias` ^1.9.0 → ^1.9.1

package/changelog/0.1.x/0.1.16.md

@@ -0,0 +1,21 @@
+---
+summary: "nvd_audit_cpe and nvd_search_cpes gain offset paging; nvd_get_cve's format() renders CPE match criteria and every language a record carries instead of a bare count and English-only text; search results carry a truncated description; docs/design.md and README describe the enrichment block instead of the removed queryMeta envelope."
+breaking: false
+security: false
+---
+
+# 0.1.16 — 2026-07-27
+
+## Added
+
+- **`offset` input on `nvd_audit_cpe` and `nvd_search_cpes`** — zero-based, threaded to NVD's `startIndex` and echoed in the `enrichment` block alongside `totalCount` and `returned`, matching the pattern `nvd_search_cves` already used. `nvd_search_cpes`'s truncation notice now names the offset that reaches the remainder instead of telling the caller to narrow an already vendor-level keyword; both tools distinguish an offset past the end of the result set from their other empty-result cases. ([#31](https://github.com/cyanheads/nist-nvd-mcp-server/issues/31))
+- **Truncated description on brief CVE rows** — `BriefCveRecord` gains an optional `description` (first 200 characters of the English text, exported as `BRIEF_DESCRIPTION_CHARS`), populated on both `nvd_search_cves` results and `nvd_get_cve`'s `brief: true` mode. Lets a caller distinguish search hits without a follow-up full-detail fetch. ([#32](https://github.com/cyanheads/nist-nvd-mcp-server/issues/32))
+
+## Changed
+
+- **`nvd_get_cve`'s `format()` now matches `structuredContent`** — CPE match criteria render through the shared `formatCpeMatch()`/`flattenCpeMatches()` helpers (moved to `src/mcp-server/tools/formatting/cpe-match.ts`, also used by `nvd_audit_cpe`) instead of a bare node-group count, capped at 5 with a trailer pointing at `nvd_audit_cpe` for the remainder; every language a record carries renders under `allLanguages` instead of only English; references cap raised from 5 to 15. ([#30](https://github.com/cyanheads/nist-nvd-mcp-server/issues/30))
+- **`docs/design.md`, `README.md`, and the tool template in `CLAUDE.md`/`AGENTS.md` describe the `enrichment` block** — all three still described the `queryMeta` output envelope, which stopped being emitted several releases ago. Rewritten against each tool's actual `enrichment` fields, including ones added since the drift started (`filtersApplied`, `severityMin`, `filteredCount`, `offset`). ([#26](https://github.com/cyanheads/nist-nvd-mcp-server/issues/26))
+
+## Fixed
+
+- **`nvd://cve/{cveId}` resource carried a dead empty-result branch** — a single-ID miss always throws `cve_not_found` inside `fetchById`, so the resource's own `result.cves.length === 0` check could never execute. Removed; tests retargeted to exercise the real throw path over a mocked HTTP client.

package/dist/mcp-server/resources/definitions/nvd-cve.resource.d.ts

@@ -3,7 +3,23 @@
  * @module src/mcp-server/resources/definitions/nvd-cve
  */
 import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 export declare const nvdCveResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
     cveId: z.ZodString;
-}, z.core.$strip>, undefined, undefined>;
+}, z.core.$strip>, undefined, readonly [{
+    readonly reason: "invalid_cve_id_format";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The cveId segment of the URI fails format validation.";
+    readonly recovery: "Use a URI of the form nvd://cve/CVE-YYYY-NNNNN, for example nvd://cve/CVE-2021-44228.";
+}, {
+    /**
+     * Thrown by the service, not this handler: a single-ID fetch that NVD answers with no
+     * records raises `cve_not_found` there. The entry stays declared here so the service's
+     * `ctx.recoveryFor('cve_not_found')` resolves this recovery text onto the wire.
+     */
+    readonly reason: "cve_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The CVE ID is well-formed but NVD holds no record for it.";
+    readonly recovery: "Verify the CVE ID is correct, or use nvd_search_cves to find it by keyword or date range.";
+}]>;
 //# sourceMappingURL=nvd-cve.resource.d.ts.map

package/dist/mcp-server/resources/definitions/nvd-cve.resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nvd-cve.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/nvd-cve.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAMrD,eAAO,MAAM,cAAc;;wCAqCzB,CAAC"}
+{"version":3,"file":"nvd-cve.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/nvd-cve.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAKjE,eAAO,MAAM,cAAc;;;;;;;;IAuBrB;;;;OAIG;;;;;GA+BP,CAAC"}

package/dist/mcp-server/resources/definitions/nvd-cve.resource.js

@@ -3,7 +3,7 @@
  * @module src/mcp-server/resources/definitions/nvd-cve
  */
 import { resource, z } from '@cyanheads/mcp-ts-core';
-import { notFound, validationError } from '@cyanheads/mcp-ts-core/errors';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { getNvdCveService } from '../../../services/nvd-cve/nvd-cve-service.js';
 const CVE_ID_REGEX = /^CVE-\d{4}-\d{4,}$/i;
 export const nvdCveResource = resource('nvd://cve/{cveId}', {
@@ -17,19 +17,34 @@ export const nvdCveResource = resource('nvd://cve/{cveId}', {
             .string()
             .describe('CVE identifier (e.g., "CVE-2021-44228"). Must match the format CVE-YYYY-NNNNN.'),
     }),
+    errors: [
+        {
+            reason: 'invalid_cve_id_format',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'The cveId segment of the URI fails format validation.',
+            recovery: 'Use a URI of the form nvd://cve/CVE-YYYY-NNNNN, for example nvd://cve/CVE-2021-44228.',
+        },
+        {
+            /**
+             * Thrown by the service, not this handler: a single-ID fetch that NVD answers with no
+             * records raises `cve_not_found` there. The entry stays declared here so the service's
+             * `ctx.recoveryFor('cve_not_found')` resolves this recovery text onto the wire.
+             */
+            reason: 'cve_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The CVE ID is well-formed but NVD holds no record for it.',
+            recovery: 'Verify the CVE ID is correct, or use nvd_search_cves to find it by keyword or date range.',
+        },
+    ],
     async handler(params, ctx) {
         const { cveId } = params;
         if (!CVE_ID_REGEX.test(cveId)) {
-            throw validationError(`Invalid CVE ID format: "${cveId}". Expected format: CVE-YYYY-NNNNN.`, {
-                cveId,
-            });
+            throw ctx.fail('invalid_cve_id_format', `Invalid CVE ID format: "${cveId}". Expected format: CVE-YYYY-NNNNN.`, { cveId, ...ctx.recoveryFor('invalid_cve_id_format') });
         }
         ctx.log.debug('Fetching CVE resource', { cveId });
         const service = getNvdCveService();
+        // A single-ID miss throws `cve_not_found` inside fetchById, so this always has a record.
         const result = await service.fetchById([cveId.toUpperCase()], { includeReferences: true, allLanguages: false }, ctx);
-        if (result.cves.length === 0) {
-            throw notFound(`CVE ${cveId} not found in the NVD database.`, { cveId });
-        }
         return result.cves[0];
     },
 });

package/dist/mcp-server/resources/definitions/nvd-cve.resource.js.map

@@ -1 +1 @@
-{"version":3,"file":"nvd-cve.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/nvd-cve.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAEzE,MAAM,YAAY,GAAG,qBAAqB,CAAC;AAE3C,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC,mBAAmB,EAAE;IAC1D,IAAI,EAAE,gBAAgB;IACtB,WAAW,EACT,sEAAsE;QACtE,0FAA0F;QAC1F,sDAAsD;IACxD,QAAQ,EAAE,kBAAkB;IAE5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,CAAC,gFAAgF,CAAC;KAC9F,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;QACzB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,eAAe,CAAC,2BAA2B,KAAK,qCAAqC,EAAE;gBAC3F,KAAK;aACN,CAAC,CAAC;QACL,CAAC;QAED,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,uBAAuB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;QAEnC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,CACpC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,EACrB,EAAE,iBAAiB,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,EAChD,GAAG,CACJ,CAAC;QAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,QAAQ,CAAC,OAAO,KAAK,iCAAiC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC3E,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"nvd-cve.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/nvd-cve.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAEzE,MAAM,YAAY,GAAG,qBAAqB,CAAC;AAE3C,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC,mBAAmB,EAAE;IAC1D,IAAI,EAAE,gBAAgB;IACtB,WAAW,EACT,sEAAsE;QACtE,0FAA0F;QAC1F,sDAAsD;IACxD,QAAQ,EAAE,kBAAkB;IAE5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,CAAC,gFAAgF,CAAC;KAC9F,CAAC;IAEF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,uBAAuB;YAC/B,IAAI,EAAE,gBAAgB,CAAC,eAAe;YACtC,IAAI,EAAE,uDAAuD;YAC7D,QAAQ,EACN,uFAAuF;SAC1F;QACD;YACE;;;;eAIG;YACH,MAAM,EAAE,eAAe;YACvB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,2DAA2D;YACjE,QAAQ,EACN,2FAA2F;SAC9F;KACF;IAED,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;QACzB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,GAAG,CAAC,IAAI,CACZ,uBAAuB,EACvB,2BAA2B,KAAK,qCAAqC,EACrE,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,uBAAuB,CAAC,EAAE,CACvD,CAAC;QACJ,CAAC;QAED,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,uBAAuB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;QAEnC,yFAAyF;QACzF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,CACpC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,EACrB,EAAE,iBAAiB,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,EAChD,GAAG,CACJ,CAAC;QAEF,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/nvd-audit-cpe.tool.d.ts

@@ -25,6 +25,7 @@ export declare const nvdAuditCpe: import("@cyanheads/mcp-ts-core").ToolDefinitio
     }>>;
     allLanguages: z.ZodDefault<z.ZodBoolean>;
     limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     cves: z.ZodArray<z.ZodObject<{
         cveId: z.ZodString;
@@ -111,6 +112,7 @@ export declare const nvdAuditCpe: import("@cyanheads/mcp-ts-core").ToolDefinitio
 }], {
     readonly totalCount: z.ZodNumber;
     readonly returned: z.ZodNumber;
+    readonly offset: z.ZodNumber;
     readonly auditTarget: z.ZodString;
     readonly severityMin: z.ZodOptional<z.ZodString>;
     readonly filteredCount: z.ZodOptional<z.ZodNumber>;

package/dist/mcp-server/tools/definitions/nvd-audit-cpe.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nvd-audit-cpe.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/nvd-audit-cpe.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAsJjE,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyTtB,CAAC"}
+{"version":3,"file":"nvd-audit-cpe.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/nvd-audit-cpe.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA0HjE,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2UtB,CAAC"}

package/dist/mcp-server/tools/definitions/nvd-audit-cpe.tool.js

@@ -4,6 +4,7 @@
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { CPE_MATCH_CAP, flattenCpeMatches } from '../../../mcp-server/tools/formatting/cpe-match.js';
 import { getNvdCveService } from '../../../services/nvd-cve/nvd-cve-service.js';
 const CPE_V23_REGEX = /^cpe:2\.3:/i;
 const CvssScoreSchema = z.object({
@@ -28,30 +29,8 @@ const CpeMatchSchema = z.object({
     versionEndIncluding: z.string().optional().describe('Inclusive upper version bound.'),
     versionEndExcluding: z.string().optional().describe('Exclusive upper version bound.'),
 });
-/** Cap on CPE match criteria rendered per CVE — mirrors the references cap in this formatter. */
-const CPE_MATCH_CAP = 5;
-/**
- * Render one CPE match as a single line: the criteria string, its version bounds, and the
- * operators that govern it. `nodeOperator` combines the matches inside a node; `groupOperator`
- * combines sibling nodes in the group, so an `AND` there marks conditions that hold together
- * (e.g. a firmware match and the hardware it runs on) rather than independent alternatives.
- */
-function formatCpeMatch(match, groupOperator, nodeOperator) {
-    const bounds = [
-        match.versionStartIncluding && `>= ${match.versionStartIncluding}`,
-        match.versionStartExcluding && `> ${match.versionStartExcluding}`,
-        match.versionEndIncluding && `<= ${match.versionEndIncluding}`,
-        match.versionEndExcluding && `< ${match.versionEndExcluding}`,
-    ].filter(Boolean);
-    const notes = [
-        nodeOperator,
-        groupOperator && `${groupOperator} with sibling nodes`,
-        match.vulnerable ? undefined : 'not the vulnerable component',
-    ].filter(Boolean);
-    return (`${match.criteria}` +
-        (bounds.length > 0 ? ` (${bounds.join(', ')})` : '') +
-        (notes.length > 0 ? ` [${notes.join('; ')}]` : ''));
-}
+/** References rendered per CVE — this tool returns full records for many CVEs at once. */
+const REFERENCE_CAP = 5;
 const CveRecordSchema = z.object({
     cveId: z.string().describe('CVE identifier (e.g., "CVE-2021-44228").'),
     vulnStatus: z.string().describe('NVD analysis status.'),
@@ -172,6 +151,13 @@ export const nvdAuditCpe = tool('nvd_audit_cpe', {
             .max(2000)
             .default(20)
             .describe('Maximum number of CVEs to return (default 20, max 2000).'),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe('Zero-based page offset for pagination. Page through totalCount with a modest limit ' +
+            'rather than raising limit — this tool returns full CVE records, so a large limit is a large response.'),
     }),
     output: z.object({
         cves: z
@@ -181,6 +167,7 @@ export const nvdAuditCpe = tool('nvd_audit_cpe', {
     enrichment: {
         totalCount: z.number().describe('Total CVEs matched before pagination.'),
         returned: z.number().describe('Number of CVE records returned.'),
+        offset: z.number().describe('Page offset used in this query.'),
         auditTarget: z.string().describe('The CPE name or virtual match string used for this audit.'),
         severityMin: z
             .string()
@@ -197,6 +184,7 @@ export const nvdAuditCpe = tool('nvd_audit_cpe', {
     },
     enrichmentTrailer: {
         returned: { label: 'Returned' },
+        offset: { label: 'Offset' },
         auditTarget: { label: 'Audit Target' },
         severityMin: { label: 'Severity Filter' },
         filteredCount: { label: 'Dropped by Severity Filter' },
@@ -261,6 +249,7 @@ export const nvdAuditCpe = tool('nvd_audit_cpe', {
             cpeName: input.cpeName,
             virtualMatchString: input.virtualMatchString,
             limit: input.limit,
+            offset: input.offset,
         });
         const service = getNvdCveService();
         const result = await service.auditCpe({
@@ -273,10 +262,12 @@ export const nvdAuditCpe = tool('nvd_audit_cpe', {
             ...(input.severityMin && { severityMin: input.severityMin }),
             allLanguages: input.allLanguages,
             limit: input.limit,
+            offset: input.offset,
         }, ctx);
         const auditTarget = result.cpeName ?? result.virtualMatchString ?? 'unknown CPE';
         ctx.enrich({
             returned: result.returned,
+            offset: result.offset,
             auditTarget,
             ...(input.severityMin && {
                 severityMin: input.severityMin,
@@ -285,9 +276,14 @@ export const nvdAuditCpe = tool('nvd_audit_cpe', {
         });
         ctx.enrich.total(result.totalResults);
         if (result.cves.length === 0) {
-            // Distinguish "the CPE has no CVEs" from "severityMin dropped everything on the page":
-            // filteredCount > 0 means NVD did return CVEs, they were just below the threshold.
-            if (input.severityMin && result.filteredCount > 0) {
+            // Distinguish "the CPE has no CVEs" from "severityMin dropped everything on the page" from
+            // "the offset ran off the end": filteredCount > 0 means NVD did return CVEs, they were just
+            // below the threshold; an offset at or past totalCount means the product has CVEs but this
+            // page is empty, so telling the caller to re-check the CPE would send them the wrong way.
+            if (result.totalResults > 0 && input.offset >= result.totalResults) {
+                ctx.enrich.notice(`Offset ${input.offset} is past the end of the result set (${result.totalResults} total). Use a lower offset to page through results.`);
+            }
+            else if (input.severityMin && result.filteredCount > 0) {
                 ctx.enrich.notice(`All ${result.filteredCount} CVE(s) on the fetched page scored below ${input.severityMin}. ` +
                     'Lower severityMin or raise limit to widen the page NVD returns.');
             }
@@ -338,7 +334,7 @@ export const nvdAuditCpe = tool('nvd_audit_cpe', {
                 lines.push(`  - Required Action: ${cve.cisaKev.requiredAction}`);
             }
             if (cve.configurations && cve.configurations.length > 0) {
-                const matches = cve.configurations.flatMap((cfg) => cfg.nodes.flatMap((node) => node.cpeMatch.map((m) => formatCpeMatch(m, cfg.operator, node.operator))));
+                const matches = flattenCpeMatches(cve.configurations);
                 lines.push(`**Configurations:** ${cve.configurations.length} node group(s), ${matches.length} CPE match(es)`);
                 for (const match of matches.slice(0, CPE_MATCH_CAP))
                     lines.push(`  - ${match}`);
@@ -348,13 +344,14 @@ export const nvdAuditCpe = tool('nvd_audit_cpe', {
             }
             if (cve.references && cve.references.length > 0) {
                 lines.push(`**References (${cve.references.length}):**`);
-                for (const ref of cve.references.slice(0, 5)) {
+                for (const ref of cve.references.slice(0, REFERENCE_CAP)) {
                     const sourcePart = ref.source ? ` [${ref.source}]` : '';
                     const tagPart = ref.tags?.length ? ` (${ref.tags.join(', ')})` : '';
                     lines.push(`  - ${ref.url}${sourcePart}${tagPart}`);
                 }
-                if (cve.references.length > 5)
-                    lines.push(`  - … ${cve.references.length - 5} more`);
+                if (cve.references.length > REFERENCE_CAP) {
+                    lines.push(`  - … ${cve.references.length - REFERENCE_CAP} more`);
+                }
             }
             lines.push('');
         }