@cyanheads/mcp-ts-core 0.13.1 → 0.13.3

package/AGENTS.md

@@ -1,10 +1,10 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.13.1
+**Version:** 0.13.3
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revisions 2026-07-28 and 2025-*)
-**Zod:** ^4.6.1
+**Zod:** ^4.6.5
 **GitHub:** [cyanheads/mcp-ts-core](https://github.com/cyanheads/mcp-ts-core)
 **npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 **Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
@@ -22,7 +22,7 @@ This package serves two consumer paths. When making changes, know which audience
 | **Direct package import** — existing project pulls in the package | `bun add @cyanheads/mcp-ts-core` → `import { createApp, tool, z } from '@cyanheads/mcp-ts-core'` | Public API surface (`src/`) — existing consumers feel changes immediately on upgrade |
 | **Init-scaffolded server** — fresh project bootstrapped from this repo's templates | `bunx @cyanheads/mcp-ts-core init [name]` copies `templates/` into the new directory | `templates/` — only affects newly scaffolded servers, not existing ones |
 
-Both paths share the same public API. Init copies starter `package.json`, configs (`tsconfig`, `biome.json`, `vitest.config.ts`, `devcheck.config.json`, `bunfig.toml`), `.env.example`, `Dockerfile`, `LICENSE`, `.gitattributes`, `CLAUDE.md`/`AGENTS.md`, `.github/` (issue forms, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`), example definitions and tests, framework `scripts/`, and external-audience `framework-skills/`. `_`-prefixed files (e.g. `_.gitignore`) drop the prefix on copy. Existing files are never overwritten; `init` without a name scaffolds in place (upgrade flow). After init, consult the `setup` skill.
+Both paths share the same public API. Init copies starter `package.json`, configs (`tsconfig`, `biome.json`, `vitest.config.ts`, `devcheck.config.json`, `bunfig.toml`), `.env.example`, `Dockerfile`, `LICENSE`, `.gitattributes`, `CLAUDE.md`/`AGENTS.md`, `.github/` (issue forms, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `workflows/codeql.yml`), example definitions and tests, framework `scripts/`, and external-audience `framework-skills/`. `_`-prefixed files (e.g. `_.gitignore`) drop the prefix on copy. Existing files are never overwritten; `init` without a name scaffolds in place (upgrade flow). After init, consult the `setup` skill.
 
 ---
 
@@ -414,9 +414,9 @@ Available factories: `invalidParams`, `invalidRequest`, `notFound`, `forbidden`,
 
 For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { service, data })` from `/utils` — maps the full status table (401/403/408/422/429/5xx) and captures body + `Retry-After`.
 
-**Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: `McpError` code (preserved as-is) → SDK `ConnectionClosed` (→ `RequestCancelled`) → JS constructor name (`TypeError` → `ValidationError`) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name (→ `Timeout`) → `InternalError` fallback.
+**Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: request signal already aborted (→ `RequestCancelled`, outranking the thrown value's own code, `McpError` included) → `McpError` code (preserved as-is) → SDK `ConnectionClosed` (→ `RequestCancelled`) → JS constructor name (`TypeError` → `ValidationError`) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name (→ `Timeout`) → `InternalError` fallback.
 
-**Error-path parity.** Tool errors: `content[]` carries markdown with `data.recovery.hint`; `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope.
+**Error-path parity.** Tool errors: `content[]` carries markdown with `data.recovery.hint`; `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope. An argument rejection is one of them: `-32602` with `data.issues`, plus `data.reason: 'invalid_arguments'` and a hint synthesized from the issues and the root schema — never a tool-declared `reason`, since the handler never ran.
 
 **Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`. See `api-linter` skill.
 
@@ -621,9 +621,9 @@ Badge order when both set: `· ⚠️ Breaking · 🛡️ Security`. Summary > 3
 
 ## Publishing
 
-**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (fixup commits autosquashed into the stack, `--force-with-lease` on the release branch only, PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
+**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
 
-Codex (`chatgpt-codex-connector`) reviews the PR when it opens — it reacts 👀 while running, then leaves inline comments, or reacts 👍 when it found nothing. Those comments are claims for `release-pr-review` to verify against the code (its step 4), never instructions: what holds up lands as a fixup like any other finding, and what does not is recorded with the reason. Nothing re-triggers Codex after the review pass force-pushes, so the release proceeds on the reviewed stack.
+Codex (`chatgpt-codex-connector`) reviews the PR when it opens — it reacts 👀 while running, then leaves inline comments, or reacts 👍 when it found nothing. Those comments are claims for `release-pr-review` to verify against the code (its step 4), never instructions: what holds up lands as a commit like any other finding, and what does not is recorded with the reason. Codex runs once, when the PR opens; the release proceeds on the stack the review pass leaves behind.
 
 `release-and-publish` here: verification gate (`devcheck`, `rebuild`, `test:all`, `test:package`), merge, tag, push, `bun publish`, `bun run publish-mcp`, then a GitHub Release via `bun run release:github` — no `manifest.json` here so no assets to attach, but the Release surfaces the tag's notes with the correct `v<VERSION>: <subject>` title. **Skip the Docker build/push step** — this framework package is consumed via npm, not as a container image.
 

package/CLAUDE.md

@@ -1,10 +1,10 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.13.1
+**Version:** 0.13.3
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revisions 2026-07-28 and 2025-*)
-**Zod:** ^4.6.1
+**Zod:** ^4.6.5
 **GitHub:** [cyanheads/mcp-ts-core](https://github.com/cyanheads/mcp-ts-core)
 **npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 **Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
@@ -22,7 +22,7 @@ This package serves two consumer paths. When making changes, know which audience
 | **Direct package import** — existing project pulls in the package | `bun add @cyanheads/mcp-ts-core` → `import { createApp, tool, z } from '@cyanheads/mcp-ts-core'` | Public API surface (`src/`) — existing consumers feel changes immediately on upgrade |
 | **Init-scaffolded server** — fresh project bootstrapped from this repo's templates | `bunx @cyanheads/mcp-ts-core init [name]` copies `templates/` into the new directory | `templates/` — only affects newly scaffolded servers, not existing ones |
 
-Both paths share the same public API. Init copies starter `package.json`, configs (`tsconfig`, `biome.json`, `vitest.config.ts`, `devcheck.config.json`, `bunfig.toml`), `.env.example`, `Dockerfile`, `LICENSE`, `.gitattributes`, `CLAUDE.md`/`AGENTS.md`, `.github/` (issue forms, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`), example definitions and tests, framework `scripts/`, and external-audience `framework-skills/`. `_`-prefixed files (e.g. `_.gitignore`) drop the prefix on copy. Existing files are never overwritten; `init` without a name scaffolds in place (upgrade flow). After init, consult the `setup` skill.
+Both paths share the same public API. Init copies starter `package.json`, configs (`tsconfig`, `biome.json`, `vitest.config.ts`, `devcheck.config.json`, `bunfig.toml`), `.env.example`, `Dockerfile`, `LICENSE`, `.gitattributes`, `CLAUDE.md`/`AGENTS.md`, `.github/` (issue forms, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `workflows/codeql.yml`), example definitions and tests, framework `scripts/`, and external-audience `framework-skills/`. `_`-prefixed files (e.g. `_.gitignore`) drop the prefix on copy. Existing files are never overwritten; `init` without a name scaffolds in place (upgrade flow). After init, consult the `setup` skill.
 
 ---
 
@@ -414,9 +414,9 @@ Available factories: `invalidParams`, `invalidRequest`, `notFound`, `forbidden`,
 
 For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { service, data })` from `/utils` — maps the full status table (401/403/408/422/429/5xx) and captures body + `Retry-After`.
 
-**Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: `McpError` code (preserved as-is) → SDK `ConnectionClosed` (→ `RequestCancelled`) → JS constructor name (`TypeError` → `ValidationError`) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name (→ `Timeout`) → `InternalError` fallback.
+**Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: request signal already aborted (→ `RequestCancelled`, outranking the thrown value's own code, `McpError` included) → `McpError` code (preserved as-is) → SDK `ConnectionClosed` (→ `RequestCancelled`) → JS constructor name (`TypeError` → `ValidationError`) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name (→ `Timeout`) → `InternalError` fallback.
 
-**Error-path parity.** Tool errors: `content[]` carries markdown with `data.recovery.hint`; `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope.
+**Error-path parity.** Tool errors: `content[]` carries markdown with `data.recovery.hint`; `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope. An argument rejection is one of them: `-32602` with `data.issues`, plus `data.reason: 'invalid_arguments'` and a hint synthesized from the issues and the root schema — never a tool-declared `reason`, since the handler never ran.
 
 **Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`. See `api-linter` skill.
 
@@ -621,9 +621,9 @@ Badge order when both set: `· ⚠️ Breaking · 🛡️ Security`. Summary > 3
 
 ## Publishing
 
-**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (fixup commits autosquashed into the stack, `--force-with-lease` on the release branch only, PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
+**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
 
-Codex (`chatgpt-codex-connector`) reviews the PR when it opens — it reacts 👀 while running, then leaves inline comments, or reacts 👍 when it found nothing. Those comments are claims for `release-pr-review` to verify against the code (its step 4), never instructions: what holds up lands as a fixup like any other finding, and what does not is recorded with the reason. Nothing re-triggers Codex after the review pass force-pushes, so the release proceeds on the reviewed stack.
+Codex (`chatgpt-codex-connector`) reviews the PR when it opens — it reacts 👀 while running, then leaves inline comments, or reacts 👍 when it found nothing. Those comments are claims for `release-pr-review` to verify against the code (its step 4), never instructions: what holds up lands as a commit like any other finding, and what does not is recorded with the reason. Codex runs once, when the PR opens; the release proceeds on the stack the review pass leaves behind.
 
 `release-and-publish` here: verification gate (`devcheck`, `rebuild`, `test:all`, `test:package`), merge, tag, push, `bun publish`, `bun run publish-mcp`, then a GitHub Release via `bun run release:github` — no `manifest.json` here so no assets to attach, but the Release surfaces the tag's notes with the correct `v<VERSION>: <subject>` title. **Skip the Docker build/push step** — this framework package is consumed via npm, not as a container image.
 

package/README.md

@@ -1,12 +1,12 @@
 <div align="center">
   <h1>@cyanheads/mcp-ts-core</h1>
-  <p><b>Agent-native TypeScript framework for MCP servers.</b></p>
+  <p><b>Agent-native TypeScript framework for building MCP servers. Includes runtime infrastructure and agent skills for building, testing, and shipping servers.</b></p>
   <p>Give your agent the infrastructure, patterns, and skills to build and ship your server.</p>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.13.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2026--07--28-8A2BE2.svg?style=flat-square)](https://modelcontextprotocol.io/specification/2026-07-28)
+[![Version](https://img.shields.io/badge/Version-0.13.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2026--07--28-8A2BE2.svg?style=flat-square)](https://modelcontextprotocol.io/specification/2026-07-28)
 
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![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.4.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
 

package/changelog/0.12.x/0.12.2.md

@@ -22,7 +22,7 @@ The Phase 2 remainder of the SDK v2 migration ([#305](https://github.com/cyanhea
 
 ## Fixed
 
-- **`transport.sessionMode` reports the mode the server actually runs in, never `auto`** ([#357](https://github.com/cyanheads/mcp-ts-core/issues/357)). A default HTTP deployment serves sessions statefully while advertising `auto` on the landing page and the `/.well-known/mcp.json` server card; it reads `stateful` there now.
+- **`transport.sessionMode` reports the mode the server actually runs in, never `auto`** ([#357](https://github.com/cyanheads/mcp-ts-core/issues/357)). A default HTTP deployment serves sessions statefully while the `GET /mcp` status JSON reported `auto`; it reads `stateful` there now.
 
 ## Dependencies
 

package/changelog/0.13.x/0.13.2.md

@@ -0,0 +1,43 @@
+---
+summary: "A fresh init scaffold builds again — the shipped build scripts resolve both tsconfig layouts — and devcheck gains a README version-badge check. runToolContract rejects out-of-schema arguments with the InvalidParams envelope a client actually receives."
+breaking: false
+security: false
+agent-notes: |
+  Two adoption steps for a consumer upgrading from 0.13.1.
+
+  1. A test asserting `ValidationError` (`-32007`) on an argument rejection
+     through `runToolContract` now receives `InvalidParams` (`-32602`) with the
+     production message — flip the assertion. Message assertions hold either
+     way, since both texts name the offending field.
+  2. After the next `scripts/` sync, `devcheck` fails when the `README.md`
+     `Version-` badge disagrees with the `package.json` `version`. Fix the
+     badge before syncing.
+---
+
+# 0.13.2 — 2026-09-13
+
+## Added
+
+- **`lint:packaging` check 12 — README version badge parity** ([#418](https://github.com/cyanheads/mcp-ts-core/issues/418)). A shields.io `Version-<semver>-` badge in `README.md` must carry the `package.json` `version`, with `--` decoded so a prerelease matches. `devcheck`'s Packaging step now triggers on `README.md` too, so the check gates a project carrying no bundle or plugin metadata.
+- **Server card publishes the resolved session mode** ([#387](https://github.com/cyanheads/mcp-ts-core/issues/387)) under the `_meta` key `io.github.cyanheads.mcp-ts-core/sessionMode` — `stateful` or `stateless`, never `auto`. SEP-2127 closes the card's top-level field set, so it ships as a namespaced extension; every field the card already emitted is unchanged.
+
+## Changed
+
+- **Sync-guarantee comments in `scripts/clean-mcpb.ts` and `scripts/lint-packaging.ts` read true in a consumer's copy** ([#313](https://github.com/cyanheads/mcp-ts-core/issues/313)). The four `AGENT_DOC_ENTRY` / `NATIVE_BINDING_ENTRY` blocks no longer claim a unit test enforces the pair where `tests/` never ships, and the `KNOWN_DEV_DIRS` note names `.mcpbignore` rather than `templates/_.mcpbignore`.
+- **`add-tool` skill and the 0.8.11 entry drop the server-card disabled-tool claim** ([#409](https://github.com/cyanheads/mcp-ts-core/issues/409)). The card carries no per-tool entries; the landing page is the only surface that renders a disabled tool.
+- **0.12.2's session-mode entry names `GET /mcp`** — the surface that actually reported the resolved mode, rather than the landing page and server card it claimed (#387).
+- **README tagline matches the `package.json` `description` verbatim.**
+- Skill versions: `add-tool` 2.25 → 2.26, `api-testing` 1.9 → 1.10, `git-wrapup` 1.16 → 1.17, `polish-docs-meta` 2.16 → 2.17.
+
+## Fixed
+
+- **`scripts/build.ts` resolves the build tsconfig in either layout** ([#440](https://github.com/cyanheads/mcp-ts-core/issues/440)). It probes `config/tsconfig.build.json`, then `tsconfig.build.json`, so a fresh `init` scaffold builds with no `--project` and no consumer edit; an explicit `--project` still reaches the compiler verbatim.
+- **`devcheck`'s TypeScript (Worker) step probes both tsconfig locations** ([#440](https://github.com/cyanheads/mcp-ts-core/issues/440)). A worker tsconfig at the project root rendered `SKIPPED`, indistinguishable from a project with no Workers lane.
+- **`scripts/verify-package.ts` builds the scaffold through its own `build` script** and asserts `dist/index.js` ([#440](https://github.com/cyanheads/mcp-ts-core/issues/440)), so a default-path regression fails `bun run test:package`.
+- **`scripts/clean.ts` removes every build-info file the project's tsconfigs write** ([#441](https://github.com/cyanheads/mcp-ts-core/issues/441)) — the lane-suffixed `.tsbuildinfo.<lane>` forms, and files written beside a tsconfig in `config/`. Explicit positional arguments still replace the default set entirely.
+- **`devcheck`'s running log marks a warning-demoted step as a warning** ([#344](https://github.com/cyanheads/mcp-ts-core/issues/344)). `formatCheckResult` read `exitCode` alone and printed `finished successfully` for a result the summary reported as `WARNING`; both surfaces now key on the same guard.
+- **`runToolContract` rejects out-of-schema arguments as `InvalidParams` (`-32602`)** ([#416](https://github.com/cyanheads/mcp-ts-core/issues/416)), through the same `parseToolArguments` call `createToolHandler` makes, so the code, message, and `content[0].text` are what a client receives. A `ZodError` thrown inside a handler and an output-schema rejection still classify as `ValidationError`.
+
+## Dependencies
+
+- `zod` ^4.6.1 → ^4.6.2

package/changelog/0.13.x/0.13.3.md

@@ -0,0 +1,44 @@
+---
+summary: "Argument rejections carry a reason and a schema-derived recovery hint, and render an omitted required field as missing rather than as a wrong choice. A handler unwound after its request was cancelled classifies RequestCancelled whatever it threw."
+breaking: false
+security: false
+agent-notes: |
+  Two adoption steps for a consumer upgrading from 0.13.2.
+
+  1. Every argument rejection's `content[0].text` now ends with a
+     `\n\nRecovery: <hint>` suffix, and its `data` carries
+     `reason: "invalid_arguments"`. `runToolContract` routes through the
+     production rejection path, so a test pinning that text byte-exact fails on
+     upgrade — assert that it *contains* the offending field instead.
+     `toolContractSuite` asserts only the `Error:` prefix and is unaffected.
+  2. A cancelled call now logs at `info` with `metrics.errorCode: "-32011"`. A
+     dashboard or alert keyed on `UNKNOWN_ERROR` / `InternalError` to count
+     client disconnects no longer matches — key it on `-32011`.
+---
+
+# 0.13.3 — 2026-09-17
+
+## Added
+
+- **`data.reason: "invalid_arguments"` and a synthesized `data.recovery.hint` on every argument rejection** ([#445](https://github.com/cyanheads/mcp-ts-core/issues/445)). The hint is derived from the Zod issues, the arguments as sent, and the root schema: an unknown key names the root properties the tool does accept, a wrong type names the type to send instead, and missing fields collapse into one `Provide …` sentence. It rides `content[]` as `Recovery: …` like any handler-thrown hint. A `z.discriminatedUnion()` root omits the accepted-key list, since no single call accepts the union of every variant's keys.
+- **`.github/workflows/codeql.yml`, at the repo root and in the scaffold** — the one workflow a server carries, copied by `init`. It runs only while the repo's CodeQL *default setup* is off.
+
+## Changed
+
+- **A required field omitted from an enum or literal renders as missing** ([#378](https://github.com/cyanheads/mcp-ts-core/issues/378)) — `what: Missing required field. Expected one of "os"|"cpu"|"memory"`, where an omission and a wrong choice were previously byte-identical. A value outside the set keeps Zod's invalid-option sentence. Absence is resolved from the arguments in-process, so no value a caller sent is copied onto `data.issues`.
+- **A union rejection renders its branch messages** ([#417](https://github.com/cyanheads/mcp-ts-core/issues/417)) joined by ` or `, instead of Zod's `Invalid input` placeholder. A branch whose only issue is a single-valued `invalid_value` — the `z.literal('')` blank-field sentinel — is skipped.
+- **The scaffold's `instructions` comment shows the shape to write** — two to three cohesive sentences in one string literal, addressed to the calling agent, with operator configuration left to the README. `tool-defs-analysis` checks the same shape on `description` and `instructions`.
+- Skill versions: `api-errors` 1.10 → 1.12, `git-wrapup` 1.17 → 1.18, `orchestrations` 1.9 → 1.10, `release-and-publish` 2.17 → 2.18, `release-pr-review` 1.1 → 1.3, `tool-defs-analysis` 1.5 → 1.6.
+
+## Fixed
+
+- **A handler unwound after its request's abort signal fired classifies `RequestCancelled` (`-32011`)** ([#421](https://github.com/cyanheads/mcp-ts-core/issues/421)) whatever it threw — a `notifications/cancelled` `reason` string, the `AbortError` `DOMException` a reason-less cancellation leaves, a service's own `McpError`. It is resolved inside the measured region of both handler factories, so the completion log's `metrics.errorCode` and the execution span carry `-32011` too, and the record logs at `info` with neither a stack nor a cause chain. A throw raised while the signal is still live is untouched.
+- **`git-wrapup` step 7 and `release-pr-review` step 5 commit by pathspec** ([#444](https://github.com/cyanheads/mcp-ts-core/issues/444)) — `git commit --only <paths>`, so anything staged before the run (a migration's `git mv`, a hook's output, a concurrent session) cannot ride into the first concern's commit. `release-pr-review` step 5 lands each review fix as an ordinary commit on top of the release branch and pushes plainly, so nothing already pushed is rewritten and `main` keeps the record of what the review corrected. `git-wrapup` step 1 also diffs against `HEAD` rather than the index, so a pre-staged group is reviewed rather than skipped.
+
+## Dependencies
+
+- `zod` ^4.6.2 → ^4.6.5
+- `@duckdb/node-api` ^1.5.5-r.4 → ^1.5.5-r.5 (dev)
+- `fast-check` ^4.9.0 → ^4.10.0 (dev)
+- `js-yaml` ^5.4.1 → ^5.4.2 (dev)
+- `tsc-alias` ^1.9.4 → ^1.9.5 (dev; scaffold pin ^1.9.2 → ^1.9.5, alongside `ignore` ^7.0.7 → ^7.0.9)

package/changelog/0.8.x/0.8.11.md

@@ -9,9 +9,9 @@ Three small surface changes plus a documentation policy. The framework gains a `
 
 ## Added
 
-- **`disabledTool(def, meta)` wrapper** — new `@cyanheads/mcp-ts-core/tools` export (also re-exported from the framework root). Marks a tool definition as present-in-manifest but skipped at MCP registration so `tools/list` clients can't invoke it while operators reading `/.well-known/mcp.json` and the HTML landing page still see the gated tool with an operator-facing `reason`, optional `hint`, and optional `since`. Public `ToolDefinition` interface and the `tool()` builder are untouched — the wrapper attaches an internal `__mcpDisabled` field that only `ToolRegistry` and `buildServerManifest()` read. ([#96](https://github.com/cyanheads/mcp-ts-core/issues/96))
+- **`disabledTool(def, meta)` wrapper** — new `@cyanheads/mcp-ts-core/tools` export (also re-exported from the framework root). Marks a tool definition as present-in-manifest but skipped at MCP registration so `tools/list` clients can't invoke it while operators reading the HTML landing page still see the gated tool with an operator-facing `reason`, optional `hint`, and optional `since`. Public `ToolDefinition` interface and the `tool()` builder are untouched — the wrapper attaches an internal `__mcpDisabled` field that only `ToolRegistry` and `buildServerManifest()` read. ([#96](https://github.com/cyanheads/mcp-ts-core/issues/96))
 - **`DisabledMetadata` type** — `{ reason: string; hint?: string; since?: string }`. Re-exported from `@cyanheads/mcp-ts-core` and `/tools`.
-- **`ManifestTool.disabled`** — optional `DisabledMetadata` field threaded through `buildServerManifest()`. Surfaces in `/.well-known/mcp.json` `definitions.tools` for discovery agents that need to know a tool is gated without invoking it.
+- **`ManifestTool.disabled`** — optional `DisabledMetadata` field threaded through `buildServerManifest()`. Read by the HTML landing page, which renders the gate for operators who need to know a tool is unavailable without invoking it.
 - **Landing page `disabled` bucket** — new fourth bucket rendered after `read | unspecified | write | destructive`. Cards use a muted dashed-border variant (`tool-card--disabled`), replace the invocation `<details>` with a callout containing reason + optional hint + optional `since`, and keep the schema preview so operators can still read the tool's contract. Companion "would be `<mutability>`" pill surfaces the underlying classification, suppressed when underlying is `unspecified`.
 - **Landing page `unspecified` bucket** — new third bucket between `read` and `write`. Pills, chip, and card spine use muted/italic styling to read as indeterminate, distinct from the `write` bucket's deliberate-mutation signal. ([#92](https://github.com/cyanheads/mcp-ts-core/issues/92))
 

package/dist/mcp-server/resources/utils/resourceHandlerFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resourceHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/resourceHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,SAAS,EACV,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oDAAoD,CAAC;AAWhG,gEAAgE;AAChE,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAiBrE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnC,kBAAkB,CAAC,UAAU,CAAC,CAShC;AAkBD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,qBAAqB,EAC1B,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,eAAe,GACzB,CACD,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,kBAAkB,GAAG,mBAAmB,CAAC,CAsErD"}
+{"version":3,"file":"resourceHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/resourceHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,SAAS,EACV,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oDAAoD,CAAC;AAWhG,gEAAgE;AAChE,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAiBrE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnC,kBAAkB,CAAC,UAAU,CAAC,CAShC;AAkBD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,qBAAqB,EAC1B,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,eAAe,GACzB,CACD,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,kBAAkB,GAAG,mBAAmB,CAAC,CA6ErD"}

package/dist/mcp-server/resources/utils/resourceHandlerFactory.js

@@ -7,7 +7,7 @@ import { buildHandlerContext, handlerParentContext, resolveHandlerRequest, } fro
 import { isInputRequiredSignal } from '../../inputRequired.js';
 import { withRequiredScopes } from '../../transports/auth/lib/authUtils.js';
 import { McpError } from '../../../types-global/errors.js';
-import { ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
+import { asRequestCancelled, ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
 import { measureResourceExecution } from '../../../utils/internal/performance.js';
 import { requestContextService } from '../../../utils/internal/requestContext.js';
 // ---------------------------------------------------------------------------
@@ -94,14 +94,22 @@ export function createResourceHandler(def, services, notifiers) {
             // the handler returned recorded those as successes (#346).
             return await measureResourceExecution(async (spanContext, recordOutput) => {
                 const ctx = buildHandlerContext(request, services, spanContext, def.errors, uri);
-                // Handler may return sync or async.
-                const handlerResult = await def.handler(validatedParams, ctx);
-                // The domain value is what `mcp.resource.output_bytes` measures — not
-                // the assembled `contents` this callback returns.
-                recordOutput(handlerResult);
-                // Validate output against schema when defined
-                const validatedResult = def.output ? def.output.parse(handlerResult) : handlerResult;
-                return { contents: formatter(validatedResult, { uri, mimeType }) };
+                try {
+                    // Handler may return sync or async.
+                    const handlerResult = await def.handler(validatedParams, ctx);
+                    // The domain value is what `mcp.resource.output_bytes` measures — not
+                    // the assembled `contents` this callback returns.
+                    recordOutput(handlerResult);
+                    // Validate output against schema when defined
+                    const validatedResult = def.output ? def.output.parse(handlerResult) : handlerResult;
+                    return { contents: formatter(validatedResult, { uri, mimeType }) };
+                }
+                catch (error) {
+                    // Inside the measurement on purpose: the completion log's
+                    // `metrics.errorCode` and the span's error-code attribute are
+                    // derived from what leaves this callback (#421).
+                    throw asRequestCancelled(error, request.signal);
+                }
             }, { ...appContext, resourceName }, { uri: resourceUri, mimeType });
         }
         catch (error) {

package/dist/mcp-server/resources/utils/resourceHandlerFactory.js.map

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

package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts

@@ -4,7 +4,7 @@
  * @module src/mcp-server/tools/utils/toolHandlerFactory
  */
 import type { CallToolResult, ContentBlock, InputRequiredResult, ServerContext } from '@modelcontextprotocol/server';
-import { ZodError, type ZodObject, type ZodRawShape } from 'zod';
+import { ZodError, type ZodObject, type ZodRawShape, z } from 'zod';
 import type { Context } from '../../../core/context.js';
 import { type HandlerServices } from '../../handlerContext.js';
 import type { NotifierSources } from '../../notifications.js';
@@ -45,8 +45,28 @@ export declare function buildToolErrorResult(code: JsonRpcErrorCode, message: st
  * is unchanged for clients that read `content[]` text. The framework owns this
  * rejection (see `deferInputValidation`) purely so it can also carry
  * `structuredContent.error`.
+ *
+ * `args` are the caller's raw arguments, read only through
+ * {@link readArgumentAt}; see {@link renderIssueMessage} for what that decides.
+ */
+export declare function formatInputValidationMessage(toolName: string, error: ZodError, args: unknown): string;
+/**
+ * Validates raw tool arguments against the definition's `input` schema, or
+ * throws the rejection a client receives on the wire: `InvalidParams`
+ * (`-32602`), the message {@link formatInputValidationMessage} renders, the Zod
+ * issues as `data.issues`, and — as with any other declared failure —
+ * `data.reason` plus a `data.recovery.hint` {@link buildArgumentRecoveryHint}
+ * synthesizes (#445). {@link buildToolErrorResult} mirrors that hint into
+ * `content[]`, so it reaches format()-only clients with no extra work.
+ *
+ * The single argument-rejection path. {@link createToolHandler} and the
+ * `runToolContract` test helper both route through it, so a test written to
+ * the helper pins the code, message, and `content[]` text a deployment
+ * actually produces (#416). Anything that classifies a `ZodError` as
+ * `ValidationError` — a handler's own validation, the output-schema parse —
+ * is a different failure and does not come through here.
  */
-export declare function formatInputValidationMessage(toolName: string, error: ZodError): string;
+export declare function parseToolArguments<TDefinition extends AnyToolDefinition>(def: TDefinition, input: unknown): z.infer<TDefinition['input']>;
 /**
  * Builds an error `CallToolResult` from a raw thrown value. Classifies via
  * {@link ErrorHandler.classifyOnly} when the value isn't already an

package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACd,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAmB,MAAM,KAAK,CAAC;AAElF,OAAO,KAAK,EAAE,OAAO,EAAmB,MAAM,mBAAmB,CAAC;AAElE,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,EAAiB,gBAAgB,EAAY,MAAM,0BAA0B,CAAC;AAKrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,oEAAoE;AACpE,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAUrE;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,GAAG,EAAE,OAAO,GACX,YAAY,EAAE,CAahB;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACxC,cAAc,CAchB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,CAStF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAO9E;AAMD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAGpF;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAkCrF;AA0GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,iBAAiB,EACtB,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,aAAa,EAAE,YAAY,EAAE,GAC5B,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,mBAAmB,CAAC,CAkBvD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,eAAe,GACzB,CACD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,cAAc,GAAG,mBAAmB,CAAC,CAoFjD"}
+{"version":3,"file":"toolHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACd,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAgB,CAAC,EAAE,MAAM,KAAK,CAAC;AAElF,OAAO,KAAK,EAAE,OAAO,EAAmB,MAAM,mBAAmB,CAAC;AAElE,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,EAAiB,gBAAgB,EAAY,MAAM,0BAA0B,CAAC;AAMrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,oEAAoE;AACpE,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAUrE;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,GAAG,EAAE,OAAO,GACX,YAAY,EAAE,CAahB;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACxC,cAAc,CAchB;AAgGD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,QAAQ,EACf,IAAI,EAAE,OAAO,GACZ,MAAM,CAQR;AA0FD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,SAAS,iBAAiB,EACtE,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,OAAO,GACb,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAc/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAO9E;AAMD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAGpF;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAkCrF;AA0GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,iBAAiB,EACtB,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,aAAa,EAAE,YAAY,EAAE,GAC5B,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,mBAAmB,CAAC,CAkBvD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,eAAe,GACzB,CACD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,cAAc,GAAG,mBAAmB,CAAC,CAmFjD"}