@cyanheads/mcp-ts-core 0.8.2 → 0.8.4

package/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: "1.9"
+  version: "2.2"
   audience: external
   type: reference
 ---
@@ -44,6 +44,7 @@ For shape selection (Workflow or Instruction variants — standard single-action
  */
 
 import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 
 export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
   title: '{{TOOL_TITLE}}',
@@ -58,17 +59,36 @@ 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 },
-  // ],
+
+  // Each entry declares a domain-specific failure mode and types
+  // `ctx.fail(reason, …)` against the declared union. Baseline codes
+  // (InternalError, ServiceUnavailable, Timeout, ValidationError,
+  // SerializationError) bubble freely — only declare domain-specific reasons.
+  // Delete this block if no domain failures apply.
+  //
+  // `recovery` is required (≥ 5 words) — it's the agent's next move when this
+  // failure fires. Forcing function for thoughtful guidance: placeholders like
+  // "Try again." get flagged by the linter. Contract-level `recovery` is
+  // descriptive metadata; for the wire payload's `data.recovery.hint` (which
+  // the framework mirrors into content[] text), pass it explicitly at the
+  // throw site when dynamic context matters.
+  errors: [
+    { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+      when: 'No items matched the query.',
+      recovery: 'Broaden the query or check the spelling and try again.' },
+    { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
+      when: 'Local queue at capacity.', retryable: true,
+      recovery: 'Wait a few seconds before retrying or reduce batch size.' },
+  ],
 
   async handler(input, ctx) {
     ctx.log.info('Processing', { /* relevant input fields */ });
     // 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 */ };
+    const items = await search(input);
+    if (items.length === 0) throw ctx.fail('no_match', `No items matched "${input.query}"`);
+    return { items };
   },
 
   // format() populates MCP content[] — the markdown twin of structuredContent.
@@ -186,18 +206,38 @@ Single-item tools don't need this — they either succeed or throw. The partial
 
 ### Empty results need context
 
-An empty array with no explanation is a dead end. Echo back the criteria that produced zero results and, where possible, suggest how to broaden the search.
+An empty array with no explanation is a dead end. Echo back the criteria that produced zero results and, where possible, suggest how to broaden the search. The recovery hint needs three pieces working together — schema entry, handler return, and `format()` rendering — or the `format-parity` lint will flag the missing field.
 
 ```typescript
-// In handler — after getting zero results:
-if (results.length === 0) {
-  return {
-    items: [],
-    totalCount: 0,
-    message: `No items matched status="${input.status}" in project "${input.project}". `
-      + `Try a broader status filter or verify the project name.`,
-  };
-}
+// 1. Output schema — declare the recovery field so the linter sees it
+output: z.object({
+  items: z.array(ItemSchema).describe('Matching items.'),
+  totalCount: z.number().describe('Total matches before pagination.'),
+  message: z.string().optional()
+    .describe('Recovery hint when results are empty — echoes filters and suggests how to broaden. Absent on successful result pages.'),
+}),
+
+// 2. Handler — populate `message` when the result is empty
+async handler(input, ctx) {
+  const results = await search(input);
+  if (results.length === 0) {
+    return {
+      items: [],
+      totalCount: 0,
+      message: `No items matched status="${input.status}" in project "${input.project}". `
+        + `Try a broader status filter or verify the project name.`,
+    };
+  }
+  return { items: results, totalCount: results.length };
+},
+
+// 3. format() — render the recovery hint so content[]-only clients see it too
+format: (result) => {
+  const lines = [`**Total:** ${result.totalCount}`];
+  if (result.message) lines.push(`\n> ${result.message}`);
+  for (const item of result.items) lines.push(`- ${item.name}`);
+  return [{ type: 'text', text: lines.join('\n') }];
+},
 ```
 
 ### Sparse upstream data must stay honest
@@ -248,9 +288,11 @@ 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.' },
+      when: 'None of the requested PMIDs returned data.',
+      recovery: 'Try pubmed_search_articles to discover valid PMIDs first.' },
     { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
-      when: 'Local request queue at capacity.', retryable: true },
+      when: 'Local request queue at capacity.', retryable: true,
+      recovery: 'Wait 30 seconds and retry, or reduce batch size.' },
   ],
   input: z.object({ pmids: z.array(z.string()).describe('PMIDs to fetch') }),
   output: z.object({ articles: z.array(ArticleSchema).describe('Resolved articles') }),
@@ -265,13 +307,52 @@ export const fetchArticles = tool('fetch_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.
+**Baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring. Wire-level behavior is identical when the contract is omitted, but you lose the type-checked `ctx.fail`, the `tools/list` advertisement, and conformance lint coverage — declare a contract whenever the tool has a domain-specific failure mode.
 
 `ctx.fail` accepts an optional 4th `options` argument for ES2022 cause chaining: `throw ctx.fail('upstream_error', 'Upstream returned 500', { url }, { cause: e })`.
 
-**Service-thrown contract reasons.** When the throw happens in a called service rather than the handler itself, `ctx.fail` isn't reachable — services don't have `ctx`. Pass `data: { reason: 'X' }` to the factory in the service; the framework's auto-classifier preserves `data` on the wire, so the contract reason rides through unchanged. The handler bubbles the error without catching. See `add-service` for the pattern.
+#### Service-layer throws
+
+API-wrapping tools usually delegate to a service: `const data = await ncbi.fetch(input)`. The throw lives in the service, not the handler — and services don't receive `ctx`, so `ctx.fail` is unreachable from there. The fix is to pass `data: { reason: 'X' }` to the factory in the service. The framework's auto-classifier preserves `data` on the wire, so clients see the same `error.data.reason` they would have seen from `ctx.fail`. The handler doesn't catch — it just bubbles.
+
+The contract entry on the tool and the `data: { reason }` on the service throw need to use the **same reason string** so the two sides line up.
 
-**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
+// service — passes data.reason to match the consuming tool's contract
+import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+
+export class NcbiService {
+  async fetch(pmids: string[]) {
+    const response = await fetchWithRetry(...);
+    if (!response.ok) {
+      throw serviceUnavailable(
+        `NCBI returned HTTP ${response.status}`,
+        { reason: 'ncbi_unreachable', status: response.status },  // ← matches contract entry
+        { cause: undefined },
+      );
+    }
+    return response.json();
+  }
+}
+
+// tool — declares the matching contract entry, calls the service, doesn't catch
+export const fetchArticles = tool('fetch_articles', {
+  errors: [
+    { reason: 'ncbi_unreachable', code: JsonRpcErrorCode.ServiceUnavailable,
+      when: 'NCBI E-utilities is unreachable.', retryable: true,
+      recovery: 'NCBI is degraded; retry in a few minutes.' },
+  ],
+  async handler(input, ctx) {
+    return { articles: await ncbi.fetch(input.pmids) };  // throws bubble unchanged
+  },
+});
+```
+
+See `add-service` for the full pattern.
+
+#### Ad-hoc factory throws (fallback)
+
+When no contract entry fits — prototype code, one-off throws, or service-layer fallbacks — use error factories or plain `throw new Error()`. The framework auto-classifies plain `Error` from message patterns as a last resort.
 
 ```typescript
 // Client input error — agent can fix and retry
@@ -287,15 +368,23 @@ throw notFound(
 import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
 throw serviceUnavailable(`arXiv API returned HTTP ${status}. Retry in a few seconds.`);
 
-// Structured hint for programmatic recovery
+// Recovery hint via the canonical `data.recovery.hint` shape — the framework
+// auto-mirrors it into the content[] text as `Recovery: <hint>`, so format()-only
+// clients (Claude Desktop) see the same guidance that structuredContent clients
+// (Claude Code) read from `error.data.recovery.hint`. Other `data` keys reach
+// structuredContent only.
 import { invalidParams } from '@cyanheads/mcp-ts-core/errors';
 throw invalidParams(
-  `Date range exceeds 90-day API limit. Narrow the range or split into multiple queries.`,
-  { maxDays: 90, requestedDays: daysBetween },
+  `Date range exceeds 90-day API limit.`,
+  {
+    maxDays: 90,
+    requestedDays: daysBetween,
+    recovery: { hint: 'Narrow the range or split into multiple queries.' },
+  },
 );
 ```
 
-**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.
+**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, auto-classification table, and error-path parity (how `data.recovery.hint` reaches both client surfaces).
 
 ### Include operational metadata
 
@@ -365,7 +454,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)
+- [ ] `errors: [...]` contract declared for the tool's domain-specific failure modes — or block deleted if no domain failures apply (baseline codes bubble freely)
 - [ ] `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

package/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.1"
+  version: "1.2"
   audience: external
   type: reference
 ---
@@ -37,11 +37,14 @@ export const fetchTool = tool('fetch_articles', {
 
   errors: [
     { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
-      when: 'No requested PMID returned data' },
+      when: 'No requested PMID returned data',
+      recovery: 'Try pubmed_search_articles to discover valid PMIDs first.' },
     { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
-      when: 'Local request queue is at capacity', retryable: true },
+      when: 'Local request queue is at capacity', retryable: true,
+      recovery: 'Wait 30 seconds and retry, or reduce batch size.' },
     { reason: 'ncbi_down', code: JsonRpcErrorCode.ServiceUnavailable,
-      when: 'NCBI E-utilities unreachable after retries', retryable: true },
+      when: 'NCBI E-utilities unreachable after retries', retryable: true,
+      recovery: 'NCBI is degraded; retry in a few minutes.' },
   ],
 
   async handler(input, ctx) {
@@ -61,11 +64,12 @@ 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. |
-| `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 (startup) | Each `code` validated against `JsonRpcErrorCode`. Reasons validated as snake_case + unique within contract. `recovery` validated as non-empty and ≥ 5 words. |
 | 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.
+> **`recovery` is descriptive, not auto-injected.** 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 is **not** auto-populated into runtime `data.recovery.hint`. The wire payload's recovery hint — which the framework mirrors into `content[]` text per the [error-path parity](#error-path-parity) invariant — is populated separately at the throw site, where dynamic context (input values, attempted IDs, queue state) is available: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. The two fields can carry the same string when no dynamic context is needed; they're decoupled by design — what the author writes at the throw site is what flows to the wire, with no hidden transformation.
+
+**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.
 
 > **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.
 
@@ -82,12 +86,16 @@ throw serviceUnavailable('Upstream timeout',          { reason: 'evaluation_time
 ```ts
 // my-tool.tool.ts
 errors: [
-  { reason: 'empty_expression',   code: JsonRpcErrorCode.ValidationError,    when: 'Input is empty.' },
-  { reason: 'evaluation_timeout', code: JsonRpcErrorCode.ServiceUnavailable, when: 'Upstream exceeded the configured timeout.' },
+  { reason: 'empty_expression',   code: JsonRpcErrorCode.ValidationError,
+    when: 'Input is empty.',
+    recovery: 'Provide a non-empty expression to evaluate.' },
+  { reason: 'evaluation_timeout', code: JsonRpcErrorCode.ServiceUnavailable,
+    when: 'Upstream exceeded the configured timeout.',
+    recovery: 'Simplify the expression or retry the request after a brief delay.' },
 ]
 ```
 
-The handler doesn't catch and re-throw — letting service errors bubble unchanged keeps "logic throws, framework catches" intact. The contract still publishes in `tools/list`, 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.
+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.
 
 ---
 
@@ -266,9 +274,24 @@ Checked before common patterns. Cover: AWS exception names, HTTP status codes, D
 | Layer | Pattern |
 |:------|:--------|
 | Tool/resource handlers | Throw `McpError` — no try/catch |
-| Handler factory | Catches all errors, normalizes to `McpError`, sets `isError: true` |
+| Handler factory (tools) | Catches all errors, normalizes to `McpError`, sets `isError: true`, mirrors error across both client surfaces (see [Error-path parity](#error-path-parity)) |
+| Handler factory (resources) | Catches and re-throws to the SDK, which routes through the JSON-RPC error envelope |
 | Services/setup code | `ErrorHandler.tryCatch` for graceful recovery |
 
+### Error-path parity
+
+MCP clients differ in which `CallToolResult` surface they forward to the agent. Tool errors mirror the success-path `format-parity` invariant — both surfaces carry the same payload:
+
+| Surface | Content | Read by |
+|:--------|:--------|:--------|
+| `content[]` | Text rendering: `Error: <message>` (plus `Recovery: <hint>` when `data.recovery.hint` is present) | Claude Desktop and other format()-only clients |
+| `structuredContent.error` | JSON `{ code, message, data? }` carrying the error code, message, and any structured data from the thrown `McpError` or `ZodError` | Claude Code and other structuredContent-only clients |
+
+Important properties:
+- **`_meta.error` is NOT emitted.** Error code/data live on `structuredContent.error` instead. Don't read `_meta.error` in clients or tests — it doesn't exist.
+- **`data` propagation is restricted** to explicitly-thrown `McpError.data` and `ZodError.issues`. Auto-classified plain errors (`TypeError`, network errors, etc.) emit `code` + `message` only — no `data` — so internal classification context never leaks to clients.
+- **Recovery hint mirroring is automatic.** When the thrown `McpError` carries `data.recovery.hint`, the handler factory appends it to the `content[]` text so the markdown surface matches the JSON surface. Authors don't need to format the hint manually.
+
 **Handler — throw freely, no try/catch:**
 
 ```ts
@@ -349,7 +372,7 @@ if (!response.ok) {
 
 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.
+> **Body reaches the client.** `error.data` is forwarded to the MCP client as `structuredContent.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:
 
@@ -402,13 +425,16 @@ The linter validates the structure of `errors[]` and (when present) cross-checks
 | `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-recovery-required` | error | `recovery` missing or not a string |
+| `error-contract-recovery-empty` | error | `recovery` is empty/whitespace-only |
+| `error-contract-recovery-min-words` | warning | `recovery` has fewer than 5 words — placeholders like "Try again." or "Check input." get flagged in favor of specific guidance |
 | `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-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. |
 
 ### Baseline codes (auto-allowed)
@@ -421,7 +447,7 @@ These codes bubble up from anywhere — services, framework utilities, the auto-
 - `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.
+If you *want* to declare one of these as a domain-specific failure (e.g., a tool that intentionally times out under defined conditions), put it in `errors[]` anyway — the contract still binds `ctx.fail(reason)` and the conformance lint will catch undeclared throws. The lint just doesn't *require* you to enumerate baselines.
 
 ### When to declare vs. let it bubble
 

package/skills/api-linter/SKILL.md

@@ -502,7 +502,7 @@ throw serviceUnavailable('Upstream failed', { upstreamError: e }, { cause: e });
 
 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.
+When a contract is declared, 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
 

package/skills/design-mcp-server/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "2.7"
+  version: "2.8"
   audience: external
   type: workflow
 ---
@@ -323,7 +323,7 @@ The pattern: name the shortcut for what it does (`text_search`, `name_search`),
 
 Errors are part of the tool's interface — design them during the design phase, not as an afterthought. Three aspects: **the contract** (which failures are public), **classification** (what error code), and **messaging** (what the LLM reads).
 
-**Declare a typed contract for domain failures.** When a tool has known failure modes the agent should plan around (`no_match`, `queue_full`, `vendor_down`), enumerate them as `errors: [{ reason, code, when, retryable? }]` on the definition. The framework publishes the contract under `tools/list` `_meta['mcp-ts-core/errors']` so capable clients can preview failure modes, types `ctx.fail(reason, …)` against the declared reason union (typos become TS errors), and auto-populates `_meta.error.data.reason` on responses for stable observability. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble from anywhere and don't need to be enumerated. See `api-errors` skill for the full pattern.
+**Declare a typed contract for domain failures.** When a tool has known failure modes the agent should plan around (`no_match`, `queue_full`, `vendor_down`), enumerate them as `errors: [{ reason, code, when, retryable? }]` on the definition. The framework types `ctx.fail(reason, …)` against the declared reason union (typos become TS errors) and auto-populates `data.reason` on the thrown error for stable observability. The error reaches clients with parity across both surfaces — `structuredContent.error` (Claude Code) and `content[]` text (Claude Desktop). Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble from anywhere and don't need to be enumerated. See `api-errors` skill for the full pattern.
 
 **Classify errors by origin.** Different error sources need different codes and different recovery guidance. Map the failure modes for each tool during design:
 
@@ -346,10 +346,17 @@ throw new Error('Not found');
 // Good — names both resolution options
 "No session working directory set. Please specify a 'path' or use 'git_set_working_dir' first."
 
-// Good — structured hint in error data
+// Good — structured hint in error data using the canonical `data.recovery.hint` shape.
+// The framework auto-mirrors `data.recovery.hint` into the content[] text as
+// `Recovery: <hint>` so format()-only clients (Claude Desktop) see the same
+// guidance structuredContent clients (Claude Code) read from `error.data.recovery.hint`.
 throw forbidden(
   "Cannot perform 'reset --hard' on protected branch 'main' without explicit confirmation.",
-  { branch: 'main', operation: 'reset --hard', hint: 'Set the confirmed parameter to true to proceed.' },
+  {
+    branch: 'main',
+    operation: 'reset --hard',
+    recovery: { hint: 'Set the confirmed parameter to true to proceed.' },
+  },
 );
 
 // Good — upstream error with actionable context

package/skills/field-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
 metadata:
   author: cyanheads
-  version: "2.1"
+  version: "2.2"
   audience: external
   type: debug
 ---
@@ -15,6 +15,15 @@ Unit tests (`add-test` skill) verify handler logic with mocked context. Field te
 
 **Actively call the tools. Don't read code and guess.**
 
+### Transport coverage
+
+This skill drives an HTTP server because curl + JSON-RPC is the most reliable harness for shell-based agents. Most servers ship both transports (`bun run dev:http` and `dev:stdio`), so HTTP coverage is sufficient: the same handler runs on both, only the framing differs. If the server is **stdio-only** (no HTTP transport in `package.json` / no `MCP_TRANSPORT_TYPE=http` path), drive it through one of:
+
+- **MCP Inspector** (`npx @modelcontextprotocol/inspector bun run dev:stdio`) — interactive UI for catalog browsing and tool calls; best for hands-on exploration
+- **mcp-cli** (`uvx mcp-cli --stdio bun run dev:stdio`) — scriptable JSON-RPC client; best for batch/agentic testing
+
+Adapt the test plan below the same way — universal battery on every definition, situational categories only when triggered, same error-contract verification — but call the tools through the inspector / mcp-cli rather than `mcp_call`. Pino startup + handler logs land on stderr in stdio mode (stdout is reserved for JSON-RPC), so tail with `2>/tmp/mcp-server.log` if you start the server yourself.
+
 ---
 
 ## Steps
@@ -190,8 +199,8 @@ Runs `initialize`, captures the session id, sends `notifications/initialized`.
 
 ```bash
 . /tmp/mcp-field-test.sh
-mcp_call tools/list     | jq '.result.tools[]     | {name, description, inputSchema, outputSchema, errors: ._meta["mcp-ts-core/errors"]}'
-mcp_call resources/list | jq '.result.resources[] | {uri, name, mimeType, errors: ._meta["mcp-ts-core/errors"]}'
+mcp_call tools/list     | jq '.result.tools[]     | {name, description, inputSchema, outputSchema}'
+mcp_call resources/list | jq '.result.resources[] | {uri, name, mimeType}'
 mcp_call prompts/list   | jq '.result.prompts[]   | {name, description, arguments}'
 ```
 
@@ -229,7 +238,7 @@ Treat any hit as a `ux` finding in the report. The authoring rule lives under *T
 | Hits external API / live upstream | One call that exercises upstream; note rate-limit / timeout / transient-failure behavior |
 | Chained with other tools (search → detail → act) | Run one representative chain end-to-end; does each step return the IDs/cursors the next needs? |
 | `cursor` / `offset` / `limit` params | Pagination: second page, end-of-list |
-| Tool declared an `errors: [...]` contract | Error contract (tool): trigger ≥1 declared failure mode. Verify `result._meta.error.code` matches the contract entry, `result._meta.error.data.reason` is the declared reason (only present when the handler threw an `McpError` — `ctx.fail` always does, plain `throw new Error(...)` does not), and `content[0].text` is actionable. Reasons declared but unreachable from any input are dead contract entries. |
+| Tool declared an `errors: [...]` contract | Error contract (tool): trigger ≥1 declared failure mode. Verify `result.structuredContent.error.code` matches the contract entry, `result.structuredContent.error.data.reason` is the declared reason (only present when the handler threw an `McpError` — `ctx.fail` always does, plain `throw new Error(...)` does not), and `content[0].text` is actionable. Reasons declared but unreachable from any input are dead contract entries. |
 | Resource declared an `errors: [...]` contract | Error contract (resource): trigger ≥1 declared failure mode by reading a URI that exercises it. Resources re-throw errors at the JSON-RPC level — verify `error.code` matches the contract entry and `error.data.reason` is the declared reason. (Resources don't use the `result.isError` envelope — they fail the request itself.) |
 
 **Resources.** Happy path, not-found URI, `list` if defined, pagination if used.
@@ -253,7 +262,7 @@ When a call surprises you — slow, hangs, returns terse output, surfaces an unh
 **Interpreting responses**
 
 - Tool domain errors return `{result: {content: [...], isError: true}}` — they live in `result`, not `error`. Check `isError`, not the JSON-RPC error field.
-- **Tool error code/reason** rides on `result._meta.error.{code, data.reason}` — inspect that, not just the text. `data` is only spread when the handler threw an `McpError` (or `ZodError`); plain `throw new Error(...)` won't populate `data.reason`. Use `ctx.fail`-thrown errors when the contract reason matters.
+- **Tool error code/reason** rides on `result.structuredContent.error.{code, message, data?.reason}` — inspect that, not just the text. `data` is only spread when the handler threw an `McpError` (or `ZodError`); plain `throw new Error(...)` won't populate `data.reason`. Use `ctx.fail`-thrown errors when the contract reason matters. The text in `result.content[0].text` mirrors the message and includes `Recovery: <hint>` when `data.recovery.hint` is present.
 - **Resource errors** are JSON-RPC-level — they appear in the top-level `error.{code, data.reason}` field, not inside `result`. Resource handlers re-throw rather than producing an `isError` envelope.
 - JSON-RPC `error` only appears for protocol issues (bad session, malformed envelope, unknown method).
 - `mcp_call` already strips SSE framing. Pipe to `jq` for readability.
@@ -317,7 +326,7 @@ End with:
 - [ ] Catalog surfaced and presented; descriptions audited for leaks (implementation details, meta-coaching, consumer-aware phrasing)
 - [ ] Universal battery run on every definition
 - [ ] Situational categories applied only when triggered
-- [ ] **If a tool declared an `errors: [...]` contract:** ≥1 declared failure mode triggered; `result._meta.error.code` and `data.reason` verified against the contract entry
+- [ ] **If a tool declared an `errors: [...]` contract:** ≥1 declared failure mode triggered; `result.structuredContent.error.code` and `data.reason` verified against the contract entry
 - [ ] **If a resource declared an `errors: [...]` contract:** ≥1 declared failure mode triggered; top-level JSON-RPC `error.code` and `error.data.reason` verified against the contract entry
 - [ ] External-state / auth-gated tools handled explicitly (run, skip, or confirm)
 - [ ] Server stopped; state file removed

package/templates/AGENTS.md

@@ -90,6 +90,7 @@ export const searchItems = tool('search_items', {
 
 ```ts
 import { resource, z } from '@cyanheads/mcp-ts-core';
+import { notFound } from '@cyanheads/mcp-ts-core/errors';
 
 export const itemData = resource('inventory://{itemId}', {
   description: 'Fetch an inventory item by ID.',
@@ -97,7 +98,7 @@ export const itemData = resource('inventory://{itemId}', {
   auth: ['inventory:read'],
   async handler(params, ctx) {
     const item = await ctx.state.get(`item:${params.itemId}`);
-    if (!item) throw new Error(`Item ${params.itemId} not found`);
+    if (!item) throw notFound(`Item ${params.itemId} not found`, { itemId: params.itemId });
     return item;
   },
 });
@@ -167,11 +168,13 @@ 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, retryable? }]` on `tool()` / `resource()` to advertise the failure surface in `tools/list` (under `_meta['mcp-ts-core/errors']`) and receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire payload's `data.recovery.hint` (which the framework mirrors into `content[]` text), pass it explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
 errors: [
-  { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No item matched the query' },
+  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+    when: 'No item matched the query',
+    recovery: 'Broaden the query or check the spelling and try again.' },
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);

package/templates/CLAUDE.md

@@ -90,6 +90,7 @@ export const searchItems = tool('search_items', {
 
 ```ts
 import { resource, z } from '@cyanheads/mcp-ts-core';
+import { notFound } from '@cyanheads/mcp-ts-core/errors';
 
 export const itemData = resource('inventory://{itemId}', {
   description: 'Fetch an inventory item by ID.',
@@ -97,7 +98,7 @@ export const itemData = resource('inventory://{itemId}', {
   auth: ['inventory:read'],
   async handler(params, ctx) {
     const item = await ctx.state.get(`item:${params.itemId}`);
-    if (!item) throw new Error(`Item ${params.itemId} not found`);
+    if (!item) throw notFound(`Item ${params.itemId} not found`, { itemId: params.itemId });
     return item;
   },
 });
@@ -167,11 +168,13 @@ 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, retryable? }]` on `tool()` / `resource()` to advertise the failure surface in `tools/list` (under `_meta['mcp-ts-core/errors']`) and receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire payload's `data.recovery.hint` (which the framework mirrors into `content[]` text), pass it explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
 errors: [
-  { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No item matched the query' },
+  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+    when: 'No item matched the query',
+    recovery: 'Broaden the query or check the spelling and try again.' },
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);

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

@@ -4,6 +4,7 @@
  */
 
 import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 
 // Tool names are snake_case, prefixed with your server name to avoid collisions across servers.
 // e.g. for a "tasks" server: tasks_fetch_list, tasks_create_item.
@@ -17,7 +18,24 @@ export const echoTool = tool('template_echo_message', {
     message: z.string().describe('The echoed message.'),
   }),
 
-  handler(input) {
+  // Declare each domain failure mode the agent should plan around. The framework
+  // types `ctx.fail(reason, …)` against the declared union. Baseline codes
+  // (InternalError, ServiceUnavailable, Timeout, ValidationError,
+  // SerializationError) bubble freely — only declare domain-specific reasons.
+  // Delete this block if no domain-specific failures apply to your tool.
+  errors: [
+    {
+      reason: 'empty_message',
+      code: JsonRpcErrorCode.InvalidParams,
+      when: 'Message contained only whitespace.',
+      recovery: 'Provide a message with at least one non-whitespace character.',
+    },
+  ],
+
+  handler(input, ctx) {
+    if (input.message.trim().length === 0) {
+      throw ctx.fail('empty_message', 'Message must contain at least one non-whitespace character.');
+    }
     return { message: input.message };
   },