holon-sh 0.0.1-dev.6 → 0.0.1-dev.8

package/src/ext/files.client.ts

@@ -0,0 +1,329 @@
+// Client side of the MCP files extension (draft):
+// https://github.com/modelcontextprotocol/experimental-ext-file-uploads/blob/main/specification/draft/file-uploads.md
+import type { Client, JSONRPCMessage, MessageExtraInfo, Transport } from "@modelcontextprotocol/client";
+import { base64, fetchGlobal, sha256 } from "#platform";
+import { EXTENSION, type Download } from "./files.js";
+
+type Json = Record<string, unknown>;
+
+export interface FileConnection {
+  client: Pick<Client, "getServerCapabilities">;
+  resolved: { endpoint: URL | string; fileOrigins?: string[]; installationUID?: string };
+  authorization?: string;
+}
+
+interface FileInput { id: string; name?: string; mimeType: string; size: number; digest?: { algorithm: "sha-256"; value: string }; data?: string }
+interface Attachment { blob: Blob; input: FileInput }
+export type Files = Map<string, Attachment>;
+
+const list = (value: unknown): unknown[] => Array.isArray(value) ? value : [];
+const isObject = (value: unknown): value is Json => typeof value === "object" && value !== null && !Array.isArray(value);
+const isPlain = (value: unknown): value is Json => isObject(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const present = (value: unknown): Json | undefined => isObject(value) ? Object.fromEntries(Object.entries(value).filter(([, member]) => member !== null)) : undefined;
+const quoted = (name: string | undefined) => name === undefined ? "a file" : JSON.stringify(name);
+
+function refuse(reason: string): never {
+  throw new Error(reason);
+}
+
+export function settings({ client }: FileConnection): Json | undefined {
+  const advertised = client.getServerCapabilities()?.extensions?.[EXTENSION];
+  return isObject(advertised) && advertised.revision == null ? advertised : undefined;
+}
+
+const uploadRequests = new WeakSet<object>();
+
+export function isUploadRequest(error: unknown): error is { data: Json } {
+  const data = (error as { data?: unknown } | null | undefined)?.data;
+  return isObject(data) && uploadRequests.has(data);
+}
+
+// The MCP client rejects a result type it does not know and drops the result, and has no hook for extension result
+// types yet (typescript-sdk#2782). The transport hands an upload request to it as a JSON-RPC error instead, whose data is
+// the result: the client keeps an error's data as received. Every other message passes through unchanged.
+export function acceptUploadRequests<T extends Transport>(transport: T): T {
+  let handler: Transport["onmessage"];
+  const receive = (message: JSONRPCMessage, extra?: MessageExtraInfo) => {
+    if ("result" in message && message.result?.resultType === "upload_required") {
+      uploadRequests.add(message.result);
+      message = { jsonrpc: "2.0", id: message.id, error: { code: -32603, message: "Unsupported result type 'upload_required'", data: message.result } };
+    }
+    handler?.(message, extra);
+  };
+  Object.defineProperty(transport, "onmessage", { configurable: true, get: () => handler && receive, set: (value: Transport["onmessage"]) => { handler = value; } });
+  return transport;
+}
+
+function contains(value: unknown): boolean {
+  if (value instanceof Blob) return true;
+  if (Array.isArray(value)) return value.some(contains);
+  return isPlain(value) && Object.values(value).some(contains);
+}
+
+const resolve = (root: unknown, ref: string) => ref.slice(1).split("/").slice(1)
+  .reduce<unknown>((node, token) => node === null || typeof node !== "object" ? undefined : (node as Json)[decodeURIComponent(token).replaceAll("~1", "/").replaceAll("~0", "~")], root);
+
+function expand(schemas: unknown[], root: unknown, seen = new Set<object>()): Json[] {
+  return schemas.flatMap(schema => {
+    if (!isObject(schema) || seen.has(schema)) return [];
+    seen.add(schema);
+    const target = typeof schema.$ref === "string" && schema.$ref.startsWith("#") ? resolve(root, schema.$ref) : undefined;
+    return [schema, ...expand([target, ...list(schema.anyOf), ...list(schema.oneOf), ...list(schema.allOf)], root, seen)];
+  });
+}
+
+interface Found { blob: Blob; schema: Json; input: FileInput }
+
+function replace(value: unknown, schemas: unknown[], root: unknown, path: string, found: Found[], label: string): unknown {
+  if (value instanceof Blob) {
+    const schema = expand(schemas, root).find(schema => "x-mcp-file" in schema);
+    if (!schema) throw new Error(`${label}: the Blob at ${path || "/"} is not a file argument of the tool; the tool was not called.`);
+    const input = {} as FileInput;
+    found.push({ blob: value, schema, input });
+    return input;
+  }
+  if (Array.isArray(value)) {
+    const all = expand(schemas, root);
+    return value.map((item, index) => replace(item, all.map(schema => index < list(schema.prefixItems).length ? list(schema.prefixItems)[index] : schema.items), root, `${path}/${index}`, found, label));
+  }
+  if (!isPlain(value)) return value;
+  const all = expand(schemas, root);
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, replace(item, all.map(schema => isObject(schema.properties) ? schema.properties[key] : undefined), root, `${path}/${key}`, found, label)]));
+}
+
+function baseName(name: unknown): string | undefined {
+  const base = typeof name === "string" ? name.split(/[/\\]/).pop() : "";
+  return base && base !== "." && base !== ".." ? base : undefined;
+}
+
+export async function prepare(args: Json | undefined, { label, connection, schema }: { label: string; connection: FileConnection | undefined; schema: () => Promise<unknown> }): Promise<{ arguments: Json | undefined; files: Files }> {
+  const files: Files = new Map();
+  if (!contains(args)) return { arguments: args, files };
+  if (!connection) throw new Error(`${label}: file arguments need an endpoint binding; the tool was not called.`);
+  const server = settings(connection);
+  if (!server) throw new Error(`${label}: the server does not accept files; the tool was not called.`);
+  const root = await schema();
+  const found: Found[] = [];
+  const replaced = replace(args, [root], root, "", found, label) as Json;
+  await Promise.all(found.map(async ({ blob, schema, input }) => {
+    const descriptor = present(schema["x-mcp-file"]) ?? {};
+    const name = baseName((blob as { name?: unknown }).name);
+    if (blob.size > (descriptor.maxSize as number)) throw new Error(`${label}: ${quoted(name)} is ${blob.size} bytes, over the tool's limit of ${descriptor.maxSize}; the tool was not called.`);
+    Object.assign(input, { id: crypto.randomUUID(), ...(name !== undefined && { name }), mimeType: blob.type || "application/octet-stream", size: blob.size });
+    if (list(schema.required).includes("digest")) input.digest = { algorithm: "sha-256", value: await sha256(blob) };
+    files.set(input.id, { blob, input });
+  }));
+  let budget = Number.isSafeInteger(server.maxInlineBytes) ? server.maxInlineBytes as number : 0;
+  for (const { blob, input } of [...files.values()].sort((a, b) => a.blob.size - b.blob.size)) {
+    if (blob.size === 0) continue;
+    if (blob.size <= budget) {
+      budget -= blob.size;
+      input.data = await base64(blob);
+    } else if (!isObject(server.upload)) {
+      throw new Error(`${label}: the server cannot receive ${quoted(input.name)} (${blob.size} bytes): it takes ${budget} more bytes inline and no uploads; the tool was not called.`);
+    }
+  }
+  return { arguments: replaced, files };
+}
+
+interface Form { fileField: string; fields: Array<{ name: string; value: string }> }
+interface Target { url: string; path: boolean; allowlisted: boolean; include: boolean; headers: Record<string, string>; method: string; form?: Form; expiresAt?: string }
+
+const UPLOAD = new Set(["fileId", "url", "path", "method", "form", "headers", "credentials", "expiresAt", "_meta"]);
+const DOWNLOAD = new Set(["name", "mimeType", "size", "digest", "url", "path", "headers", "credentials", "expiresAt", "_meta"]);
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const FIELD_VALUE = /^(?:[\x21-\x7e\x80-\xff](?:[\t\x20-\x7e\x80-\xff]*[\x21-\x7e\x80-\xff])?)?$/;
+// https://fetch.spec.whatwg.org/#forbidden-request-header, plus Authorization.
+const FORBIDDEN = new Set(["accept-charset", "accept-encoding", "access-control-request-headers", "access-control-request-method", "authorization", "connection", "content-length", "cookie", "cookie2", "date", "dnt", "expect", "host", "keep-alive", "origin", "referer", "set-cookie", "te", "trailer", "transfer-encoding", "upgrade", "via"]);
+const OVERRIDES = new Set(["x-http-method-override", "x-http-method", "x-method-override"]);
+const ROUTING = new Set(["forwarded", "x-original-url", "x-rewrite-url", ...OVERRIDES]);
+const FORM_HEADERS = new Set(["content-type", "content-encoding", "content-range", "content-digest", "repr-digest"]);
+const FORM_NAME = /^[^\p{Cc}"\\]+$/u;
+const PATH = /^(?:\/(?!\.\.?(?:\/|$))[A-Za-z0-9\-_~.]+)+$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$/;
+const loopback = (host: string) => host === "localhost" || host.endsWith(".localhost") || /^127\.\d+\.\d+\.\d+$/.test(host) || host === "[::1]";
+const expired = (target: { expiresAt?: string }) => target.expiresAt !== undefined && Date.parse(target.expiresAt) <= Date.now();
+
+function parse(url: string): URL | undefined {
+  try { return new URL(url); } catch { return undefined; }
+}
+
+function check(raw: unknown, kind: "upload" | "download", { resolved }: FileConnection): Target {
+  const target = present(raw);
+  if (!target) refuse("not an object");
+  const unknown = Object.keys(target).find(key => !(kind === "upload" ? UPLOAD : DOWNLOAD).has(key));
+  if (unknown !== undefined) refuse(`unknown member ${JSON.stringify(unknown)}`);
+  if (typeof target.url === "string" === (typeof target.path === "string") || [target.url, target.path].some(value => value !== undefined && typeof value !== "string")) refuse("needs exactly one of url and path");
+  if (target.credentials !== "omit" && target.credentials !== "include") refuse("credentials must be omit or include");
+  const { expiresAt } = target;
+  if (expiresAt !== undefined && !(typeof expiresAt === "string" && TIMESTAMP.test(expiresAt) && !Number.isNaN(Date.parse(expiresAt)))) refuse("expiresAt is not an RFC 3339 timestamp");
+  if (target.headers !== undefined && !(isObject(target.headers) && Object.values(target.headers).every(value => typeof value === "string"))) refuse("headers must map names to strings");
+  const headers = (target.headers ?? {}) as Record<string, string>;
+  let form: Form | undefined;
+  if (kind === "upload") {
+    if (typeof target.fileId !== "string") refuse("fileId is not a string");
+    if (target.method !== undefined && target.method !== "PUT" && target.method !== "POST") refuse("method must be PUT or POST");
+    if (target.form !== undefined) {
+      const raw = present(target.form);
+      if (target.method !== "POST") refuse("a form target must use POST");
+      if (!raw || Object.keys(raw).some(key => key !== "fields" && key !== "fileField") || !Array.isArray(raw.fields) || typeof raw.fileField !== "string") refuse("form is malformed");
+      const fields = raw.fields.map(present);
+      if (!FORM_NAME.test(raw.fileField)) refuse("form fileField is not allowed");
+      for (const field of fields) {
+        if (!field || Object.keys(field).some(key => key !== "name" && key !== "value") || typeof field.name !== "string" || typeof field.value !== "string") refuse("a form field is malformed");
+        if (!FORM_NAME.test(field.name) || field.name === raw.fileField || /[\r\n\0]/.test(field.value)) refuse("a form field is not allowed");
+      }
+      form = { fileField: raw.fileField, fields: fields as Form["fields"] };
+    }
+  } else {
+    if (target.name !== undefined && typeof target.name !== "string") refuse("name is not a string");
+    if (typeof target.mimeType !== "string") refuse("mimeType is not a string");
+    if (!Number.isSafeInteger(target.size) || (target.size as number) < 0) refuse("size is not a non-negative integer");
+    const digest = target.digest === undefined ? undefined : present(target.digest);
+    if (target.digest !== undefined && (!digest || Object.keys(digest).some(key => key !== "algorithm" && key !== "value") || digest.algorithm !== "sha-256" || typeof digest.value !== "string")) refuse("digest is malformed");
+  }
+  const include = target.credentials === "include";
+  for (const [name, value] of Object.entries(headers)) {
+    const lower = name.toLowerCase();
+    if (!TOKEN.test(name) || !FIELD_VALUE.test(value)) refuse("a header is not valid HTTP");
+    if (FORBIDDEN.has(lower) || lower.startsWith("proxy-") || lower.startsWith("sec-")
+      || OVERRIDES.has(lower) && value.split(",").some(method => ["connect", "trace", "track"].includes(method.trim().toLowerCase()))) refuse(`header ${name} is not allowed`);
+    if ((target.path !== undefined || include) && (ROUTING.has(lower) || lower.startsWith("x-forwarded-"))) refuse(`header ${name} is not allowed with this target`);
+    if (form && FORM_HEADERS.has(lower)) refuse(`header ${name} is not allowed with a form`);
+  }
+  const endpoint = new URL(resolved.endpoint);
+  const origins = resolved.fileOrigins && new Set(resolved.fileOrigins.map(origin => new URL(origin).origin));
+  let url: URL;
+  let allowlisted = false;
+  if (typeof target.url === "string") {
+    const parsed = parse(target.url);
+    if (!parsed || parsed.username || parsed.password) refuse("url is not an absolute URL without userinfo");
+    url = parsed;
+    allowlisted = origins?.has(url.origin) ?? false;
+    if (origins && !allowlisted) refuse("url is not on fileOrigins");
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && allowlisted && loopback(url.hostname))) refuse("url is not https");
+    if (include && url.origin !== endpoint.origin) refuse("credentials include is honored only at the server's origin");
+  } else {
+    const path = target.path as string;
+    if (!PATH.test(path)) refuse("path is not a valid path");
+    if (endpoint.protocol !== "https:" && !loopback(endpoint.hostname) && !origins?.has(endpoint.origin)) refuse("a path under an http MCP address needs loopback or fileOrigins");
+    url = new URL(endpoint);
+    url.pathname = url.pathname.replace(/\/$/, "") + path;
+    url.hash = "";
+  }
+  return { url: url.href, path: target.path !== undefined, allowlisted, include, headers, method: (target.method ?? "PUT") as string, form, expiresAt };
+}
+
+function send(target: Target, init: RequestInit, { resolved, authorization }: FileConnection): Promise<Response> {
+  const headers = new Headers(target.headers);
+  if (target.include && authorization) headers.set("authorization", authorization);
+  if (target.path && resolved.installationUID) headers.set("x-holon-installation-uid", resolved.installationUID);
+  return (target.path || target.allowlisted ? fetch : fetchGlobal)(target.url, { ...init, headers, credentials: "omit", redirect: "error" });
+}
+
+const reason = (error: unknown) => {
+  const { message, cause } = (error ?? {}) as { message?: unknown; cause?: { message?: unknown } };
+  return String(cause?.message ?? message ?? error);
+};
+const TYPE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+\/[!#$%&'*+.^_`|~0-9A-Za-z-]+(?:[ \t]*;[ \t]*[!#$%&'*+.^_`|~0-9A-Za-z-]+=(?:[!#$%&'*+.^_`|~0-9A-Za-z-]+|"(?:[\t\x20\x21\x23-\x5b\x5d-\x7e]|\\[\t\x20-\x7e])*"))*$/;
+
+// fetch's own FormData boundary has too little randomness for the extension (128 bits), so the body is built here,
+// encoding names and the filename as the WHATWG multipart/form-data algorithm does.
+function multipart({ fields, fileField }: Form, { blob, input }: Attachment): { body: Blob; type: string } {
+  const boundary = `----holon${Array.from(crypto.getRandomValues(new Uint8Array(16)), byte => byte.toString(16).padStart(2, "0")).join("")}`;
+  const filename = (baseName(input.name) ?? "file").replaceAll('"', "%22").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+  const parts: Array<string | Blob> = fields.map(({ name, value }) => `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`);
+  parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="${fileField}"; filename="${filename}"\r\nContent-Type: ${TYPE.test(input.mimeType) ? input.mimeType : "application/octet-stream"}\r\n\r\n`, blob, `\r\n--${boundary}--\r\n`);
+  return { body: new Blob(parts), type: `multipart/form-data; boundary=${boundary}` };
+}
+
+async function transfer(target: Target, file: Attachment, connection: FileConnection, signal: AbortSignal): Promise<void> {
+  const { body, type } = target.form ? multipart(target.form, file) : { body: file.blob.slice(0, file.blob.size, ""), type: undefined };
+  for (let attempt = 0; ; attempt++) {
+    if (expired(target)) throw new Error("its target expired");
+    let response: Response | undefined;
+    try {
+      response = await send(type ? { ...target, headers: { ...target.headers, "Content-Type": type } } : target, { method: target.method, body, signal }, connection);
+    } catch (error) {
+      if (signal.aborted || target.method !== "PUT" || attempt === 2) throw new Error(reason(error));
+    }
+    if (response) {
+      await response.body?.cancel();
+      if (response.ok) return;
+      const retry = response.status >= 500 || response.status === 408 || response.status === 429;
+      if (target.method !== "PUT" || !retry || attempt === 2) throw new Error(`HTTP ${response.status}`);
+    }
+    await new Promise(resolve => setTimeout(resolve, 200 * (attempt + 1)));
+  }
+}
+
+export async function upload(request: Json, files: Files, connection: FileConnection, signal: AbortSignal | undefined, label: string): Promise<string> {
+  const fail = (reason: string) => new Error(`${label}: ${reason}; the tool did not run.`);
+  const { requestState, uploads } = request;
+  if (typeof requestState !== "string") throw fail("the server's upload request has no requestState");
+  const waiting = new Set<unknown>([...files.values()].filter(({ input }) => input.size > 0 && input.data === undefined).map(({ input }) => input.id));
+  const ids = list(uploads).map(target => (target as { fileId?: unknown } | null | undefined)?.fileId);
+  if (!Array.isArray(uploads) || ids.length !== waiting.size || new Set(ids).size !== ids.length || !ids.every(id => waiting.has(id))) {
+    throw fail("the server's upload request does not list each file sent without data exactly once");
+  }
+  const targets = uploads.map((target: { fileId: string }) => {
+    const file = files.get(target.fileId)!;
+    try { return { file, target: check(target, "upload", connection) }; } catch (error) { throw fail(`the upload target for ${quoted(file.input.name)} was rejected (${(error as Error).message})`); }
+  });
+  const controller = new AbortController();
+  const stop = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+  await Promise.all(targets.map(async ({ file, target }) => {
+    try {
+      await transfer(target, file, connection, stop);
+    } catch (error) {
+      controller.abort();
+      throw fail(signal?.aborted ? "the call was cancelled during the upload" : `uploading ${quoted(file.input.name)} failed (${(error as Error).message})`);
+    }
+  }));
+  return requestState;
+}
+
+function download(raw: unknown, connection: FileConnection): Download {
+  const { name, mimeType, size, digest, expiresAt }: Json = present(raw) ?? {};
+  const label = `Downloading ${quoted(typeof name === "string" ? name : undefined)}`;
+  const blob = async ({ signal }: { signal?: AbortSignal } = {}) => {
+    let target: Target;
+    try { target = check(raw, "download", connection); } catch (error) { throw new Error(`${label} was refused: its target was rejected (${(error as Error).message}).`); }
+    if (expired(target)) throw new Error(`${label} was refused: its target expired.`);
+    const declared = size as number;
+    const chunks: Uint8Array[] = [];
+    let received = 0;
+    try {
+      const response = await send(target, { method: "GET", signal }, connection);
+      if (response.status !== 200) {
+        await response.body?.cancel();
+        throw new Error(`HTTP ${response.status}`);
+      }
+      const reader = response.body?.getReader();
+      while (reader) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        received += chunk.value.byteLength;
+        if (received > declared) {
+          await reader.cancel();
+          throw new Error(`more than the declared ${declared} bytes; discarded`);
+        }
+        chunks.push(chunk.value);
+      }
+    } catch (error) {
+      throw new Error(`${label} failed (${reason(error)}).`);
+    }
+    if (received !== declared) throw new Error(`${label} failed (${received} bytes, not the declared ${declared}; discarded).`);
+    const file = new Blob(chunks, { type: mimeType as string });
+    if (digest && await sha256(file) !== (digest as { value: string }).value) throw new Error(`${label} failed (the bytes do not match the digest; discarded).`);
+    return file;
+  };
+  return Object.freeze({ ...Object.fromEntries(Object.entries({ name, mimeType, size, digest, expiresAt }).filter(([, value]) => value !== undefined)), blob }) as Download;
+}
+
+export function downloads<R extends { resultType?: string; _meta?: object }>(result: R, connection: FileConnection, enabled: boolean): R & { downloads?: Download[] } {
+  if (result.resultType === "input_required" || !isObject(result._meta) || !(EXTENSION in result._meta)) return result;
+  const { [EXTENSION]: meta, ...rest } = result._meta;
+  const handles = enabled ? list((meta as { downloads?: unknown } | null | undefined)?.downloads).map(target => download(target, connection)) : [];
+  return { ...result, _meta: rest, ...(handles.length > 0 && { downloads: handles }) };
+}

package/src/ext/files.ts

@@ -0,0 +1,16 @@
+/** Identifier of the MCP files extension (draft), the key under which a client and a server declare it in their capabilities. */
+export const EXTENSION = "io.modelcontextprotocol/files";
+
+/** A file a tool returned for the caller to fetch. Its fields come from the server and are untrusted. */
+export interface Download {
+  readonly name?: string;
+  readonly mimeType: string;
+  /** Size in bytes. */
+  readonly size: number;
+  /** SHA-256 of the file, base64url without padding. */
+  readonly digest?: { algorithm: "sha-256"; value: string };
+  /** RFC 3339 time after which the file can no longer be fetched. */
+  readonly expiresAt?: string;
+  /** Fetch the file. Rejects, keeping no bytes, when it has expired, its target breaks the extension's rules, or the bytes do not match size or digest. */
+  blob(options?: { signal?: AbortSignal }): Promise<Blob>;
+}

package/src/ext/platform.browser.ts

@@ -0,0 +1,15 @@
+export async function base64(blob: Blob): Promise<string> {
+  const bytes = new Uint8Array(await blob.arrayBuffer());
+  let binary = "";
+  for (let start = 0; start < bytes.length; start += 0x8000) binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));
+  return btoa(binary);
+}
+
+export async function sha256(blob: Blob): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", await blob.arrayBuffer());
+  return (await base64(new Blob([digest]))).replace(/=+$/, "").replaceAll("+", "-").replaceAll("/", "_");
+}
+
+export function fetchGlobal(url: string, init: RequestInit): Promise<Response> {
+  return fetch(url, init);
+}

package/src/ext/platform.node.ts

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import { lookup } from "node:dns";
+import { isIP, type LookupFunction } from "node:net";
+import type * as undici from "undici";
+
+export async function base64(blob: Blob): Promise<string> {
+  return Buffer.from(await blob.arrayBuffer()).toString("base64");
+}
+
+export async function sha256(blob: Blob): Promise<string> {
+  const hash = createHash("sha256");
+  for await (const chunk of blob.stream()) hash.update(chunk);
+  return hash.digest("base64url");
+}
+
+let loaded: Promise<{ fetch: typeof undici.fetch; agent: undici.Agent; global: (address: string) => boolean }> | undefined;
+
+export async function fetchGlobal(url: string, init: RequestInit): Promise<Response> {
+  const { fetch, agent, global } = await (loaded ??= load());
+  const host = new URL(url).hostname.replace(/^\[(.*)\]$/, "$1");
+  if (isIP(host) && !global(host)) throw new TypeError("fetch failed", { cause: new Error("the address is not globally reachable") });
+  return fetch(url, { ...init, dispatcher: agent } as Parameters<typeof undici.fetch>[1]) as unknown as Promise<Response>;
+}
+
+async function load() {
+  const [{ Agent, fetch }, { default: ipaddr }] = await Promise.all([import("undici"), import("ipaddr.js")]);
+  const nat64 = ipaddr.parseCIDR("64:ff9b::/96");
+  const global = (address: string) => {
+    let ip = ipaddr.process(address);
+    if (ip.kind() === "ipv6" && ip.match(nat64)) ip = new ipaddr.IPv4(ip.toByteArray().slice(12));
+    return ip.range() === "unicast";
+  };
+  const resolve: LookupFunction = (hostname, options, callback) => lookup(hostname, { ...options, all: true }, (error, addresses) => {
+    if (error) return callback(error, "");
+    const usable = addresses.filter(({ address }) => global(address));
+    const [first] = usable;
+    if (!first) return callback(Object.assign(new Error("the host has no globally reachable address"), { code: "ENOTFOUND" }), "");
+    if (options.all) callback(null, usable);
+    else callback(null, first.address, first.family);
+  });
+  const agent = new Agent({ connect: { lookup: resolve } });
+  return { fetch, agent, global };
+}

package/{protocol.d.ts → src/protocol.ts}

@@ -1,35 +1,59 @@
-import type { CallToolRequest, CallToolResult, ElicitRequestParams, ElicitResult, InputRequiredResult, InputResponses, ListToolsResult, RequestOptions } from "@modelcontextprotocol/client";
+import type { AuthProvider as BearerAuthProvider, CallToolRequest, CallToolResult, ElicitRequestParams, ElicitResult, InputRequiredResult, InputResponses, ListToolsResult, OAuthClientProvider, RequestOptions } from "@modelcontextprotocol/client";
+import type { Download } from "./ext/files.js";
 
 /** Bearer-token or OAuth provider accepted by the MCP transport. */
-export type AuthProvider =
-  | { token(): Promise<string | undefined>; onUnauthorized?(context: unknown): Promise<void> }
-  | { tokens(): unknown; redirectUrl: unknown; clientMetadata: unknown };
+export type AuthProvider = BearerAuthProvider | OAuthClientProvider;
 /** Answers a server's question so the call that asked can complete. `params.mode` tells a form from a URL to open. */
 export type ElicitHandler = (params: ElicitRequestParams) => ElicitResult | Promise<ElicitResult>;
 
-/** MCP request options, including AbortSignal and timeout in milliseconds. Input-required responses are enabled by the runtime. */
+/** MCP request options, including AbortSignal and timeout in milliseconds. A request without a timeout waits for its answer; progress from the server restarts a timeout. Input-required responses are enabled by the runtime. */
 export type CallOptions = Omit<RequestOptions, "allowInputRequired">;
 /** Call options for a tool. `elicit` answers its questions in place, so the call returns the completed result. */
 export type ToolCallOptions = CallOptions & { elicit?: ElicitHandler };
 /** MCP request metadata and input continuation fields. Pass inputResponses and requestState when continuing an input-required result. */
 export type CallMetadata = Omit<CallToolRequest["params"], "name" | "arguments"> & { inputResponses?: InputResponses; requestState?: string };
-/** @internal */
 type Fields<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
+type Files = {
+  /** Files the tool returned, from a server with the files extension. Their targets are removed from _meta. */
+  downloads?: Download[];
+};
 /** Successful tool result with contract-typed structured content. */
-export type CompleteResult<Output> = Omit<Fields<CallToolResult>, "structuredContent" | "isError"> & { resultType: "complete"; isError?: false; structuredContent: Output };
+export type CompleteResult<Output> = Omit<Fields<CallToolResult>, "structuredContent" | "isError"> & Files & { resultType: "complete"; isError?: false; structuredContent: Output };
 /** Full tool result: successful typed output, an application error, or an input-required continuation. */
 export type ToolResult<Output> =
   | CompleteResult<Output>
-  | (Omit<Fields<CallToolResult>, "structuredContent" | "isError"> & { resultType: "complete"; isError: true; structuredContent?: unknown })
+  | (Omit<Fields<CallToolResult>, "structuredContent" | "isError"> & Files & { resultType: "complete"; isError: true; structuredContent?: unknown })
   | InputRequiredResult;
 
-/** Error thrown by the tools convenience methods for error or input_required results. Inspect the original result; pass elicit to answer questions in place, or continue later through callTool. */
-export declare class ToolCallError extends Error {
+function json(text: string | undefined): unknown {
+  try { return text === undefined ? undefined : JSON.parse(text); } catch { return undefined; }
+}
+
+/** Error thrown by the tools convenience methods for error or input_required results. A failure's message carries its text; `data` is what the server said in a form to branch on. Pass elicit to answer questions in place, or continue later through callTool. */
+export class ToolCallError extends Error {
   readonly result: Extract<ToolResult<unknown>, { isError: true } | { resultType: "input_required" }>;
-  constructor(app: string, tool: string, result: ToolCallError["result"]);
+  /** The failure's text content, its text blocks joined by newlines. Undefined for questions left unanswered. */
+  readonly text?: string;
+  /** The failure's structured content, or else its text parsed as JSON when that text is JSON. Its shape is the server's own. */
+  readonly data?: unknown;
+  constructor(app: string, tool: string, result: ToolCallError["result"]) {
+    const asking = result.resultType === "input_required";
+    const text = (asking ? undefined : result.content?.filter(part => part.type === "text").map(part => part.text).join("\n")) || undefined;
+    // A question says what it asks, and a URL question where to answer it.
+    const detail = asking
+      ? Object.values(result.inputRequests ?? {}).flatMap(question => question.method === "elicitation/create"
+        ? [question.params.message, question.params.mode === "url" ? question.params.url : undefined]
+        : []).filter(Boolean).join(" ")
+      : text;
+    super(`${app}.${tool}: ${asking ? "additional input required" : "tool failed"}${detail ? `: ${detail}` : ""}`);
+    this.name = "ToolCallError";
+    this.result = result;
+    this.text = text;
+    this.data = result.structuredContent ?? json(text);
+  }
 }
 
-/** Client operations shared by generated app clients. Transport, validation, and protocol errors reject the returned promises. */
+/** Client operations shared by generated app clients. Transport, validation, and protocol errors reject the returned promises. A Blob at a file argument (x-mcp-file) is sent with the files extension: inline when the server takes it, else uploaded to the target the server names. A failure before the call completes says whether the tool did not run or the outcome is unknown. */
 export interface ToolClient<I, O, R> {
   /** Close the cached endpoint session. Scoped calls close their own session; a host-owned session is closed by its host. */
   readonly close: () => Promise<void>;
@@ -40,8 +64,8 @@ export interface ToolClient<I, O, R> {
     readonly read: (options?: CallOptions) => Promise<R[U]>;
     readonly watch: (onChange: (value: R[U]) => void | Promise<void>, options?: { signal?: AbortSignal }) => Promise<void>;
   } };
-  /** Convenience methods returning structured output, or the complete result for a tool without an output schema. Error results throw ToolCallError, as do questions left unanswered. Reserved object method names remain callable through callTool. */
+  /** Convenience methods returning structured output, or the complete MCP result, with its content blocks typed, for a tool without an output schema. Error results throw ToolCallError, as do questions left unanswered. Reserved object method names remain callable through callTool. */
   readonly tools: { readonly [K in Exclude<keyof I, "then" | "toJSON" | "toString" | "valueOf" | "toLocaleString">]: (input: I[K], options?: ToolCallOptions) => Promise<K extends keyof O ? O[K] : CompleteResult<unknown>> };
-  /** Return the full MCP result, preserving error results and questions left unanswered. Arguments and successful output are contract-validated. */
+  /** Return the full MCP result, preserving error results and questions left unanswered. Successful output is contract-validated; the server validates arguments. */
   readonly callTool: <K extends keyof I & string>(request: CallMetadata & { name: K; arguments: I[K] }, options?: ToolCallOptions) => Promise<ToolResult<K extends keyof O ? O[K] : unknown>>;
 }