fix(core): address review on isSpecType/specTypeSchemas

- Explicit auth-schema allowlist (excludes SafeUrl/OptionalSafeUrl/IdJagTokenExchangeResponse helpers)
- Guard predicate types value as schema input (z.input), not output, since safeParse only proves input shape
- SchemaRecord typed as StandardSchemaV1<In, Out> so validate() output is the spec type
- JSDoc/migration examples await validate() (Result | Promise<Result>); drop stale setCustom* refs

Author: felixweinberger

docs/migration-SKILL.md

@@ -439,12 +439,12 @@ Remove unused schema imports: `CallToolResultSchema`, `CompatibilityCallToolResu
 
 If a `*Schema` constant was used for **runtime validation** (not just as a `request()` argument), replace with `isSpecType` / `specTypeSchemas`:
 
-| v1 pattern                                         | v2 replacement                                               |
-| -------------------------------------------------- | ------------------------------------------------------------ |
-| `CallToolResultSchema.safeParse(value).success`    | `isSpecType.CallToolResult(value)`                           |
-| `<TypeName>Schema.safeParse(value).success`        | `isSpecType.<TypeName>(value)`                               |
-| `<TypeName>Schema.parse(value)`                    | `specTypeSchemas.<TypeName>['~standard'].validate(value)`    |
-| Passing `<TypeName>Schema` as a validator argument | `specTypeSchemas.<TypeName>` (returns `StandardSchemaV1<T>`) |
+| v1 pattern                                         | v2 replacement                                                                         |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `CallToolResultSchema.safeParse(value).success`    | `isSpecType.CallToolResult(value)`                                                     |
+| `<TypeName>Schema.safeParse(value).success`        | `isSpecType.<TypeName>(value)`                                                         |
+| `<TypeName>Schema.parse(value)`                    | `await specTypeSchemas.<TypeName>['~standard'].validate(value)` (returns a `Result`, not the value) |
+| Passing `<TypeName>Schema` as a validator argument | `specTypeSchemas.<TypeName>` (a `StandardSchemaV1<In, Out>`)                           |
 
 `isCallToolResult(value)` still works, but `isSpecType` covers every spec type by name.
 

docs/migration.md

@@ -461,11 +461,10 @@ const blocks = mixed.filter(isSpecType.ContentBlock);
 
 // v2: or get the StandardSchemaV1 validator object directly
 import { specTypeSchemas } from '@modelcontextprotocol/client';
-const result = specTypeSchemas.CallToolResult['~standard'].validate(value);
+const result = await specTypeSchemas.CallToolResult['~standard'].validate(value);
 ```
 
-`isSpecType` and `specTypeSchemas` are keyed by `SpecTypeName` — a literal union of every named type in the MCP spec — so you get autocomplete and a compile error on typos. `specTypeSchemas.X` is a `StandardSchemaV1<T>`, which composes with any Standard-Schema-aware library and is accepted
-by `setCustomRequestHandler`/`sendCustomRequest`. The pre-existing `isCallToolResult(value)` guard still works.
+`isSpecType` and `specTypeSchemas` are keyed by `SpecTypeName` — a literal union of every named type in the MCP spec — so you get autocomplete and a compile error on typos. `specTypeSchemas.X` is a `StandardSchemaV1<In, Out>`, which composes with any Standard-Schema-aware library. The pre-existing `isCallToolResult(value)` guard still works.
 
 ### Client list methods return empty results for missing capabilities
 

packages/core/src/types/specTypeSchema.ts

@@ -1,9 +1,35 @@
 import type * as z from 'zod/v4';
 
-import * as authSchemas from '../shared/auth.js';
+import {
+    OAuthClientInformationFullSchema,
+    OAuthClientInformationSchema,
+    OAuthClientMetadataSchema,
+    OAuthClientRegistrationErrorSchema,
+    OAuthErrorResponseSchema,
+    OAuthMetadataSchema,
+    OAuthProtectedResourceMetadataSchema,
+    OAuthTokenRevocationRequestSchema,
+    OAuthTokensSchema,
+    OpenIdProviderDiscoveryMetadataSchema,
+    OpenIdProviderMetadataSchema
+} from '../shared/auth.js';
 import type { StandardSchemaV1 } from '../util/standardSchema.js';
 import * as schemas from './schemas.js';
 
+const authSchemas = {
+    OAuthClientInformationFullSchema,
+    OAuthClientInformationSchema,
+    OAuthClientMetadataSchema,
+    OAuthClientRegistrationErrorSchema,
+    OAuthErrorResponseSchema,
+    OAuthMetadataSchema,
+    OAuthProtectedResourceMetadataSchema,
+    OAuthTokenRevocationRequestSchema,
+    OAuthTokensSchema,
+    OpenIdProviderDiscoveryMetadataSchema,
+    OpenIdProviderMetadataSchema
+};
+
 type SchemaModule = typeof schemas & typeof authSchemas;
 
 type StripSchemaSuffix<K> = K extends `${infer N}Schema` ? N : never;
@@ -30,11 +56,20 @@ export type SpecTypeName = StripSchemaSuffix<SchemaKey>;
  * `SpecTypes['CallToolResult']` is equivalent to importing the `CallToolResult` type directly.
  */
 export type SpecTypes = {
-    [K in SchemaKey as StripSchemaSuffix<K>]: SchemaModule[K] extends z.ZodType<infer T> ? T : never;
+    [K in SchemaKey as StripSchemaSuffix<K>]: SchemaModule[K] extends z.ZodType ? z.output<SchemaModule[K]> : never;
+};
+
+/**
+ * Input shape for each {@linkcode SpecTypeName}. For most types this equals {@linkcode SpecTypes},
+ * but a few schemas apply defaults/preprocessing, so the accepted input may be looser than the
+ * resulting output type.
+ */
+type SpecTypeInputs = {
+    [K in SchemaKey as StripSchemaSuffix<K>]: SchemaModule[K] extends z.ZodType ? z.input<SchemaModule[K]> : never;
 };
 
-type SchemaRecord = { readonly [K in SpecTypeName]: StandardSchemaV1<SpecTypes[K]> };
-type GuardRecord = { readonly [K in SpecTypeName]: (value: unknown) => value is SpecTypes[K] };
+type SchemaRecord = { readonly [K in SpecTypeName]: StandardSchemaV1<SpecTypeInputs[K], SpecTypes[K]> };
+type GuardRecord = { readonly [K in SpecTypeName]: (value: unknown) => value is SpecTypeInputs[K] };
 
 const _specTypeSchemas: Record<string, z.ZodTypeAny> = {};
 const _isSpecType: Record<string, (value: unknown) => boolean> = {};
@@ -56,12 +91,12 @@ for (const source of [schemas, authSchemas]) {
  * example an extension's custom-method payload that embeds a `CallToolResult`, or a value read from
  * storage that should be a `Tool`.
  *
- * Each entry implements the Standard Schema interface (`schema['~standard'].validate(value)`), so it
- * composes with any Standard-Schema-aware library.
+ * Each entry implements the Standard Schema interface, so it composes with any
+ * Standard-Schema-aware library. For a simple boolean check, use {@linkcode isSpecType} instead.
  *
  * @example
  * ```ts
- * const result = specTypeSchemas.CallToolResult['~standard'].validate(untrusted);
+ * const result = await specTypeSchemas.CallToolResult['~standard'].validate(untrusted);
  * if (result.issues === undefined) {
  *     // result.value is CallToolResult
  * }