@cyanheads/cpsc-recalls-mcp-server 0.1.4 → 0.1.6

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Developer Protocol
 
 **Server:** cpsc-recalls-mcp-server
-**Version:** 0.1.4
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.9`
+**Version:** 0.1.6
+**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.
 
@@ -139,9 +139,24 @@ export function getServerConfig() {
 
 `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`MY_API_KEY`) not the path (`apiKey`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.
 
-### Server instructions
+For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
 
-`createApp({ instructions })` — optional server-level orientation, sent to clients on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
+### Server identity and instructions
+
+`createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`):
+
+```ts
+await createApp({
+  name: 'cpsc-recalls-mcp-server',
+  title: 'cpsc-recalls-mcp-server',            // display name — the hyphenated repo name
+  icons: [{ src: 'https://example.com/icon.png', sizes: ['48x48'], mimeType: 'image/png' }],
+  instructions: 'Use shortcut alpha for the most common case.', // session-level context
+});
+```
+
+`description` and `websiteUrl` are also accepted but derive from `package.json` — setting them here duplicates the canonical source and drifts.
+
+`instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
 
 ---
 
@@ -152,13 +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.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
-| `ctx.sample` | Request LLM completion from the client. **Check for presence first:** `if (ctx.sample) { ... }` |
+| `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. |
 | `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. |
 
 ---
 
@@ -166,7 +182,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -178,7 +194,7 @@ errors: [
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);
-  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
   return item;
 }
 ```
@@ -237,7 +253,9 @@ src/
 
 ## Skills
 
-Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
+Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
+
+**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills below into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
 
 **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
@@ -257,7 +275,6 @@ Available skills:
 | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
-| `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `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` |
@@ -265,12 +282,14 @@ Available skills:
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
+| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
 | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, 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 |
@@ -293,20 +312,23 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
 | `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 tree` | Generate directory structure doc |
+| `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 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 |
+| `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 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 |
 
 ---
 
 ## Bundling
 
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
 **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
 
@@ -324,14 +346,14 @@ Each per-version file opens with YAML frontmatter:
 ---
 summary: "One-line headline, ≤350 chars"  # required — powers the rollup index
 breaking: false                            # optional — true flags breaking changes
-security: false                            # optional — true flags security fixes
+security: false                            # optional — true ONLY for a source-code security fix, never a dependency CVE bump
 ---
 
 # 0.1.0 — YYYY-MM-DD
 ...
 ```
 
-`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
+`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
 
 `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
 

package/CLAUDE.md

@@ -1,8 +1,8 @@
 # Developer Protocol
 
 **Server:** cpsc-recalls-mcp-server
-**Version:** 0.1.4
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.9`
+**Version:** 0.1.6
+**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.
 
@@ -139,9 +139,24 @@ export function getServerConfig() {
 
 `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`MY_API_KEY`) not the path (`apiKey`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.
 
-### Server instructions
+For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
 
-`createApp({ instructions })` — optional server-level orientation, sent to clients on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
+### Server identity and instructions
+
+`createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`):
+
+```ts
+await createApp({
+  name: 'cpsc-recalls-mcp-server',
+  title: 'cpsc-recalls-mcp-server',            // display name — the hyphenated repo name
+  icons: [{ src: 'https://example.com/icon.png', sizes: ['48x48'], mimeType: 'image/png' }],
+  instructions: 'Use shortcut alpha for the most common case.', // session-level context
+});
+```
+
+`description` and `websiteUrl` are also accepted but derive from `package.json` — setting them here duplicates the canonical source and drifts.
+
+`instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
 
 ---
 
@@ -152,13 +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.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
-| `ctx.sample` | Request LLM completion from the client. **Check for presence first:** `if (ctx.sample) { ... }` |
+| `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. |
 | `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. |
 
 ---
 
@@ -166,7 +182,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -178,7 +194,7 @@ errors: [
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);
-  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
   return item;
 }
 ```
@@ -237,7 +253,9 @@ src/
 
 ## Skills
 
-Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
+Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
+
+**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills below into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
 
 **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
@@ -257,7 +275,6 @@ Available skills:
 | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
-| `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `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` |
@@ -265,12 +282,14 @@ Available skills:
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
+| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
 | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, 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 |
@@ -293,20 +312,23 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
 | `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 tree` | Generate directory structure doc |
+| `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 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 |
+| `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 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 |
 
 ---
 
 ## Bundling
 
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
 **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
 
@@ -324,14 +346,14 @@ Each per-version file opens with YAML frontmatter:
 ---
 summary: "One-line headline, ≤350 chars"  # required — powers the rollup index
 breaking: false                            # optional — true flags breaking changes
-security: false                            # optional — true flags security fixes
+security: false                            # optional — true ONLY for a source-code security fix, never a dependency CVE bump
 ---
 
 # 0.1.0 — YYYY-MM-DD
 ...
 ```
 
-`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
+`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
 
 `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
 

package/Dockerfile

@@ -4,15 +4,17 @@
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
 # ==============================================================================
-FROM oven/bun:1.3 AS build
+FROM oven/bun:1.3.14 AS build
 
 WORKDIR /usr/src/app
 
 # Copy dependency manifests for optimized layer caching
 COPY package.json bun.lock ./
 
-# Install all dependencies (including dev dependencies for building)
-RUN bun install --frozen-lockfile
+# Install all dependencies (including dev dependencies for building).
+# The BuildKit cache mount persists Bun's global package cache across builds.
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    bun install --frozen-lockfile --ignore-scripts
 
 # Copy the rest of the source code
 COPY . .
@@ -28,7 +30,7 @@ RUN bun run build
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1.3-slim AS production
+FROM oven/bun:1.3.14-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -49,14 +51,16 @@ COPY package.json bun.lock ./
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
-RUN bun install --production --frozen-lockfile --ignore-scripts
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    bun install --production --frozen-lockfile --ignore-scripts
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # These are not bundled by default to keep the base image lean. Enable at build time
 # with: docker build --build-arg OTEL_ENABLED=true
 ARG OTEL_ENABLED=true
-RUN if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add @hono/otel \
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    if [ "$OTEL_ENABLED" = "true" ]; then \
+      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.4-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/cpsc-recalls-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/cpsc-recalls-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/cpsc-recalls-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.0+-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.1.6-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/cpsc-recalls-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/cpsc-recalls-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/cpsc-recalls-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0+-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -33,7 +33,7 @@
 
 | Tool | Description |
 |:---|:---|
-| `cpsc_search_recalls` | Search consumer product recalls by product name, brand, retailer, importer, or description keyword, with optional date filtering |
+| `cpsc_search_recalls` | Search consumer product recalls by title, product name, brand, retailer, importer, distributor, hazard, remedy, or description keyword, with optional date filtering and offset paging |
 | `cpsc_get_recall` | Full detail for a single recall by recall number — hazards, remedy, products, injuries, images, and the official CPSC page |
 | `cpsc_get_recent` | Fetch the most recent recalls ordered newest-first, scoped to a configurable date window |
 
@@ -43,15 +43,20 @@ Data sourced from the [U.S. Consumer Product Safety Commission](https://www.safe
 
 ### `cpsc_search_recalls`
 
-Search recalls with flexible filtering across product, organization, and description fields.
+Search recalls with flexible filtering across title, product, organization, hazard, remedy, and description fields.
 
-- Filter by product name, manufacturer, retailer, importer, or description keyword — all fields are optional substring matches that combine with AND
-- Date range filtering via `date_start` / `date_end` (ISO 8601)
-- Client-side limit (1–200, default 20) applied after fetching all matching records
+- Filter by `title_search`, `product_name`, `manufacturer`, `retailer`, `importer`, `distributor`, `remedy`, or `description_search` — all optional substring matches, applied upstream, combining with AND
+- `title_search` is usually the highest-signal filter: CPSC titles name the brand, the product, and the hazard
+- `hazard_search` is a client-side filter applied after the upstream fetch — it matches when the term appears in hazard descriptions, product names, **or** remedy instructions (case-insensitive). Use it for hazard concepts like "fire", "choking", or "burn"; the upstream `Hazard` parameter is recognized but never matches, so it is not exposed
+- `remedy` searches the free-text remedy instructions, not the `remedy_options` type enum — `remedy: "repair"` matches records whose `remedy_options` list only `Refund` but whose instructions describe a free repair kit
+- Two independent date axes: `date_start` / `date_end` bound the recall issue date, `updated_start` / `updated_end` bound the date CPSC last published the record. A 2003 recall re-published in 2025 matches `updated_start: "2025-01-01"`. All four must be real calendar dates — `2026-02-31` and `2026-99-99` are rejected at input validation, and a reversed range fails with `invalid_date_range` rather than silently returning nothing
+- Client-side limit (1–200, default 20) and `offset` (default 0) applied after fetching all matching records. Page with `offset: 0, 20, 40`; an offset at or past `total_found` returns an empty result set rather than an error
+- `total_found` counts matches after `hazard_search` is applied and before `offset`/`limit` narrow the window; `has_more` is the paging signal; `truncated` stays limit-only and does not move with `offset`
 - Returns hazard descriptions, remedy options, remedy instructions, product list, UPCs, manufacturer/importer/retailer names, images, and the CPSC recall page URL
-- Includes `total_found` and `truncated` fields for pagination awareness
-- Note: the `Hazard` filter param is non-functional in the upstream API — use `description_search` for hazard-type keywords like "fire", "choking", or "burn"
-- When `manufacturer` returns no results, try `importer` or `retailer` — many recalls list the importer as the primary organization
+- Manufacturer and importer are reported and rendered as separate roles — CPSC org names contain commas, so multiple orgs in one role are separated with `; `
+- Per-recall `data_quality_notes` records gaps in the upstream record (no hazard text, no product entries); empty when nothing is missing
+- When `manufacturer` returns no results, try `importer`, `retailer`, or `distributor` — many recalls list one of those as the primary organization
+- Deterministic upstream rejections surface as `upstream_rejected` (`retryable: false`) and carry the CPSC message; transient outages stay on `upstream_error` (`retryable: true`)
 
 ---
 
@@ -62,6 +67,9 @@ Full detail for a single CPSC recall by recall number.
 - Accepts modern 5-digit recall numbers (e.g. `"25043"`) and historical 1998–2001 records with letter suffixes (e.g. `"99003a"`)
 - Returns the complete record: full description, all hazard descriptions, remedy type and instructions, all product variants with unit counts, UPCs, incident/injury narrative, manufacturer and importer names, retailer names with sale date ranges, country of manufacture, images, and coordinated agency recall URLs
 - Model numbers are typically embedded in the description text, not in a structured field
+- `description` is nullable — a small number of genuine CPSC records carry no description; the record is still returned and the absence is stated rather than rendered as a blank section
+- Manufacturer and importer are rendered under separate headings, so role attribution survives into `content[]`
+- `data_quality_notes` records gaps in the upstream record (absent description, no hazard text, no product entries); empty when nothing is missing
 - Use `cpsc_search_recalls` or `cpsc_get_recent` to find a recall number first
 
 ---
@@ -71,9 +79,11 @@ Full detail for a single CPSC recall by recall number.
 Fetch the most recent CPSC recalls, ordered newest-first.
 
 - Configurable look-back window of 1–365 days (default 30)
-- Limit of 1–100 results (default 20)
+- Limit of 1–100 results (default 20), with `offset` (default 0) to page through `total_found`. Narrowing `days` cannot page — the window is anchored to today, so shrinking it drops the oldest records rather than advancing past the newest
+- `has_more` is the paging signal; `truncated` stays limit-only and does not move with `offset`
 - Always applies a date window — without one, the upstream API returns 9,800+ records
 - Returns a lightweight record per recall: number, date, title, hazards, remedy types, product names, and CPSC URL
+- Per-recall `data_quality_notes` records gaps in the upstream record (no hazard text, no product entries); empty when nothing is missing
 - Use `cpsc_get_recall` to retrieve full detail for any result
 
 ## Features
@@ -96,8 +106,10 @@ CPSC-specific:
 Agent-friendly output:
 
 - Jurisdiction note on every response — agents can route callers to the correct agency (FDA, NHTSA, USCG, EPA) when the product is out of scope
-- `total_found` + `truncated` fields on search/recent responses — agents can detect when results are clipped and suggest narrowing filters
+- `total_found`, `offset`, `has_more`, and `truncated` fields on search/recent responses — agents can tell when results are clipped and page through the rest with `offset`
 - `cpsc_url` on every recall — authoritative source link for consumer verification
+- `source_note` on every response, plus `(CPSC source text)` labels and blockquotes in the rendered output — relayed CPSC narrative is marked as source data, distinct from the server's own guidance
+- `data_quality_notes` on every response — gaps observed in the upstream record, derived from which fields CPSC left empty rather than any judgement about the recall
 
 ## Getting started
 

package/changelog/0.1.x/0.1.5.md

@@ -0,0 +1,52 @@
+---
+summary: "Reject impossible dates and sentinel error rows, fix null-Description and manufacturer/importer rendering, frame CPSC narrative as source text; mcp-ts-core ^0.11.0, TypeScript ^7.0.2"
+breaking: false
+security: false
+---
+
+# 0.1.5 — 2026-07-27
+
+## Added
+
+- **Calendar-valid date filters** — `date_start`/`date_end` on `cpsc_search_recalls` now parse with `z.iso.date()` instead of a digit-shape regex, so `2026-99-99` and `2026-02-31` are rejected at input validation instead of reaching the upstream API ([#1](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/1)).
+- **`invalid_date_range` error** — `date_start` later than `date_end` now throws a declared `ValidationError` naming both values instead of silently returning `no_results` ([#1](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/1)).
+- **CPSC error-row rejection** — `CpscRecallService.fetchRecalls` now recognizes the one-row sentinel array CPSC substitutes for malformed requests (identifying fields null, upstream message in `Title`) and throws a non-retryable `serviceUnavailable` instead of crashing on `null.slice()` during normalization. Shared by `search`, `getByNumber`, and `getRecent` ([#1](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/1)).
+- **`data_quality_notes`** — new array output field on all three tools recording upstream gaps (absent description, no hazard text, no product entries) observed directly from empty fields, with no judgement about the recall itself ([#3](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/3)).
+- **`source_note`** — new string output field on all three tools stating that recall fields are relayed verbatim from CPSC, unedited and unverified, and that `cpsc_url` should be checked before a consumer-facing decision ([#3](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/3)).
+- **Source-text framing** — `cpsc_get_recall.format()` renders relayed CPSC narrative (hazard, remedy, contact, description, injuries, retailers, image captions) as markdown blockquotes under `(CPSC source text)` headings, visually separated from server-authored guidance; `cpsc_search_recalls.format()` labels its per-record relayed block `CPSC source fields:` ([#3](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/3)).
+- **`tests/services/cpsc-recall/cpsc-recall-service.test.ts`** — new service-level test file covering error-row rejection on the `search` and `getRecent` paths and a sparse-but-genuine record passing through untouched.
+
+## Changed
+
+- **`description` is nullable** — `cpsc_get_recall`'s output field is now `z.string().nullable()` instead of a normalized empty string, so recall `04084` (a genuine record with no upstream description) returns instead of failing output validation. `format()` renders `_Not provided by CPSC._` for the null, empty, and whitespace-only cases ([#4](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/4)).
+- **`RawRecall.Description`** — retyped `string | null` to match observed upstream reality.
+- **Manufacturer and importer render as separate roles** — `cpsc_get_recall.format()` splits the merged `## Manufactured By / Imported By` section into `## Manufactured By` and `## Imported By`, each shown only when populated; `cpsc_search_recalls.format()` emits separate `**Manufacturer:**` / `**Importer:**` lines and joins multiple orgs within a role with `; ` instead of `, ` (CPSC org names contain commas, which made the merged `, `-joined line unparseable) ([#5](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/5)).
+- **`cpsc_search_recalls.format()` product list** — joined with `; ` instead of `, ` for the same comma-collision reason.
+
+## Fixed
+
+- **`cpsc_get_recall` returns recall `04084`** — previously failed output validation with "expected string, received null" ([#4](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/4)).
+- **Impossible calendar dates no longer crash the search handler** — previously threw `null is not an object (evaluating 'r.RecallDate.slice')` when CPSC's sentinel row reached normalization ([#1](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/1)).
+- **Manufacturer/importer attribution no longer collapses into one unparseable line** in `content[]` output ([#5](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/5)).
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.10.9 → ^0.11.0
+- `typescript` ^6.0.3 → ^7.0.2 (dev)
+- `@biomejs/biome` ^2.5.0 → ^2.5.5 (dev)
+- `@types/node` ^26.0.0 → ^26.1.1 (dev)
+- `tsc-alias` ^1.8.17 → ^1.9.1 (dev)
+- `vitest` ^4.1.9 → ^4.1.10 (dev)
+- `ignore` ^7.0.5 → ^7.0.6 (dev)
+- `@socketsecurity/bun-security-scanner` ^1.1.2 added (dev) — Socket install-time scanner wired into `bunfig.toml`'s new `[install.security]` block
+- Two all-transitive advisories remain with no in-range fix (`depcheck › minimatch › brace-expansion`, `@cyanheads/mcp-ts-core › @hono/node-server`); `devcheck`'s Security Audit step reports them as a warning with the run passing
+
+## Other
+
+- `bunfig.toml` — `minimumReleaseAge` (3-day supply-chain delay) with `@cyanheads/mcp-ts-core` excluded for same-day framework adoption; Socket scanner wired via `[install.security]`.
+- `Dockerfile` — pinned `oven/bun:1.3.14` (was floating `1.3`), BuildKit cache mounts on every `bun install` layer, `--ignore-scripts` on the OTel peer-dependency install.
+- `.gitignore` — anchored `data/` to `/data/` so a nested `data/` directory in `src/` isn't accidentally ignored.
+- `devcheck.config.json` — added `@socketsecurity/bun-security-scanner` to the outdated-check allowlist.
+- Repo metadata sync: `package.json` description, author, and `packageManager` (`bun@1.3.14`); `manifest.json` gained a `license` field; both plugin manifests' descriptions updated to match.
+- Added `.gitattributes` (LF normalization, binary asset handling, `linguist-generated` markers), `.github/SECURITY.md`, `.github/FUNDING.yml`.
+- `scripts/`, `skills/`, `CLAUDE.md`/`AGENTS.md`, and `changelog/template.md` re-synced from the `@cyanheads/mcp-ts-core` 0.11.0 project template (new `lint:mcp`/`lint:packaging` standalone commands, `list-skills`, `ctx.enrich`/`ctx.content` docs, `api-mirror` skill, tightened `security:` changelog-flag guidance).

package/changelog/0.1.x/0.1.6.md

@@ -0,0 +1,29 @@
+---
+summary: "Add title/distributor/remedy/publish-date filters and client-side hazard search to cpsc_search_recalls, offset paging with has_more on search and recent, and a non-retryable upstream_rejected error distinct from transient failures"
+breaking: false
+security: false
+---
+
+# 0.1.6 — 2026-07-27
+
+## Added
+
+- **`title_search`, `distributor`, `remedy`, `updated_start`/`updated_end`** — four new `cpsc_search_recalls` filters mapped to verified-working upstream parameters (`RecallTitle`, `Distributor`, `Remedy`, `LastPublishDateStart`/`End`), forwarded through `CpscSearchParams` and `CpscRecallService.search()`'s param-whitelist object literal ([#6](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/6)). `remedy` matches the free-text remedy narrative, not the `remedy_options` type enum. `updated_start`/`updated_end` bound `LastPublishDate`, a separate axis from `date_start`/`date_end`'s recall-issue date.
+- **`invalid_date_range` now also covers `updated_start`/`updated_end`** — a reversed publish-date range throws the same validation error as a reversed recall-date range, instead of silently returning nothing ([#6](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/6)).
+- **`hazard_search`** on `cpsc_search_recalls` — client-side, case-insensitive OR filter across `hazards`, `products[].name`, and `remedy_summary`, applied to the full normalized array before `total_found`/`offset`/`limit` narrow it ([#2](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/2)). Replaces the prior guidance to use `description_search` for hazard terms, which only reached the upstream `RecallDescription` field.
+- **`offset` and `has_more`** on `cpsc_search_recalls` and `cpsc_get_recent` — pages past the existing `limit` ceiling; `has_more` is `offset + returned < total_found` and is independent of `truncated`, which stays limit-only ([#7](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/7)). An offset at or past `total_found` returns an empty result set rather than a `no_results` error.
+
+## Changed
+
+- **`no_results` on `cpsc_search_recalls`** moved off the raw pre-filter count — it now throws on the count after `hazard_search` runs (and before the `offset`/`limit` window), so a filter that legitimately empties the set still reports correctly ([#2](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/2), [#7](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/7)).
+- **`remedy_options` output description** on all three tools now lists `Inspect` and `No Remedy Available` alongside the previous six values, and notes the field is often empty (CPSC classifies remedy on fewer than half its records) with a fallback to `remedy_summary`/`remedy_instructions`, then `cpsc_url`.
+- **`format()` footers** on `cpsc_search_recalls` and `cpsc_get_recent` now report the current offset and a "More available — repeat with offset N" line when `has_more` is true.
+- **Tool descriptions and README** — the "`Hazard` filter is non-functional, use `description_search`" framing is gone; hazard concepts route to `hazard_search`, the recall headline to `title_search`, and `description_search` is rescoped to product-detail text (model numbers, colors, sale channels).
+
+## Fixed
+
+- **`upstream_rejected` error reason** (`ServiceUnavailable`, `retryable: false`) added to all three tools, distinct from `upstream_error` ([#8](https://github.com/cyanheads/cpsc-recalls-mcp-server/issues/8)). Previously every service error — deterministic CPSC rejection or transient outage alike — was reported as `upstream_error` with `retryable: true`, so a client honoring the recovery hint retried a request that could never succeed. Each tool's catch block now routes on `err.data.retryable === false`; the caught error's own message reaches the client on both arms instead of a fixed `CPSC API request failed.` string.
+
+## Other
+
+- **`docs/design.md`** reconciled to as-built: entries the shipped code now contradicts (the `Hazard`/`description_search` framing, "no pagination") carry a **Superseded** note rather than being rewritten, so the pre-build rationale stays legible alongside the current behavior.

package/changelog/template.md

@@ -15,9 +15,11 @@ summary: ""
 # usage. Flagged as `Breaking` in the rollup.
 breaking: false
 
-# Set `true` if this release contains any security fix. Pairs with the
-# `## Security` section below. Flagged as `Security` in the rollup so
-# users can triage upgrade urgency at a glance.
+# Set `true` ONLY for a security fix in THIS project's own source code — a
+# vulnerability or hardening in code you ship. A dependency or transitive CVE
+# bump is routine maintenance, NOT a security release: record it under
+# `## Dependencies` (with the advisory ID) and leave this `false`. When true,
+# pairs with the `## Security` section below and flags `Security` in the rollup.
 security: false
 
 # Optional free-form notes for maintenance agents processing this release.

package/dist/mcp-server/tools/definitions/cpsc-get-recall.tool.d.ts

@@ -11,7 +11,7 @@ export declare const cpscGetRecall: import("@cyanheads/mcp-ts-core").ToolDefinit
     recall_date: z.ZodString;
     last_updated: z.ZodString;
     title: z.ZodString;
-    description: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
     cpsc_url: z.ZodString;
     consumer_contact: z.ZodNullable<z.ZodString>;
     hazards: z.ZodArray<z.ZodObject<{
@@ -35,7 +35,9 @@ export declare const cpscGetRecall: import("@cyanheads/mcp-ts-core").ToolDefinit
         caption: z.ZodString;
     }, z.core.$strip>>;
     coordinated_recalls: z.ZodArray<z.ZodString>;
+    data_quality_notes: z.ZodArray<z.ZodString>;
     cpsc_jurisdiction: z.ZodString;
+    source_note: z.ZodString;
 }, z.core.$strip>, readonly [{
     readonly reason: "not_found";
     readonly code: JsonRpcErrorCode.NotFound;
@@ -44,8 +46,14 @@ export declare const cpscGetRecall: import("@cyanheads/mcp-ts-core").ToolDefinit
 }, {
     readonly reason: "upstream_error";
     readonly code: JsonRpcErrorCode.ServiceUnavailable;
-    readonly when: "The saferproducts.gov API returned an error or timed out";
+    readonly when: "The saferproducts.gov API returned a transient error or timed out";
     readonly recovery: "The CPSC API is occasionally unavailable. Retry in a few seconds.";
     readonly retryable: true;
+}, {
+    readonly reason: "upstream_rejected";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The saferproducts.gov API answered with an error row instead of a recall record, which the same request will always produce";
+    readonly recovery: "Do not retry this request unchanged — it fails deterministically. Read the message for what CPSC rejected, then confirm the recall number with cpsc_search_recalls.";
+    readonly retryable: false;
 }], undefined>;
 //# sourceMappingURL=cpsc-get-recall.tool.d.ts.map