# schemas

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

## Purpose

`schemas.ts` is the single source of truth for every wire shape in `@suaveplan/mcp`. Every public TypeScript type for an MCP wire payload — JSON-RPC envelopes, initialize, tool/resource/prompt records, sampling, completion, roots, logging, progress, cancellation — is derived via `z.infer<>` from a schema declared here. The schema IS the contract, so the runtime parser and the static TS type can never drift apart: changing one is changing the other.

## Features

- JSON-RPC 2.0 envelope schemas: `JsonRpcRequestSchema`, `JsonRpcResponseSchema`, `JsonRpcNotificationSchema`, and the `JsonRpcMessageSchema` discriminated union.
- Initialize handshake: `InitializeParamsSchema`, `InitializeResultSchema`, `ClientCapabilitiesSchema`, `ServerCapabilitiesSchema`, `ImplementationSchema`.
- Tools: `ToolSchema`, `ToolsListResultSchema`, `ToolCallParamsSchema`, `ToolCallResultSchema`.
- Resources: `ResourceSchema`, `ResourceTemplateSchema`, `ResourceContentSchema`, plus `*Read` / `*Subscribe` params.
- Prompts: `PromptSchema`, `PromptArgumentSchema`, `PromptMessageSchema`, `PromptGetParamsSchema`, `PromptGetResultSchema`.
- Sampling + completion + roots + logging schemas.
- Notification params: `ProgressNotificationParamsSchema`, `CancelledNotificationParamsSchema`, `LoggingMessageParamsSchema`.

## Usage: Basic Example

```ts
import { JsonRpcRequestSchema } from "@suaveplan/mcp/schemas";

const request = JsonRpcRequestSchema.parse({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/list",
});
```

## Usage: Advanced Example

```ts
import {
    type ToolCallParams,
    ToolCallParamsSchema,
} from "@suaveplan/mcp";

function safeToolCall(raw: unknown): ToolCallParams | null {
    const parsed = ToolCallParamsSchema.safeParse(raw);
    if (!parsed.success) {
        for (const issue of parsed.error.issues) {
            metrics.record("mcp.invalid_params", { path: issue.path.join(".") });
        }
        return null;
    }
    return parsed.data;
}
```

## API Reference

- Every schema is exported alongside its inferred TypeScript type (`<Name>Schema` + `<Name>`).
- Schemas validate strictly — extra fields are preserved but the inferred type only includes declared shapes.
- `JsonRpcMessageSchema` is a `z.union` over request/response/notification; downstream code uses `safeParse` to discriminate.
- `ContentItemSchema` is a `z.discriminatedUnion("type", ...)` over text, image, and inline-resource variants.

## Implementation Notes

The `import z from "zod"` form is the Bun-safe default-import idiom mandated by the suaveplan guidelines; the named `{ z }` form fails under Bun's CJS interop for the Zod 4 build. `_meta.progressToken` is `string | number | undefined` because the MCP spec allows both shapes and a missing token means progress is not requested. Server- and client-side dispatchers register a subset of these schemas as the params-validation map for the JSON-RPC dispatcher: invalid params produce a JSON-RPC `-32602` response mapped to `MCPError(INVALID_PARAMS)` carrying the failing field path.