@cyanheads/mcp-ts-core 0.7.6 → 0.8.0

package/skills/api-context/SKILL.md

@@ -41,6 +41,10 @@ interface Context {
   readonly elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
   readonly sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
 
+  // Resource notifications — present when transport supports them
+  readonly notifyResourceListChanged?: () => void;
+  readonly notifyResourceUpdated?: (uri: string) => void;
+
   // Cancellation
   readonly signal: AbortSignal;
 
@@ -52,6 +56,8 @@ interface Context {
 }
 ```
 
+> **`ctx.fail` is on `HandlerContext<R>`, not `Context`.** When a definition declares `errors: [...]`, the handler receives `HandlerContext<R> = Context & { fail: TypedFail<R> }` — the typed `fail` lives on the intersection, not on bare `Context`. See [`ctx.fail`](#ctxfail) below.
+
 ### Identity fields
 
 | Field | Always present | Source |
@@ -223,7 +229,7 @@ if (ctx.sample) {
 interface SamplingOpts {
   includeContext?: 'none' | 'thisServer' | 'allServers';
   maxTokens?: number;
-  modelPreferences?: Record<string, unknown>;
+  modelPreferences?: ModelPreferences;
   stopSequences?: string[];
   temperature?: number;
 }
@@ -320,6 +326,71 @@ Prefer `params` (the extracted URI template variables) over parsing `ctx.uri` ma
 
 ---
 
+## `ctx.fail`
+
+Present only when the definition declares an `errors[]` contract. Builds an `McpError` keyed by the contract's `reason` union, so the resulting code is consistent with what the tool advertises in `tools/list`.
+
+```ts
+export const fetchItems = tool('fetch_items', {
+  description: 'Fetch items by ID.',
+  errors: [
+    { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No items matched' },
+    { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited, when: 'Local queue at capacity', retryable: true },
+  ],
+  input: z.object({ ids: z.array(z.string()).describe('Item IDs') }),
+  output: z.object({ items: z.array(ItemSchema).describe('Resolved items') }),
+  async handler(input, ctx) {
+    if (queue.full()) throw ctx.fail('queue_full');
+    const items = await fetch(input.ids);
+    if (items.length === 0) throw ctx.fail('no_match', `No items match ${input.ids.length} IDs`, { ids: input.ids });
+    // ctx.fail('typo')   ← TypeScript error: 'typo' isn't in the contract
+    return { items };
+  },
+});
+```
+
+### Signature
+
+```ts
+// TypedFail<R> — R is the union of declared `reason` strings, derived from the
+// definition's `errors: [...]` const tuple via the framework's `ReasonOf<E>`.
+ctx.fail(
+  reason: R,                         // union of declared reason strings
+  message?: string,                  // defaults to the contract entry's `when` text
+  data?: Record<string, unknown>,    // merged into err.data; cannot override `reason`
+  options?: { cause?: unknown },     // ES2022 cause chain
+): McpError
+```
+
+### Behavior
+
+| Aspect | Detail |
+|:-------|:-------|
+| Code resolution | `code` comes from the matching contract entry — never from the caller. The thrown `McpError.code` always equals what's advertised in `tools/list`. |
+| Default message | When `message` is omitted, the contract entry's `when` text is used. |
+| `data.reason` | Auto-populated from the contract entry. Caller-supplied `data.reason` **cannot** override it — the framework spreads caller data first and writes `reason` last so observers see a stable identifier. |
+| Cause chains | Pass `{ cause: e }` to preserve the original error — `pino-pretty` and observability platforms render the chain automatically. |
+| Unknown reason | If the type-system guard is bypassed (JS caller, stale contract), `ctx.fail` returns an `McpError(InternalError)` with `data.reason` and `data.declaredReasons` set so the bug is loud rather than silent. |
+
+### Without a contract
+
+When the definition has no `errors[]` field, `ctx` is plain `Context` and `ctx.fail` is absent. Throw `McpError` directly (or via factory):
+
+```ts
+import { notFound, rateLimited } from '@cyanheads/mcp-ts-core/errors';
+
+async handler(input, ctx) {
+  if (queue.full()) throw rateLimited('Queue at capacity');
+  const items = await fetch(input.ids);
+  if (items.length === 0) throw notFound(`No items match ${input.ids.length} IDs`);
+  return { items };
+}
+```
+
+The contract is opt-in. See `skills/api-errors/SKILL.md` for the full type-driven pattern, lint rules, and baseline-codes guidance.
+
+---
+
 ## Quick reference
 
 | Property | Type | Present when |
@@ -335,5 +406,8 @@ Prefer `params` (the extracted URI template variables) over parsing `ctx.uri` ma
 | `ctx.signal` | `AbortSignal` | Always |
 | `ctx.elicit` | `function \| undefined` | Client supports elicitation |
 | `ctx.sample` | `function \| undefined` | Client supports sampling |
+| `ctx.notifyResourceListChanged` | `function \| undefined` | Transport supports resource notifications |
+| `ctx.notifyResourceUpdated` | `function \| undefined` | Transport supports resource notifications |
 | `ctx.progress` | `ContextProgress \| undefined` | Tool defined with `task: true` |
 | `ctx.uri` | `URL \| undefined` | Resource handlers only |
+| `ctx.fail` | `(reason, msg?, data?, opts?) => McpError` | Definition declares `errors[]` contract |

package/skills/api-errors/SKILL.md

@@ -22,9 +22,58 @@ import { ErrorHandler } from '@cyanheads/mcp-ts-core/utils';
 
 ---
 
-## Error Factories (Preferred)
+## Type-Driven Error Contract (recommended)
 
-Shorter than `new McpError(...)` and self-documenting. All return `McpError` instances. All accept an optional `options` parameter for error chaining via `{ cause }`.
+The recommended path for new tools and resources. Declare failure modes as a const tuple under `errors`; the reason union flows into the handler's `ctx.fail` and TypeScript enforces that you can only fail with a declared reason:
+
+```ts
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+export const fetchTool = tool('fetch_articles', {
+  description: 'Fetch articles by PMID',
+  input: z.object({ pmids: z.array(z.string()).describe('PMIDs') }),
+  output: z.object({ articles: z.array(z.unknown()).describe('Articles') }),
+
+  errors: [
+    { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+      when: 'No requested PMID returned data' },
+    { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
+      when: 'Local request queue is at capacity', retryable: true },
+    { reason: 'ncbi_down', code: JsonRpcErrorCode.ServiceUnavailable,
+      when: 'NCBI E-utilities unreachable after retries', retryable: true },
+  ],
+
+  async handler(input, ctx) {
+    const articles = await ncbi.fetch(input.pmids);
+    if (articles.length === 0) {
+      throw ctx.fail('no_match', `None of ${input.pmids.length} PMIDs returned data`);
+    }
+    // ctx.fail('typo')   ← TypeScript error: 'typo' isn't in the contract
+    return { articles };
+  },
+});
+```
+
+**What you get:**
+
+| Surface | Behavior |
+|:--------|:---------|
+| 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. |
+| `tools/list` | Contract surfaced under `_meta['mcp-ts-core/errors']` so clients/agents can preview failure modes. |
+| Lint (startup) | Each `code` validated against `JsonRpcErrorCode`. Reasons validated as snake_case + unique within contract. |
+| Lint (conformance) | If the handler `throw new McpError(JsonRpcErrorCode.X)` outside `ctx.fail`, conformance check warns when X isn't declared. |
+
+**Skip the contract** for one-off internal tools or quick prototypes — `ctx` is plain `Context` (no `fail`) and you throw via [factories](#error-factories-fallback) directly. Behavior is identical at the wire; the contract just adds compile-time safety + advertising.
+
+> **Limits of the conformance lint.** The conformance and prefer-fail rules scan the handler's source text for `throw` statements. Errors thrown from called services (e.g. `await myService.fetch()` raising `RateLimited` internally) are invisible — the lint only sees what's lexically in the handler. Treat the contract as the *advertised* failure surface; bubbled-up codes still reach the client correctly via the auto-classifier, just without lint enforcement.
+
+---
+
+## Error Factories (fallback)
+
+Use when no contract entry fits — ad-hoc throws, tools without a contract, or service-layer code. Shorter than `new McpError(...)` and self-documenting. All return `McpError` instances and accept an optional `options` parameter for error chaining via `{ cause }`.
 
 ```ts
 throw notFound('Item not found', { itemId: '123' });
@@ -50,6 +99,9 @@ throw serviceUnavailable('API call failed', { url }, { cause: error });
 | `timeout(msg, data?, options?)` | Timeout (-32004) |
 | `serviceUnavailable(msg, data?, options?)` | ServiceUnavailable (-32000) |
 | `configurationError(msg, data?, options?)` | ConfigurationError (-32008) |
+| `internalError(msg, data?, options?)` | InternalError (-32603) |
+| `serializationError(msg, data?, options?)` | SerializationError (-32070) — JSON/XML/parser failures |
+| `databaseError(msg, data?, options?)` | DatabaseError (-32010) |
 
 `options` is `{ cause?: unknown }` — the standard ES2022 `ErrorOptions` type.
 
@@ -57,7 +109,7 @@ throw serviceUnavailable('API call failed', { url }, { cause: error });
 
 ## McpError Constructor
 
-For codes not covered by factories (InternalError, DatabaseError, etc.):
+For codes not covered by factories (rare — `MethodNotFound`, `ParseError`, `InitializationFailed`, `UnknownError`):
 
 ```ts
 throw new McpError(code, message?, data?, options?)
@@ -134,13 +186,15 @@ The framework applies these steps in order — first match wins:
 | Constructor | Mapped Code |
 |:------------|:------------|
 | `SyntaxError` | `ValidationError` |
-| `TypeError` | `ValidationError` |
 | `RangeError` | `ValidationError` |
 | `URIError` | `ValidationError` |
+| `ZodError` | `ValidationError` |
 | `ReferenceError` | `InternalError` |
 | `EvalError` | `InternalError` |
 | `AggregateError` | `InternalError` |
 
+`TypeError` is **intentionally excluded** from the constructor table — runtime `TypeError`s (e.g. *"Cannot read property X of undefined"*) are programmer errors, not validation failures. They fall through to message-pattern matching, then to the `InternalError` fallback.
+
 ### Common Message Patterns
 
 Patterns are tested against both the error `message` and `name`, case-insensitively. First match wins.
@@ -254,3 +308,107 @@ const parsed = await ErrorHandler.tryCatch(
 | `critical` | `boolean` | No | Marks the error as critical in logs (default `false`) |
 | `includeStack` | `boolean` | No | Include stack trace in log output (default `true`) |
 | `errorMapper` | `(error: unknown) => Error` | No | Custom transform applied instead of default `McpError` wrapping |
+
+---
+
+## HTTP Response → McpError
+
+When you bypass `fetchWithTimeout` and use raw `fetch` (typically because you need granular code classification or response body access), use `httpErrorFromResponse` instead of writing your own status mapping ladder:
+
+```ts
+import { httpErrorFromResponse } from '@cyanheads/mcp-ts-core/utils';
+
+const response = await fetch(url, { signal: ctx.signal });
+if (!response.ok) {
+  throw await httpErrorFromResponse(response, {
+    service: 'NCBI',                  // included in message
+    data: { endpoint, requestId: ctx.requestId },
+  });
+}
+```
+
+Captures the response body (truncated, configurable limit) and `Retry-After` header (stored as `data.retryAfter`) into `error.data`. The codes it produces line up with `withRetry`'s transient-code set, so retryable responses are retried automatically.
+
+> **Body reaches the client.** `error.data` is forwarded to the MCP client as `_meta.error.data` (tool errors) or JSON-RPC `error.data` (resource errors). Upstream 401/403/422 responses sometimes echo token claims, internal user IDs, or schema validation hints — that text becomes client-visible. For sensitive endpoints, pass `captureBody: false` (or `bodyLimit: 0`) so the body stays out of `data`. Defaults remain `captureBody: true` because most upstreams return useful diagnostic text and silent dropping helps no one debug.
+
+Full status table:
+
+| Status | Code |
+|:-------|:-----|
+| 400 | `InvalidParams` |
+| 401 | `Unauthorized` |
+| 402, 403 | `Forbidden` |
+| 404 | `NotFound` |
+| 408, 425, 504 | `Timeout` |
+| 409, 423, 424 | `Conflict` |
+| 422 | `ValidationError` |
+| 429 | `RateLimited` |
+| 405, 406, 410, 412, 415, 416, 417, 428, 431, 451, 4xx (other) | `InvalidRequest` |
+| 500, 501 | `InternalError` |
+| 502, 503, 5xx (other) | `ServiceUnavailable` |
+
+Also exports `httpStatusToErrorCode(status)` for sync mapping when you don't have a Response object.
+
+---
+
+## Handler-Body Lint Rules
+
+The startup linter (`bun run lint:mcp` and `createApp()` startup) checks handler bodies for common anti-patterns. All emit warnings (not errors) — they don't block startup but show up in `devcheck` output.
+
+| Rule | Catches |
+|:-----|:--------|
+| `prefer-mcp-error-in-handler` | `throw new Error(...)` inside a handler — use `McpError` or a factory so the framework returns a specific code |
+| `prefer-error-factory` | `new McpError(JsonRpcErrorCode.NotFound, ...)` when `notFound(...)` exists |
+| `preserve-cause-on-rethrow` | `catch (e) { throw new McpError(...) }` without `{ cause: e }` |
+| `no-stringify-upstream-error` | `JSON.stringify(...)` inside a thrown message — risks leaking internal traces; use `data` payload instead |
+
+---
+
+## Error Contract Lint Rules
+
+The linter validates the structure of `errors[]` and (when present) cross-checks the handler body against the declared contract.
+
+### Structural rules
+
+| Rule | Severity | Catches |
+|:-----|:---------|:--------|
+| `error-contract-type` | error | `errors` is present but not an array |
+| `error-contract-empty` | warning | `errors: []` — drop the field instead, or declare actual failure modes |
+| `error-contract-entry-type` | error | An entry isn't an object |
+| `error-contract-code-type` | error | `code` missing or not a number |
+| `error-contract-code-unknown` | error | `code` isn't a real `JsonRpcErrorCode` value |
+| `error-contract-code-unknown-error` | warning | `code` is `JsonRpcErrorCode.UnknownError` (the giveup-fallback — pick a more specific code) |
+| `error-contract-reason-required` | error | `reason` missing or empty |
+| `error-contract-reason-format` | warning | `reason` not snake_case |
+| `error-contract-reason-unique` | error | Duplicate `reason` within one contract |
+| `error-contract-when-required` | error | `when` missing or empty |
+| `error-contract-retryable-type` | warning | `retryable` is present but not a boolean |
+
+### Conformance rules
+
+| Rule | Severity | Catches |
+|:-----|:---------|:--------|
+| `error-contract-conformance` | warning | Handler throws a non-baseline code that isn't in the contract. Suggests adding it to `errors[]` so `tools/list` advertises the failure mode. |
+| `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. |
+
+### Baseline codes (auto-allowed)
+
+These codes bubble up from anywhere — services, framework utilities, the auto-classifier — and are implicitly always-possible on any tool. They're skipped by the conformance check, so the contract can stay focused on intentional domain failures:
+
+- `InternalError` — bug, programmer error, truly unexpected
+- `ServiceUnavailable` — upstream/network failures
+- `Timeout` — request deadline exceeded, abort
+- `ValidationError` — schema violations, malformed input
+- `SerializationError` — JSON/XML parse failures
+
+If you *want* to advertise one of these as a domain-specific failure (e.g., a tool that intentionally times out under defined conditions), declare it in `errors[]` anyway — the contract still surfaces in `tools/list`. The lint just doesn't *require* you to.
+
+### When to declare vs. let it bubble
+
+The contract describes the **public failure surface** — the failures clients/agents can plan around. Modeled after how OpenAPI-driven frameworks treat 5xx: enumerated 4xx for intentional failures, implicit 5xx for infrastructure.
+
+| Pattern | Use for |
+|:--------|:--------|
+| `throw ctx.fail('reason', …)` | Declared domain failures — typed, contract-checked, `data.reason` populated |
+| `throw notFound(…)` / factories | Errors not in the contract; the auto-classifier handles them. Prefer `ctx.fail` when a matching contract entry exists. |
+| Bubble up from services | Upstream classification already produced an `McpError` — don't re-wrap |

package/skills/api-linter/SKILL.md

@@ -48,7 +48,11 @@ Grouped by family. Jump to any rule ID via its anchor.
 | Names | `name-required`, `name-format`, `name-unique` | [Name rules](#name-rules) |
 | Tools | `description-required`, `handler-required`, `auth-type`, `auth-scope-format`, `annotation-type`, `annotation-coherence`, `meta-ui-type`, `meta-ui-resource-uri-required`, `meta-ui-resource-uri-scheme`, `app-tool-resource-pairing` | [Tool rules](#tool-rules) |
 | Resources | `uri-template-required`, `uri-template-valid`, `resource-name-not-uri`, `template-params-align` | [Resource rules](#resource-rules) |
+| Landing | `landing-*` (23 rules — shape, tagline, logo, links, repo, envExample, connectSnippets, theme) | [Landing config rules](#landing-config-rules) |
 | 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 rules](#error-contract-rules) |
+| Error contract (conformance) | `error-contract-conformance`, `error-contract-prefer-fail` | [Error contract rules](#error-contract-rules) |
 | server.json | ~40 rules prefixed `server-json-*` | [server.json rules](#server-json-rules) |
 
 ---
@@ -196,7 +200,9 @@ Every tool, resource, and prompt definition needs a non-empty `name` string. For
 
 **Severity:** error
 
-Names must match `^[a-zA-Z0-9._-]+$` (alphanumerics, dots, hyphens, underscores). Tools conventionally use `snake_case`, resources and prompts use `kebab-case` or `snake_case`.
+**Scope:** tools only — resources and prompts are checked by `name-required` only.
+
+Tool names must match `^[A-Za-z0-9._-]{1,128}$` (alphanumerics, dots, hyphens, underscores; 1–128 chars). Tools conventionally use `snake_case`.
 
 **Fix:** rename to a valid identifier. If the legacy name is user-facing, keep `title` as the display string and use a valid `name` internally.
 
@@ -259,7 +265,7 @@ Every element in `auth` must be a non-empty string. Empty strings in the array a
 
 **Severity:** warning
 
-Contradictory annotation combinations. The canonical case: `readOnlyHint: true` with `destructiveHint: true` — a read-only tool cannot be destructive. `idempotentHint: true` alongside `readOnlyHint: true` is fine (explicit redundancy is allowed).
+Catches `readOnlyHint: true` with **any** explicit `destructiveHint` value (even `false`) — the destructive hint is meaningless on a read-only tool, so its presence signals authoring confusion. Drop `destructiveHint` entirely when the tool is read-only.
 
 ### meta-ui-type
 
@@ -322,7 +328,7 @@ resource('myscheme://{id}/data', {
 
 **Severity:** error
 
-Every variable in the URI template must appear as a key in the `params` schema, and vice versa. `test://{itemId}/data` with `params: z.object({ item_id: ... })` is rejected — casing mismatches count.
+Every variable in the URI template must appear as a key in the `params` schema. `test://{itemId}/data` with `params: z.object({ item_id: ... })` is rejected — casing mismatches count. The check is template → schema only; extra schema keys not referenced by the template are not flagged.
 
 **Fix:** rename one side so they match exactly. The error message names which variables are on which side.
 
@@ -391,6 +397,220 @@ Most of these are mechanical — fix the manifest field named in the diagnostic'
 
 ---
 
+## Landing config rules
+
+Validate the `landing` config passed to `createApp()` (the config object that drives the framework's landing page). Run only when `input.landing` is provided to `validateDefinitions`. All errors — landing config that's structurally broken would render incorrectly on the public page.
+
+| Rule | Severity | Catches |
+|:-----|:---------|:--------|
+| `landing-shape` | error | `landing` is not a plain object |
+| `landing-tagline-type` | error | `tagline` is present but not a string |
+| `landing-tagline-length` | error | `tagline` exceeds the max length |
+| `landing-logo-type` | error | `logo` is present but not a string |
+| `landing-logo-size` | error | `logo` is too long for inline rendering |
+| `landing-links-type` | error | `links` is present but not an array |
+| `landing-links-count` | error | `links` exceeds the max count |
+| `landing-link-shape` | error | A `links[]` entry is not a plain object |
+| `landing-link-href` | error | A link entry's `href` is missing or not a non-empty string |
+| `landing-link-label` | error | A link entry's `label` is missing or not a non-empty string |
+| `landing-repo-root-type` | error | `repoRoot` is present but not a string |
+| `landing-repo-root-shape` | error | `repoRoot` is not a recognized GitHub URL shape |
+| `landing-env-example-type` | error | `envExample` is present but not a plain object |
+| `landing-env-example-count` | error | `envExample` has too many entries |
+| `landing-env-example-key` | error | An `envExample` key is empty or invalid |
+| `landing-env-example-value` | error | An `envExample` value is not a string |
+| `landing-connect-snippets-type` | error | `connectSnippets` is present but not a plain object |
+| `landing-connect-snippets-key` | error | A `connectSnippets` key is empty |
+| `landing-connect-snippets-value` | error | A `connectSnippets` value is not a string |
+| `landing-connect-snippets-empty` | error | A `connectSnippets` value is an empty string |
+| `landing-theme-type` | error | `theme` is present but not a plain object |
+| `landing-theme-accent` | error | `theme.accent` is present but not a string |
+| `landing-theme-accent-format` | error | `theme.accent` doesn't match the expected color format |
+
+Diagnostic anchors for these rules are the rule ID — e.g. `skills/api-linter/SKILL.md#landing-shape`. Pass `landing` to `validateDefinitions({ landing, tools, resources, prompts })` to opt in.
+
+---
+
+## Handler body rules
+
+Heuristic source-text checks that scan `handler.toString()` for common error-handling anti-patterns. All warnings — false positives are possible because the rules can't see code reached through wrappers, factories assigned to variables, or service-layer throws. Each rule fires at most once per handler to keep reports quiet.
+
+### prefer-mcp-error-in-handler
+
+**Severity:** warning
+
+Fires when a handler contains `throw new Error(...)`. Plain `Error` doesn't carry a JSON-RPC code — the framework's auto-classifier degrades to `InternalError`, hiding the actual failure mode.
+
+**Fix:** use `McpError` or a factory:
+
+```ts
+// instead of:
+throw new Error('Item not found');
+// use:
+throw notFound('Item not found', { itemId });
+```
+
+### prefer-error-factory
+
+**Severity:** warning
+
+Fires when a handler builds an error via `new McpError(JsonRpcErrorCode.X, ...)` and a matching factory exists (`notFound`, `rateLimited`, `serviceUnavailable`, …). The factory form is shorter, self-documenting, and consistent with the rest of the codebase.
+
+**Fix:** swap the constructor for the factory the diagnostic names:
+
+```ts
+// instead of:
+throw new McpError(JsonRpcErrorCode.NotFound, 'Item missing');
+// use:
+throw notFound('Item missing');
+```
+
+### preserve-cause-on-rethrow
+
+**Severity:** warning
+
+Fires when a `catch (e)` block throws a structured `McpError` (or factory) without passing `{ cause: e }`. Dropping the cause loses the original stack trace — observability platforms and `pino-pretty` rely on it to render error chains.
+
+**Fix:** thread the cause through the 4th `McpError` argument or factory options:
+
+```ts
+try {
+  await fetchUpstream();
+} catch (e) {
+  throw serviceUnavailable('Upstream failed', { service: 'pubmed' }, { cause: e });
+}
+```
+
+### no-stringify-upstream-error
+
+**Severity:** warning
+
+Fires when a handler throws an error message containing `JSON.stringify(...)`. Stringifying caught or upstream errors into the message risks leaking internal stack traces, AWS internal ARNs, or third-party trace IDs to clients.
+
+**Fix:** sanitize first, or attach the raw blob to the error's `data` payload — never the message.
+
+```ts
+// instead of:
+throw new Error(`Upstream failed: ${JSON.stringify(e)}`);
+// use:
+throw serviceUnavailable('Upstream failed', { upstreamError: e }, { cause: e });
+```
+
+---
+
+## Error contract rules
+
+Validate the optional `errors[]` declarative contract on tool/resource definitions. Structural rules check the shape of contract entries; conformance rules cross-check the handler body against the declared codes.
+
+When a contract is declared, surfaced under `_meta['mcp-ts-core/errors']` in `tools/list` / `resources/list`, and the handler receives a typed `ctx.fail(reason, …)` keyed by the declared reason union. See `skills/api-errors/SKILL.md` for runtime semantics.
+
+### error-contract-type
+
+**Severity:** error
+
+Fires when `errors` is present but not an array. The contract must be a tuple of `ErrorContract` entries.
+
+### error-contract-empty
+
+**Severity:** warning
+
+Fires when `errors: []` is declared. An empty contract is a no-op — nothing to surface in `tools/list`, no reason union for `ctx.fail`, no conformance to check.
+
+**Fix:** drop the field, or declare actual failure modes.
+
+### error-contract-entry-type
+
+**Severity:** error
+
+Fires when an entry in `errors[]` isn't an object. Each entry must be `{ code, reason, when }` (and optionally `retryable`).
+
+### error-contract-code-type
+
+**Severity:** error
+
+Fires when an entry's `code` is missing or not a number. Use the `JsonRpcErrorCode` enum:
+
+```ts
+errors: [{ code: JsonRpcErrorCode.NotFound, reason: 'no_match', when: 'No items matched' }]
+```
+
+### error-contract-code-unknown
+
+**Severity:** error
+
+Fires when an entry's `code` is a number but not a known `JsonRpcErrorCode` value. Likely a typo or stale magic number — import the enum and use a member.
+
+### error-contract-code-unknown-error
+
+**Severity:** warning
+
+Fires when an entry uses `JsonRpcErrorCode.UnknownError` (-32099). That code is the auto-classifier's giveup-fallback; declaring it in a contract conveys nothing useful to clients.
+
+**Fix:** pick a more specific code (`InternalError`, `ServiceUnavailable`, etc.) or drop the entry.
+
+### error-contract-reason-required
+
+**Severity:** error
+
+Fires when an entry's `reason` is missing or empty. `reason` is the stable machine-readable identifier clients switch on; it must always be present.
+
+### error-contract-reason-format
+
+**Severity:** warning
+
+Fires when `reason` isn't snake_case (matched against `^[a-z][a-z0-9_]*$`). Reasons are part of the public API — treat them like API constants. `'NotFound'`, `'no-match'`, `'1bad'` all warn.
+
+**Fix:** rename to snake_case (`'no_match'`, `'rate_limited'`, …).
+
+### error-contract-reason-unique
+
+**Severity:** error
+
+Fires when two entries in the same contract share a `reason`. Reasons must be unique within a contract — they're how `ctx.fail(reason, …)` selects the entry.
+
+### error-contract-when-required
+
+**Severity:** error
+
+Fires when an entry's `when` field is missing or empty. `when` is the human-readable explanation surfaced to LLMs and UI clients; without it, the contract is opaque.
+
+### error-contract-retryable-type
+
+**Severity:** warning
+
+Fires when an entry's optional `retryable` field is present but isn't a boolean. Only `true` or `false` is meaningful — drop the field if you can't commit to either.
+
+### error-contract-conformance
+
+**Severity:** warning
+
+Cross-check rule. Fires when a handler throws a non-baseline code (via `JsonRpcErrorCode.X` or a factory like `notFound()`) that isn't declared in `errors[]`.
+
+Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) are auto-allowed because they bubble from anywhere — services, framework utilities, the auto-classifier — and are implicitly always-possible on any tool. Only domain-specific codes need declaring.
+
+**Fix:** add the missing code to `errors[]` with a stable reason, or route through `ctx.fail(reason, …)` if it maps to an existing entry.
+
+**Heuristic limitations:** the scan reads `handler.toString()` and only catches direct `throw new McpError(JsonRpcErrorCode.X, …)` and `throw factory(…)` patterns. Indirect throws (`const e = notFound(); throw e;`), throws from called services, and throws via runtime helpers like `httpErrorFromResponse(...)` are invisible.
+
+### error-contract-prefer-fail
+
+**Severity:** warning
+
+Fires when a handler throws a code that **is** declared in the contract directly (via factory or `new McpError`) instead of routing through `ctx.fail(reason, …)`. Direct throws bypass the typed helper, leaving observers without a stable `data.reason` and disconnecting the throw site from the contract entry.
+
+**Fix:** swap the direct throw for `ctx.fail` using the reason the diagnostic suggests:
+
+```ts
+// instead of:
+throw notFound('No items match');
+// use:
+throw ctx.fail('no_match', 'No items match');
+```
+
+The diagnostic message includes the declared reason(s) for the code so you can copy-paste.
+
+---
+
 ## Escape hatches
 
 ### Dynamic upstream data