@ikuma.cloud/pix-mcp 0.0.3 → 0.0.4

package/README.md

@@ -180,17 +180,78 @@ permission extensions must coordinate any shared approval UI. Discovered tools
 stay active until session shutdown or a server catalog change.
 Changed and removed definitions are withdrawn; changed tools require loading
 again. Unsupported input schemas or metadata, name collisions, and task-only
-tools are counted as `unsupportedTools` in discovery results. An unsupported
-output schema fails that server's discovery. Losing an established HTTP
-notification stream also withdraws tools rather than silently keeping a stale
-catalog; servers that decline the optional stream with HTTP 405 remain usable.
-Reload Pi to reconnect a failed server or reread configuration.
+tools are counted as `unsupportedTools` in discovery results. Each server with
+rejections also includes up to five `rejections` and an `omittedRejections`
+count. Each rejection has a one-based catalog `index`, an adapter-owned `code`
+and `message`, and the original `tool` name only if it passes name validation.
+For example, `draft07-reference` identifies unsupported draft-07 references;
+`unsupported-dialect` identifies an unrecognized dialect. These diagnostics are
+returned by list, search, and load, and replaced on each catalog refresh. Raw
+exceptions, schema contents, invalid tool names, and dialect URLs are not exposed.
+
+An unsupported output schema still fails that server's discovery rather than
+producing a per-tool rejection. Losing an established HTTP notification stream
+also withdraws tools rather than silently keeping a stale catalog; servers that
+decline the optional stream with HTTP 405 remain usable. Reload Pi to reconnect
+a failed server or reread configuration.
 
 Pi handles provider compatibility. Some providers support transcript-anchored
 schema additions; others rebuild the tool set and may invalidate prompt caches.
 For very small catalogs, eager loading would avoid a discovery round trip, but
 v1 intentionally offers only the deferred mode.
 
+### Schema compatibility
+
+Schemas without `$schema` use MCP's default JSON Schema 2020-12 dialect. Explicit
+2020-12 schemas and a conservative draft-07 subset are supported. Draft-07
+accepts `http://json-schema.org/draft-07/schema` and its HTTPS spelling, with or
+without a trailing `#`.
+
+Draft-07 schemas are syntax-checked against their own bundled meta-schema, then
+checked against this keyword allowlist:
+
+| Category | Supported draft-07 keywords |
+| --- | --- |
+| Types and values | `type` (including unions), `enum`, `const`, boolean subschemas |
+| Objects | `properties`, `patternProperties`, `additionalProperties`, `required`, `propertyNames`, `minProperties`, `maxProperties` |
+| Arrays | Schema-valued `items`, `contains`, `minItems`, `maxItems`, `uniqueItems: false` |
+| Numbers | `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum` |
+| Strings | `minLength`, `maxLength`, `pattern` |
+| Composition | `allOf`, `anyOf`, `oneOf`, `not`, `if`, `then`, `else` |
+| Metadata and storage | `$comment`, `title`, `description`, `default`, `examples`, `readOnly`, `writeOnly`, `definitions` |
+
+After these checks, the schema is normalized to equivalent 2020-12 constraints.
+String length bounds must be safe integers and become Unicode patterns that
+count code points rather than Pi's native grapheme-cluster lengths. Object
+normalization also avoids an incorrect native property-count optimization.
+The normalized schema is both exposed to Pi and used for adapter validation;
+output schemas use the same compatibility policy. Literal data in annotations,
+`const`, and `enum` is preserved without interpreting it as a schema. Pi's normal
+argument coercion still applies before adapter execution.
+
+`multipleOf`, `uniqueItems: true`, and `properties`/`required` names inherited from
+`Object.prototype` (for example, `toString`, `constructor`, and `__proto__`) are
+rejected with specific diagnostics. Pi's current validator uses inexact numeric
+comparisons, lossy uniqueness hashes, and inherited-property checks for these
+constructs; accepting them would not preserve JSON Schema semantics. These
+compatibility restrictions and normalizations apply to draft-07 admission;
+existing default/2020-12 validation behavior is unchanged.
+
+`const` and `enum` literals cannot contain arrays, even nested inside objects:
+native equality can conflate array literals with unequal objects. Arrays in
+annotation data such as `default` and `examples` remain legal. Numeric
+backreferences in `patternProperties` are also rejected, regardless of
+`additionalProperties`, because native pattern combination changes their capture
+indices. Escaped literal backslashes and named backreferences remain supported.
+
+Draft-07 references (including local references), `$id`, nested `$schema`
+declarations, tuple `items`, `additionalItems`, `dependencies`, `format`, content
+keywords, and other unlisted keywords are rejected. In particular, newer keywords
+such as `dependentRequired` cannot silently become constraints. This is not a
+complete draft-07 converter. For unsupported dialect constructs, the server must
+supply an equivalent supported schema—not merely remove or change `$schema`.
+Embedded draft-07 declarations inside a 2020-12 document also remain unsupported.
+
 ## Output and limits
 
 Text, supported images, and structured content are retained. Long text gets a
@@ -211,11 +272,11 @@ servers concurrently. Each catalog is limited to 1000 tools, 100 pagination
 cursors, and 2 MiB of metadata; individual input/output schemas are limited to
 64 KiB. Tool names must use 1–128 ASCII letters, digits, underscores, hyphens, or
 periods; descriptions are limited to 16 KiB. Stdio messages are limited to 16 MiB.
-Schemas are syntax-checked before compilation. Only the default MCP dialect,
-JSON Schema 2020-12, is supported; explicit legacy dialects (including embedded
-resources) are rejected rather than interpreted with incorrect reference
-semantics. External schema references are unsupported, but literal `$ref` fields
-inside instance data are allowed.
+Schemas are syntax-checked before compilation; see [schema compatibility](#schema-compatibility)
+for supported dialects and the draft-07 subset. Schema nesting is limited to 64
+levels, including literal data. External schema references are unsupported, but
+literal `$ref` fields inside instance data are allowed. Meta-schema validation
+never fetches a server-provided URL.
 
 The adapter never automatically retries `tools/call`: a timeout or lost response
 may occur after a mutating operation took effect. Cancellation or expiration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikuma.cloud/pix-mcp",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "publishConfig": {
     "access": "public"
   },

package/src/index.ts

@@ -1,5 +1,5 @@
 import { resolve } from "node:path";
-import { Type, type TSchema } from "@earendil-works/pi-ai";
+import { Type } from "@earendil-works/pi-ai";
 import type {
   ExtensionAPI,
   ExtensionContext,
@@ -9,7 +9,18 @@ import { compact, entry, search, summary, type Entry } from "./catalog.ts";
 import { Connection } from "./client.ts";
 import { readConfig, type ConfigIssue, type ServerConfig } from "./config.ts";
 import { formatResult } from "./output.ts";
-import { compileSchema } from "./schema.ts";
+import { prepareSchema } from "./schema.ts";
+import { ToolRejectionError, type RejectionCode } from "./rejection.ts";
+
+interface Rejections {
+  count: number;
+  samples: {
+    tool?: string;
+    index: number;
+    code: RejectionCode;
+    message: string;
+  }[];
+}
 
 interface State {
   alive: boolean;
@@ -17,7 +28,7 @@ interface State {
   entries: Map<string, Entry>;
   loaded: Map<string, string>;
   connections: Map<string, Connection>;
-  rejected: Map<string, number>;
+  rejected: Map<string, Rejections>;
   configIssues: ConfigIssue[];
 }
 
@@ -191,11 +202,21 @@ export default function mcp(pi: ExtensionAPI) {
               status: issue.message,
               unsupportedTools: 0,
             })),
-            ...[...owner.connections.values()].map((connection) => ({
-              name: connection.config.name,
-              status: connection.status,
-              unsupportedTools: owner.rejected.get(connection.config.name) ?? 0,
-            })),
+            ...[...owner.connections.values()].map((connection) => {
+              const rejected = owner.rejected.get(connection.config.name);
+              return {
+                name: connection.config.name,
+                status: connection.status,
+                unsupportedTools: rejected?.count ?? 0,
+                ...(rejected?.count
+                  ? {
+                      rejections: rejected.samples,
+                      omittedRejections:
+                        rejected.count - rejected.samples.length,
+                    }
+                  : {}),
+              };
+            }),
           ],
           items: selected.map((item) => ({
             ...summary(item),
@@ -223,27 +244,27 @@ export default function mcp(pi: ExtensionAPI) {
     const active = new Set(pi.getActiveTools());
     const registered = new Set(pi.getAllTools().map((tool) => tool.name));
     const next = new Map<string, Entry>();
-    let rejected = 0;
-    for (const tool of tools) {
+    const rejected: Rejections = { count: 0, samples: [] };
+    for (const [index, tool] of tools.entries()) {
       const item = entry(config.name, tool);
+      const validName = /^[A-Za-z0-9_.-]{1,128}$/.test(tool.name);
       try {
         if (
-          !/^[A-Za-z0-9_.-]{1,128}$/.test(tool.name) ||
+          !validName ||
           Buffer.byteLength(tool.description ?? "") > 16 * 1024
         ) {
-          throw new Error("Unsupported tool metadata");
+          throw new ToolRejectionError("invalid-tool-metadata");
         }
         if (tool.execution?.taskSupport === "required")
-          throw new Error("Tasks unsupported");
+          throw new ToolRejectionError("tasks-required");
         if (
           next.has(item.name) ||
           (registered.has(item.name) && !owned.has(item.name))
         )
-          throw new Error("Tool name collision");
-        const validator = compileSchema(tool.inputSchema);
+          throw new ToolRejectionError("name-collision");
+        const { parameters, validator } = prepareSchema(tool.inputSchema);
         const old = previous.get(item.name);
         if (old?.fingerprint !== item.fingerprint) {
-          const parameters = tool.inputSchema as TSchema;
           pi.registerTool({
             name: item.name,
             label: `MCP: ${config.name}/${tool.name}`,
@@ -287,8 +308,22 @@ export default function mcp(pi: ExtensionAPI) {
           owned.add(item.name);
         }
         next.set(item.name, item);
-      } catch {
-        rejected++;
+      } catch (error) {
+        rejected.count++;
+        // Bound discovery independently of catalog size. Invalid names and raw
+        // compiler/SDK errors are never reflected back into model context.
+        if (rejected.samples.length < 5) {
+          const reason =
+            error instanceof ToolRejectionError
+              ? error
+              : new ToolRejectionError("registration-failed");
+          rejected.samples.push({
+            ...(validName ? { tool: tool.name } : {}),
+            index: index + 1,
+            code: reason.code,
+            message: reason.message,
+          });
+        }
       }
     }
     for (const [name, old] of previous) {

package/src/rejection.ts

@@ -0,0 +1,53 @@
+// Discovery may expose only these adapter-owned messages, never compiler/SDK
+// exceptions: schemas, dialect URLs, and exception payloads can contain secrets.
+const messages = {
+  "invalid-schema": "Invalid or unsupported MCP JSON Schema.",
+  "unsupported-dialect":
+    "Invalid or unsupported MCP JSON Schema dialect. Use 2020-12 or the documented draft-07 subset.",
+  "embedded-dialect":
+    "Embedded dialect declarations are unsupported in the draft-07 subset.",
+  "draft07-reference":
+    "Draft-07 references are unsupported. Supply an equivalent reference-free schema or a 2020-12 schema.",
+  "draft07-tuple":
+    "Draft-07 tuple items are unsupported. Supply an equivalent 2020-12 schema using prefixItems.",
+  "draft07-dependencies":
+    "Draft-07 dependencies are unsupported. Supply an equivalent 2020-12 schema using dependentRequired/dependentSchemas.",
+  "draft07-resource":
+    "Draft-07 resource identifiers ($id) are unsupported in the compatible subset.",
+  "draft07-format":
+    "Draft-07 format validation is unsupported in the compatible subset.",
+  "draft07-keyword":
+    "An unsupported draft-07 keyword is present. Use the documented subset or supply an equivalent 2020-12 schema.",
+  "draft07-length":
+    "Draft-07 string length bounds outside the safe integer range are unsupported.",
+  "draft07-property-name":
+    "Draft-07 properties/required names inherited from Object.prototype are unsupported by Pi's native validator.",
+  "draft07-unique-items":
+    "Draft-07 uniqueItems:true is unsupported because Pi's native validator can conflate distinct values.",
+  "draft07-multiple-of":
+    "Draft-07 multipleOf is unsupported because Pi's native validator uses inexact numeric comparisons.",
+  "draft07-literal-array":
+    "Draft-07 const/enum literals containing arrays are unsupported because Pi's native equality check can conflate arrays and objects.",
+  "draft07-pattern-backreference":
+    "Draft-07 patternProperties with numeric backreferences are unsupported because Pi's native validator changes their capture indices.",
+  "external-reference": "External MCP schema references are unsupported.",
+  "schema-too-large": "MCP schema exceeds 64 KiB.",
+  "schema-too-deep": "MCP schema is too deeply nested.",
+  "invalid-tool-metadata":
+    "Unsupported tool metadata: names require 1–128 ASCII letters, digits, underscores, hyphens, or periods; descriptions must not exceed 16 KiB.",
+  "tasks-required": "Tools requiring MCP task execution are unsupported.",
+  "name-collision": "The native tool name conflicts with another tool.",
+  "registration-failed": "Native tool registration failed.",
+} as const;
+
+export type RejectionCode = keyof typeof messages;
+
+export class ToolRejectionError extends Error {
+  readonly code: RejectionCode;
+
+  constructor(code: RejectionCode) {
+    super(messages[code]);
+    this.name = "ToolRejectionError";
+    this.code = code;
+  }
+}

package/src/schema.ts

@@ -1,10 +1,14 @@
 import type { TSchema } from "@earendil-works/pi-ai";
 import type { jsonSchemaValidator } from "@modelcontextprotocol/sdk/validation";
+import { Ajv } from "ajv";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import { Compile } from "typebox/compile";
+import { ToolRejectionError } from "./rejection.ts";
 
 const syntax = new Ajv2020({ strict: false, validateFormats: false });
+const legacySyntax = new Ajv({ strict: false, validateFormats: false });
 const dialect = "https://json-schema.org/draft/2020-12/schema";
+const legacyDialect = "http://json-schema.org/draft-07/schema";
 const schemaMaps = new Set([
   "$defs",
   "definitions",
@@ -27,28 +31,202 @@ const schemaValues = new Set([
   "contentSchema",
 ]);
 
+// An allowlist, not a blacklist: a newer or custom keyword could acquire a
+// constraint when interpreted by Pi's TypeBox validator. Instance/annotation
+// data is copied verbatim, never traversed as a schema.
+const legacyKeywords = new Set([
+  "$comment",
+  "title",
+  "description",
+  "default",
+  "examples",
+  "readOnly",
+  "writeOnly",
+  "type",
+  "enum",
+  "const",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "items",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "contains",
+  "properties",
+  "patternProperties",
+  "additionalProperties",
+  "required",
+  "propertyNames",
+  "minProperties",
+  "maxProperties",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "not",
+  "if",
+  "then",
+  "else",
+  "definitions",
+]);
+
+function containsArray(value: unknown): boolean {
+  return (
+    Array.isArray(value) ||
+    (value !== null &&
+      typeof value === "object" &&
+      Object.values(value).some(containsArray))
+  );
+}
+
+function hasNumericBackreference(pattern: string): boolean {
+  for (let index = 0; index < pattern.length; index++) {
+    if (pattern[index] === "\\" && /[1-9]/.test(pattern[++index] ?? ""))
+      return true;
+  }
+  return false;
+}
+
+function normalizeLegacy(value: unknown, root = false): unknown {
+  if (typeof value === "boolean") return value;
+  const schema = value as Record<string, unknown>;
+  const normalized = Object.fromEntries(
+    Object.entries(schema).map(([keyword, child]) => {
+      if (keyword === "$schema") {
+        if (!root) throw new ToolRejectionError("embedded-dialect");
+        return [keyword, dialect];
+      }
+      if (["$ref", "$dynamicRef", "$recursiveRef"].includes(keyword))
+        throw new ToolRejectionError("draft07-reference");
+      if (keyword === "items" && Array.isArray(child))
+        throw new ToolRejectionError("draft07-tuple");
+      if (keyword === "dependencies")
+        throw new ToolRejectionError("draft07-dependencies");
+      if (keyword === "$id") throw new ToolRejectionError("draft07-resource");
+      if (keyword === "format") throw new ToolRejectionError("draft07-format");
+      // TypeBox 1.3 uses a numeric tolerance for multiples and lossy hashes for
+      // uniqueness. A private validator cannot fix Pi's native acceptance set.
+      if (keyword === "multipleOf")
+        throw new ToolRejectionError("draft07-multiple-of");
+      if (keyword === "uniqueItems" && child === true)
+        throw new ToolRejectionError("draft07-unique-items");
+      // TypeBox and Pi's preprocessing use `in` for properties/required. Reject
+      // prototype-sensitive names even when optional: inherited values can fail
+      // a property constraint or satisfy a requirement on an absent JSON key.
+      if (
+        (keyword === "required" &&
+          (child as string[]).some((name) => name in Object.prototype)) ||
+        (keyword === "properties" &&
+          Object.keys(child as object).some((name) => name in Object.prototype))
+      )
+        throw new ToolRejectionError("draft07-property-name");
+      // TypeBox's deep equality can equate array literals with objects such as
+      // {length:0}. Inspect literal structure only for that defect, not for schema
+      // keywords; default/examples remain unrestricted instance data.
+      if (
+        (keyword === "const" && containsArray(child)) ||
+        (keyword === "enum" && (child as unknown[]).some(containsArray))
+      )
+        throw new ToolRejectionError("draft07-literal-array");
+      // additionalProperties combines these patterns inside a capturing group,
+      // changing numeric backreference indices. Reject rather than rewrite regex
+      // syntax; escaped backslashes and named backreferences keep their meaning.
+      if (
+        keyword === "patternProperties" &&
+        Object.keys(child as object).some(hasNumericBackreference)
+      )
+        throw new ToolRejectionError("draft07-pattern-backreference");
+      if (!legacyKeywords.has(keyword))
+        throw new ToolRejectionError("draft07-keyword");
+      if (schemaMaps.has(keyword)) {
+        return [
+          keyword,
+          Object.fromEntries(
+            Object.entries(child as Record<string, unknown>).map(
+              ([name, nested]) => [name, normalizeLegacy(nested)],
+            ),
+          ),
+        ];
+      }
+      if (schemaArrays.has(keyword))
+        return [
+          keyword,
+          (child as unknown[]).map((item) => normalizeLegacy(item)),
+        ];
+      if (schemaValues.has(keyword) || keyword === "items")
+        return [keyword, normalizeLegacy(child)];
+      return [keyword, child];
+    }),
+  );
+  if (
+    normalized.minLength !== undefined ||
+    normalized.maxLength !== undefined
+  ) {
+    const minimum = (normalized.minLength ?? 0) as number;
+    const maximum = normalized.maxLength as number | undefined;
+    if (
+      !Number.isSafeInteger(minimum) ||
+      (maximum !== undefined && !Number.isSafeInteger(maximum))
+    )
+      throw new ToolRejectionError("draft07-length");
+    // TypeBox counts grapheme clusters for min/maxLength, not JSON Schema code
+    // points. Its Unicode regex engine does count code points, including astral
+    // characters. Match all characters (also newlines), and preserve any existing
+    // pattern/allOf rather than overwriting a constraint. Bounds without type
+    // must still accept non-strings, including when the bounds contradict.
+    const pattern =
+      maximum !== undefined && minimum > maximum
+        ? "(?!)"
+        : `^[\\s\\S]{${minimum},${maximum ?? ""}}(?![\\s\\S])`;
+    delete normalized.minLength;
+    delete normalized.maxLength;
+    if (normalized.pattern === undefined) normalized.pattern = pattern;
+    else
+      normalized.allOf = [
+        ...((normalized.allOf as unknown[] | undefined) ?? []),
+        { pattern },
+      ];
+  }
+  const properties = normalized.properties as
+    | Record<string, unknown>
+    | undefined;
+  if (
+    normalized.additionalProperties === false &&
+    properties !== undefined &&
+    normalized.patternProperties === undefined &&
+    Array.isArray(normalized.required) &&
+    Object.keys(properties).length === normalized.required.length &&
+    normalized.required.some((name) => !Object.hasOwn(properties, name))
+  ) {
+    // TypeBox's fast path compares key counts, not sets. An empty pattern map
+    // changes no constraints but selects its correct standard property check.
+    normalized.patternProperties = {};
+  }
+  return normalized;
+}
+
 function checkSchemaSupport(value: unknown): void {
   if (!value || typeof value !== "object" || Array.isArray(value)) return;
   const schema = value as Record<string, unknown>;
-  // Pi validates the exposed schema with TypeBox before execute. A different
-  // private validator cannot repair legacy semantics there (e.g. draft-07 must
-  // ignore $ref siblings). Reject legacy dialects, including embedded resources,
-  // rather than misrepresent them as supported or silently relabeling the schema.
+  // A 2020-12 document cannot silently opt an embedded resource into legacy
+  // semantics. Draft-07 normalization is intentionally limited to whole schemas.
   if (
     schema.$schema !== undefined &&
     (typeof schema.$schema !== "string" ||
       schema.$schema.replace(/#$/, "") !== dialect)
   ) {
-    throw new Error("Invalid or unsupported MCP JSON Schema dialect.");
+    throw new ToolRejectionError("unsupported-dialect");
   }
   for (const keyword of ["$ref", "$dynamicRef", "$recursiveRef"]) {
     const reference = schema[keyword];
     if (typeof reference === "string" && !reference.startsWith("#")) {
-      throw new Error("External MCP schema references are unsupported.");
+      throw new ToolRejectionError("external-reference");
     }
   }
-  // const/enum/default/examples and unknown annotation keywords contain instance
-  // data, not schemas: a literal {$ref: 'https://...'} there must remain legal.
   for (const [keyword, child] of Object.entries(schema)) {
     if (schemaMaps.has(keyword) || keyword === "dependencies") {
       for (const nested of Object.values(child as Record<string, unknown>))
@@ -60,28 +238,51 @@ function checkSchemaSupport(value: unknown): void {
   }
 }
 
-export function compileSchema(schema: Record<string, unknown>) {
-  const serialized = JSON.stringify(schema);
-  if (Buffer.byteLength(serialized) > 64 * 1024)
-    throw new Error("MCP schema exceeds 64 KiB.");
+function checkLimits(schema: unknown): void {
   const checkDepth = (value: unknown, depth: number): void => {
-    if (depth > 64) throw new Error("MCP schema is too deeply nested.");
+    if (depth > 64) throw new ToolRejectionError("schema-too-deep");
     if (!value || typeof value !== "object") return;
     for (const child of Object.values(value)) checkDepth(child, depth + 1);
   };
   checkDepth(schema, 0);
-  // TypeBox code generation is not schema syntax validation: unknown type names
-  // can compile into always-true checks. Validate the dialect's meta-schema first.
-  // Validate against the supported meta-schema directly, without consulting an
-  // untrusted $schema URI or attempting to load a remote meta-schema.
-  if (syntax.validate(dialect, schema) !== true)
-    throw new Error("Invalid or unsupported MCP JSON Schema.");
-  checkSchemaSupport(schema);
-  return Compile(schema as TSchema);
+  if (Buffer.byteLength(JSON.stringify(schema)) > 64 * 1024)
+    throw new ToolRejectionError("schema-too-large");
+}
+
+export function prepareSchema(schema: Record<string, unknown>) {
+  try {
+    checkLimits(schema);
+    const declared = schema.$schema;
+    const uri =
+      typeof declared === "string" ? declared.replace(/#$/, "") : declared;
+    const legacy =
+      uri === legacyDialect || uri === legacyDialect.replace("http:", "https:");
+    if (declared !== undefined && !legacy && uri !== dialect)
+      throw new ToolRejectionError("unsupported-dialect");
+    if (legacy && legacySyntax.validate(legacyDialect, schema) !== true)
+      throw new ToolRejectionError("invalid-schema");
+    const parameters = (
+      legacy ? normalizeLegacy(schema, true) : schema
+    ) as TSchema;
+    if (legacy) checkLimits(parameters);
+    // TypeBox compilation is not syntax validation. Use only bundled meta-schemas,
+    // never an untrusted $schema URI, both before and after normalization.
+    if (syntax.validate(dialect, parameters) !== true)
+      throw new ToolRejectionError("invalid-schema");
+    checkSchemaSupport(parameters);
+    return { parameters, validator: Compile(parameters) };
+  } catch (error) {
+    if (error instanceof ToolRejectionError) throw error;
+    throw new ToolRejectionError("invalid-schema");
+  }
+}
+
+export function compileSchema(schema: Record<string, unknown>) {
+  return prepareSchema(schema).validator;
 }
 
-// Use Pi's validator family for SDK output validation too, rather than silently
-// downgrading MCP's default 2020-12 schemas to the SDK's default draft-07 validator.
+// Input exposure and SDK/output validation share normalization and the same
+// validator family. A private legacy validator cannot repair Pi's native schema.
 export const schemaValidator: jsonSchemaValidator = {
   getValidator<T>(schema: Record<string, unknown>) {
     const validator = compileSchema(schema);