@cyanheads/mcp-ts-core 0.7.6 → 0.8.1

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.8"
+  version: "1.9"
   audience: external
   type: reference
 ---
@@ -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,39 @@ 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 })`.
+
+**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.
+
+**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 +295,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 +365,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

package/skills/api-context/SKILL.md

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

package/skills/api-errors/SKILL.md

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