@cyanheads/mcp-ts-core 0.8.2 → 0.8.3

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

@@ -6,6 +6,7 @@
 import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import type { CallToolResult, ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
 import type { StorageService } from '../../../storage/core/StorageService.js';
+import { type JsonRpcErrorCode } from '../../../types-global/errors.js';
 import type { Logger } from '../../../utils/internal/logger.js';
 import type { AnyToolDefinition } from './toolDefinition.js';
 type SdkExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
@@ -25,6 +26,33 @@ export interface HandlerNotifiers {
     notifyResourceListChanged?: () => void;
     notifyResourceUpdated?: (uri: string) => void;
 }
+/**
+ * Shapes a `CallToolResult` for a tool error response with parity across both
+ * surfaces clients forward to the agent:
+ * - `content[]` — read by clients like Claude Desktop (markdown)
+ * - `structuredContent.error` — read by clients like Claude Code (JSON)
+ *
+ * Both surfaces carry the same payload. When `data.recovery.hint` is present,
+ * it is also mirrored into the `content[]` text so format()-only clients see
+ * the recovery guidance.
+ *
+ * Note: `_meta.error` is intentionally NOT emitted — the error code, message,
+ * and data live on `structuredContent.error` instead, mirroring the success
+ * path's `structuredContent` surface.
+ */
+export declare function buildToolErrorResult(code: JsonRpcErrorCode, message: string, data: Record<string, unknown> | undefined): CallToolResult;
+/**
+ * Builds an error `CallToolResult` from a raw thrown value. Classifies via
+ * {@link ErrorHandler.classifyOnly} when the value isn't already an
+ * `McpError`. Only propagates data from `McpError` (its declared `data`) or
+ * `ZodError` (its `issues`) — other thrown values get a `structuredContent.error`
+ * with `code` and `message` only, so internal classification context never
+ * leaks to clients.
+ *
+ * Use after invoking {@link ErrorHandler.handleError} for OTel/logging side
+ * effects — this helper does not log.
+ */
+export declare function classifyAndBuildToolErrorResult(error: unknown): CallToolResult;
 /**
  * Creates an MCP tool handler from a tool definition.
  * The returned function is compatible with the MCP SDK's ToolCallback type.

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

@@ -1 +1 @@
-{"version":3,"file":"toolHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EACV,cAAc,EAEd,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAGvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,KAAK,QAAQ,GAAG,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAOvE,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/C;AAgCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,gBAAgB,GAC1B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,CAwG9E"}
+{"version":3,"file":"toolHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EACV,cAAc,EAEd,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,KAAK,gBAAgB,EAAY,MAAM,0BAA0B,CAAC;AAE3E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,KAAK,QAAQ,GAAG,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAOvE,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/C;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACxC,cAAc,CAchB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAO9E;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,gBAAgB,GAC1B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,CAiF9E"}

package/dist/mcp-server/tools/utils/toolHandlerFactory.js

@@ -6,7 +6,7 @@
 import { ZodError } from 'zod';
 import { attachTypedFail, createContext } from '../../../core/context.js';
 import { withRequiredScopes } from '../../../mcp-server/transports/auth/lib/authUtils.js';
-import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
+import { McpError } from '../../../types-global/errors.js';
 import { ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
 import { measureToolExecution } from '../../../utils/internal/performance.js';
 import { requestContextService } from '../../../utils/internal/requestContext.js';
@@ -17,6 +17,67 @@ const defaultResponseFormatter = (result) => [
     { type: 'text', text: JSON.stringify(result, null, 2) },
 ];
 // ---------------------------------------------------------------------------
+// Error response shaping
+// ---------------------------------------------------------------------------
+/**
+ * Pulls `data.recovery.hint` from an error data payload when present and
+ * non-empty. Returns `undefined` otherwise. Used to mirror the hint into
+ * `content[]` text so format()-only clients see the same recovery guidance
+ * structuredContent-only clients receive via `error.data.recovery.hint`.
+ */
+function extractRecoveryHint(data) {
+    const hint = data?.recovery?.hint;
+    return typeof hint === 'string' && hint.length > 0 ? hint : undefined;
+}
+/**
+ * Shapes a `CallToolResult` for a tool error response with parity across both
+ * surfaces clients forward to the agent:
+ * - `content[]` — read by clients like Claude Desktop (markdown)
+ * - `structuredContent.error` — read by clients like Claude Code (JSON)
+ *
+ * Both surfaces carry the same payload. When `data.recovery.hint` is present,
+ * it is also mirrored into the `content[]` text so format()-only clients see
+ * the recovery guidance.
+ *
+ * Note: `_meta.error` is intentionally NOT emitted — the error code, message,
+ * and data live on `structuredContent.error` instead, mirroring the success
+ * path's `structuredContent` surface.
+ */
+export function buildToolErrorResult(code, message, data) {
+    const hint = extractRecoveryHint(data);
+    const text = hint ? `Error: ${message}\n\nRecovery: ${hint}` : `Error: ${message}`;
+    return {
+        isError: true,
+        content: [{ type: 'text', text }],
+        structuredContent: {
+            error: {
+                code,
+                message,
+                ...(data !== undefined && { data }),
+            },
+        },
+    };
+}
+/**
+ * Builds an error `CallToolResult` from a raw thrown value. Classifies via
+ * {@link ErrorHandler.classifyOnly} when the value isn't already an
+ * `McpError`. Only propagates data from `McpError` (its declared `data`) or
+ * `ZodError` (its `issues`) — other thrown values get a `structuredContent.error`
+ * with `code` and `message` only, so internal classification context never
+ * leaks to clients.
+ *
+ * Use after invoking {@link ErrorHandler.handleError} for OTel/logging side
+ * effects — this helper does not log.
+ */
+export function classifyAndBuildToolErrorResult(error) {
+    if (error instanceof McpError) {
+        return buildToolErrorResult(error.code, error.message, error.data);
+    }
+    const { code, message } = ErrorHandler.classifyOnly(error);
+    const data = error instanceof ZodError ? { issues: error.issues } : undefined;
+    return buildToolErrorResult(code, message, data);
+}
+// ---------------------------------------------------------------------------
 // Capability detection helpers
 // ---------------------------------------------------------------------------
 function wrapElicit(sdkContext) {
@@ -104,31 +165,11 @@ export function createToolHandler(def, services, notifiers) {
             };
         }
         catch (error) {
-            const handled = ErrorHandler.handleError(error, {
+            ErrorHandler.handleError(error, {
                 operation: `tool:${def.name}`,
                 context: appContext,
             });
-            const mcpError = handled instanceof McpError
-                ? handled
-                : new McpError(JsonRpcErrorCode.InternalError, handled.message, {
-                    originalError: handled.name,
-                });
-            // Surface error classification via _meta so programmatic clients can distinguish error types (auth, validation, not-found, etc.) without parsing the text message. Only propagate data from explicitly thrown McpError instances and ZodError (structured validation issues) — ErrorHandler enrichment contains internal context (stack traces, operation details) that shouldn't be client-visible.
-            const originalData = error instanceof McpError
-                ? error.data
-                : error instanceof ZodError
-                    ? { issues: error.issues }
-                    : undefined;
-            return {
-                isError: true,
-                content: [{ type: 'text', text: `Error: ${mcpError.message}` }],
-                _meta: {
-                    error: {
-                        code: mcpError.code,
-                        ...(originalData !== undefined && { data: originalData }),
-                    },
-                },
-            };
+            return classifyAndBuildToolErrorResult(error);
         }
     };
 }

package/dist/mcp-server/tools/utils/toolHandlerFactory.js.map

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

package/dist/types-global/errors.d.ts

@@ -116,13 +116,9 @@ export type ErrorResponse = z.infer<typeof ErrorSchema>;
  * Lets a definition advertise what it can fail with — the JSON-RPC code, a
  * stable machine-readable `reason`, and a human-readable `when` description.
  *
- * **Where it shows up:**
- * - Surfaced in `tools/list` / `resources/list` under
- *   `_meta['mcp-ts-core/errors']`, so MCP clients and agents can preview failure
- *   modes alongside the input/output schema.
- * - Validated by the startup linter — invalid codes, duplicate `reason` strings
- *   within a single definition, and (with the conformance check enabled)
- *   handler bodies that throw codes not in the contract are flagged.
+ * **Validation.** Checked by the startup linter — invalid codes, duplicate
+ * `reason` strings within a single definition, and (with the conformance check
+ * enabled) handler bodies that throw codes not in the contract are flagged.
  *
  * **Authoring guidance:**
  * - Keep `reason` short, snake_case, stable. Treat it like a CSS class name
@@ -171,19 +167,4 @@ export interface ErrorContract {
      */
     when: string;
 }
-/**
- * The MCP `_meta` namespace key under which `errors[]` is published in
- * `tools/list` and `resources/list`. Namespaced to avoid collisions with
- * other framework or vendor extensions.
- */
-export declare const ERROR_CONTRACT_META_KEY = "mcp-ts-core/errors";
-/**
- * Merges a tool/resource's `errors[]` contract into its `_meta` object under
- * {@link ERROR_CONTRACT_META_KEY}. Returns `undefined` when both sides are
- * absent so callers can spread conditionally without producing an empty
- * `_meta` field. Used by the tool and resource registries.
- *
- * @internal
- */
-export declare function buildMetaWithErrorContract(baseMeta: Record<string, unknown> | undefined, errors: readonly unknown[] | undefined): Record<string, unknown> | undefined;
 //# sourceMappingURL=errors.d.ts.map

package/dist/types-global/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types-global/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types-global/errors.ts"],"names":[],"mappings":"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"}

package/dist/types-global/errors.js

@@ -138,23 +138,4 @@ export const ErrorSchema = z
         .describe('Optional structured data providing more context about the error'),
 })
     .describe('Schema for validating structured error objects, ensuring consistency in error reporting.');
-/**
- * The MCP `_meta` namespace key under which `errors[]` is published in
- * `tools/list` and `resources/list`. Namespaced to avoid collisions with
- * other framework or vendor extensions.
- */
-export const ERROR_CONTRACT_META_KEY = 'mcp-ts-core/errors';
-/**
- * Merges a tool/resource's `errors[]` contract into its `_meta` object under
- * {@link ERROR_CONTRACT_META_KEY}. Returns `undefined` when both sides are
- * absent so callers can spread conditionally without producing an empty
- * `_meta` field. Used by the tool and resource registries.
- *
- * @internal
- */
-export function buildMetaWithErrorContract(baseMeta, errors) {
-    if (!errors || errors.length === 0)
-        return baseMeta;
-    return { ...(baseMeta ?? {}), [ERROR_CONTRACT_META_KEY]: errors };
-}
 //# sourceMappingURL=errors.js.map

package/dist/types-global/errors.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "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",

package/skills/add-resource/SKILL.md

@@ -109,7 +109,7 @@ If the repo already uses `src/mcp-server/resources/definitions/index.ts`, update
 
 ### 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:
+Resources can opt into the same typed error contract as tools — bound to a typed `ctx.fail(reason, …)` keyed by the declared reason union:
 
 ```typescript
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';

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.0"
   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,25 @@ 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.
+  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.
     // 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 +195,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
@@ -265,13 +294,51 @@ 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.
+
+```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 },
+  ],
+  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)
 
-**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.
+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
@@ -365,7 +432,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

@@ -61,11 +61,10 @@ 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 (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.
+**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.
 
@@ -87,7 +86,7 @@ errors: [
 ]
 ```
 
-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 +265,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 +363,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:
 
@@ -408,7 +422,7 @@ The linter validates the structure of `errors[]` and (when present) cross-checks
 
 | 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 +435,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

@@ -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: