@cyanheads/mcp-ts-core 0.7.6 → 0.8.0

package/dist/utils/network/httpError.js

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Helpers for converting HTTP `Response` objects into properly
+ * classified `McpError` instances. Replaces the hand-rolled status → code ladder
+ * that consumer servers tend to write (and get wrong, especially for 401/403/408).
+ * @module src/utils/network/httpError
+ */
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+/**
+ * Maps an HTTP status code to a `JsonRpcErrorCode`. Covers the full client/server
+ * 4xx/5xx range, with specific mappings for the codes most upstream APIs use to
+ * signal authoritative outcomes (auth failures, conflicts, validation, rate limits).
+ *
+ * Returns `undefined` when the status is in the 1xx/2xx/3xx range — those are not
+ * errors and the caller should not be invoking error mapping on them.
+ *
+ * | Status | Code |
+ * |:-------|:-----|
+ * | 400 | `InvalidParams` |
+ * | 401 | `Unauthorized` |
+ * | 402 | `Forbidden` (payment-required, treated as access denial) |
+ * | 403 | `Forbidden` |
+ * | 404 | `NotFound` |
+ * | 405, 406, 410, 415 | `InvalidRequest` |
+ * | 408 | `Timeout` |
+ * | 409 | `Conflict` |
+ * | 412, 416, 417 | `InvalidRequest` |
+ * | 422 | `ValidationError` |
+ * | 423, 424 | `Conflict` |
+ * | 425 | `Timeout` |
+ * | 428 | `InvalidRequest` |
+ * | 429 | `RateLimited` |
+ * | 431, 451 | `InvalidRequest` |
+ * | 4xx (other) | `InvalidRequest` |
+ * | 500, 501 | `InternalError` |
+ * | 502, 503 | `ServiceUnavailable` |
+ * | 504 | `Timeout` |
+ * | 5xx (other) | `ServiceUnavailable` |
+ */
+export function httpStatusToErrorCode(status) {
+    if (status < 400)
+        return;
+    switch (status) {
+        case 400:
+            return JsonRpcErrorCode.InvalidParams;
+        case 401:
+            return JsonRpcErrorCode.Unauthorized;
+        case 402:
+        case 403:
+            return JsonRpcErrorCode.Forbidden;
+        case 404:
+            return JsonRpcErrorCode.NotFound;
+        case 408:
+            return JsonRpcErrorCode.Timeout;
+        case 409:
+            return JsonRpcErrorCode.Conflict;
+        case 422:
+            return JsonRpcErrorCode.ValidationError;
+        case 423:
+        case 424:
+            return JsonRpcErrorCode.Conflict;
+        case 425:
+            return JsonRpcErrorCode.Timeout;
+        case 429:
+            return JsonRpcErrorCode.RateLimited;
+        case 500:
+        case 501:
+            return JsonRpcErrorCode.InternalError;
+        case 502:
+        case 503:
+            return JsonRpcErrorCode.ServiceUnavailable;
+        case 504:
+            return JsonRpcErrorCode.Timeout;
+        default:
+            return status >= 500 ? JsonRpcErrorCode.ServiceUnavailable : JsonRpcErrorCode.InvalidRequest;
+    }
+}
+const DEFAULT_BODY_LIMIT = 500;
+/**
+ * Builds an `McpError` from an HTTP `Response`, with status-aware classification
+ * and optional body capture.
+ *
+ * Reads the response body (consuming it) when `captureBody` is true, so callers
+ * must `response.clone()` first if they intend to read the body elsewhere.
+ *
+ * Always returns an `McpError` even for 1xx/2xx/3xx — the caller is expected to
+ * have verified `!response.ok` first, but the helper falls back to a sensible
+ * code (`InternalError`) instead of silently producing nothing.
+ *
+ * @example
+ * ```ts
+ * const response = await fetch(url);
+ * if (!response.ok) {
+ *   throw await httpErrorFromResponse(response, {
+ *     service: 'NCBI',
+ *     data: { endpoint: 'esearch' },
+ *   });
+ * }
+ * ```
+ *
+ * @example Wrapping a network failure
+ * ```ts
+ * try {
+ *   const response = await fetch(url);
+ *   if (!response.ok) {
+ *     throw await httpErrorFromResponse(response, { service: 'NCBI' });
+ *   }
+ *   return await response.text();
+ * } catch (error) {
+ *   if (error instanceof McpError) throw error;
+ *   throw new McpError(JsonRpcErrorCode.ServiceUnavailable, 'NCBI request failed', { url }, { cause: error });
+ * }
+ * ```
+ */
+export async function httpErrorFromResponse(response, options = {}) {
+    const { captureBody = true, bodyLimit = DEFAULT_BODY_LIMIT, service, data: extraData, cause, codeOverride, } = options;
+    const code = codeOverride?.(response.status) ??
+        httpStatusToErrorCode(response.status) ??
+        JsonRpcErrorCode.InternalError;
+    const subject = service ?? safeHost(response.url) ?? 'Upstream';
+    const statusText = response.statusText ? ` ${response.statusText}` : '';
+    let body;
+    if (captureBody) {
+        try {
+            const raw = await response.text();
+            body = raw.length > bodyLimit ? `${raw.slice(0, bodyLimit)}…` : raw;
+        }
+        catch {
+            /* body unreadable (already consumed, network error mid-stream) */
+        }
+    }
+    const retryAfter = response.headers.get('retry-after') ?? undefined;
+    const data = {
+        url: response.url || undefined,
+        status: response.status,
+        statusText: response.statusText || undefined,
+        ...(body !== undefined && { body }),
+        ...(retryAfter !== undefined && { retryAfter }),
+        ...extraData,
+    };
+    return new McpError(code, `${subject} returned HTTP ${response.status}${statusText}.`, data, cause !== undefined ? { cause } : undefined);
+}
+/** Returns the hostname from a URL string, or `undefined` if it can't be parsed. */
+function safeHost(url) {
+    if (!url)
+        return;
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return;
+    }
+}
+//# sourceMappingURL=httpError.js.map

package/dist/utils/network/httpError.js.map

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

package/dist/utils/network/retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAYzE,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA6DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAiD/F"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAYzE,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA6DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAiD/F"}

package/dist/utils/network/retry.js

@@ -3,7 +3,6 @@
  * may fail transiently. Designed so the retry boundary covers the full pipeline
  * (HTTP fetch + response parsing/validation), not just the network call.
  * @module src/utils/network/retry
- * @see docs/service-resilience.md
  */
 import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
 import { logger } from '../../utils/internal/logger.js';

package/dist/utils/network/retry.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -16,6 +16,7 @@
     "scripts/clean.ts",
     "scripts/devcheck.ts",
     "scripts/lint-mcp.ts",
+    "scripts/split-changelog.ts",
     "scripts/tree.ts",
     "skills/",
     "templates/",
@@ -173,7 +174,7 @@
     "@opentelemetry/sdk-node": "^0.215.0",
     "@opentelemetry/sdk-trace-node": "^2.7.0",
     "@opentelemetry/semantic-conventions": "^1.40.0",
-    "@supabase/supabase-js": "^2.105.0",
+    "@supabase/supabase-js": "^2.105.1",
     "@types/bun": "^1.3.13",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.6.0",
@@ -194,7 +195,7 @@
     "js-yaml": "^4.1.1",
     "linkedom": "^0.18.12",
     "node-cron": "^4.2.1",
-    "openai": "^6.34.0",
+    "openai": "^6.35.0",
     "papaparse": "^5.5.3",
     "partial-json": "^0.1.7",
     "pdf-lib": "^1.17.1",
@@ -204,7 +205,7 @@
     "tsc-alias": "^1.8.16",
     "typedoc": "^0.28.19",
     "typescript": "^6.0.3",
-    "unpdf": "^1.6.0",
+    "unpdf": "^1.6.1",
     "validator": "^13.15.35",
     "vite": "8.0.10",
     "vitest": "^4.1.5"

package/scripts/split-changelog.ts

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview One-shot migration: split the monolithic CHANGELOG.md into
+ * per-version files under `changelog/<major.minor>.x/<version>.md`.
+ *
+ * After the initial migration, this script is no longer needed — the
+ * per-version files become the source of truth and `scripts/build-changelog.ts`
+ * regenerates CHANGELOG.md from them. Keep this around only long enough to
+ * verify the round-trip (split → build → diff).
+ *
+ * Behavior:
+ *   • Reads CHANGELOG.md, splits on `## [X.Y.Z] - YYYY-MM-DD` headers
+ *   • Groups by minor series: 0.1.4 → changelog/0.1.x/0.1.4.md
+ *   • Writes each version block with an H1 heading
+ *   • Creates changelog/template.md template if missing
+ *   • Overwrites existing per-version files (idempotent)
+ *   • Drops the preamble (title + description) — that's handled by the build script
+ *
+ * Usage: bun run scripts/split-changelog.ts
+ *
+ * @module scripts/split-changelog
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const CHANGELOG_PATH = resolve('CHANGELOG.md');
+const CHANGELOG_DIR = resolve('changelog');
+const TEMPLATE_PATH = resolve(CHANGELOG_DIR, 'template.md');
+
+const TEMPLATE_CONTENT = `# <version> — YYYY-MM-DD
+
+<!-- Brief summary of the upcoming release — delete this comment when filled in. -->
+
+## Added
+
+-
+
+## Changed
+
+-
+
+## Fixed
+
+-
+`;
+
+interface Section {
+  body: string;
+  date: string;
+  version: string;
+}
+
+function extractSections(content: string): Section[] {
+  const regex = /^## \[([^\]]+)\] - (\d{4}-\d{2}-\d{2})$/gm;
+  const matches = [...content.matchAll(regex)];
+  if (matches.length === 0) {
+    throw new Error('No version sections found in CHANGELOG.md (expected ## [X.Y.Z] - YYYY-MM-DD)');
+  }
+
+  const sections: Section[] = [];
+  for (let i = 0; i < matches.length; i++) {
+    const match = matches[i] as RegExpMatchArray & { index: number };
+    const next = matches[i + 1] as (RegExpMatchArray & { index: number }) | undefined;
+    const start = match.index + match[0].length;
+    const end = next ? next.index : content.length;
+
+    let body = content.slice(start, end);
+    body = body.replace(/^\n+/, '');
+    body = body.replace(/\n+---\n*$/, '\n');
+    body = body.replace(/\n*$/, '\n');
+
+    sections.push({
+      version: match[1] as string,
+      date: match[2] as string,
+      body,
+    });
+  }
+  return sections;
+}
+
+/**
+ * Promote heading levels by stripping one `#` from H2+ lines. Assumes no H1
+ * or H2 in section bodies (the version H2 was already stripped); the existing
+ * CHANGELOG.md uses H3 for Added/Changed/Fixed etc., which become H2 here.
+ */
+function promoteHeadings(body: string): string {
+  return body.replace(/^(#{2,6}) /gm, (_, hashes: string) => `${hashes.slice(1)} `);
+}
+
+function toPerVersionFile(section: Section): string {
+  return `# ${section.version} — ${section.date}\n\n${promoteHeadings(section.body)}`;
+}
+
+/** Extract the `major.minor.x` series directory for a version string. */
+function seriesOf(version: string): string {
+  const [major, minor] = version.split('.');
+  if (!major || !minor) throw new Error(`Cannot derive series from version: ${version}`);
+  return `${major}.${minor}.x`;
+}
+
+function main(): void {
+  const content = readFileSync(CHANGELOG_PATH, 'utf-8');
+  const sections = extractSections(content);
+
+  mkdirSync(CHANGELOG_DIR, { recursive: true });
+
+  const seriesCounts = new Map<string, number>();
+
+  for (const section of sections) {
+    const series = seriesOf(section.version);
+    const seriesDir = resolve(CHANGELOG_DIR, series);
+    mkdirSync(seriesDir, { recursive: true });
+    const path = resolve(seriesDir, `${section.version}.md`);
+    writeFileSync(path, toPerVersionFile(section));
+    seriesCounts.set(series, (seriesCounts.get(series) ?? 0) + 1);
+  }
+
+  for (const [series, count] of [...seriesCounts.entries()].sort()) {
+    console.log(`  + changelog/${series}/ (${count} file${count === 1 ? '' : 's'})`);
+  }
+
+  if (!existsSync(TEMPLATE_PATH)) {
+    writeFileSync(TEMPLATE_PATH, TEMPLATE_CONTENT);
+    console.log('  + changelog/template.md (format reference)');
+  }
+
+  console.log(`\nSplit ${sections.length} versions into ${seriesCounts.size} series.`);
+  console.log('Next: `bun run scripts/build-changelog.ts` to regenerate CHANGELOG.md,');
+  console.log('      then `diff` against the original to verify byte-equality.');
+}
+
+main();

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

@@ -9,6 +9,18 @@ metadata:
   type: reference
 ---
 
+## When to Use
+
+App tools are **rarely the right choice**. Reach for one only when all of the following hold:
+
+1. A *human* will actively interact with the result in real time — not just an LLM consuming text.
+2. The target deployment runs in a client that supports MCP Apps. Many clients (Claude Code, Cursor, most chat UIs) are tool-only and will only ever see the `format()` text fallback you have to maintain anyway.
+3. The interaction the UI enables — scrubbing a dense table, approving a multi-step plan, filling a structured form — is core to the workflow, not nice-to-have rendering.
+
+App tools cost more than standard tools: an iframe + CSP setup, `app.ontoolresult` / `callServerTool` plumbing, host-context wiring (theme, fonts, styles), and a `format()` text path that has to be content-complete because most clients see only that. Two surfaces to keep in sync, two failure modes per change.
+
+Default to `add-tool`. This skill is the how-to once that bar is cleared — the "whether to" decision belongs in `design-mcp-server`.
+
 ## Context
 
 MCP Apps extend the standard tool pattern with an interactive HTML UI rendered in a sandboxed iframe by the host. Each MCP App consists of two definitions:

package/skills/add-resource/SKILL.md

@@ -107,6 +107,46 @@ await createApp({
 
 If the repo already uses `src/mcp-server/resources/definitions/index.ts`, update that barrel instead of changing the registration style.
 
+### Optional: declarative `errors[]` contract
+
+Resources can opt into the same typed error contract as tools — surfaced in `resources/list` under `_meta['mcp-ts-core/errors']` and bound to a typed `ctx.fail(reason, …)` keyed by the declared reason union:
+
+```typescript
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+export const articleResource = resource('article://{pmid}', {
+  description: 'Read an article by PMID.',
+  errors: [
+    { reason: 'no_pmid_match', code: JsonRpcErrorCode.NotFound,
+      when: 'PMID not found in the index.' },
+    { reason: 'withdrawn', code: JsonRpcErrorCode.NotFound,
+      when: 'Article was withdrawn upstream.' },
+    { reason: 'upstream_throttled', code: JsonRpcErrorCode.RateLimited,
+      when: 'Upstream PubMed quota hit.', retryable: true },
+  ],
+  params: z.object({ pmid: z.string().describe('PubMed ID') }),
+  async handler(params, ctx) {
+    const article = await fetchOne(params.pmid);
+    if (!article) throw ctx.fail('no_pmid_match', `PMID ${params.pmid} not indexed`);
+    if (article.withdrawn) throw ctx.fail('withdrawn');
+    return article;
+  },
+});
+```
+
+Without `errors[]`, the handler receives plain `Context` (no `fail` method) and throws via error factories (`notFound`, `serviceUnavailable`, …) directly. The contract is opt-in. See `skills/api-errors/SKILL.md` for the full pattern, baseline codes, and conformance rules.
+
+### Other `resource()` options
+
+Beyond `description`, `params`, `handler`, and `list`, the builder also supports:
+
+| Field | Purpose |
+|:------|:--------|
+| `output` | Optional Zod schema for runtime validation of the handler return value (parity with `tool()`'s `output`). |
+| `format` | Optional formatter mapping the handler's return to the `ReadResourceResult.contents[]` shape. Default: string passthrough; objects serialized to JSON. Override when you need to attach permissions, custom encodings, or split into multiple content items. |
+| `annotations` | Resource annotations (e.g., `audience`, `priority`) — see `ResourceAnnotations`. |
+| `title` | Human-readable display title (defaults to `name`). |
+
 ## Checklist
 
 - [ ] File created at `src/mcp-server/resources/definitions/{{resource-name}}.resource.ts`

package/skills/add-service/SKILL.md

@@ -115,6 +115,7 @@ async fetchItem(id: string, ctx: Context): Promise<Item> {
         `${this.baseUrl}/items/${id}`,
         10_000,
         ctx,
+        { signal: ctx.signal },
       );
       const text = await response.text();
       return this.parseResponse<Item>(text);
@@ -136,9 +137,37 @@ async fetchItem(id: string, ctx: Context): Promise<Item> {
 3. **Classify parse failures by content.** If the upstream returns HTTP 200 with an HTML error page, detect it and throw `ServiceUnavailable` (transient) instead of `SerializationError` (non-transient).
 4. **Exhausted retries say so.** `withRetry` automatically enriches the final error with attempt count — callers know retries were already attempted.
 
+### When you need finer-grained HTTP error classification
+
+`fetchWithTimeout` collapses every non-2xx into `ServiceUnavailable`. That's the safe default but it isn't always right — a `401` should be `Unauthorized`, a `429` should be `RateLimited` (and is retryable), a `408` should be `Timeout` (and is retryable). When you need the nuance, drop down to raw `fetch` + `httpErrorFromResponse`:
+
+```typescript
+import { httpErrorFromResponse, withRetry } from '@cyanheads/mcp-ts-core/utils';
+
+async fetchItem(id: string, ctx: Context): Promise<Item> {
+  return withRetry(
+    async () => {
+      const response = await fetch(`${this.baseUrl}/items/${id}`, { signal: ctx.signal });
+      if (!response.ok) {
+        throw await httpErrorFromResponse(response, {
+          service: 'MyAPI',
+          data: { itemId: id },
+        });
+      }
+      return this.parseResponse<Item>(await response.text());
+    },
+    { operation: 'fetchItem', context: ctx, signal: ctx.signal },
+  );
+}
+```
+
+`httpErrorFromResponse` maps the full status table (401/403/408/422/429/5xx) to the appropriate `JsonRpcErrorCode`, captures the response body (truncated), and forwards `Retry-After` headers into `error.data.retryAfter`. The codes it produces line up with `withRetry`'s transient-code set, so retryable HTTP failures (429, 503, 504) are retried automatically and non-retryable ones (401, 404, 422) fail immediately.
+
 ### Response handler pattern
 
 ```typescript
+import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+
 parseResponse<T>(text: string): T {
   // Detect HTML error pages masquerading as successful responses
   if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
@@ -188,6 +217,24 @@ function normalizeRepo(raw: RawRepo): Repo {
 }
 ```
 
+## Error Handling in Services
+
+Services don't declare `errors: [...]` contracts and don't have `ctx.fail` — that contract surface is tool/resource-only. Inside services:
+
+- **Throw via factories** when a specific code matters: `throw notFound(...)`, `throw rateLimited(...)`, `throw serviceUnavailable(...)`. The framework's auto-classifier catches anything else.
+- **Wrap risky pipelines in `ErrorHandler.tryCatch`** when you want structured logging + auto-classification without writing try/catch boilerplate. It always rethrows — never swallows. Useful for parsing untrusted input (JSON, config) or third-party SDK calls whose error types you don't control:
+
+  ```ts
+  import { ErrorHandler } from '@cyanheads/mcp-ts-core/utils';
+
+  const parsed = await ErrorHandler.tryCatch(
+    () => JSON.parse(rawConfig),
+    { operation: 'MyService.parseConfig', errorCode: JsonRpcErrorCode.ConfigurationError },
+  );
+  ```
+
+- **Tool/resource handlers bubble service errors unchanged** — the contract advertises the *advertised* failure surface, and any code thrown from a service still reaches the client correctly via the auto-classifier. The conformance lint scans handler source text only, so service-thrown codes aren't flagged.
+
 ## API Efficiency
 
 When a service wraps an external API, design methods to minimize upstream calls. These patterns compound — a tool calling 3 service methods that each make N requests is 3N calls; batching drops it to 3.

package/skills/add-test/SKILL.md

@@ -38,6 +38,7 @@ Read the handler and identify:
 | **`ctx.state` usage** | Use `createMockContext({ tenantId: 'test' })` to enable storage |
 | **`ctx.elicit` / `ctx.sample`** | Mock with `vi.fn()`, also test the absent case (undefined) |
 | **`ctx.progress`** | Use `createMockContext({ progress: true })` for task tools |
+| **`ctx.fail` (typed contract)** | Definitions with `errors[]` need `fail` attached to the mock ctx — `createMockContext({ errors: myTool.errors })` does it for you. Assert on `data.reason` (stable per-contract entry), not just `code`. |
 | **`format` function** | Test separately if defined — it's pure, no ctx needed. Verify it renders the IDs and fields the model needs, not just a count or title. For projection-style tools, test non-default field selections. |
 | **Sparse upstream payloads** | For third-party API integrations, build a fixture with omitted fields. Assert normalized output still validates and `format()` preserves unknown values instead of inventing facts. |
 | **Auth scopes** | Not tested at handler level (framework enforces) — skip |
@@ -76,6 +77,17 @@ describe('{{TOOL_EXPORT}}', () => {
     await expect({{TOOL_EXPORT}}.handler(input, ctx)).rejects.toThrow();
   });
 
+  // Only when the tool declares `errors: [...]`. Drop this block otherwise.
+  it('throws ctx.fail("{{REASON}}") for the declared failure mode', async () => {
+    const ctx = createMockContext({ errors: {{TOOL_EXPORT}}.errors });
+    const input = {{TOOL_EXPORT}}.input.parse({
+      // input that triggers the declared failure mode
+    });
+    await expect({{TOOL_EXPORT}}.handler(input, ctx)).rejects.toMatchObject({
+      data: { reason: '{{REASON}}' },
+    });
+  });
+
   it('formats output completely', () => {
     const output = { /* mock output matching the output schema */ };
     const blocks = {{TOOL_EXPORT}}.format!(output);
@@ -115,6 +127,13 @@ describe('{{RESOURCE_EXPORT}}', () => {
     await expect({{RESOURCE_EXPORT}}.handler(params, ctx)).rejects.toThrow();
   });
 
+  // For resources that declare an `errors: [...]` contract, pass the contract via
+  // `createMockContext` so the typed `ctx.fail` is wired automatically:
+  //   const ctx = createMockContext({ errors: {{RESOURCE_EXPORT}}.errors });
+  //   const err = await {{RESOURCE_EXPORT}}.handler(params, ctx).catch((e) => e);
+  //   expect(err.code).toBe(JsonRpcErrorCode.NotFound);
+  //   expect(err.data.reason).toBe('no_match');
+
   it('lists available resources', async () => {
     const listing = await {{RESOURCE_EXPORT}}.list!();
     expect(listing.resources).toBeInstanceOf(Array);
@@ -139,9 +158,12 @@ import { beforeEach, describe, expect, it } from 'vitest';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
 import { get{{ServiceClass}}, init{{ServiceClass}} } from '@/services/{{domain}}/{{domain}}-service.js';
 
+import { createInMemoryStorage } from '@cyanheads/mcp-ts-core/testing';
+
 describe('{{ServiceClass}}', () => {
   beforeEach(() => {
     // Re-initialize with fresh config/storage for each test
+    const mockStorage = createInMemoryStorage();
     init{{ServiceClass}}(mockConfig, mockStorage);
   });
 
@@ -189,6 +211,23 @@ it('respects cancellation', async () => {
 });
 ```
 
+## Fuzz Testing
+
+For schema-heavy or input-validation-critical handlers, the framework ships fuzz helpers that generate valid + adversarial inputs from your Zod schemas via `fast-check` and assert handler invariants (no crashes, no prototype pollution, no stack-trace leaks):
+
+```typescript
+import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';
+
+it('survives fuzz testing', async () => {
+  const report = await fuzzTool({{TOOL_EXPORT}}, { numRuns: 100 });
+  expect(report.crashes).toHaveLength(0);
+  expect(report.leaks).toHaveLength(0);
+  expect(report.prototypePollution).toBe(false);
+});
+```
+
+Available helpers from `@cyanheads/mcp-ts-core/testing/fuzz`: `fuzzTool`, `fuzzResource`, `fuzzPrompt`, `zodToArbitrary` (custom property-based tests), `adversarialArbitrary` and `ADVERSARIAL_STRINGS` (targeted injection sets). Returns a `FuzzReport` you can assert against. Options: `numRuns`, `numAdversarial`, `seed` (reproducibility), `timeout`, `ctx` (`MockContextOptions` for stateful handlers).
+
 ## Generating Tests from Schemas
 
 When scaffolding tests for an existing handler, use the Zod schemas to generate meaningful test cases:

package/skills/add-tool/SKILL.md

@@ -58,10 +58,16 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
     // All fields need .describe(). Only JSON-Schema-serializable Zod types allowed.
   }),
   // auth: ['tool:{{tool_name}}:read'],
+  // errors: [
+  //   { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No items matched the query.' },
+  //   { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited, when: 'Local queue at capacity.', retryable: true },
+  // ],
 
   async handler(input, ctx) {
     ctx.log.info('Processing', { /* relevant input fields */ });
-    // Pure logic — throw on failure, no try/catch
+    // Pure logic — throw on failure, no try/catch.
+    // With an `errors[]` contract: `throw ctx.fail('reason_id', message?, data?)`.
+    // Without: throw via factories (`notFound`, `validationError`, …) or plain `Error`.
     return { /* output */ };
   },
 
@@ -233,9 +239,37 @@ format: (result) => [{
 
 ### Error classification and messaging
 
-The framework auto-classifies many errors at runtime (HTTP status codes, JS error types, common patterns). Use explicit error factories when you want a specific code and clear recovery guidance; plain `throw new Error()` when auto-classification is sufficient.
+**Recommended: declare an `errors[]` contract.** A typed contract surfaces in `tools/list` and gives the handler a typed `ctx.fail(reason, …)` keyed by the declared reason union — TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated and tamper-proof, and the linter enforces conformance against the handler body.
 
-**Classify by origin** — different sources need different codes:
+```typescript
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+export const fetchArticles = tool('fetch_articles', {
+  description: 'Fetch articles by PMID.',
+  errors: [
+    { reason: 'no_pmid_match', code: JsonRpcErrorCode.NotFound,
+      when: 'None of the requested PMIDs returned data.' },
+    { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
+      when: 'Local request queue at capacity.', retryable: true },
+  ],
+  input: z.object({ pmids: z.array(z.string()).describe('PMIDs to fetch') }),
+  output: z.object({ articles: z.array(ArticleSchema).describe('Resolved articles') }),
+  async handler(input, ctx) {
+    if (queue.full()) throw ctx.fail('queue_full');
+    const articles = await fetch(input.pmids);
+    if (articles.length === 0) {
+      throw ctx.fail('no_pmid_match', `No data for ${input.pmids.length} PMIDs`, { pmids: input.pmids });
+    }
+    return { articles };
+  },
+});
+```
+
+**Baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring. Omit the contract only for throwaway prototypes — declare it everywhere else. Wire-level behavior is identical when omitted, but you lose the type-checked `ctx.fail`, the `tools/list` advertisement, and conformance lint coverage.
+
+`ctx.fail` accepts an optional 4th `options` argument for ES2022 cause chaining: `throw ctx.fail('upstream_error', 'Upstream returned 500', { url }, { cause: e })`.
+
+**Fallback: error factories.** Use when no contract entry fits — ad-hoc throws, prototype tools, or service-layer code. The framework also auto-classifies plain `throw new Error()` from message patterns as a last resort.
 
 ```typescript
 // Client input error — agent can fix and retry
@@ -259,7 +293,7 @@ throw invalidParams(
 );
 ```
 
-**Error messages are recovery instructions.** Name what went wrong, why, and what action to take. The message is the agent's only signal — a bare "Not found" is a dead end.
+**Error messages are recovery instructions.** Name what went wrong, why, and what action to take. The message is the agent's only signal — a bare "Not found" is a dead end. See `skills/api-errors/SKILL.md` for the full contract pattern, factories list, and auto-classification table.
 
 ### Include operational metadata
 
@@ -329,6 +363,7 @@ Large payloads burn the agent's context window. Default to curated summaries; of
 - [ ] `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
 - [ ] If wrapping external API: output schema and `format()` preserve uncertainty from sparse upstream payloads instead of inventing concrete values
 - [ ] `auth` scopes declared if the tool needs authorization
+- [ ] `errors: [...]` contract declared for known domain failure modes (recommended; omit only for throwaway prototypes)
 - [ ] `task: true` added if the tool is long-running
 - [ ] Registered in the project's existing `createApp()` tool list (directly or via barrel)
 - [ ] `bun run devcheck` passes