@warlock.js/ai-tools 5.34.0 → 5.34.2

package/esm/contracts/index.d.mts

@@ -2,5 +2,5 @@ import { FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult, Search
 import { HttpMethod, HttpRequestInput, HttpRequestOptions, HttpRequestResult } from "./http.type.mjs";
 import { CalculatorInput, CalculatorOptions, CalculatorResult, DateTimeInput, DateTimeOp, DateTimeOptions, DateTimeResult } from "./utility.type.mjs";
 import { JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcVersion, McpClient, McpClientOptions, McpContentBlock, McpToolCallResult, McpToolDescriptor, McpTransport } from "./mcp.type.mjs";
-import { McpBeforeCall, McpCallRefusal, McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpRoute, McpHttpRouteContext, McpHttpRouteResponse, McpHttpServeHandle, McpHttpServeTransport, McpListFilter, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, McpToolSource, McpValidateCallParams } from "./mcp-serve.type.mjs";
-export type { CalculatorInput, CalculatorOptions, CalculatorResult, DateTimeInput, DateTimeOp, DateTimeOptions, DateTimeResult, FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult, HttpMethod, HttpRequestInput, HttpRequestOptions, HttpRequestResult, JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcVersion, McpBeforeCall, McpCallRefusal, McpClient, McpClientOptions, McpContentBlock, McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpRoute, McpHttpRouteContext, McpHttpRouteResponse, McpHttpServeHandle, McpHttpServeTransport, McpListFilter, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, McpToolCallResult, McpToolDescriptor, McpToolSource, McpTransport, McpValidateCallParams, SearchProvider, WebSearchInput, WebSearchOptions, WebSearchResult, WebSearchResultItem };
+import { McpBeforeCall, McpCallRefusal, McpGroupedToolSource, McpHttpAuth, McpHttpAuthRefusal, McpHttpAuthRefusalBody, McpHttpAuthRefusalContext, McpHttpAuthRefusalHeader, McpHttpAuthRefusalResponse, McpHttpRequestInfo, McpHttpRoute, McpHttpRouteContext, McpHttpRouteResponse, McpHttpServeHandle, McpHttpServeTransport, McpListFilter, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, McpToolSource, McpValidateCallParams } from "./mcp-serve.type.mjs";
+export type { CalculatorInput, CalculatorOptions, CalculatorResult, DateTimeInput, DateTimeOp, DateTimeOptions, DateTimeResult, FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult, HttpMethod, HttpRequestInput, HttpRequestOptions, HttpRequestResult, JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcVersion, McpBeforeCall, McpCallRefusal, McpClient, McpClientOptions, McpContentBlock, McpGroupedToolSource, McpHttpAuth, McpHttpAuthRefusal, McpHttpAuthRefusalBody, McpHttpAuthRefusalContext, McpHttpAuthRefusalHeader, McpHttpAuthRefusalResponse, McpHttpRequestInfo, McpHttpRoute, McpHttpRouteContext, McpHttpRouteResponse, McpHttpServeHandle, McpHttpServeTransport, McpListFilter, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, McpToolCallResult, McpToolDescriptor, McpToolSource, McpTransport, McpValidateCallParams, SearchProvider, WebSearchInput, WebSearchOptions, WebSearchResult, WebSearchResultItem };

package/esm/contracts/mcp-serve.type.d.mts

@@ -47,7 +47,7 @@ export type McpHttpRequestInfo = ToolRequestContext & {
 /**
  * Authentication for an HTTP-served MCP endpoint. At least one of
  * `bearer` / `authorize` / `authenticate` is required; all configured checks
- * must pass, in that order. A request that fails gets HTTP 401 before its body is read.
+ * must pass, in that order. A request that fails is refused before its body is read.
  */
 export type McpHttpAuth = {
   /**
@@ -71,6 +71,29 @@ export type McpHttpAuth = {
    */
   authenticate?: (request: McpHttpRequestInfo) => unknown | Promise<unknown>;
 };
+/** Safe refusal metadata: no credentials, principal, body or thrown error. */
+export type McpHttpAuthRefusalContext = Readonly<{
+  check: "bearer" | "authorize" | "authenticate";
+  method: string;
+  /** Pathname only; excludes the query string. */
+  path: string;
+  target: "mcp" | "route";
+}>;
+/** JSON values accepted in an authentication refusal body. */
+export type McpHttpAuthRefusalBody = null | boolean | number | string | readonly McpHttpAuthRefusalBody[] | {
+  readonly [key: string]: McpHttpAuthRefusalBody;
+};
+/** Headers an auth refusal may set; framing, cookies and CORS stay transport-owned. */
+export type McpHttpAuthRefusalHeader = "www-authenticate" | "cache-control" | "retry-after" | "content-language" | "x-request-id";
+export type McpHttpAuthRefusalResponse = {
+  /** Integer from 400 through 599. Defaults to 401. */
+  status?: number;
+  /** Merged over the default challenge. Names are case-insensitive at runtime. */
+  headers?: Partial<Record<McpHttpAuthRefusalHeader, string>>;
+  body: McpHttpAuthRefusalBody;
+};
+/** Customize a denial only. Throws, invalid results or void retain the default 401. */
+export type McpHttpAuthRefusal = (context: McpHttpAuthRefusalContext) => void | McpHttpAuthRefusalResponse | Promise<void | McpHttpAuthRefusalResponse>;
 /** Authenticated context for an extra HTTP route; there is no JSON-RPC id. */
 export type McpHttpRouteContext = McpServeCallContext & {
   request: McpHttpRequestInfo;
@@ -130,6 +153,8 @@ export type McpHttpServeTransport = {
   path?: string;
   /** Bearer, authorize and/or authenticate checks. Required off loopback. */
   auth?: McpHttpAuth;
+  /** Shared by MCP and routes after failed auth; never runs for Host/Origin refusals. */
+  onAuthRefusal?: McpHttpAuthRefusal;
   /** Extra HTTP routes with the same Host/Origin and authentication checks. */
   routes?: readonly McpHttpRoute[];
   /**

package/esm/contracts/mcp-serve.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-serve.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/contracts/mcp-serve.type.ts"],"mappings":";;;;;;;;;;;;;YAcY;EAAkB,SAAS;IAAmB;;;;;;;;;YAU9C;;EAEV,QAAQ,eAAe;;;;;;;;YASb,iBAAiB,gBAAgB;;;;;;YAOjC,qBAAqB;;EAE/B;;EAEA;;;;;;;YAQU;;;;;;;;EAQV;;;;;;EAMA,aAAa,SAAS,iCAAiC;;;;;;EAMvD,gBAAgB,SAAS,iCAAiC;;;YAIhD,sBAAsB;EAChC,SAAS;;EAET,KAAK;;EAEL;EACA,QAAQ;;;YAIE;;EAEV;EACA,UAAU;EACV;;;YAIU;EACV;;;;;;;EAOA;EACA,QAAQ,SAAS,sBAAsB,uBAAuB,QAAQ;;;;;;;;YAS5D;;EAEV;;;;;;;EAOA;;;;;;;EAOA;;;;;;EAMA;;EAEA,OAAO;;EAEP,kBAAkB;;;;;;;;;EASlB;;;;;;;EAOA;;;;;;EAMA;;;;;;;EAOA;;;;;;;;YASU,oBAAoB,yBAAyB;;YAG7C;EACV;;EAEA;;EAEA,qBAAqB,SAAS,kCAAkC;;;;;;YAOtD;;EAEV,UAAU;;EAEV,YAAY;;EAEZ;;EAEA,SAAS;;;YAIC,sBAAsB;EAAwB,WAAW;;;YAGzD,iBAAiB;EAAsB;;;YAGvC,iBACV,SAAS,qBACT,MAAM,cACN,0BACU,iBAAiB,eAAe;;YAGhC,iBACV,SAAS,qBACT,gBAAgB,iCACJ,sBAAsB,iBAAiB;;;;;YAMzC,yBACV,SAAS,qBACT,QAAQ,SAAS,oCACP;;;;YAKA;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;;;;EAKA,KAAK,SAAS,+BAA+B,aAAa,iBAAiB;;;YAIjE;;EAEV;;EAEA;;EAEA;;;YAIU;;EAEV;;EAEA,SAAS;;;;;YAMC;;EAEV;;EAEA;;EAEA;;EAEA,YAAY;;;;;;EAMZ,IACE,MAAM,wBACN,SAAS,+BACC,qBAAqB,iBAAiB;;;;;;iBAOnC;;EAEf;;;;;;EAMA;;;;;;EAMA,YAAY;;;;;;;;EAQZ,eAAe;;;;;;;;;EASf;;;;;;;EAOA,aAAa;;EAEb,aAAa;;;;;EAKb,qBAAqB;;;;;;;;EAQrB,8BAA8B,eAAe;;EAE7C,YAAY;;EAEZ,UAAU;;;;;;iBAOK;;EAEf;;;;;;EAMA,SAAS;;;iBAIM,2BAA2B;;EAE1C;;;;;iBAMe,UAAU,gBAAgB,iBAAiB;;;;;;EAM1D,SAAS,QAAQ;;EAEjB,QAAQ"}
+{"version":3,"file":"mcp-serve.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/contracts/mcp-serve.type.ts"],"mappings":";;;;;;;;;;;;;YAcY;EAAkB,SAAS;IAAmB;;;;;;;;;YAU9C;;EAEV,QAAQ,eAAe;;;;;;;;YASb,iBAAiB,gBAAgB;;;;;;YAOjC,qBAAqB;;EAE/B;;EAEA;;;;;;;YAQU;;;;;;;;EAQV;;;;;;EAMA,aAAa,SAAS,iCAAiC;;;;;;EAMvD,gBAAgB,SAAS,iCAAiC;;;YAIhD,4BAA4B;EACtC;EACA;;EAEA;EACA;;;YAIU,qEAKC;YACG,cAAc;;;YAGlB;YAOA;;EAEV;;EAEA,UAAU,QAAQ,OAAO;EACzB,MAAM;;;YAII,sBACV,SAAS,qCACC,6BAA6B,eAAe;;YAG5C,sBAAsB;EAChC,SAAS;;EAET,KAAK;;EAEL;EACA,QAAQ;;;YAIE;;EAEV;EACA,UAAU;EACV;;;YAIU;EACV;;;;;;;EAOA;EACA,QAAQ,SAAS,sBAAsB,uBAAuB,QAAQ;;;;;;;;YAS5D;;EAEV;;;;;;;EAOA;;;;;;;EAOA;;;;;;EAMA;;EAEA,OAAO;;EAEP,gBAAgB;;EAEhB,kBAAkB;;;;;;;;;EASlB;;;;;;;EAOA;;;;;;EAMA;;;;;;;EAOA;;;;;;;;YASU,oBAAoB,yBAAyB;;YAG7C;EACV;;EAEA;;EAEA,qBAAqB,SAAS,kCAAkC;;;;;;YAOtD;;EAEV,UAAU;;EAEV,YAAY;;EAEZ;;EAEA,SAAS;;;YAIC,sBAAsB;EAAwB,WAAW;;;YAGzD,iBAAiB;EAAsB;;;YAGvC,iBACV,SAAS,qBACT,MAAM,cACN,0BACU,iBAAiB,eAAe;;YAGhC,iBACV,SAAS,qBACT,gBAAgB,iCACJ,sBAAsB,iBAAiB;;;;;YAMzC,yBACV,SAAS,qBACT,QAAQ,SAAS,oCACP;;;;YAKA;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;;;;EAKA,KAAK,SAAS,+BAA+B,aAAa,iBAAiB;;;YAIjE;;EAEV;;EAEA;;EAEA;;;YAIU;;EAEV;;EAEA,SAAS;;;;;YAMC;;EAEV;;EAEA;;EAEA;;EAEA,YAAY;;;;;;EAMZ,IACE,MAAM,wBACN,SAAS,+BACC,qBAAqB,iBAAiB;;;;;;iBAOnC;;EAEf;;;;;;EAMA;;;;;;EAMA,YAAY;;;;;;;;EAQZ,eAAe;;;;;;;;;EASf;;;;;;;EAOA,aAAa;;EAEb,aAAa;;;;;EAKb,qBAAqB;;;;;;;;EAQrB,8BAA8B,eAAe;;EAE7C,YAAY;;EAEZ,UAAU;;;;;;iBAOK;;EAEf;;;;;;EAMA,SAAS;;;iBAIM,2BAA2B;;EAE1C;;;;;iBAMe,UAAU,gBAAgB,iBAAiB;;;;;;EAM1D,SAAS,QAAQ;;EAEjB,QAAQ"}

package/esm/index.d.mts

@@ -2,13 +2,13 @@ import { FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult, Search
 import { HttpMethod, HttpRequestInput, HttpRequestOptions, HttpRequestResult } from "./contracts/http.type.mjs";
 import { CalculatorInput, CalculatorOptions, CalculatorResult, DateTimeInput, DateTimeOp, DateTimeOptions, DateTimeResult } from "./contracts/utility.type.mjs";
 import { JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcVersion, McpClient, McpClientOptions, McpContentBlock, McpToolCallResult, McpToolDescriptor, McpTransport } from "./contracts/mcp.type.mjs";
-import { McpBeforeCall, McpCallRefusal, McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpRoute, McpHttpRouteContext, McpHttpRouteResponse, McpHttpServeHandle, McpHttpServeTransport, McpListFilter, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, McpToolSource, McpValidateCallParams } from "./contracts/mcp-serve.type.mjs";
+import { McpBeforeCall, McpCallRefusal, McpGroupedToolSource, McpHttpAuth, McpHttpAuthRefusal, McpHttpAuthRefusalBody, McpHttpAuthRefusalContext, McpHttpAuthRefusalHeader, McpHttpAuthRefusalResponse, McpHttpRequestInfo, McpHttpRoute, McpHttpRouteContext, McpHttpRouteResponse, McpHttpServeHandle, McpHttpServeTransport, McpListFilter, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, McpToolSource, McpValidateCallParams } from "./contracts/mcp-serve.type.mjs";
 import "./contracts/index.mjs";
 import { McpServeRequestHandler, createServeHandler, serve } from "./mcp/serve.mjs";
 import { SUPPORTED_PROTOCOL_VERSIONS } from "./mcp/protocol.mjs";
 import { McpError } from "./mcp/error.mjs";
 import { McpNativeResult, mcpResult } from "./mcp/result.mjs";
-import { jsonSchemaToStandard } from "./mcp/json-schema-to-standard.mjs";
+import { JsonSchemaStandard, jsonSchemaToStandard } from "./mcp/json-schema-to-standard.mjs";
 import { McpTransportClient } from "./mcp/transport.type.mjs";
 import { JsonRpcClientHandle, createJsonRpcClient, createTransport } from "./mcp/transport.mjs";
 import { McpFactory, mcp } from "./mcp/index.mjs";
@@ -21,6 +21,6 @@ import { calculatorTool } from "./utility/calculator.mjs";
 import { dateTimeTool } from "./utility/date-time.mjs";
 import "./utility/index.mjs";
 import { CalculatorError, CalculatorErrorOptions, CalculatorFailure, DateTimeError, DateTimeErrorOptions, DateTimeFailure, HttpPolicyError, HttpPolicyErrorOptions, HttpPolicyFailure, McpServeError, McpServeErrorOptions, McpServeFailure, McpTransportError, McpTransportErrorOptions, McpTransportFailure, WebToolError, WebToolErrorOptions, WebToolFailure } from "./errors.mjs";
-export { type AiToolsNamespace, CalculatorError, type CalculatorErrorOptions, type CalculatorFailure, type CalculatorInput, type CalculatorOptions, type CalculatorResult, DateTimeError, type DateTimeErrorOptions, type DateTimeFailure, type DateTimeInput, type DateTimeOp, type DateTimeOptions, type DateTimeResult, type FetchUrlExtract, type FetchUrlInput, type FetchUrlOptions, type FetchUrlResult, type HttpMethod, HttpPolicyError, type HttpPolicyErrorOptions, type HttpPolicyFailure, type HttpRequestInput, type HttpRequestOptions, type HttpRequestResult, type JsonRpcClientHandle, type JsonRpcError, type JsonRpcId, type JsonRpcMessage, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type JsonRpcVersion, type McpBeforeCall, type McpCallRefusal, type McpClient, type McpClientOptions, type McpContentBlock, McpError, type McpFactory, type McpGroupedToolSource, type McpHttpAuth, type McpHttpRequestInfo, type McpHttpRoute, type McpHttpRouteContext, type McpHttpRouteResponse, type McpHttpServeHandle, type McpHttpServeTransport, type McpListFilter, type McpNativeResult, type McpPromptArgument, type McpPromptMessage, type McpServeCallContext, McpServeError, type McpServeErrorOptions, type McpServeFailure, type McpServeHandle, type McpServeOptions, type McpServePrompt, type McpServeRequestHandler, type McpServeResource, type McpServeSource, type McpServeToolContext, type McpServeTransport, type McpServer, type McpStdioServeTransport, type McpToolCallResult, type McpToolDescriptor, type McpToolSource, type McpTransport, type McpTransportClient, McpTransportError, type McpTransportErrorOptions, type McpTransportFailure, type McpValidateCallParams, SUPPORTED_PROTOCOL_VERSIONS, type SearchProvider, type WebSearchInput, type WebSearchOptions, type WebSearchResult, type WebSearchResultItem, WebToolError, type WebToolErrorOptions, type WebToolFailure, calculatorTool, createJsonRpcClient, createServeHandler, createTransport, dateTimeTool, fetchUrlTool, httpRequestTool, jsonSchemaToStandard, mcp, mcpResult, serve, webSearchTool };
+export { type AiToolsNamespace, CalculatorError, type CalculatorErrorOptions, type CalculatorFailure, type CalculatorInput, type CalculatorOptions, type CalculatorResult, DateTimeError, type DateTimeErrorOptions, type DateTimeFailure, type DateTimeInput, type DateTimeOp, type DateTimeOptions, type DateTimeResult, type FetchUrlExtract, type FetchUrlInput, type FetchUrlOptions, type FetchUrlResult, type HttpMethod, HttpPolicyError, type HttpPolicyErrorOptions, type HttpPolicyFailure, type HttpRequestInput, type HttpRequestOptions, type HttpRequestResult, type JsonRpcClientHandle, type JsonRpcError, type JsonRpcId, type JsonRpcMessage, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type JsonRpcVersion, type JsonSchemaStandard, type McpBeforeCall, type McpCallRefusal, type McpClient, type McpClientOptions, type McpContentBlock, McpError, type McpFactory, type McpGroupedToolSource, type McpHttpAuth, type McpHttpAuthRefusal, type McpHttpAuthRefusalBody, type McpHttpAuthRefusalContext, type McpHttpAuthRefusalHeader, type McpHttpAuthRefusalResponse, type McpHttpRequestInfo, type McpHttpRoute, type McpHttpRouteContext, type McpHttpRouteResponse, type McpHttpServeHandle, type McpHttpServeTransport, type McpListFilter, type McpNativeResult, type McpPromptArgument, type McpPromptMessage, type McpServeCallContext, McpServeError, type McpServeErrorOptions, type McpServeFailure, type McpServeHandle, type McpServeOptions, type McpServePrompt, type McpServeRequestHandler, type McpServeResource, type McpServeSource, type McpServeToolContext, type McpServeTransport, type McpServer, type McpStdioServeTransport, type McpToolCallResult, type McpToolDescriptor, type McpToolSource, type McpTransport, type McpTransportClient, McpTransportError, type McpTransportErrorOptions, type McpTransportFailure, type McpValidateCallParams, SUPPORTED_PROTOCOL_VERSIONS, type SearchProvider, type WebSearchInput, type WebSearchOptions, type WebSearchResult, type WebSearchResultItem, WebToolError, type WebToolErrorOptions, type WebToolFailure, calculatorTool, createJsonRpcClient, createServeHandler, createTransport, dateTimeTool, fetchUrlTool, httpRequestTool, jsonSchemaToStandard, mcp, mcpResult, serve, webSearchTool };
 import "./mcp/index.mjs";
 import "./register.mjs";

package/esm/mcp/index.d.mts

@@ -5,7 +5,7 @@ import { McpServeRequestHandler, createServeHandler, serve } from "./serve.mjs";
 import { SUPPORTED_PROTOCOL_VERSIONS } from "./protocol.mjs";
 import { McpError } from "./error.mjs";
 import { McpNativeResult, mcpResult } from "./result.mjs";
-import { jsonSchemaToStandard } from "./json-schema-to-standard.mjs";
+import { JsonSchemaStandard, jsonSchemaToStandard } from "./json-schema-to-standard.mjs";
 import { McpTransportClient } from "./transport.type.mjs";
 import { JsonRpcClientHandle, createJsonRpcClient, createTransport } from "./transport.mjs";
 //#region ../../packages/ai-tools/src/mcp/index.d.ts

package/esm/mcp/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["mcpClient"],"sources":["../../../../../../../../packages/ai-tools/src/mcp/index.ts"],"sourcesContent":["import type {\n  McpClient,\n  McpClientOptions,\n  McpHttpServeHandle,\n  McpHttpServeTransport,\n  McpServeOptions,\n  McpServeSource,\n  McpServer,\n  McpTransport,\n} from \"../contracts\";\nimport { mcp as mcpClient } from \"./client\";\nimport { serve } from \"./serve\";\n\nexport { serve, createServeHandler } from \"./serve\";\nexport type { McpServeRequestHandler } from \"./serve\";\nexport { SUPPORTED_PROTOCOL_VERSIONS } from \"./protocol\";\nexport { McpError } from \"./error\";\nexport { mcpResult } from \"./result\";\nexport type { McpNativeResult } from \"./result\";\nexport { jsonSchemaToStandard } from \"./json-schema-to-standard\";\nexport { createJsonRpcClient, createTransport } from \"./transport\";\nexport type { JsonRpcClientHandle } from \"./transport\";\nexport type { McpTransportClient } from \"./transport.type\";\n\n/**\n * The callable `ai.mcp` surface — a factory that connects to an external\n * MCP server (Direction A) and also carries `.serve` to expose a local\n * primitive AS an MCP server (Direction B). Modeled as a function with an\n * attached `serve` property, mirroring how `ai.mcp(server).tools()` and\n * `ai.mcp.serve(source, options).start()` read in the design.\n */\nexport interface McpFactory {\n  /**\n   * Connect to an external MCP server and adapt its tools as agent tools.\n   *\n   * @param server - The transport config (`{ type: \"stdio\" }` / `{ type: \"http\" }`).\n   * @param options - Prefix / filter / per-call timeout, and a `signal`\n   *   that closes the client (and fails its calls) when it aborts.\n   */\n  (server: McpTransport, options?: McpClientOptions): McpClient;\n  /**\n   * Expose a built agent / supervisor / orchestrator (or a literal\n   * `ToolContract[]`, or named `{ groups }`) AS an MCP server. Over\n   * `{ type: \"http\" }`, `start()` resolves `{ url, close }`.\n   *\n   * @param source - The tools to expose.\n   * @param options - Server name, version, transport, schema dialect, resources, prompts.\n   */\n  serve(\n    source: McpServeSource,\n    options: McpServeOptions & { transport: McpHttpServeTransport },\n  ): McpServer<McpHttpServeHandle>;\n  serve(source: McpServeSource, options: McpServeOptions): McpServer;\n}\n\n/**\n * The `ai.mcp` factory value: the client factory with `.serve` attached.\n * `Object.assign` keeps `mcp` callable (Direction A) while widening it with\n * the `serve` member (Direction B) — one object, both directions. The\n * `declare module \"@warlock.js/ai\"` augmentation and the runtime\n * registration (`ai.mcp = mcp`) live in `../register`, so this barrel is a\n * pure value/type module the registrar consumes.\n */\nexport const mcp: McpFactory = Object.assign(\n  (server: McpTransport, options?: McpClientOptions): McpClient => mcpClient(server, options),\n  { serve },\n);\n"],"mappings":";;;;;;;;;;;;;;;;;AA+DA,MAAa,MAAkB,OAAO,QACnC,QAAsB,YAA0CA,MAAU,QAAQ,OAAO,GAC1F,EAAE,MAAM,CACV"}
+{"version":3,"file":"index.mjs","names":["mcpClient"],"sources":["../../../../../../../../packages/ai-tools/src/mcp/index.ts"],"sourcesContent":["import type {\n  McpClient,\n  McpClientOptions,\n  McpHttpServeHandle,\n  McpHttpServeTransport,\n  McpServeOptions,\n  McpServeSource,\n  McpServer,\n  McpTransport,\n} from \"../contracts\";\nimport { mcp as mcpClient } from \"./client\";\nimport { serve } from \"./serve\";\n\nexport { serve, createServeHandler } from \"./serve\";\nexport type { McpServeRequestHandler } from \"./serve\";\nexport { SUPPORTED_PROTOCOL_VERSIONS } from \"./protocol\";\nexport { McpError } from \"./error\";\nexport { mcpResult } from \"./result\";\nexport type { McpNativeResult } from \"./result\";\nexport { jsonSchemaToStandard, type JsonSchemaStandard } from \"./json-schema-to-standard\";\nexport { createJsonRpcClient, createTransport } from \"./transport\";\nexport type { JsonRpcClientHandle } from \"./transport\";\nexport type { McpTransportClient } from \"./transport.type\";\n\n/**\n * The callable `ai.mcp` surface — a factory that connects to an external\n * MCP server (Direction A) and also carries `.serve` to expose a local\n * primitive AS an MCP server (Direction B). Modeled as a function with an\n * attached `serve` property, mirroring how `ai.mcp(server).tools()` and\n * `ai.mcp.serve(source, options).start()` read in the design.\n */\nexport interface McpFactory {\n  /**\n   * Connect to an external MCP server and adapt its tools as agent tools.\n   *\n   * @param server - The transport config (`{ type: \"stdio\" }` / `{ type: \"http\" }`).\n   * @param options - Prefix / filter / per-call timeout, and a `signal`\n   *   that closes the client (and fails its calls) when it aborts.\n   */\n  (server: McpTransport, options?: McpClientOptions): McpClient;\n  /**\n   * Expose a built agent / supervisor / orchestrator (or a literal\n   * `ToolContract[]`, or named `{ groups }`) AS an MCP server. Over\n   * `{ type: \"http\" }`, `start()` resolves `{ url, close }`.\n   *\n   * @param source - The tools to expose.\n   * @param options - Server name, version, transport, schema dialect, resources, prompts.\n   */\n  serve(\n    source: McpServeSource,\n    options: McpServeOptions & { transport: McpHttpServeTransport },\n  ): McpServer<McpHttpServeHandle>;\n  serve(source: McpServeSource, options: McpServeOptions): McpServer;\n}\n\n/**\n * The `ai.mcp` factory value: the client factory with `.serve` attached.\n * `Object.assign` keeps `mcp` callable (Direction A) while widening it with\n * the `serve` member (Direction B) — one object, both directions. The\n * `declare module \"@warlock.js/ai\"` augmentation and the runtime\n * registration (`ai.mcp = mcp`) live in `../register`, so this barrel is a\n * pure value/type module the registrar consumes.\n */\nexport const mcp: McpFactory = Object.assign(\n  (server: McpTransport, options?: McpClientOptions): McpClient => mcpClient(server, options),\n  { serve },\n);\n"],"mappings":";;;;;;;;;;;;;;;;;AA+DA,MAAa,MAAkB,OAAO,QACnC,QAAsB,YAA0CA,MAAU,QAAQ,OAAO,GAC1F,EAAE,MAAM,CACV"}

package/esm/mcp/json-schema-to-standard.d.mts

@@ -1,4 +1,4 @@
-import { StandardSchemaV1 } from "@standard-schema/spec";
+import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
 //#region ../../packages/ai-tools/src/mcp/json-schema-to-standard.d.ts
 /**
  * Wrap a raw JSON Schema as a {@link StandardSchemaV1} whose
@@ -18,7 +18,8 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  *
  * @param schema - The JSON Schema (an MCP tool's `inputSchema`), or
  *   `undefined` for a no-argument tool.
- * @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })`.
+ * @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })` that also implements
+ * Standard JSON Schema, so provider adapters advertise the wrapped schema.
  *
  * @example
  * const input = jsonSchemaToStandard<{ q: string }>({
@@ -27,6 +28,8 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  *   required: ["q"],
  * });
  */
-export declare function jsonSchemaToStandard<TInput = unknown>(schema: Record<string, unknown> | undefined): StandardSchemaV1<TInput>;
+/** A validating wrapper that also exposes the JSON Schema it wraps. */
+export type JsonSchemaStandard<TInput = unknown> = StandardSchemaV1<TInput> & StandardJSONSchemaV1<TInput>;
+export declare function jsonSchemaToStandard<TInput = unknown>(schema: Record<string, unknown> | undefined): JsonSchemaStandard<TInput>;
 //#endregion
 //# sourceMappingURL=json-schema-to-standard.d.mts.map

package/esm/mcp/json-schema-to-standard.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"json-schema-to-standard.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/json-schema-to-standard.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA+JgB,qBAAqB,kBACnC,QAAQ,sCACP,iBAAiB"}
+{"version":3,"file":"json-schema-to-standard.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/json-schema-to-standard.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAiKY,mBAAmB,oBAAoB,iBAAiB,UAClE,qBAAqB;wBAcP,qBAAqB,kBACnC,QAAQ,sCACP,mBAAmB"}

package/esm/mcp/json-schema-to-standard.mjs

@@ -74,42 +74,31 @@ function makeCompiler(schema) {
 	};
 }
 /**
-* Wrap a raw JSON Schema as a {@link StandardSchemaV1} whose
-* `~standard.validate` runs Ajv. The shape mirrors `passthroughSchema()`
-* (`{ "~standard": { version: 1, vendor, validate } }`) so it drops into
-* `tool({ input })` exactly like a native seal schema.
-*
-* Validation behavior:
-* - **Valid input** → `{ value }` (the input is passed through unchanged;
-*   Ajv validates, it does not transform).
-* - **Invalid input** → `{ issues }` carrying Ajv's `instancePath` +
-*   message per failure, so `tool()` produces a `SchemaValidationError`.
-* - **Missing `ajv` peer** → a single issue carrying the curated install
-*   string, surfaced the same way (a developer-facing message in logs).
-* - **No / empty schema** → an accept-all passthrough (an MCP tool may
-*   advertise no `inputSchema`).
-*
-* @param schema - The JSON Schema (an MCP tool's `inputSchema`), or
-*   `undefined` for a no-argument tool.
-* @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })`.
-*
-* @example
-* const input = jsonSchemaToStandard<{ q: string }>({
-*   type: "object",
-*   properties: { q: { type: "string" } },
-*   required: ["q"],
-* });
+* Standard JSON Schema converter returning a copy of the wrapped schema, so
+* provider adapters (which may compact or rewrite it) never mutate the source.
+* The remote server owns its schema, so every target receives it unchanged.
 */
+function exposeSchema(schema) {
+	return {
+		input: () => structuredClone(schema),
+		output: () => structuredClone(schema)
+	};
+}
 function jsonSchemaToStandard(schema) {
 	if (!schema || Object.keys(schema).length === 0) return { "~standard": {
 		version: 1,
 		vendor: VENDOR,
-		validate: (value) => ({ value })
+		validate: (value) => ({ value }),
+		jsonSchema: exposeSchema({
+			type: "object",
+			properties: {}
+		})
 	} };
 	const compile = makeCompiler(schema);
 	return { "~standard": {
 		version: 1,
 		vendor: VENDOR,
+		jsonSchema: exposeSchema(schema),
 		async validate(value) {
 			await loadAjv();
 			if (!isAjvAvailable) return { issues: [{ message: AJV_INSTALL_INSTRUCTIONS }] };

package/esm/mcp/json-schema-to-standard.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"json-schema-to-standard.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/json-schema-to-standard.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * The inverse of `@warlock.js/ai`'s `extractJsonSchema` (which goes\n * Standard Schema → JSON Schema). Here we wrap a raw JSON Schema as a\n * {@link StandardSchemaV1} whose `~standard.validate` runs a lazily-imported\n * Ajv validator — so an MCP server's `inputSchema` (JSON Schema) becomes a\n * `ToolConfig.input` the `tool()` factory can validate against.\n *\n * Ajv is an OPTIONAL peer, lazy-imported on first validate following the\n * langfuse/readability pattern: a missing peer surfaces a curated install\n * string (via the returned issues), never a raw module-resolution stack.\n */\n\n/** The structural vendor template, mirroring `passthroughSchema()`. */\nconst VENDOR = \"warlock-ai\";\n\n// ============================================================\n// Lazily-loaded ajv (OPTIONAL peer)\n// ============================================================\n\n/**\n * Minimal structural view of an Ajv-compiled validator. Ajv is an optional\n * peer that may not be installed, so we model only the surface we touch\n * rather than depending on ajv's own published types. A validator is a\n * callable that returns a boolean and exposes the `errors` it collected.\n */\ninterface AjvValidateFunctionLike {\n  (data: unknown): boolean;\n  errors?: AjvErrorObject[] | null;\n}\n\n/** Minimal structural view of an `Ajv` instance — only `compile`. */\ninterface AjvInstanceLike {\n  compile(schema: Record<string, unknown>): AjvValidateFunctionLike;\n}\n\n/** The `Ajv` constructor, as exposed by both the CJS and ESM builds. */\ntype AjvConstructorLike = new (options?: Record<string, unknown>) => AjvInstanceLike;\n\n/**\n * Minimal structural view of the dynamically imported `ajv` module. Ajv\n * ships its constructor as a `default` export under ESM interop; the older\n * CJS shape exposes the constructor as the module namespace itself, so\n * `default` is optional here and the loader falls back to the namespace.\n */\ninterface AjvModuleLike {\n  default?: AjvConstructorLike;\n}\n\nlet AjvSdk: AjvModuleLike | undefined;\nlet ajvInstance: AjvInstanceLike | undefined;\nlet isAjvAvailable: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\nconst AJV_INSTALL_INSTRUCTIONS = `\nThe MCP client's JSON-Schema validation requires the ajv package.\nInstall it with:\n\n  npm install ajv\n\nOr with your preferred package manager:\n\n  pnpm add ajv\n  yarn add ajv\n`.trim();\n\n/**\n * Settle the lazy import of `ajv` once, concurrency-safe. A bare `catch`\n * flips the availability flag to `false`; the curated install string then\n * surfaces at validate time as a Standard Schema issue, never a raw\n * module-resolution error. The constructed `Ajv` instance is cached and\n * reused for every schema compile.\n */\nasync function loadAjv(): Promise<void> {\n  if (isAjvAvailable !== undefined) {\n    return;\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      AjvSdk = (await import(\"ajv\")) as AjvModuleLike;\n      // Ajv ships as a default export under both CJS and ESM interop; the\n      // older CJS shape exposes the constructor as the namespace itself.\n      const AjvCtor: AjvConstructorLike =\n        AjvSdk.default ?? (AjvSdk as unknown as AjvConstructorLike);\n      ajvInstance = new AjvCtor({ allErrors: true, strict: false });\n      isAjvAvailable = true;\n    } catch {\n      isAjvAvailable = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Compile a JSON Schema with the shared Ajv instance, caching the compiled\n * validator on a closure so repeated validations don't recompile. A schema\n * Ajv itself rejects at compile time (an invalid meta-schema) degrades to\n * an accept-all validator so a malformed remote schema can't wedge the\n * tool — the server, not us, owns its schema's correctness.\n */\nfunction makeCompiler(schema: Record<string, unknown>): () => AjvValidateFunctionLike | undefined {\n  let compiled: AjvValidateFunctionLike | undefined;\n  let attempted = false;\n\n  return () => {\n    if (attempted) {\n      return compiled;\n    }\n\n    attempted = true;\n\n    if (!ajvInstance) {\n      return undefined;\n    }\n\n    try {\n      compiled = ajvInstance.compile(schema);\n    } catch {\n      compiled = undefined;\n    }\n\n    return compiled;\n  };\n}\n\n/**\n * Wrap a raw JSON Schema as a {@link StandardSchemaV1} whose\n * `~standard.validate` runs Ajv. The shape mirrors `passthroughSchema()`\n * (`{ \"~standard\": { version: 1, vendor, validate } }`) so it drops into\n * `tool({ input })` exactly like a native seal schema.\n *\n * Validation behavior:\n * - **Valid input** → `{ value }` (the input is passed through unchanged;\n *   Ajv validates, it does not transform).\n * - **Invalid input** → `{ issues }` carrying Ajv's `instancePath` +\n *   message per failure, so `tool()` produces a `SchemaValidationError`.\n * - **Missing `ajv` peer** → a single issue carrying the curated install\n *   string, surfaced the same way (a developer-facing message in logs).\n * - **No / empty schema** → an accept-all passthrough (an MCP tool may\n *   advertise no `inputSchema`).\n *\n * @param schema - The JSON Schema (an MCP tool's `inputSchema`), or\n *   `undefined` for a no-argument tool.\n * @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })`.\n *\n * @example\n * const input = jsonSchemaToStandard<{ q: string }>({\n *   type: \"object\",\n *   properties: { q: { type: \"string\" } },\n *   required: [\"q\"],\n * });\n */\nexport function jsonSchemaToStandard<TInput = unknown>(\n  schema: Record<string, unknown> | undefined,\n): StandardSchemaV1<TInput> {\n  // A tool with no schema (or an empty object schema) validates everything\n  // — return an accept-all passthrough and never touch Ajv.\n  if (!schema || Object.keys(schema).length === 0) {\n    return {\n      \"~standard\": {\n        version: 1,\n        vendor: VENDOR,\n        validate: (value: unknown) => ({ value: value as TInput }),\n      },\n    };\n  }\n\n  const compile = makeCompiler(schema);\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: VENDOR,\n      async validate(value: unknown): Promise<StandardSchemaV1.Result<TInput>> {\n        await loadAjv();\n\n        if (!isAjvAvailable) {\n          return {\n            issues: [{ message: AJV_INSTALL_INSTRUCTIONS }],\n          };\n        }\n\n        const validator = compile();\n\n        // A schema Ajv could not compile degrades to accept-all rather\n        // than failing every call — the remote server owns its schema.\n        if (!validator) {\n          return { value: value as TInput };\n        }\n\n        const ok = validator(value);\n\n        if (ok) {\n          return { value: value as TInput };\n        }\n\n        const issues: StandardSchemaV1.Issue[] = (validator.errors ?? []).map((error) => ({\n          message: formatAjvError(error),\n          path: pathFromInstancePath(error.instancePath),\n        }));\n\n        return {\n          issues: issues.length > 0 ? issues : [{ message: \"input failed JSON Schema validation\" }],\n        };\n      },\n    },\n  };\n}\n\n/** A single Ajv error object — narrowed to the fields we read. */\ninterface AjvErrorObject {\n  instancePath?: string;\n  message?: string;\n  keyword?: string;\n}\n\n/**\n * Render one Ajv error into a human-readable issue message. Prefixes the\n * failing instance path (when present) so the model can see WHICH field\n * was wrong, e.g. `/query: must be string`.\n */\nfunction formatAjvError(error: AjvErrorObject): string {\n  const where = error.instancePath ? `${error.instancePath}: ` : \"\";\n  const message = error.message ?? `failed \"${error.keyword ?? \"validation\"}\"`;\n\n  return `${where}${message}`;\n}\n\n/**\n * Convert an Ajv `instancePath` (a JSON-Pointer like `/items/0/name`) into\n * the Standard Schema `path` segment array (`[\"items\", \"0\", \"name\"]`).\n * Empty paths (a root-level failure) become an empty array.\n */\nfunction pathFromInstancePath(instancePath: string | undefined): string[] {\n  if (!instancePath) {\n    return [];\n  }\n\n  return instancePath\n    .split(\"/\")\n    .filter((segment) => segment.length > 0)\n    .map((segment) => segment.replace(/~1/g, \"/\").replace(/~0/g, \"~\"));\n}\n\n/**\n * Reset the cached lazy-import state. Test-only seam so a spec can mock\n * `ajv` as present/absent across cases without module-cache bleed.\n *\n * @internal\n */\nexport function resetAjvCacheForTests(): void {\n  AjvSdk = undefined;\n  ajvInstance = undefined;\n  isAjvAvailable = undefined;\n  loadingPromise = undefined;\n}\n"],"mappings":";;;;;;;;;;;;;AAeA,MAAM,SAAS;AAmCf,IAAI;AACJ,IAAI;AACJ,IAAI;AACJ,IAAI;AAEJ,MAAM,2BAA2B;;;;;;;;;;EAU/B,KAAK;;;;;;;;AASP,eAAe,UAAyB;CACtC,IAAI,mBAAmB,QACrB;CAGF,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GACF,SAAU,MAAM,OAAO;GAKvB,cAAc,KADZ,OAAO,WAAY,QACK;IAAE,WAAW;IAAM,QAAQ;GAAM,CAAC;GAC5D,iBAAiB;EACnB,QAAQ;GACN,iBAAiB;EACnB;CACF,EAAC,CAAE;CAEH,OAAO;AACT;;;;;;;;AASA,SAAS,aAAa,QAA4E;CAChG,IAAI;CACJ,IAAI,YAAY;CAEhB,aAAa;EACX,IAAI,WACF,OAAO;EAGT,YAAY;EAEZ,IAAI,CAAC,aACH;EAGF,IAAI;GACF,WAAW,YAAY,QAAQ,MAAM;EACvC,QAAQ;GACN,WAAW;EACb;EAEA,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,qBACd,QAC0B;CAG1B,IAAI,CAAC,UAAU,OAAO,KAAK,MAAM,CAAC,CAAC,WAAW,GAC5C,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,WAAoB,EAAS,MAAgB;CAC1D,EACF;CAGF,MAAM,UAAU,aAAa,MAAM;CAEnC,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,MAAM,SAAS,OAA0D;GACvE,MAAM,QAAQ;GAEd,IAAI,CAAC,gBACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAChD;GAGF,MAAM,YAAY,QAAQ;GAI1B,IAAI,CAAC,WACH,OAAO,EAAS,MAAgB;GAKlC,IAFW,UAAU,KAEhB,GACH,OAAO,EAAS,MAAgB;GAGlC,MAAM,UAAoC,UAAU,UAAU,CAAC,EAAC,CAAE,KAAK,WAAW;IAChF,SAAS,eAAe,KAAK;IAC7B,MAAM,qBAAqB,MAAM,YAAY;GAC/C,EAAE;GAEF,OAAO,EACL,QAAQ,OAAO,SAAS,IAAI,SAAS,CAAC,EAAE,SAAS,sCAAsC,CAAC,EAC1F;EACF;CACF,EACF;AACF;;;;;;AAcA,SAAS,eAAe,OAA+B;CAIrD,OAAO,GAHO,MAAM,eAAe,GAAG,MAAM,aAAa,MAAM,KAC/C,MAAM,WAAW,WAAW,MAAM,WAAW,aAAa;AAG5E;;;;;;AAOA,SAAS,qBAAqB,cAA4C;CACxE,IAAI,CAAC,cACH,OAAO,CAAC;CAGV,OAAO,aACJ,MAAM,GAAG,CAAC,CACV,QAAQ,YAAY,QAAQ,SAAS,CAAC,CAAC,CACvC,KAAK,YAAY,QAAQ,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC;AACrE"}
+{"version":3,"file":"json-schema-to-standard.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/json-schema-to-standard.ts"],"sourcesContent":["import type { StandardJSONSchemaV1, StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * The inverse of `@warlock.js/ai`'s `extractJsonSchema` (which goes\n * Standard Schema → JSON Schema). Here we wrap a raw JSON Schema as a\n * {@link StandardSchemaV1} whose `~standard.validate` runs a lazily-imported\n * Ajv validator — so an MCP server's `inputSchema` (JSON Schema) becomes a\n * `ToolConfig.input` the `tool()` factory can validate against.\n *\n * Ajv is an OPTIONAL peer, lazy-imported on first validate following the\n * langfuse/readability pattern: a missing peer surfaces a curated install\n * string (via the returned issues), never a raw module-resolution stack.\n */\n\n/** The structural vendor template, mirroring `passthroughSchema()`. */\nconst VENDOR = \"warlock-ai\";\n\n// ============================================================\n// Lazily-loaded ajv (OPTIONAL peer)\n// ============================================================\n\n/**\n * Minimal structural view of an Ajv-compiled validator. Ajv is an optional\n * peer that may not be installed, so we model only the surface we touch\n * rather than depending on ajv's own published types. A validator is a\n * callable that returns a boolean and exposes the `errors` it collected.\n */\ninterface AjvValidateFunctionLike {\n  (data: unknown): boolean;\n  errors?: AjvErrorObject[] | null;\n}\n\n/** Minimal structural view of an `Ajv` instance — only `compile`. */\ninterface AjvInstanceLike {\n  compile(schema: Record<string, unknown>): AjvValidateFunctionLike;\n}\n\n/** The `Ajv` constructor, as exposed by both the CJS and ESM builds. */\ntype AjvConstructorLike = new (options?: Record<string, unknown>) => AjvInstanceLike;\n\n/**\n * Minimal structural view of the dynamically imported `ajv` module. Ajv\n * ships its constructor as a `default` export under ESM interop; the older\n * CJS shape exposes the constructor as the module namespace itself, so\n * `default` is optional here and the loader falls back to the namespace.\n */\ninterface AjvModuleLike {\n  default?: AjvConstructorLike;\n}\n\nlet AjvSdk: AjvModuleLike | undefined;\nlet ajvInstance: AjvInstanceLike | undefined;\nlet isAjvAvailable: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\nconst AJV_INSTALL_INSTRUCTIONS = `\nThe MCP client's JSON-Schema validation requires the ajv package.\nInstall it with:\n\n  npm install ajv\n\nOr with your preferred package manager:\n\n  pnpm add ajv\n  yarn add ajv\n`.trim();\n\n/**\n * Settle the lazy import of `ajv` once, concurrency-safe. A bare `catch`\n * flips the availability flag to `false`; the curated install string then\n * surfaces at validate time as a Standard Schema issue, never a raw\n * module-resolution error. The constructed `Ajv` instance is cached and\n * reused for every schema compile.\n */\nasync function loadAjv(): Promise<void> {\n  if (isAjvAvailable !== undefined) {\n    return;\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      AjvSdk = (await import(\"ajv\")) as AjvModuleLike;\n      // Ajv ships as a default export under both CJS and ESM interop; the\n      // older CJS shape exposes the constructor as the namespace itself.\n      const AjvCtor: AjvConstructorLike =\n        AjvSdk.default ?? (AjvSdk as unknown as AjvConstructorLike);\n      ajvInstance = new AjvCtor({ allErrors: true, strict: false });\n      isAjvAvailable = true;\n    } catch {\n      isAjvAvailable = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Compile a JSON Schema with the shared Ajv instance, caching the compiled\n * validator on a closure so repeated validations don't recompile. A schema\n * Ajv itself rejects at compile time (an invalid meta-schema) degrades to\n * an accept-all validator so a malformed remote schema can't wedge the\n * tool — the server, not us, owns its schema's correctness.\n */\nfunction makeCompiler(schema: Record<string, unknown>): () => AjvValidateFunctionLike | undefined {\n  let compiled: AjvValidateFunctionLike | undefined;\n  let attempted = false;\n\n  return () => {\n    if (attempted) {\n      return compiled;\n    }\n\n    attempted = true;\n\n    if (!ajvInstance) {\n      return undefined;\n    }\n\n    try {\n      compiled = ajvInstance.compile(schema);\n    } catch {\n      compiled = undefined;\n    }\n\n    return compiled;\n  };\n}\n\n/**\n * Wrap a raw JSON Schema as a {@link StandardSchemaV1} whose\n * `~standard.validate` runs Ajv. The shape mirrors `passthroughSchema()`\n * (`{ \"~standard\": { version: 1, vendor, validate } }`) so it drops into\n * `tool({ input })` exactly like a native seal schema.\n *\n * Validation behavior:\n * - **Valid input** → `{ value }` (the input is passed through unchanged;\n *   Ajv validates, it does not transform).\n * - **Invalid input** → `{ issues }` carrying Ajv's `instancePath` +\n *   message per failure, so `tool()` produces a `SchemaValidationError`.\n * - **Missing `ajv` peer** → a single issue carrying the curated install\n *   string, surfaced the same way (a developer-facing message in logs).\n * - **No / empty schema** → an accept-all passthrough (an MCP tool may\n *   advertise no `inputSchema`).\n *\n * @param schema - The JSON Schema (an MCP tool's `inputSchema`), or\n *   `undefined` for a no-argument tool.\n * @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })` that also implements\n * Standard JSON Schema, so provider adapters advertise the wrapped schema.\n *\n * @example\n * const input = jsonSchemaToStandard<{ q: string }>({\n *   type: \"object\",\n *   properties: { q: { type: \"string\" } },\n *   required: [\"q\"],\n * });\n */\n/** A validating wrapper that also exposes the JSON Schema it wraps. */\nexport type JsonSchemaStandard<TInput = unknown> = StandardSchemaV1<TInput> &\n  StandardJSONSchemaV1<TInput>;\n\n/**\n * Standard JSON Schema converter returning a copy of the wrapped schema, so\n * provider adapters (which may compact or rewrite it) never mutate the source.\n * The remote server owns its schema, so every target receives it unchanged.\n */\nfunction exposeSchema(schema: Record<string, unknown>): StandardJSONSchemaV1.Converter {\n  return {\n    input: () => structuredClone(schema),\n    output: () => structuredClone(schema),\n  };\n}\n\nexport function jsonSchemaToStandard<TInput = unknown>(\n  schema: Record<string, unknown> | undefined,\n): JsonSchemaStandard<TInput> {\n  // A tool with no schema (or an empty object schema) validates everything\n  // — return an accept-all passthrough and never touch Ajv.\n  if (!schema || Object.keys(schema).length === 0) {\n    return {\n      \"~standard\": {\n        version: 1,\n        vendor: VENDOR,\n        validate: (value: unknown) => ({ value: value as TInput }),\n        jsonSchema: exposeSchema({ type: \"object\", properties: {} }),\n      },\n    };\n  }\n\n  const compile = makeCompiler(schema);\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: VENDOR,\n      jsonSchema: exposeSchema(schema),\n      async validate(value: unknown): Promise<StandardSchemaV1.Result<TInput>> {\n        await loadAjv();\n\n        if (!isAjvAvailable) {\n          return {\n            issues: [{ message: AJV_INSTALL_INSTRUCTIONS }],\n          };\n        }\n\n        const validator = compile();\n\n        // A schema Ajv could not compile degrades to accept-all rather\n        // than failing every call — the remote server owns its schema.\n        if (!validator) {\n          return { value: value as TInput };\n        }\n\n        const ok = validator(value);\n\n        if (ok) {\n          return { value: value as TInput };\n        }\n\n        const issues: StandardSchemaV1.Issue[] = (validator.errors ?? []).map((error) => ({\n          message: formatAjvError(error),\n          path: pathFromInstancePath(error.instancePath),\n        }));\n\n        return {\n          issues: issues.length > 0 ? issues : [{ message: \"input failed JSON Schema validation\" }],\n        };\n      },\n    },\n  };\n}\n\n/** A single Ajv error object — narrowed to the fields we read. */\ninterface AjvErrorObject {\n  instancePath?: string;\n  message?: string;\n  keyword?: string;\n}\n\n/**\n * Render one Ajv error into a human-readable issue message. Prefixes the\n * failing instance path (when present) so the model can see WHICH field\n * was wrong, e.g. `/query: must be string`.\n */\nfunction formatAjvError(error: AjvErrorObject): string {\n  const where = error.instancePath ? `${error.instancePath}: ` : \"\";\n  const message = error.message ?? `failed \"${error.keyword ?? \"validation\"}\"`;\n\n  return `${where}${message}`;\n}\n\n/**\n * Convert an Ajv `instancePath` (a JSON-Pointer like `/items/0/name`) into\n * the Standard Schema `path` segment array (`[\"items\", \"0\", \"name\"]`).\n * Empty paths (a root-level failure) become an empty array.\n */\nfunction pathFromInstancePath(instancePath: string | undefined): string[] {\n  if (!instancePath) {\n    return [];\n  }\n\n  return instancePath\n    .split(\"/\")\n    .filter((segment) => segment.length > 0)\n    .map((segment) => segment.replace(/~1/g, \"/\").replace(/~0/g, \"~\"));\n}\n\n/**\n * Reset the cached lazy-import state. Test-only seam so a spec can mock\n * `ajv` as present/absent across cases without module-cache bleed.\n *\n * @internal\n */\nexport function resetAjvCacheForTests(): void {\n  AjvSdk = undefined;\n  ajvInstance = undefined;\n  isAjvAvailable = undefined;\n  loadingPromise = undefined;\n}\n"],"mappings":";;;;;;;;;;;;;AAeA,MAAM,SAAS;AAmCf,IAAI;AACJ,IAAI;AACJ,IAAI;AACJ,IAAI;AAEJ,MAAM,2BAA2B;;;;;;;;;;EAU/B,KAAK;;;;;;;;AASP,eAAe,UAAyB;CACtC,IAAI,mBAAmB,QACrB;CAGF,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GACF,SAAU,MAAM,OAAO;GAKvB,cAAc,KADZ,OAAO,WAAY,QACK;IAAE,WAAW;IAAM,QAAQ;GAAM,CAAC;GAC5D,iBAAiB;EACnB,QAAQ;GACN,iBAAiB;EACnB;CACF,EAAC,CAAE;CAEH,OAAO;AACT;;;;;;;;AASA,SAAS,aAAa,QAA4E;CAChG,IAAI;CACJ,IAAI,YAAY;CAEhB,aAAa;EACX,IAAI,WACF,OAAO;EAGT,YAAY;EAEZ,IAAI,CAAC,aACH;EAGF,IAAI;GACF,WAAW,YAAY,QAAQ,MAAM;EACvC,QAAQ;GACN,WAAW;EACb;EAEA,OAAO;CACT;AACF;;;;;;AAuCA,SAAS,aAAa,QAAiE;CACrF,OAAO;EACL,aAAa,gBAAgB,MAAM;EACnC,cAAc,gBAAgB,MAAM;CACtC;AACF;AAEA,SAAgB,qBACd,QAC4B;CAG5B,IAAI,CAAC,UAAU,OAAO,KAAK,MAAM,CAAC,CAAC,WAAW,GAC5C,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,WAAoB,EAAS,MAAgB;EACxD,YAAY,aAAa;GAAE,MAAM;GAAU,YAAY,CAAC;EAAE,CAAC;CAC7D,EACF;CAGF,MAAM,UAAU,aAAa,MAAM;CAEnC,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,YAAY,aAAa,MAAM;EAC/B,MAAM,SAAS,OAA0D;GACvE,MAAM,QAAQ;GAEd,IAAI,CAAC,gBACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAChD;GAGF,MAAM,YAAY,QAAQ;GAI1B,IAAI,CAAC,WACH,OAAO,EAAS,MAAgB;GAKlC,IAFW,UAAU,KAEhB,GACH,OAAO,EAAS,MAAgB;GAGlC,MAAM,UAAoC,UAAU,UAAU,CAAC,EAAC,CAAE,KAAK,WAAW;IAChF,SAAS,eAAe,KAAK;IAC7B,MAAM,qBAAqB,MAAM,YAAY;GAC/C,EAAE;GAEF,OAAO,EACL,QAAQ,OAAO,SAAS,IAAI,SAAS,CAAC,EAAE,SAAS,sCAAsC,CAAC,EAC1F;EACF;CACF,EACF;AACF;;;;;;AAcA,SAAS,eAAe,OAA+B;CAIrD,OAAO,GAHO,MAAM,eAAe,GAAG,MAAM,aAAa,MAAM,KAC/C,MAAM,WAAW,WAAW,MAAM,WAAW,aAAa;AAG5E;;;;;;AAOA,SAAS,qBAAqB,cAA4C;CACxE,IAAI,CAAC,cACH,OAAO,CAAC;CAGV,OAAO,aACJ,MAAM,GAAG,CAAC,CACV,QAAQ,YAAY,QAAQ,SAAS,CAAC,CAAC,CACvC,KAAK,YAAY,QAAQ,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC;AACrE"}

package/esm/mcp/serve-http.mjs

@@ -1,8 +1,9 @@
 import { McpServeError } from "../errors.mjs";
 import { SUPPORTED_PROTOCOL_VERSIONS } from "./protocol.mjs";
+import { isRecord } from "./result.mjs";
 import { McpServeRequests } from "./serve-requests.mjs";
 import { createHash, timingSafeEqual } from "node:crypto";
-import { createServer } from "node:http";
+import { createServer, validateHeaderValue } from "node:http";
 import { isIPv4, isIPv6 } from "node:net";
 
 //#region ../../packages/ai-tools/src/mcp/serve-http.ts
@@ -147,6 +148,7 @@ function resolveSettings(transport) {
 		tokenDigests: tokens.map(digest),
 		authorize: auth?.authorize,
 		authenticate: auth?.authenticate,
+		onAuthRefusal: transport.onAuthRefusal,
 		authRequired,
 		allowedOrigins: new Set((transport.allowedOrigins ?? []).map(normalizeOrigin)),
 		allowedHosts: new Set((transport.allowedHosts ?? []).map((name) => hostnameOf(name))),
@@ -187,6 +189,52 @@ function sendRefusal(response, status, code, message, headers = {}) {
 		}
 	}, headers);
 }
+const AUTH_REFUSAL_HEADERS = /* @__PURE__ */ new Set([
+	"www-authenticate",
+	"cache-control",
+	"retry-after",
+	"content-language",
+	"x-request-id"
+]);
+/** Snapshot plain JSON, rejecting cycles and values JSON would silently coerce/drop. */
+function copyRefusalBody(value, ancestors = /* @__PURE__ */ new Set()) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value !== "object" || value === null || ancestors.has(value)) throw new TypeError("Invalid auth refusal body.");
+	const prototype = Object.getPrototypeOf(value);
+	if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) throw new TypeError("Invalid auth refusal body.");
+	ancestors.add(value);
+	const result = Array.isArray(value) ? Array.from(value, (entry) => copyRefusalBody(entry, ancestors)) : Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, copyRefusalBody(entry, ancestors)]));
+	ancestors.delete(value);
+	return result;
+}
+/** A custom response can only end a denied exchange; it cannot authorize dispatch. */
+async function sendAuthRefusal(response, settings, context) {
+	const challenge = settings.tokenDigests.length > 0 || settings.authenticate ? { "www-authenticate": "Bearer realm=\"mcp\"" } : {};
+	if (settings.onAuthRefusal) try {
+		const result = await settings.onAuthRefusal(Object.freeze(context));
+		if (!isRecord(result)) throw new TypeError("Invalid auth refusal response.");
+		const customStatus = result.status;
+		const status = customStatus === void 0 ? 401 : customStatus;
+		if (typeof status !== "number" || !Number.isInteger(status) || status < 400 || status > 599) throw new TypeError("Invalid auth refusal status.");
+		const headers = { ...challenge };
+		const customHeaders = result.headers;
+		if (customHeaders !== void 0) {
+			if (!isRecord(customHeaders)) throw new TypeError("Invalid auth refusal headers.");
+			const prototype = Object.getPrototypeOf(customHeaders);
+			if (prototype !== Object.prototype && prototype !== null) throw new TypeError("Invalid auth refusal headers.");
+			for (const [name, value] of Object.entries(customHeaders)) {
+				const normalized = name.toLowerCase();
+				if (!AUTH_REFUSAL_HEADERS.has(normalized) || typeof value !== "string") throw new TypeError("Invalid auth refusal header.");
+				validateHeaderValue(normalized, value);
+				headers[normalized] = value;
+			}
+		}
+		sendJson(response, status, copyRefusalBody(result.body), headers);
+		return;
+	} catch {}
+	sendRefusal(response, 401, JSON_RPC_SERVER_ERROR, "Unauthorized.", challenge);
+}
 /** Write an empty-bodied status (202 / 405). */
 function sendEmpty(response, status, headers = {}) {
 	if (response.headersSent || response.destroyed) return;
@@ -302,8 +350,12 @@ async function handleRequest(request, response, settings, dispatch, signal, requ
 	if (request.socket.remoteAddress !== void 0) info.remoteAddress = request.socket.remoteAddress;
 	const authentication = await authorized(info, settings);
 	if (!authentication.allowed) {
-		const challenge = settings.tokenDigests.length > 0 || settings.authenticate ? { "www-authenticate": "Bearer realm=\"mcp\"" } : {};
-		sendRefusal(response, 401, JSON_RPC_SERVER_ERROR, "Unauthorized.", challenge);
+		await sendAuthRefusal(response, settings, {
+			check: authentication.check,
+			method,
+			path,
+			target: routes ? "route" : "mcp"
+		});
 		return;
 	}
 	if (routes) {
@@ -451,21 +503,38 @@ async function authorized(info, settings) {
 		const presented = digest(match?.[1]?.trim() ?? "");
 		let matched = false;
 		for (const expected of settings.tokenDigests) matched = timingSafeEqual(presented, expected) || matched;
-		if (!match || !matched) return { allowed: false };
+		if (!match || !matched) return {
+			allowed: false,
+			check: "bearer"
+		};
 	}
-	try {
-		if (settings.authorize && await settings.authorize(info) !== true) return { allowed: false };
-		if (settings.authenticate) {
-			const principal = await settings.authenticate(info);
-			return principal === void 0 ? { allowed: false } : {
-				allowed: true,
-				principal
-			};
-		}
-		return { allowed: true };
+	if (settings.authorize) try {
+		if (await settings.authorize(info) !== true) return {
+			allowed: false,
+			check: "authorize"
+		};
+	} catch {
+		return {
+			allowed: false,
+			check: "authorize"
+		};
+	}
+	if (settings.authenticate) try {
+		const principal = await settings.authenticate(info);
+		return principal === void 0 ? {
+			allowed: false,
+			check: "authenticate"
+		} : {
+			allowed: true,
+			principal
+		};
 	} catch {
-		return { allowed: false };
+		return {
+			allowed: false,
+			check: "authenticate"
+		};
 	}
+	return { allowed: true };
 }
 /**
 * Stateless HTTP has no connection/session id. Repeat the caller's credential