schemas

(no submodules)

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

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

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

Usage: Advanced Example

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.

3.1 KiB Raw Blame History