@ikuma.cloud/pix-mcp 0.0.2 → 0.0.4

package/README.md

@@ -4,28 +4,17 @@ A small Pi MCP adapter: discover tools, load their schemas on demand, then call
 those tools natively. No scripting engine or model-provider-specific API is
 required.
 
-**Read [CONTRIBUTING.md](../../CONTRIBUTING.md) before making changes.**
+## Usage
 
-## Development
-
-From the repository root:
+To load this package in an existing Pi installation:
 
 ```sh
-mise run mcp:dev
-mise run test --project pix-mcp
-mise run check
+pi -e /absolute/path/to/pix/packages/mcp
 ```
 
-The development task runs from `packages/mcp` and disables other extensions so
-another MCP adapter cannot collide with the `mcp` tool or flags. Pass arguments
-through the task, for example:
-
-```sh
-mise run mcp:dev --mcp-config /absolute/path/to/mcp.json
-```
-
-For an existing Pi installation, load this package with
-`pi --no-extensions -e /absolute/path/to/pix/packages/mcp`.
+Disable any other MCP adapter that would collide with the `mcp` tool or flags,
+but keep any permission-control extensions enabled. Review the configuration
+and trust requirements below before connecting servers.
 
 ## Configuration and trust
 
@@ -61,8 +50,7 @@ contact remote services. Configuration trust is not an OS sandbox.
       "description": "Issue tracking tools",
       "timeout": 960000,
       "startupTimeoutMs": 30000,
-      "catalogTimeoutMs": 30000,
-      "approve": true
+      "catalogTimeoutMs": 30000
     }
   }
 }
@@ -91,7 +79,6 @@ URLs, and HTTP headers.
 | `description` | Discovery extension: optional summary, truncated to 500 characters |
 | `startupTimeoutMs` | pix extension: complete connection/initialization handshake deadline; default 30000 |
 | `catalogTimeoutMs` | pix extension: complete catalog snapshot deadline, including all pages; default 30000 |
-| `approve` | pix policy: require confirmation for every invocation, default `true` |
 | `disabled` | Skip the server's value validation and environment expansion when `true`; unknown fields are still errors |
 
 `command`, `args`, `cwd`, `env` values, `url`, and `headers` values expand `${VAR}`
@@ -118,14 +105,14 @@ reports that no valid servers remain. Disabled entries are omitted, not reported
 as failed connections. Correct the file and reload Pi to retry.
 
 Configuration trust still applies before any valid server is started or its
-metadata exposed. Per-call approval remains independent of configuration errors.
+metadata exposed.
 
 ### Deadlines and migration
 
 All three deadline fields accept integers from 1 through 2,147,483,647 milliseconds
 (Node's timer-safe maximum). Each defaults independently to 30 seconds. Setting
 `"timeout": 960000` permits a 16-minute tool call without lengthening startup or
-discovery. The call clock starts after invocation approval and connection startup;
+discovery. The call clock starts after connection startup;
 progress does not reset it. Catalog deadlines cover all pages of one snapshot;
 a subsequent list-change refresh starts a new deadline.
 
@@ -146,14 +133,22 @@ Upstream proxies and servers may still impose their own limits.
 The 120-second call ceiling is removed. This is a configuration migration, not a
 promise to finish a remote operation within its deadline.
 
-### Invocation approval
+### Tool-call control
+
+Like Pi's built-in tools, loaded MCP tools execute without adapter-specific
+permission prompts in both interactive and headless sessions. Native calls pass
+through Pi's normal `tool_call` and `tool_result` hooks. For approvals or access
+policies, install a Pi extension that handles `tool_call` so it can manage MCP
+and other tools together. Server annotations do not bypass those hooks.
+Configuration trust above is separate: it authorizes startup, not individual calls.
+
+**Migration from 0.0.2:** Remove the server-level `approve` field. Entries that
+still contain it are rejected with migration guidance rather than silently
+ignoring an existing policy. If you relied on `approve: true`, configure an
+external permission extension before removing it.
 
-Tool invocation requires confirmation independently of config trust. In headless
-mode, calls fail closed unless the reviewed configuration explicitly sets
-`"approve": false` for that server. Native calls still pass through Pi's normal
-tool hooks. Server annotations never grant permission. Child stderr and raw SDK
-errors are not printed because they can contain credentials; debug a failing
-server separately in a trusted environment.
+Child stderr and raw SDK errors are not printed because they can contain
+credentials; debug a failing server separately in a trusted environment.
 
 ## Discovery and execution
 
@@ -180,23 +175,83 @@ Selection is tied to the current schema fingerprint: use `search`/`load`, not
 Pi's generic tool-name toggles, to enable a native MCP tool.
 
 Native names include a readable server/tool prefix and a deterministic hash to
-avoid normalization collisions. Independent, preapproved native calls can run
-concurrently. Calls requiring confirmation run sequentially to avoid overlapping
-approval dialogs. Discovered tools stay active until session shutdown or a server
-catalog change.
+avoid normalization collisions. Independent native calls can run concurrently;
+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
@@ -217,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
@@ -237,5 +292,6 @@ OAuth, legacy SSE transport, MCP prompts/resources APIs, sampling, elicitation,
 MCP apps, task execution, semantic search, scripting, config UI, and persistent
 catalog caching. Use a fuller adapter when those capabilities are required.
 
-Tests use local stdio/HTTP fixture servers and isolated Pi configuration, without
-model requests or personal credentials.
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before making changes.

package/mcp.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "pix-mcp configuration",
-  "description": "A Claude-style connection subset with pix-specific approval and lifecycle options. Environment expansion and HTTP URL/header validation also occur at runtime.",
+  "description": "A Claude-style connection subset with pix-specific discovery and lifecycle options. Environment expansion and HTTP URL/header validation also occur at runtime.",
   "type": "object",
   "required": ["mcpServers"],
   "additionalProperties": false,
@@ -43,11 +43,6 @@
           "$ref": "#/$defs/timeout",
           "description": "pix extension: one complete catalog snapshot, including all pages."
         },
-        "approve": {
-          "type": "boolean",
-          "default": true,
-          "description": "pix extension: require confirmation for every tool invocation."
-        },
         "disabled": { "const": false }
       }
     },
@@ -108,7 +103,6 @@
         "timeout": true,
         "startupTimeoutMs": true,
         "catalogTimeoutMs": true,
-        "approve": true,
         "disabled": { "type": "boolean" }
       },
       "if": {

package/package.json

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

package/src/config.ts

@@ -9,7 +9,6 @@ export interface CommonServer {
   timeout: number;
   startupTimeoutMs: number;
   catalogTimeoutMs: number;
-  approve: boolean;
 }
 export type ServerConfig = CommonServer &
   (
@@ -133,6 +132,11 @@ function parseServer(
       "timeoutMs",
       "Removed; use timeout for tool calls, startupTimeoutMs for initialization, and catalogTimeoutMs for discovery (milliseconds).",
     );
+  if (Object.hasOwn(server, "approve"))
+    invalid(
+      "approve",
+      "Removed; delete approve and use a Pi tool_call extension for permission controls.",
+    );
   const allowed = new Set([
     "type",
     "command",
@@ -145,7 +149,6 @@ function parseServer(
     "timeout",
     "startupTimeoutMs",
     "catalogTimeoutMs",
-    "approve",
     "disabled",
   ]);
   if (Object.keys(server).some((key) => !allowed.has(key)))
@@ -156,8 +159,6 @@ function parseServer(
   if (server.disabled !== undefined && typeof server.disabled !== "boolean")
     invalid("disabled", "Expected a boolean.");
   if (server.disabled === true) return undefined;
-  if (server.approve !== undefined && typeof server.approve !== "boolean")
-    invalid("approve", "Expected a boolean.");
   const common: CommonServer = {
     name,
     description:
@@ -167,7 +168,6 @@ function parseServer(
     timeout: timeout(server.timeout, "timeout"),
     startupTimeoutMs: timeout(server.startupTimeoutMs, "startupTimeoutMs"),
     catalogTimeoutMs: timeout(server.catalogTimeoutMs, "catalogTimeoutMs"),
-    approve: server.approve !== false,
   };
   const type =
     server.type === undefined && server.command !== undefined

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,73 +244,49 @@ 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}`,
             description:
               tool.description || `Call ${tool.name} on ${config.name}.`,
             parameters,
-            // Approval dialogs share Pi's UI. Only preapproved calls may overlap.
-            executionMode: config.approve ? "sequential" : "parallel",
-            async execute(_id, params, signal, _onUpdate, ctx) {
+            executionMode: "parallel",
+            async execute(_id, params, signal) {
               current(owner);
               signal?.throwIfAborted();
-              const verify = () => {
-                current(owner);
-                if (
-                  owner.entries.get(item.name)?.fingerprint !==
-                    item.fingerprint ||
-                  owner.loaded.get(item.name) !== item.fingerprint ||
-                  !pi.getActiveTools().includes(item.name)
-                ) {
-                  throw new Error(
-                    "MCP tool is unavailable or changed. Discover it again.",
-                  );
-                }
-              };
-              verify();
-              if (!validator.Check(params))
-                throw new Error("Arguments do not match the MCP input schema.");
-              if (config.approve) {
-                if (!ctx.hasUI)
-                  throw new Error(
-                    "MCP approval required. Use an interactive session or explicitly set approve:false for this trusted server.",
-                  );
-                const input = JSON.stringify(params, null, 2);
-                if (input.length > 8000)
-                  throw new Error(
-                    "MCP arguments are too large for the approval dialog.",
-                  );
-                const allowed = await ctx.ui.confirm(
-                  `Call ${config.name}/${tool.name}?`,
-                  input,
-                  signal ? { signal } : undefined,
+              if (
+                owner.entries.get(item.name)?.fingerprint !==
+                  item.fingerprint ||
+                owner.loaded.get(item.name) !== item.fingerprint ||
+                !pi.getActiveTools().includes(item.name)
+              ) {
+                throw new Error(
+                  "MCP tool is unavailable or changed. Discover it again.",
                 );
-                if (!allowed) throw new Error("MCP tool call denied.");
               }
-              signal?.throwIfAborted();
-              verify();
+              if (!validator.Check(params))
+                throw new Error("Arguments do not match the MCP input schema.");
               const connection = owner.connections.get(config.name);
               if (!connection) throw new Error("MCP connection unavailable.");
               const result = await connection.call(
@@ -311,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);