@cyanheads/mcp-ts-core 0.13.5 → 0.13.6

package/framework-skills/add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
 metadata:
   author: cyanheads
-  version: "1.10"
+  version: "1.11"
   audience: external
   type: reference
 ---
@@ -234,10 +234,13 @@ Services don't declare `errors: [...]` contracts and don't have `ctx.fail` — t
 - **Carry contract `reason` via `data: { reason }`** when the calling tool declares an `errors[]` contract entry for this failure mode. Services can't call `ctx.fail`, but passing the reason in `data` flows through the auto-classifier untouched, so clients see the same `error.data.reason` they'd see from `ctx.fail` — no handler-side catch-and-rethrow needed:
 
   ```ts
-  // tool declares: errors: [{ reason: 'empty_expression', code: JsonRpcErrorCode.ValidationError, when: '…', recovery: '…' }]
+  // tool declares: errors: [{ reason: 'empty_expression', code: JsonRpcErrorCode.ValidationError,
+  //                           when: '…', recovery: '…', thrownBy: 'service' }]
   throw validationError('Expression cannot be empty.', { reason: 'empty_expression' });
   ```
 
+  The tool's entry carries `thrownBy: 'service'` so `error-contract-unthrown` — which reads the handler body and cannot see this throw — skips it while still checking whatever the handler throws itself. Lint-only metadata; nothing at runtime reads it.
+
 - **Resolve contract `recovery` via `ctx.recoveryFor`** to land the contract's recovery hint on the wire without duplicating the string. Always-present on `Context`, returns `{}` when the calling tool has no matching reason — spread-safe regardless:
 
   ```ts

package/framework-skills/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "2.28"
+  version: "2.29"
   audience: external
   type: reference
 ---
@@ -719,6 +719,8 @@ export const fetchArticles = tool('fetch_articles', {
 
 `ctx.recoveryFor` returns `{}` when the calling tool has no contract or the reason isn't declared, so the spread is always safe — services don't have to know which tool called them.
 
+Add `thrownBy: 'service'` to a contract entry the service produces once the handler also throws one of its own. `error-contract-unthrown` reads the handler body alone: as soon as one literal `ctx.fail(` appears there, every declared reason the body does not name is flagged, and the marker is what tells the rule this one is thrown a layer down. Lint-only metadata — the entry stays typed, advertised, and thrown exactly as an unmarked one.
+
 See `add-service` for the full pattern.
 
 #### Ad-hoc factory throws (fallback)
@@ -860,7 +862,7 @@ return { items: hits };
 - [ ] Optional nested objects guarded for empty inner values from form-based clients (check `?.field` truthiness, not just object presence)
 - [ ] No `console` calls — use `ctx.log` for handler logging
 - [ ] `handler(input, ctx)` is pure — throws on failure, no try/catch (exception: batch tools with per-item isolation use try/catch inside the loop — that's intentional, don't remove it)
-- [ ] `format()` renders every field in the output schema — enforced at lint time via sentinel injection, startup fails with `format-parity` errors otherwise. Different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data. Primary fix: render the missing field in `format()` (use `z.discriminatedUnion` for list/detail variants). Escape hatch: if the output schema was over-typed for a genuinely dynamic upstream API, relax it (`z.object({}).passthrough()`) rather than maintaining aspirational typing
+- [ ] `format()` renders every field in the output schema — enforced at lint time via sentinel injection, startup fails with `format-parity` errors otherwise. Different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data. Primary fix: render the missing field in `format()` (for list/detail variants, one flat `z.object` with a `kind` discriminator and presence-based optional arms rendered by independent `if` blocks — `tool()` rejects a `z.discriminatedUnion` output). Escape hatch: if the output schema was over-typed for a genuinely dynamic upstream API, relax it (`z.object({}).passthrough()`) rather than maintaining aspirational typing
 - [ ] Agent-facing context (empty-result notices, query/filter echo, pagination totals) declared in an `enrichment` block and populated via `ctx.enrich(...)` — reaches both `structuredContent` and `content[]` automatically, not authored solely in `format()` text. Enrichment keys disjoint from `output` keys
 - [ ] If wrapping external API: output schema and `format()` preserve uncertainty from sparse upstream payloads instead of inventing concrete values, and a parsed `NaN`/`null` is dropped at the parse site rather than passed to a required output field
 - [ ] `auth` scopes declared if the tool needs authorization

package/framework-skills/api-errors/SKILL.md

@@ -4,7 +4,7 @@ description: >
   McpError constructor, JsonRpcErrorCode reference, and error handling patterns for `@cyanheads/mcp-ts-core`. Use when looking up error codes, understanding where errors should be thrown vs. caught, or using ErrorHandler.tryCatch in services.
 metadata:
   author: cyanheads
-  version: "1.14"
+  version: "1.15"
   audience: external
   type: reference
 ---
@@ -65,7 +65,7 @@ export const fetchTool = tool('fetch_articles', {
 | Compile time | `ctx.fail('typo')` is a TS error. Auto-completes declared reasons. |
 | Runtime | `ctx.fail(reason, msg?, data?, options?)` builds an `McpError(contract.code, msg, { ...data, reason }, options)` — `data.reason` is auto-populated from the contract and cannot be overridden by caller-supplied data (spread first, then `reason` written last), so observers see a stable identifier. `options` accepts `{ cause }` for ES2022 error chaining. |
 | Lint (devcheck) | Each `code` validated against `JsonRpcErrorCode`. Reasons validated as snake_case + unique within contract. `recovery` validated as non-empty and ≥ 5 words. Build-time only — not invoked at server startup. |
-| Lint (conformance) | If the handler `throw new McpError(JsonRpcErrorCode.X)` outside `ctx.fail`, conformance check warns when X isn't declared. The inverse is checked too: a declared reason no `ctx.fail` in the handler names warns as `error-contract-unthrown`. |
+| Lint (conformance) | If the handler `throw new McpError(JsonRpcErrorCode.X)` outside `ctx.fail`, conformance check warns when X isn't declared. The inverse is checked too: a declared reason no `ctx.fail` in the handler names warns as `error-contract-unthrown` (mark it `thrownBy: 'service'` when the service layer produces it), and a `ctx.fail` site that never forwards the declared `recovery` warns as `error-contract-recovery-unforwarded`. |
 
 > **`recovery` is opt-in resolution, not auto-population.** The contract `recovery` is required metadata documenting the agent's next move when this failure mode fires (a forcing function for thoughtful guidance — placeholders like "Try again." get flagged by the linter). It does **not** automatically appear in runtime `data.recovery.hint` — the framework never injects it without an explicit signal at the throw site. Authors opt in by spreading `ctx.recoveryFor('reason')` into the `data` argument, the same way `ctx.fail('reason')` opts into resolving the contract `code`. What the author types at the throw site is what flows to the wire, with no hidden transformation; the resolver is just a typed lookup keyed by the same `reason` the author already typed.
 
@@ -73,6 +73,8 @@ export const fetchTool = tool('fetch_articles', {
 
 `ctx.recoveryFor(reason)` returns `{ recovery: { hint: <contract.recovery> } }` for a declared reason, ready to spread into `data`. Always available on `Context` (returns `{}` when no contract is attached or the reason is unknown — spread-safe with no optional chaining). On `HandlerContext<R>` it tightens to a typed signature constrained to the declared reason union.
 
+Spreading it into the data object and passing it as the data argument are the same call — `ctx.fail` spreads whatever `data` it receives. Spread when the site carries other keys, pass it directly when it carries nothing else. **Forwarding is lint-enforced per throw site:** a `ctx.fail` site that carries neither the resolver nor its own `recovery` key warns as `error-contract-recovery-unforwarded`, because the declared hint then reaches neither client surface and an error-path test asserting `code` and `reason` still passes.
+
 ```ts
 export const calculateTool = tool('calculate', {
   // ...
@@ -173,6 +175,19 @@ errors: [
 
 The handler doesn't catch and re-throw — letting service errors bubble unchanged keeps "logic throws, framework catches" intact. The wire payload still carries `code` + `data.reason`, and clients can switch on reason without parsing message text. What's lost is lint-time enforcement that every reason is reachable; compensate with one wire-shape test per reason.
 
+**Mark the entries the service produces.** `error-contract-unthrown` reads the handler body alone, so in a handler that mixes one local precondition with service-thrown reasons it flags each service reason as dead. Add `thrownBy: 'service'` to those entries:
+
+```ts
+errors: [
+  { reason: 'empty_expression',   code: JsonRpcErrorCode.ValidationError,
+    when: 'Input is empty.',
+    recovery: 'Provide a non-empty expression to evaluate.',
+    thrownBy: 'service' },
+]
+```
+
+The field is lint-only metadata — nothing at runtime reads it, so the entry is typed, advertised, and thrown exactly as an unmarked one, and its reason stays in the `ctx.fail` / `ctx.recoveryFor` union. It suppresses the one rule that cannot see below the handler, and only for the entries it marks; the handler's own reasons keep being checked.
+
 To carry the contract `recovery` from a service throw, accept `ctx` and spread the resolver:
 
 ```ts
@@ -544,7 +559,8 @@ The linter validates the structure of `errors[]` and (when present) cross-checks
 |:-----|:---------|:--------|
 | `error-contract-conformance` | warning | Handler throws a non-baseline code that isn't in the contract. Suggests adding it to `errors[]` so the contract is the canonical source of truth for declared failure modes. |
 | `error-contract-prefer-fail` | warning | Handler throws a code that **is** in the contract directly (via factory or `new McpError`) instead of through `ctx.fail(reason, …)`. Encourages routing through the typed helper so observers see consistent `data.reason` values. |
-| `error-contract-unthrown` | warning | A declared `reason` that no literal `ctx.fail('<reason>'` or `ctx.recoveryFor('<reason>'` in the handler names. Fires only when the handler already holds at least one literal `ctx.fail(`, and skips the definition entirely when any of them takes a non-literal first argument. Wire the throw, or drop the entry. |
+| `error-contract-unthrown` | warning | A declared `reason` that no literal `ctx.fail('<reason>'` or `ctx.recoveryFor('<reason>'` in the handler names. Fires only when the handler already holds at least one literal `ctx.fail(`, and skips the definition entirely when either callee takes a non-literal first argument. Wire the throw, drop the entry, or mark it `thrownBy: 'service'`. |
+| `error-contract-recovery-unforwarded` | warning | A literal `ctx.fail('<reason>', …)` site carrying neither `ctx.recoveryFor('<reason>')` nor its own `recovery` key, so the declared hint reaches neither client surface. One diagnostic per site; skips a site whose data argument the scan cannot read. |
 
 ### Baseline codes (auto-allowed)
 

package/framework-skills/api-linter/SKILL.md

@@ -4,7 +4,7 @@ description: >
   MCP definition linter rules reference. Use when `bun run lint:mcp` or `bun run devcheck` reports a lint error or warning (`format-parity`, `schema-is-object`, `name-format`, `server-json-*`, etc.) and you need to understand the rule, its severity, and how to fix it. Every rule ID the linter emits has an entry in this doc.
 metadata:
   author: cyanheads
-  version: "1.16"
+  version: "1.17"
   audience: external
   type: reference
 ---
@@ -53,7 +53,7 @@ Grouped by family. Jump to any rule ID via its anchor.
 | Prompts | `generate-required` | [Prompt rules](#prompt-rules) |
 | Handler body | `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error` | [Handler body rules](#handler-body-rules) |
 | Error contract (structural) | `error-contract-type`, `error-contract-empty`, `error-contract-entry-type`, `error-contract-code-type`, `error-contract-code-unknown`, `error-contract-code-unknown-error`, `error-contract-reason-required`, `error-contract-reason-format`, `error-contract-reason-unique`, `error-contract-when-required`, `error-contract-retryable-type`, `error-contract-severity-unknown`, `error-contract-recovery-required`, `error-contract-recovery-empty`, `error-contract-recovery-min-words` | [Error contract rules](#error-contract-rules) |
-| Error contract (conformance) | `error-contract-conformance`, `error-contract-prefer-fail`, `error-contract-unthrown` | [Error contract rules](#error-contract-rules) |
+| Error contract (conformance) | `error-contract-conformance`, `error-contract-prefer-fail`, `error-contract-unthrown`, `error-contract-recovery-unforwarded` | [Error contract rules](#error-contract-rules) |
 | Enrichment | `enrichment-type`, `enrichment-empty`, `enrichment-field-type`, `enrichment-output-collision`, `enrichment-prefer-block`, `enrichment-trailer-render`, `enrichment-trailer-orphan`, `enrichment-trailer-unknown-field`, `capped-list-no-truncation` | [Enrichment rules](#enrichment-rules) |
 | server.json | ~40 rules prefixed `server-json-*` | [server.json rules](#server-json-rules) |
 
@@ -94,20 +94,27 @@ Two consequences worth knowing when writing a `format()`:
 
 Fires when `format()` does not render a field present in `output`. Emitted once per missing field; large schemas can produce many `format-parity` diagnostics from a single tool.
 
-**Primary fix:** render the missing field in `format()`. For tools that return either a summary list or a detail view, use `z.discriminatedUnion` so each branch is walked separately:
+**Primary fix:** render the missing field in `format()`. For tools that return either a summary list or a detail view, declare **one flat `z.object`** with a `kind` discriminator and presence-based optional arms — `tool()` rejects a `z.discriminatedUnion` output root, and it does so before any lint rule runs, with a `TypeError` naming a field you never declared. Render each arm on presence, with **independent `if` blocks, never `else if`**: a flat object yields one synthetic sample with every arm populated at once, so a mutually exclusive formatter leaves the untaken arm's leaves unrendered and fails parity on each of them.
 
 ```ts
-output: z.discriminatedUnion('mode', [
-  z.object({ mode: z.literal('list'), items: z.array(ItemSchema) }),
-  z.object({ mode: z.literal('detail'), item: ItemSchema, history: z.array(HistoryEntry) }),
-]),
+output: z.object({
+  kind: z.enum(['list', 'detail']).describe('Which arm this result carries'),
+  items: z.array(ItemSchema).optional().describe('Matching items — present when kind is "list"'),
+  item: ItemSchema.optional().describe('The item — present when kind is "detail"'),
+  history: z.array(HistoryEntry).optional().describe('Change history — present when kind is "detail"'),
+}),
 
 format: (result) => {
-  if (result.mode === 'list') return renderList(result.items);
-  return renderDetail(result.item, result.history);
+  const lines = [`Kind: ${result.kind}`];
+  if (result.items) for (const i of result.items) lines.push(`- ${i.id} — ${i.name}`);
+  if (result.item) lines.push(`Item: ${result.item.id} — ${result.item.name}`);
+  if (result.history) for (const h of result.history) lines.push(`  ${h.at}: ${h.note}`);
+  return [{ type: 'text', text: lines.join('\n') }];
 }
 ```
 
+A union nested *below* the root is fine — the walker does produce one sample per branch there. The constraint is the output root alone.
+
 **Escape hatch:** if the output schema was over-typed for a genuinely dynamic upstream API (e.g., a third-party JSON blob whose shape you can't nail down), relax it:
 
 ```ts
@@ -146,6 +153,8 @@ Fires when the linter cannot walk the output schema to build a synthetic sample
 
 Fires when an output field is nested deeper than the sentinel walker's depth limit (8). Everything at and below that path was **not evaluated** — parity for the subtree is unknown, not verified. Four array hops from the output root is enough to reach the limit, so it turns up on ordinary shapes, not just pathological ones.
 
+**A hop is not a path segment.** The walker counts every descent, and a `union` / `discriminated_union` dispatch descends into each branch at `depth + 1` while keeping the parent's path unchanged. So a union nested in the output shape spends a level that the reported path never shows, and a warned path can read as exactly 8 hops rather than 9. Count the unions when you are working out which field to flatten.
+
 The bound exists because every array / union / record hop multiplies the variant set, and a self-referential schema would otherwise recurse forever. What changed is the reporting: an unevaluated subtree used to be indistinguishable from a field that resolved to nothing, so it read as a pass.
 
 **Fix:** flatten the output shape so the field sits within the limit, or verify by hand that `format()` renders it (and treat the warning as the standing reminder that the linter is not covering it).
@@ -891,7 +900,7 @@ The inverse of `error-contract-conformance`. Fires when a declared `reason` has
 
 A dead entry compiles and lints clean: the typed `ctx.fail` union accepts the reason, so nothing downstream objects. The cost lands on the client, which plans around the advertised failure surface — an agent prepares for a mode the tool cannot produce, while the mode it *does* produce goes undocumented.
 
-**Fix:** wire the missing throw, or drop the entry. Which one is right is the author's call, so the rule surfaces and does not auto-remove.
+**Fix:** wire the missing throw, drop the entry, or — when the service layer produces the failure — mark the entry `thrownBy: 'service'`. Which one is right is the author's call, so the rule surfaces and does not auto-remove.
 
 ```ts
 errors: [
@@ -904,9 +913,51 @@ async handler(input, ctx) {
 // warning  error-contract-unthrown — 'site_not_found' is declared but never thrown.
 ```
 
-**Trigger.** Only when the handler holds at least one literal `ctx.fail(`. A handler with none produces its reasons somewhere the scan cannot reach, so firing there would warn on every service-layer definition. A `ctx.fail(` whose first argument is not a string literal — a variable, a template literal, a map lookup — makes the thrown set unknowable, and the whole definition is skipped rather than guessed at.
+**`thrownBy: 'service'`.** A handler that mixes one local precondition with reasons its service layer throws — the factory-error-plus-`data: { reason }` pattern — draws one diagnostic per service reason, since the scan sees only the handler body. Mark those entries and they are skipped while the handler's own reasons keep being checked:
+
+```ts
+errors: [
+  { reason: 'query_too_broad', code: JsonRpcErrorCode.ValidationError, when: '…', recovery: '…' },
+  { reason: 'item_not_found',  code: JsonRpcErrorCode.NotFound,        when: '…', recovery: '…',
+    thrownBy: 'service' },
+],
+async handler(input, ctx) {
+  if (input.query === '*') throw ctx.fail('query_too_broad', 'Wildcard query');
+  return getItemService().search(input, ctx);   // throws item_not_found
+}
+```
+
+The field is lint-only metadata: `ctx.fail`, `ctx.recoveryFor`, the `severity` lookup, and the advertised error envelope never read it, so a marked entry is typed, advertised, and thrown exactly as an unmarked one. Prefer it over the workarounds that also silence the rule — moving the literal `ctx.fail` into a module-level helper turns the whole tool off, handler-local reasons included.
+
+**Trigger.** Only when the handler holds at least one literal `ctx.fail(`. A handler with none produces its reasons somewhere the scan cannot reach, so firing there would warn on every service-layer definition. A `ctx.fail(` or `ctx.recoveryFor(` whose first argument is not a string literal — a variable, a template literal, a map lookup — makes the named set unknowable, and the whole definition is skipped rather than guessed at.
+
+**Heuristic limitations:** the scan reads `handler.toString()` and matches call sites in the comment- and string-stripped text, so a `ctx.fail('…')` written inside a comment or nested in another literal does not count as thrown. A reason produced outside the handler closure is invisible to any `toString()` scan, which is why the rule can never prove absence and stays a warning. Still silent without a marker: a `createFail(errors)` resolver built outside the handler, and an aliased `const fail = ctx.fail`.
+
+### error-contract-recovery-unforwarded
+
+**Severity:** warning
+
+Fires per literal `ctx.fail('<reason>', …)` site that does not put the contract's `recovery` on the wire.
+
+`recovery` is required on every `errors[]` entry, but reaching the client with it is opt-in — the throw site forwards `ctx.recoveryFor('<reason>')`, or passes its own `recovery` key. A site that does neither ships `reason` and `retryable` with no hint, and since the framework mirrors `data.recovery.hint` into the error `content[]`, both client surfaces lose it together. Nothing else catches this: the contract is declared, `lint:mcp` passes, and an error-path test asserting `code` and `reason` passes with the hint absent.
 
-**Heuristic limitations:** the scan reads `handler.toString()` and matches call sites in the comment- and string-stripped text, so a `ctx.fail('…')` written inside a comment or nested in another literal does not count as thrown. A reason produced outside the handler closure is invisible to any `toString()` scan, which is why the rule can never prove absence and stays a warning. Silent under the trigger above: a service that throws a factory error carrying `data: { reason }`, a `createFail(errors)` resolver built outside the handler, and an aliased `const fail = ctx.fail`.
+**Fix:** forward the resolver at the site named in the diagnostic.
+
+```ts
+// warns
+throw ctx.fail('rate_limited', 'Upstream rate limit exceeded');
+
+// clean — any of
+throw ctx.fail('rate_limited', msg, { ...ctx.recoveryFor('rate_limited') });
+throw ctx.fail('rate_limited', msg, ctx.recoveryFor('rate_limited'));
+throw ctx.fail('rate_limited', msg, { recovery: { hint: `Retry in ${waitSeconds}s.` } });
+```
+
+**Per site, not per reason.** A handler wiring one of six throws is covered at one of them, so each site is judged on its own argument list. Two sites naming one reason, one forwarding and one bare, produce exactly one diagnostic. A site whose only resolver names a *different* reason warns too, naming both — the caller would otherwise get another failure mode's guidance.
+
+**Bails.** A non-literal first argument on either `ctx.fail(` or `ctx.recoveryFor(` skips the whole definition, as it does for `error-contract-unthrown`. A resolver sitting outside every fail span — a hoisted `const hint = ctx.recoveryFor('x')` — skips that reason, since the binding is assembled where the scan cannot follow it. A data argument the scan cannot read skips that one site: an identifier (`ctx.fail('r', msg, data)`), a call other than the resolver, or an object literal spreading another value (`{ ...details }`), any of which may carry `recovery` already. An object literal of plain keys carrying no `recovery` still warns.
+
+**Heuristic limitations:** same `handler.toString()` scan as `error-contract-unthrown`, so a call written inside a comment or nested in another literal is not a site, and a failure thrown below the handler is invisible. The rule speaks only for the sites it sees, which is why it stays a warning.
 
 ---
 
@@ -985,7 +1036,8 @@ Fires when an `enrichmentTrailer` key doesn't match any declared `enrichment` fi
 Fires when a tool:
 1. has a depth-0 input field whose name is cap-*shaped*, AND
 2. has at least one depth-0 array-typed `output` field, AND
-3. declares no truncation disclosure.
+3. the cap plausibly bounds that list, AND
+4. declares no truncation disclosure.
 
 Cap-shaped means, after normalizing camelCase to snake_case (so `maxRecords` and `max_records` are one case):
 
@@ -997,7 +1049,14 @@ Cap-shaped means, after normalizing camelCase to snake_case (so `maxRecords` and
 
 Matched by shape rather than an enumerated list, so a new cap noun is covered on arrival instead of silently disabling the rule for that tool. Deliberately not matched: bare `count`, `size`, `n`, `rows`, `records`, and words that merely begin with the letters (`maximum`).
 
-The shape does not distinguish a cap on *how many* from an upper bound on a *value*, so a range filter written as `max_<noun>` — `max_magnitude`, `max_depth_km`, `maxLat`, `max_date` — matches too. On a tool that also returns an array and discloses nothing, that reads as a warning about truncation the tool does not perform. Disclose `totalCount` if the array is paged at all (which silences it honestly), or exempt the tool via `truncationAllowlist` / `MCP_LINT_TRUNCATION_ALLOWLIST`.
+**The `max_` arm is narrowed by what the noun counts.** `limit`, `<noun>_limit`, and the page-size idioms say what they bound in the name, so they always qualify. `max_<noun>` does not — the same spelling carries value bounds (`max_depth_km`, `maxLat`, `max_date`, `max_magnitude`) and budgets on secondary work (`max_court_lookups`, `maxCharacters`, `max_tokens`), none of which slice the array. So the counted noun has to name something the tool returns:
+
+- **it correlates with a depth-0 array in `output`** — plural-insensitive, with a trailing `_count` stripped first: `max_articles` → `articles`, `max_result_count` → `results`, `maxComments` → `comments`; or
+- **it is a generic result container** — `results`, `records`, `items`, `rows`, `hits`, `entries`, `matches`, `count`, `page`, `docs` — which keeps `maxRecords` firing against an `articles` array whatever the domain called its list.
+
+Singularization covers only the bounded suffixes above (`ies` → `y`, `ses`/`xes`/`ches`/`shes`, trailing `s`); it is not a general English pluralizer.
+
+**Accepted false negative:** a domain cap naming neither an array nor a container — `max_studies` returning `documents` — goes silent. Nothing in the declaration separates it from a value bound, and the allowlist only suppresses, so it cannot bring the warning back. Declaring `truncated` / `totalCount` is the outcome the rule is chasing anyway.
 
 **Disclosure-present (rule silent) when** any of the following is true:
 - The declared `enrichment` shape has a `truncated` or `totalCount` key (`ctx.enrich.truncated()` and `ctx.enrich.total()` satisfy this).
@@ -1039,7 +1098,21 @@ validateDefinitions({ tools, truncationAllowlist: ['my_search_tool'] });
 validateDefinitions({ tools, truncationAllowlist: false });
 ```
 
-**Env var:** `MCP_LINT_TRUNCATION_ALLOWLIST` — comma-separated tool names; the literal `false` disables. A programmatic `LintInput.truncationAllowlist` takes precedence.
+**Project config:** `scripts/lint-mcp.ts` — the CLI behind `bun run lint:mcp` and devcheck's MCP Definitions step — reads `lint.truncationAllowlist` from the project's `devcheck.config.json` and forwards it as `LintInput.truncationAllowlist`. One declaration covers every entrypoint that shells out to the linter, and it survives framework sync (the script itself does not — a scaffold's copy is replaced on the next maintenance pass).
+
+```json
+{
+  "lint": {
+    "truncationAllowlist": ["my_search_tool"]
+  }
+}
+```
+
+`"truncationAllowlist": false` disables the rule, matching the `LintInput` and env-var forms. The file is parsed with `JSON.parse`, so the key takes no inline comment; a value that is neither `false` nor an array of tool names is reported and ignored.
+
+**Env var:** `MCP_LINT_TRUNCATION_ALLOWLIST` — comma-separated tool names; the literal `false` disables.
+
+**Precedence:** an explicit `LintInput.truncationAllowlist` wins, then `devcheck.config.json`, then the env var. A config file that declares no `truncationAllowlist` passes nothing through, so the env var still applies — the var is the escape hatch for a project that declares nothing, not an override for one that does.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.13.5",
+  "version": "0.13.6",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for MCP servers. Includes runtime infrastructure and agent skills for building, testing, and shipping servers.",
   "files": [
@@ -197,7 +197,7 @@
     "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.13",
+    "@biomejs/biome": "2.5.14",
     "@cloudflare/vitest-pool-workers": "^0.22.0",
     "@cloudflare/workers-types": "5.20260910.1",
     "@duckdb/node-api": "^1.5.5-r.5",
@@ -228,7 +228,7 @@
     "depcheck": "^1.4.7",
     "diff": "^9.0.0",
     "execa": "^10.0.1",
-    "fast-check": "^4.10.0",
+    "fast-check": "^4.10.1",
     "fast-xml-parser": "^5.11.1",
     "ignore": "^7.0.9",
     "js-yaml": "^5.4.2",

package/scripts/lint-mcp.ts

@@ -14,10 +14,14 @@
  *
  * Runtime-agnostic: works with bun, tsx, and Node.js (via ts-node/esm).
  *
+ * Rule knobs come from the project's `devcheck.config.json` `lint` block, so one
+ * declaration covers every entrypoint that shells out to this script.
+ *
  * @module scripts/lint-mcp
  */
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 // ---------------------------------------------------------------------------
 // Import validateDefinitions — resolve from package or local source
@@ -111,6 +115,38 @@ function tryReadJson(path: string): unknown {
   }
 }
 
+/** The `lint` block of `devcheck.config.json`, as far as this script reads it. */
+interface LintConfig {
+  lint?: { truncationAllowlist?: unknown };
+}
+
+/** The `LintInput` knobs a project declares in `devcheck.config.json`. */
+export interface LintOptions {
+  truncationAllowlist?: ReadonlyArray<string> | false;
+}
+
+/**
+ * Reads `lint.truncationAllowlist` from the project's `devcheck.config.json`.
+ *
+ * An absent or unreadable key yields `{}`, which leaves `validateDefinitions()`
+ * to fall back to `MCP_LINT_TRUNCATION_ALLOWLIST`. A declared value is passed as
+ * `LintInput.truncationAllowlist` and therefore wins over that env var — a
+ * reviewed, version-controlled exemption is not something ambient environment
+ * should override.
+ */
+export function readLintOptions(configPath = resolve('devcheck.config.json')): LintOptions {
+  const allowlist = (tryReadJson(configPath) as LintConfig | undefined)?.lint?.truncationAllowlist;
+  if (allowlist === undefined) return {};
+  if (allowlist === false) return { truncationAllowlist: false };
+  if (Array.isArray(allowlist) && allowlist.every((name) => typeof name === 'string')) {
+    return { truncationAllowlist: allowlist as string[] };
+  }
+  console.warn(
+    `Warning: ${configPath} "lint.truncationAllowlist" must be an array of tool names or false — ignoring it.`,
+  );
+  return {};
+}
+
 async function main(): Promise<void> {
   const files = discoverFiles();
 
@@ -163,6 +199,7 @@ async function main(): Promise<void> {
     prompts,
     serverJson,
     ...(packageJson ? { packageJson } : {}),
+    ...readLintOptions(),
   });
 
   for (const w of report.warnings) {
@@ -187,7 +224,9 @@ async function main(): Promise<void> {
   }
 }
 
-main().catch((err) => {
-  console.error('lint-mcp failed:', err);
-  process.exit(1);
-});
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main().catch((err) => {
+    console.error('lint-mcp failed:', err);
+    process.exit(1);
+  });
+}

package/templates/AGENTS.md

@@ -214,7 +214,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 (≥ 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 unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';

package/templates/CLAUDE.md

@@ -214,7 +214,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 (≥ 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 unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';

package/templates/devcheck.config.json

@@ -14,6 +14,7 @@
   "outdated": {
     "allowlist": []
   },
+  "lint": {},
   "packaging": {
     "pluginManifests": true
   }

package/templates/package.json

@@ -66,7 +66,7 @@
     "zod": "{{ZOD_VERSION}}"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.13",
+    "@biomejs/biome": "2.5.14",
     "@socketsecurity/bun-security-scanner": "^1.1.2",
     "@types/node": "26.5.1",
     "@vitest/coverage-istanbul": "4.1.11",

package/templates/src/mcp-server/tools/definitions/echo.tool.ts

@@ -42,7 +42,13 @@ export const echoTool = tool('template_echo_message', {
 
   handler(input, ctx) {
     if (input.message.trim().length === 0) {
-      throw ctx.fail('empty_message', 'Message must contain at least one non-whitespace character.');
+      // Spreading ctx.recoveryFor puts the declared recovery on the wire. Without
+      // it the hint reaches neither structuredContent nor content[].
+      throw ctx.fail(
+        'empty_message',
+        'Message must contain at least one non-whitespace character.',
+        { ...ctx.recoveryFor('empty_message') },
+      );
     }
     // Reaches both client surfaces with no format() plumbing.
     ctx.enrich({ characterCount: input.message.length });