# error-codes

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`@suaveplan/mcp` raises three typed error classes — `MCPError`, `MCPTransportError`, and `MCPProtocolError` — for every failure mode the package exposes. Codes are registered via `defineCodes` from `@suaveplan/error`, giving consumers a stable fully-qualified string (e.g. `"MCP.UNAUTHORIZED"`) they can pattern-match on without `instanceof` chains. Discriminating on `error.code` keeps consumers, retries, dashboards, and i18n catalogues in lockstep with the package no matter how the class hierarchy evolves.

## Features

- Stable code registry: 15 codes spanning protocol, transport, lifecycle, registration, and handler failures.
- Three classes (`MCPError`, `MCPTransportError`, `MCPProtocolError`) — extends `SuaveplanError<MCPCode>` so callers get the cause-chain, redaction, OTel adapter, and i18n resolver hook for free.
- Type-safe `code` discriminator — no `instanceof` required.
- Public constructors delegate to `super` per `@suaveplan/error` policy.

## Usage: Basic Example

```ts
import { MCP_CODES, MCPError } from "@suaveplan/mcp/error-codes";

throw new MCPError(MCP_CODES.NOT_FOUND, 'Tool "echo" not found');
```

## Usage: Advanced Example

```ts
import { MCP_CODES, MCPError, MCPTransportError } from "@suaveplan/mcp";

try {
    await client.callTool("slow", { ms: 10_000 }, { timeoutMs: 100 });
} catch (error) {
    if (error instanceof MCPTransportError) {
        metrics.record("mcp.transport_error");
        return;
    }
    if (error instanceof MCPError && error.code === MCP_CODES.TIMEOUT) {
        logger.warn("call timed out", { code: error.code });
        return;
    }
    throw error;
}
```

## API Reference

- `MCP_CODES` — frozen object whose values are the fully-qualified code strings (`"MCP.<LEAF>"`).
- `MCPCode` — string-literal union of every value of `MCP_CODES`.
- `MCPError extends SuaveplanError<MCPCode>` — constructor: `(code, message, options?)`.
- `MCPTransportError extends MCPError` — same constructor; thrown when the underlying transport rejects a `send` (`TRANSPORT_CLOSED`) or surfaces an upstream failure (`TRANSPORT_ERROR`).
- `MCPProtocolError extends MCPError` — thrown for `PROTOCOL_INVALID` and `PROTOCOL_VERSION_MISMATCH`.

## Implementation Notes

The registry is declared via `defineCodes("MCP", [...] as const)` which asserts the array is a literal tuple and produces a `Record<Key, "MCP.Key">` mapping. Adding a code anywhere except the tuple breaks both the type and the runtime registry — the type-system guarantees the two stay in sync. Every registered code is reachable from a real call site exercised by a test (see `error-codes.test.ts`). The constructor delegates to `SuaveplanError`'s protected constructor; subclasses keep `name` distinct so logs and traces can still distinguish transport from protocol failures even though they share the typed-code surface.