first commit

docs/devtools/tooling/mcp/src/schemas/schemas.md

@@ -0,0 +1,62 @@
+# 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.