---
summary: "Typed error contracts — declarative `errors[]` on tools/resources, typed `ctx.fail(reason)`, advertised in `tools/list`. New `httpErrorFromResponse` and `partialResult` utilities, three more error factories, handler-body + conformance lints"
breaking: false
---

# 0.8.0 — 2026-04-28

Typed error contracts for tools and resources. Backwards compatible — definitions without `errors[]` keep the existing `Context` signature.

## Added

- **`errors: [{ reason, code, when, retryable? }]`** on `tool()` / `resource()` / `appTool()` / `appResource()`. Surfaces in `tools/list` and `resources/list` under `_meta['mcp-ts-core/errors']`. Const-tuple inference flows the reason union into the handler's `ctx.fail`.
- **`ctx.fail(reason, msg?, data?, opts?)`** — typed `TypedFail<R>` keyed against the contract's reasons. `ctx.fail('typo')` is a TS error. Constructs an `McpError` with the contract's code, message (defaults to `when`), and `data.reason` auto-populated from the contract — caller-supplied `data.reason` cannot override it.
- **New core exports:** `TypedFail`, `ReasonOf`, `HandlerContext`, `createFail`. **New `/errors` exports:** `ErrorContract`, `ERROR_CONTRACT_META_KEY`, `buildMetaWithErrorContract`.
- **`httpErrorFromResponse(response, opts?)` and `httpStatusToErrorCode(status)` in `/utils`** — full 4xx/5xx → `JsonRpcErrorCode` table (401/403/408/422/429/5xx). Captures truncated body and `Retry-After` into `error.data`. Supports `service`, `cause`, `codeOverride`. Exports `HttpErrorFromResponseOptions`.
- **`partialResult` / `partialResultSchema` / `failureEntrySchema` in `/utils`** — typed succeeded/failed pattern with stable reason enums. Generic over key names. `failed[]` is omitted when empty. Exports `PartialResultObject`.
- **Three more factories on `/errors`:** `internalError`, `serializationError`, `databaseError`. Same `(message, data?, options?)` signature as the rest.
- **Handler-body lints** (warnings, surfaced in devcheck): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`.
- **Contract lints** (warnings): structural validation (`error-contract-{type,empty,entry-type,code-type,code-unknown,reason-required,reason-format,reason-unique,when-required,retryable-type}`); conformance — `error-contract-conformance` flags undeclared codes thrown from the handler, `error-contract-prefer-fail` flags declared codes thrown directly instead of via `ctx.fail`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) auto-allowed.
- **`createMockContext({ errors })`** — attaches `ctx.fail` against a contract for tests.
- **Tests** for typed-fail propagation, the two new lint families, `httpErrorFromResponse`, `partialResult`, and the auto-task / app-tool integration paths.

## Changed

- **`ToolDefinition` / `ResourceDefinition`** gain a third type parameter `TErrors extends readonly ErrorContract[] | undefined = undefined`. Existing `ToolDefinition<X, Y>` annotations keep working; handler signature collapses to plain `Context` when no contract is declared. `AnyToolDefinition` / `AnyResourceDefinition` widened accordingly.
- **`AGENTS.md` / `CLAUDE.md` / `templates/AGENTS.md` / `templates/CLAUDE.md`** — Error Handling sections rewritten to lead with the contract path, factories demoted to fallback. Exports table and factory list updated.
- **`README.md`** — "Structured errors" feature bullet rewritten as "Typed error contracts".
- **Skills sync** — `add-tool`, `add-resource`, `add-service`, `add-test`, `add-app-tool`, `api-context`, `api-errors`, `api-linter`, `api-testing`, `api-utils`, `design-mcp-server`, `field-test` updated for the new surface. `maintenance` v1.7 → v1.8, `security-pass` v1.1 → v1.2, `report-issue-framework` v1.3 → v1.4.
- **`docs/tree.md`** regenerated.

## Fixed

- Stale `@see docs/service-resilience.md` reference removed from `src/utils/network/retry.ts`.
