@typeship-ax/mcp 0.6.0

package/dist/mcp-protocol.js

@@ -0,0 +1,1262 @@
+/**
+ * MCP 2026-07-28 for a tools-only server. Generated by typeship — https://typeship.dev
+ *
+ * The protocol layer shared by the MCP server in every generated package and
+ * by typeship's hosted endpoint: JSON-RPC shape checks, the per-request _meta
+ * rules, Streamable HTTP header validation, result wrapping, and the tool
+ * surface (per-operation tools or the three-tool "meta" shape, plus the
+ * search_docs / read_docs pair). Also the agent-facing contract of a tool
+ * call: argument validation and coercion against the tool's input schema
+ * (relative dates via ./dates), field projection, a size cap on results,
+ * and error results that carry a stable code and next steps. Transport,
+ * credentials, and how a tool call reaches the API stay with the caller.
+ * No external dependencies.
+ *
+ * Spec: https://modelcontextprotocol.io/specification/2026-07-28
+ */
+import { dateKindOf, relativeDate } from "./dates.js";
+export const MCP_PROTOCOL_VERSION = "2026-07-28";
+/** Revisions served. Legacy (initialize-handshake) revisions are not; an
+ * initialize request gets an error naming this list, as the spec asks of
+ * modern-only servers. */
+export const SUPPORTED_PROTOCOL_VERSIONS = [MCP_PROTOCOL_VERSION];
+export const META_VERSION = "io.modelcontextprotocol/protocolVersion";
+export const META_CLIENT_CAPS = "io.modelcontextprotocol/clientCapabilities";
+export const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+/** Results longer than this (in characters of JSON text) are cut down to
+ * whole items or whole keys with a note saying what was left out and how to
+ * ask for less. Roughly 16k tokens: under every major client's own cap, so
+ * the agent sees this explanation instead of a mid-JSON chop. */
+export const DEFAULT_MAX_RESULT_CHARS = 64_000;
+/** Does the operation take a file (multipart form or raw binary body)? */
+export function isUploadOp(op) {
+    return op.bodyKind === "multipart" || op.bodyKind === "binary";
+}
+/** Ops that can be MCP tools. A tool result is one value, not a stream, so
+ * event streams stay CLI/SDK-only everywhere. Uploads need a local file:
+ * they are tools on a server running on the agent's machine (stdio, or a
+ * locally launched HTTP server), where a file argument is a path the server
+ * reads, and not on a remote endpoint, which can't see the agent's disk. */
+export function mcpExposed(op, options = {}) {
+    if (op.sse === true)
+        return false;
+    return options.uploads === true || !isUploadOp(op);
+}
+// ---- JSON-RPC shape + protocol metadata --------------------------------------
+export const rpcError = (id, code, message, status, data) => ({
+    message: { jsonrpc: "2.0", id: id ?? null, error: { code, message, ...(data !== undefined ? { data } : {}) } },
+    status,
+});
+/** Shape check before anything else: batches (removed in 2025-06-18) and
+ * non-objects get an error instead of a dead server. */
+export function asJsonRpc(message) {
+    if (Array.isArray(message)) {
+        return rpcError(null, -32600, "JSON-RPC batching is not supported; send one message per request.", 400);
+    }
+    const isObject = message !== null && typeof message === "object";
+    const method = isObject ? message.method : undefined;
+    if (!isObject || typeof method !== "string") {
+        return rpcError(null, -32600, "Invalid Request: expected a JSON-RPC 2.0 message with a string method.", 400);
+    }
+    return message;
+}
+export function isRpcOutcome(value) {
+    return "status" in value;
+}
+/** Per-request protocol metadata (2026-07-28 basic/_meta): protocolVersion
+ * and clientCapabilities are REQUIRED on every request. Missing -> -32602
+ * (400 on HTTP); unsupported version -> -32022 listing what we speak. */
+export function checkRequestMeta(request) {
+    const meta = (request.params?._meta ?? undefined);
+    const version = meta?.[META_VERSION];
+    const caps = meta?.[META_CLIENT_CAPS];
+    if (typeof version !== "string") {
+        return rpcError(request.id, -32602, "Invalid params: params._meta[\"" + META_VERSION + "\"] is required on every request (MCP " + MCP_PROTOCOL_VERSION + ").", 400);
+    }
+    if (!SUPPORTED_PROTOCOL_VERSIONS.includes(version)) {
+        return rpcError(request.id, -32022, "Unsupported protocol version", 400, { supported: SUPPORTED_PROTOCOL_VERSIONS, requested: version });
+    }
+    if (caps === null || typeof caps !== "object" || Array.isArray(caps)) {
+        return rpcError(request.id, -32602, "Invalid params: params._meta[\"" + META_CLIENT_CAPS + "\"] is required on every request (MCP " + MCP_PROTOCOL_VERSION + ").", 400);
+    }
+    return { version };
+}
+/** Streamable HTTP header values may arrive as =?base64?...?= when not
+ * header-safe. atob + TextDecoder: works in Node and worker runtimes alike. */
+export function decodeHeaderValue(value) {
+    if (value.startsWith("=?base64?") && value.endsWith("?=")) {
+        try {
+            return new TextDecoder().decode(Uint8Array.from(atob(value.slice(9, -2)), (c) => c.charCodeAt(0)));
+        }
+        catch {
+            return value;
+        }
+    }
+    return value;
+}
+/** Streamable HTTP mirrors body fields into headers so intermediaries can
+ * route without parsing; a server that reads the body MUST check they
+ * agree (400 + -32020 HeaderMismatch), including when they're missing.
+ * Notifications carry no header requirements; call this for requests. */
+export function checkRequestHeaders(headers, message) {
+    const id = message.id;
+    const version = headers.get("mcp-protocol-version");
+    const bodyVersion = message.params?._meta?.[META_VERSION];
+    if (version === null)
+        return rpcError(id, -32020, "Header mismatch: MCP-Protocol-Version header is required", 400);
+    if (typeof bodyVersion === "string" && version !== bodyVersion) {
+        return rpcError(id, -32020, "Header mismatch: MCP-Protocol-Version header '" + version + "' does not match body value '" + bodyVersion + "'", 400);
+    }
+    const method = headers.get("mcp-method");
+    if (method === null)
+        return rpcError(id, -32020, "Header mismatch: Mcp-Method header is required", 400);
+    if (method !== message.method) {
+        return rpcError(id, -32020, "Header mismatch: Mcp-Method header '" + method + "' does not match body value '" + message.method + "'", 400);
+    }
+    if (message.method === "tools/call") {
+        const nameHeader = headers.get("mcp-name");
+        const bodyName = message.params?.name;
+        if (nameHeader === null)
+            return rpcError(id, -32020, "Header mismatch: Mcp-Name header is required for tools/call", 400);
+        if (typeof bodyName === "string" && decodeHeaderValue(nameHeader) !== bodyName) {
+            return rpcError(id, -32020, "Header mismatch: Mcp-Name header '" + nameHeader + "' does not match body value '" + bodyName + "'", 400);
+        }
+    }
+    return null;
+}
+/** Requests whose client cancelled them (stdio notifications/cancelled):
+ * the spec says the server MUST NOT send further messages for them. */
+const cancelled = new Set();
+/** True (and forgets the id) when a response must be suppressed. */
+export function takeCancelled(id) {
+    return (typeof id === "string" || typeof id === "number") && cancelled.delete(id);
+}
+// ---- dispatch ------------------------------------------------------------------
+export async function handleRpc(server, incoming) {
+    const parsed = asJsonRpc(incoming);
+    if (isRpcOutcome(parsed))
+        return parsed;
+    const request = parsed;
+    const id = request.id;
+    // Notifications: no id, no reply. Only notifications/cancelled means anything here.
+    if (id === undefined || id === null) {
+        if (request.method === "notifications/cancelled") {
+            const target = request.params?.requestId;
+            if (typeof target === "string" || typeof target === "number")
+                cancelled.add(target);
+        }
+        return { message: null, status: 202 };
+    }
+    // Legacy clients open with initialize; name what we do speak so their one
+    // visible error is actionable (spec: modern-only servers SHOULD do this).
+    if (request.method === "initialize") {
+        return rpcError(id, -32601, "This server speaks MCP " + SUPPORTED_PROTOCOL_VERSIONS.join(", ") + " only (stateless, no initialize handshake). Upgrade the client, or send requests with params._meta[\"" + META_VERSION + "\"].", 400, { supported: SUPPORTED_PROTOCOL_VERSIONS });
+    }
+    const meta = checkRequestMeta(request);
+    if ("status" in meta)
+        return meta;
+    const complete = (result) => ({
+        message: { jsonrpc: "2.0", id, result: { resultType: "complete", ...result, _meta: { [META_SERVER_INFO]: server.serverInfo } } },
+        status: 200,
+    });
+    const cacheScope = server.cacheScope ?? "public";
+    switch (request.method) {
+        case "server/discover":
+            return complete({
+                supportedVersions: SUPPORTED_PROTOCOL_VERSIONS,
+                capabilities: { tools: {} },
+                ...(server.instructions ? { instructions: server.instructions } : {}),
+                ttlMs: server.toolsTtlMs,
+                cacheScope,
+            });
+        case "tools/list":
+            return complete({ tools: server.listTools(), ttlMs: server.toolsTtlMs, cacheScope });
+        case "tools/call": {
+            const name = request.params?.name;
+            if (typeof name !== "string")
+                return rpcError(id, -32602, "tools/call requires a tool name", 400);
+            const args = (request.params?.arguments ?? {});
+            if (args === null || typeof args !== "object" || Array.isArray(args)) {
+                return rpcError(id, -32602, "tools/call arguments must be an object", 400);
+            }
+            const denied = server.beforeToolCall ? await server.beforeToolCall(name) : null;
+            if (denied)
+                return denied;
+            const started = Date.now();
+            const outcome = await server.callTool(name, args);
+            if (outcome === undefined)
+                return rpcError(id, -32602, "Unknown tool: " + name, 400);
+            if (server.afterToolCall)
+                await server.afterToolCall(name, outcome, Date.now() - started);
+            // A tool that declares an outputSchema MUST return structuredContent,
+            // and clients enforce it: a successful result without it fails the
+            // whole call. So every successful object result carries it, projected
+            // or cut or not — the emitted outputSchema is loosened to match (no
+            // `required`, no closed objects). Arrays and strings cannot be
+            // structuredContent (the spec wants an object) and such tools declare
+            // no outputSchema; errors keep their JSON in the text.
+            const structured = outcome.structured;
+            return complete({
+                content: outcome.content ?? [{ type: "text", text: outcome.text }],
+                ...(!outcome.isError && structured !== undefined && structured !== null && typeof structured === "object" && !Array.isArray(structured)
+                    ? { structuredContent: structured }
+                    : {}),
+                isError: outcome.isError,
+            });
+        }
+        default:
+            return rpcError(id, -32601, "Method not found: " + request.method, 404);
+    }
+}
+// ---- tool surface ---------------------------------------------------------------
+/** POST operations the IR named as reads: POST /search, POST /query, and
+ * friends are read-only in every way that matters to a client deciding
+ * whether to ask before calling. */
+const READ_METHOD_NAME = /^(list|search|query|get|find|count|lookup|retrieve|fetch|read|check|preview|validate|describe)(?![a-z])/i;
+/** Mutation names that destroy or disable what they touch. */
+const DESTRUCTIVE_NAME = /^(delete|remove|destroy|purge|archive|cancel|revoke|disable|deactivate|terminate|close|expire|reject)(?![a-z])/i;
+/** Is this operation a read (a GET/HEAD, a GraphQL query, or a POST the
+ * spec named like a search)? Drives readOnlyHint and the read-only surface. */
+export function isReadOperation(op) {
+    const m = op.httpMethod.toUpperCase();
+    if (op.graphql)
+        return op.graphql.kind === "query";
+    if (m === "GET" || m === "HEAD")
+        return true;
+    return m === "POST" && op.method !== undefined && READ_METHOD_NAME.test(op.method);
+}
+/** Tool annotations (spec: hints, untrusted by clients). Clients such as
+ * Claude Code use readOnlyHint to auto-approve reads and destructiveHint to
+ * confirm writes that overwrite or remove. The server talks to one known
+ * API, not the open world, so openWorldHint is false. */
+export function annotationsFor(op) {
+    const m = op.httpMethod.toUpperCase();
+    const classified = operationSafety(op);
+    const readOnly = classified === "read";
+    const destructive = classified === "destructive";
+    const idempotent = readOnly || m === "PUT" || m === "DELETE";
+    return {
+        title: op.summary ?? op.tool,
+        readOnlyHint: readOnly,
+        destructiveHint: destructive,
+        idempotentHint: idempotent,
+        openWorldHint: false,
+    };
+}
+/** One effect vocabulary for generated references, CLI confirmation, and
+ * MCP annotations. Stored on the operation manifest so every renderer says
+ * the same thing even when the original operation name was unusual. */
+export function operationSafety(op) {
+    if (op.safety)
+        return op.safety;
+    if (isReadOperation(op))
+        return "read";
+    const method = op.httpMethod.toUpperCase();
+    const name = op.method ?? "";
+    if (op.graphql)
+        return DESTRUCTIVE_NAME.test(name) ? "destructive" : "write";
+    return method === "DELETE" || DESTRUCTIVE_NAME.test(name)
+        ? "destructive"
+        : "write";
+}
+/** A deterministic, schema-valid-enough example for documentation and
+ * agent calls. Prefer facts supplied by the API author, then conservative
+ * values based on formats and field names. Only required object fields are
+ * included, keeping examples useful instead of manufacturing giant bodies. */
+export function exampleFromSchema(schema, field = "value", depth = 0) {
+    if (!schema || typeof schema !== "object" || depth > 8)
+        return null;
+    const node = schema;
+    if (node.const !== undefined)
+        return node.const;
+    if (node.example !== undefined)
+        return node.example;
+    if (Array.isArray(node.examples) && node.examples.length > 0)
+        return node.examples[0];
+    if (node.default !== undefined)
+        return node.default;
+    if (Array.isArray(node.enum) && node.enum.length > 0)
+        return node.enum.find((v) => v !== null) ?? node.enum[0];
+    const variants = (Array.isArray(node.oneOf) ? node.oneOf : Array.isArray(node.anyOf) ? node.anyOf : null);
+    if (variants) {
+        const useful = variants.find((v) => v && typeof v === "object" && v.type !== "null") ?? variants[0];
+        return exampleFromSchema(useful, field, depth + 1);
+    }
+    const type = Array.isArray(node.type) ? node.type.find((v) => v !== "null") : node.type;
+    if (type === "object" || node.properties || node.additionalProperties) {
+        const properties = (node.properties ?? {});
+        const required = new Set(Array.isArray(node.required) ? node.required.filter((v) => typeof v === "string") : []);
+        // At the operation root, optional really means optional: the most honest
+        // runnable example is `{}`. Inside a required object, one representative
+        // optional field still makes an otherwise empty nested shape legible.
+        const names = required.size > 0 ? [...required] : depth === 0 ? [] : Object.keys(properties).slice(0, 1);
+        const value = {};
+        for (const name of names) {
+            if (properties[name] !== undefined)
+                value[name] = exampleFromSchema(properties[name], name, depth + 1);
+        }
+        if (Object.keys(value).length === 0 && node.additionalProperties && typeof node.additionalProperties === "object") {
+            value.key = exampleFromSchema(node.additionalProperties, "key", depth + 1);
+        }
+        return value;
+    }
+    if (type === "array" || node.items) {
+        const count = typeof node.minItems === "number" && node.minItems > 1 ? Math.min(node.minItems, 3) : 1;
+        return Array.from({ length: count }, () => exampleFromSchema(node.items, field, depth + 1));
+    }
+    if (type === "integer" || type === "number") {
+        if (typeof node.minimum === "number")
+            return node.minimum;
+        if (typeof node.exclusiveMinimum === "number")
+            return node.exclusiveMinimum + 1;
+        return 1;
+    }
+    if (type === "boolean")
+        return true;
+    if (type === "string" || type === undefined) {
+        const format = typeof node.format === "string" ? node.format : "";
+        const lower = field.toLowerCase();
+        let value = format === "date-time" ? "2026-01-15T12:00:00Z"
+            : format === "date" ? "2026-01-15"
+                : format === "email" || lower.includes("email") ? "person@example.com"
+                    : (format === "uri" || format === "url" || lower.endsWith("url")) && (lower.includes("webhook") || lower.includes("callback")) ? "https://example.com/webhook"
+                        : format === "uri" || format === "url" || lower.endsWith("url") ? "https://example.com"
+                            : format === "uuid" ? "00000000-0000-4000-8000-000000000000"
+                                : lower.includes("repository") || lower === "repo" ? "acme/api"
+                                    : lower.includes("path") ? "openapi.yaml"
+                                        : lower.includes("version") ? "1.0.0"
+                                            : /(^|_)id$|Id$/.test(field) ? (lower === "id" ? "id" : field.replace(/[_-]?id$/i, "")) + "_123"
+                                                : lower.includes("name") ? "example"
+                                                    : "value";
+        const min = typeof node.minLength === "number" ? node.minLength : 0;
+        while (value.length < min)
+            value += "x";
+        if (typeof node.maxLength === "number")
+            value = value.slice(0, node.maxLength);
+        return value;
+    }
+    return null;
+}
+export function exampleArgumentsFromSchema(inputSchema) {
+    const value = exampleFromSchema(inputSchema, "arguments");
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+/** The `fields` argument every tool takes unless the API already has one:
+ * dotted paths to keep in the result (per item for paginated tools). */
+export const FIELDS_ARGUMENT = "fields";
+function fieldsArgumentSchema(op) {
+    return {
+        type: "array",
+        items: { type: "string" },
+        description: "Result keys to keep, as dotted paths" + (op.paginated ? ", applied to each item" : "") + ' (e.g. ["id","name"]). Omit for the whole result. Keeps responses small.',
+    };
+}
+/** The input schema a tool advertises: the operation's own arguments plus
+ * `select` (GraphQL selection override) and `fields` (result projection)
+ * when those names are free. */
+export function toolInputSchema(op) {
+    const base = op.inputSchema.properties;
+    const properties = { ...(base ?? {}) };
+    if (op.select && properties.select === undefined) {
+        properties.select = { type: "string", description: 'GraphQL selection set override, e.g. "{ id name }"' };
+    }
+    if (properties[FIELDS_ARGUMENT] === undefined)
+        properties[FIELDS_ARGUMENT] = fieldsArgumentSchema(op);
+    return { ...op.inputSchema, properties };
+}
+/** True when the tool's own schema has a `fields` parameter, so the
+ * projection argument is the API's, not ours. */
+export function hasOwnFieldsParam(op) {
+    return op.inputSchema.properties?.[FIELDS_ARGUMENT] !== undefined;
+}
+/** One tool per operation, as advertised by tools/list. */
+export function operationTool(op) {
+    return {
+        name: op.tool,
+        title: op.summary ?? op.tool,
+        description: op.toolDescription,
+        annotations: annotationsFor(op),
+        inputSchema: toolInputSchema(op),
+        ...(op.outputSchema ? { outputSchema: op.outputSchema } : {}),
+    };
+}
+/** Reference matches per search_docs page. */
+export const SEARCH_PAGE_SIZE = 15;
+export const SEARCH_DOCS_TOOL = {
+    name: "search_docs",
+    description: "Search this API's reference (operations, parameters) and, when a docs site is configured, its guides. Best matches first; page through with page.",
+    inputSchema: { type: "object", properties: { query: { type: "string" }, page: { type: "integer", minimum: 1, description: "Page of reference matches (15 per page), default 1" } }, required: ["query"] },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export const READ_DOCS_TOOL = {
+    name: "read_docs",
+    description: 'Read a documentation page: an operation reference (a tool name, or dotted "resource.method") or a docs-site guide page by name or URL.',
+    inputSchema: { type: "object", properties: { page: { type: "string" } }, required: ["page"] },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export const EXECUTE_TOOL = {
+    name: "execute",
+    description: "Execute an API operation by name. Discover it with search_docs, then read_docs <operation> for its full schema, example, and safety classification. Destructive operations require confirm: true.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            operation: { type: "string", description: "Operation tool name, e.g. accounts_create" },
+            arguments: { type: "object", description: "Operation arguments keyed by parameter name" },
+            confirm: { type: "boolean", description: "Required and must be true for destructive operations. Omit for reads and ordinary writes." },
+        },
+        required: ["operation"],
+    },
+    annotations: { openWorldHint: false },
+};
+/** The operations a server serves under these options: the callable set,
+ * not just the listed one, so a hidden write is not reachable by name or
+ * through execute either. Deterministic (spec) order. */
+export function visibleOps(ops, options = {}) {
+    let out = ops.filter((op) => mcpExposed(op, { uploads: options.uploads }));
+    if (options.readOnly)
+        out = out.filter(isReadOperation);
+    if (options.include && options.include.length > 0) {
+        const wanted = new Set(options.include.map((s) => s.trim().toLowerCase()).filter(Boolean));
+        out = out.filter((op) => wanted.has(op.tool.toLowerCase()) ||
+            (op.resource !== undefined && wanted.has(op.resource.toLowerCase())) ||
+            (op.resource !== undefined && op.method !== undefined && wanted.has((op.resource + "." + op.method).toLowerCase())));
+    }
+    return out;
+}
+/** Parse a comma-separated include list (from an env var or a flag). */
+export function parseIncludeList(value) {
+    const list = (value ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    return list.length > 0 ? list : undefined;
+}
+/**
+ * The tool list for a mode: every operation plus the docs pair, or the
+ * three-tool "meta" shape (search_docs, read_docs, execute) that keeps huge
+ * APIs from flooding an agent's context. Deterministic order.
+ */
+export function toolDefinitions(ops, mode) {
+    if (mode === "meta") {
+        return [
+            { ...SEARCH_DOCS_TOOL, description: "Search this API's " + ops.length + " operations and, when a docs site is configured, its guides. Start here to find the operation you need." },
+            { ...READ_DOCS_TOOL, description: "Read an operation's full reference (arguments, schemas, authentication, safety and example) by tool name, or a docs-site guide page." },
+            EXECUTE_TOOL,
+        ];
+    }
+    return [...ops.map(operationTool), SEARCH_DOCS_TOOL, READ_DOCS_TOOL];
+}
+/** How big a tools/list is, as agents pay for it. Characters of JSON and a
+ * rough token count (one token per four characters, the usual estimate for
+ * JSON). Generation and `<bin> mcp` report it. */
+export function toolsListSize(tools) {
+    const chars = JSON.stringify(tools).length;
+    return { tools: tools.length, chars, approxTokens: Math.round(chars / 4) };
+}
+/** Keep automatic per-operation discovery under roughly 10k tokens. The
+ * schema, not merely the operation count, determines what an agent pays. */
+export const MCP_AUTO_MAX_TOOLS_LIST_CHARS = 40_000;
+export function resolveToolMode(ops, requested = "auto") {
+    if (requested === "operations" || requested === "meta") {
+        return { mode: requested, ...toolsListSize(toolDefinitions(ops, requested)) };
+    }
+    const operations = toolsListSize(toolDefinitions(ops, "operations"));
+    const mode = ops.length > 100 || operations.chars > MCP_AUTO_MAX_TOOLS_LIST_CHARS ? "meta" : "operations";
+    return mode === "operations"
+        ? { mode, ...operations }
+        : { mode, ...toolsListSize(toolDefinitions(ops, mode)) };
+}
+/** Resolve an operation by tool name or dotted resource.method. */
+export function findOperation(ops, wanted) {
+    return ops.find((o) => o.tool === wanted)
+        ?? ops.find((o) => o.tool.toLowerCase() === wanted.toLowerCase().replace(/\./g, "_"));
+}
+/** Names of the arguments the caller must supply, given the op's params. */
+export function missingArguments(op, args) {
+    return op.params.filter((p) => p.required && args[p.name] === undefined).map((p) => p.name);
+}
+/** The server/discover instructions: what the tools are, how arguments and
+ * results behave, where credentials come from, plus whatever the project
+ * adds. One paragraph; agents read it once per session. */
+export function serverInstructions(input) {
+    const parts = [];
+    parts.push(input.mode === "meta"
+        ? input.title + " as MCP tools: search_docs, read_docs and execute over " + input.toolCount + " operations. Start with search_docs to find an operation, read_docs <tool> for its full argument reference, then execute it by name. Destructive operations require confirm: true on execute."
+        : input.title + " as MCP tools: one tool per operation (" + input.toolCount + "), plus search_docs to find operations and read_docs <tool> for an operation's full argument reference.");
+    parts.push("Arguments use the API's wire names; an unknown, mistyped or missing argument returns an isError result listing each problem (nothing is dropped silently), and obvious forms are coerced (\"true\" to boolean, \"3\" to number, enum case).");
+    parts.push("Paginated tools return items, hasMore and nextPage (the exact arguments for the following page). Pass fields (dotted paths) to keep only the result keys you need; oversized results are cut to whole items or keys with a truncated note saying how to ask for less.");
+    parts.push("Errors carry error, code, message, status, the API's body and next_steps.");
+    if (input.authHint)
+        parts.push(input.authHint.trim().replace(/[.]?$/, "."));
+    if (input.identityTool)
+        parts.push("Call " + input.identityTool + " first to learn which account the credential belongs to.");
+    if (input.uploads)
+        parts.push("Upload operations take a local file path for each file argument; this server reads the file and sends it. Binary responses are saved to disk and the result names the path; images come back as an image block.");
+    if (input.readOnly) {
+        parts.push("This server is read-only: " + (input.hiddenWrites ? input.hiddenWrites + " write operations are not available here." : "write operations are not available here."));
+    }
+    if (input.custom && input.custom.trim())
+        parts.push(input.custom.trim());
+    return parts.join(" ");
+}
+const normalizeName = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");
+function editDistance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diag = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diag = tmp;
+        }
+    }
+    return prev[b.length];
+}
+/** The closest accepted name: same letters ignoring case/punctuation first,
+ * then a small edit distance. Undefined when nothing is close. */
+export function closestName(name, known) {
+    const exact = known.filter((k) => normalizeName(k) === normalizeName(name));
+    if (exact.length === 1)
+        return exact[0];
+    if (exact.length > 1)
+        return undefined;
+    let best;
+    for (const k of known) {
+        const d = editDistance(name.toLowerCase(), k.toLowerCase());
+        if (d <= Math.max(1, Math.floor(k.length / 4)) && (best === undefined || d < best.d))
+            best = { name: k, d };
+    }
+    return best?.name;
+}
+function schemaTypes(schema) {
+    const t = schema.type;
+    if (typeof t === "string")
+        return [t];
+    if (Array.isArray(t))
+        return t.filter((x) => typeof x === "string");
+    return [];
+}
+/**
+ * Coerce one value toward its schema when the intent is unambiguous: the
+ * strings agents produce for booleans and numbers, a JSON string for an
+ * object or array, a scalar for a one-element array, an enum member in the
+ * wrong case. Returns the value to send, or a message when it can't be made
+ * to fit. Untyped schemas (unions, anything) pass through.
+ */
+export function coerceValue(value, schema) {
+    if (value === null || value === undefined)
+        return { value };
+    // Date-shaped arguments take relative forms (-P7D, 7 days ago, today),
+    // resolved here so the API sees an absolute value.
+    const dateKind = dateKindOf(schema.format);
+    if (dateKind && typeof value === "string") {
+        const resolved = relativeDate(value, dateKind);
+        if (resolved && "error" in resolved)
+            return { error: resolved.error };
+        if (resolved)
+            value = resolved.value;
+    }
+    const types = schemaTypes(schema);
+    const enumValues = Array.isArray(schema.enum) ? schema.enum : undefined;
+    const accepts = (t) => types.length === 0 || types.includes(t);
+    const kind = Array.isArray(value) ? "array" : typeof value;
+    let out = value;
+    if (types.length > 0) {
+        if (kind === "boolean" && !accepts("boolean")) {
+            if (accepts("string"))
+                out = String(value);
+            else
+                return { error: "expected " + types.join(" or ") + ", got boolean" };
+        }
+        else if (kind === "number" && !accepts("number") && !accepts("integer")) {
+            if (accepts("string"))
+                out = String(value);
+            else if (accepts("array"))
+                out = [value];
+            else
+                return { error: "expected " + types.join(" or ") + ", got number" };
+        }
+        else if (kind === "number" && accepts("integer") && !accepts("number") && !Number.isInteger(value)) {
+            return { error: "expected an integer, got " + String(value) };
+        }
+        else if (kind === "string" && !accepts("string")) {
+            const s = value.trim();
+            if (accepts("boolean") && /^(true|false|yes|no|1|0)$/i.test(s))
+                out = /^(true|yes|1)$/i.test(s);
+            else if ((accepts("integer") || accepts("number")) && s !== "" && !Number.isNaN(Number(s))) {
+                const n = Number(s);
+                if (accepts("integer") && !accepts("number") && !Number.isInteger(n))
+                    return { error: "expected an integer, got \"" + s + "\"" };
+                out = n;
+            }
+            else if ((accepts("object") || accepts("array")) && /^[[{]/.test(s)) {
+                try {
+                    const parsed = JSON.parse(s);
+                    const parsedKind = Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed;
+                    if (!accepts(parsedKind))
+                        return { error: "expected " + types.join(" or ") + ", got a JSON " + parsedKind + " in a string" };
+                    out = parsed;
+                }
+                catch {
+                    return { error: "expected " + types.join(" or ") + ", got a string that is not valid JSON" };
+                }
+            }
+            else if (accepts("array")) {
+                out = [value];
+            }
+            else {
+                return { error: "expected " + types.join(" or ") + ", got string" };
+            }
+        }
+        else if (kind === "object" && !accepts("object")) {
+            if (accepts("array"))
+                out = [value];
+            else
+                return { error: "expected " + types.join(" or ") + ", got object" };
+        }
+        else if (kind === "array" && !accepts("array")) {
+            return { error: "expected " + types.join(" or ") + ", got array" };
+        }
+    }
+    // Array items: coerce each against the items schema when it has one.
+    if (Array.isArray(out) && schema.items && typeof schema.items === "object" && !Array.isArray(schema.items)) {
+        const itemSchema = schema.items;
+        const items = [];
+        for (let i = 0; i < out.length; i++) {
+            const r = coerceValue(out[i], itemSchema);
+            if ("error" in r)
+                return { error: "item " + i + ": " + r.error };
+            items.push(r.value);
+        }
+        out = items;
+    }
+    if (enumValues && typeof out === "string" && !enumValues.includes(out)) {
+        const match = enumValues.filter((e) => typeof e === "string" && e.toLowerCase() === out.toLowerCase());
+        if (match.length === 1)
+            out = match[0];
+        else
+            return { error: "must be one of " + enumValues.map((e) => JSON.stringify(e)).join(", ") + ", got " + JSON.stringify(out) };
+    }
+    return { value: out };
+}
+function parseFields(value) {
+    const raw = typeof value === "string" ? value.split(",") : Array.isArray(value) ? value : null;
+    if (raw === null)
+        return { error: "expected an array of field paths, e.g. [\"id\",\"name\"]" };
+    const paths = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string")
+            return { error: "expected an array of strings" };
+        const path = entry.trim();
+        if (path !== "")
+            paths.push(path.split("."));
+    }
+    return paths;
+}
+/**
+ * Check a tool call's arguments against the tool's input schema before
+ * anything reaches the API. Unknown names are matched to the accepted one
+ * when only case or punctuation differs (accountId -> account_id) and
+ * rejected with a suggestion otherwise; values are coerced where the
+ * intent is clear and rejected where it isn't; required arguments must be
+ * present. Every problem is reported at once, as one isError result, so a
+ * single round trip fixes the call. Nothing is dropped silently.
+ */
+export function prepareCall(op, rawArgs, options = {}) {
+    const schema = toolInputSchema(op);
+    const properties = (schema.properties ?? {});
+    const known = Object.keys(properties);
+    const issues = [];
+    const args = {};
+    for (const [name, value] of Object.entries(rawArgs)) {
+        if (value === undefined)
+            continue;
+        if (properties[name] !== undefined) {
+            args[name] = value;
+            continue;
+        }
+        const close = closestName(name, known);
+        if (close !== undefined && normalizeName(close) === normalizeName(name) && rawArgs[close] === undefined) {
+            args[close] = value;
+            continue;
+        }
+        const accepted = known.length <= 20 ? " Accepted: " + known.join(", ") + "." : " read_docs \"" + op.tool + "\" lists the " + known.length + " accepted arguments.";
+        issues.push({
+            code: "UNKNOWN_ARGUMENT",
+            argument: name,
+            message: "Unknown argument \"" + name + "\"" + (close !== undefined ? "; did you mean \"" + close + "\"?" : ".") + accepted,
+        });
+    }
+    let fields = null;
+    if (!hasOwnFieldsParam(op) && args[FIELDS_ARGUMENT] !== undefined) {
+        const parsed = parseFields(args[FIELDS_ARGUMENT]);
+        if ("error" in parsed)
+            issues.push({ code: "INVALID_ARGUMENT", argument: FIELDS_ARGUMENT, message: "fields: " + parsed.error });
+        else
+            fields = parsed.length > 0 ? parsed : null;
+        delete args[FIELDS_ARGUMENT];
+    }
+    for (const [name, value] of Object.entries(args)) {
+        const propSchema = properties[name];
+        if (!propSchema)
+            continue;
+        const r = coerceValue(value, propSchema);
+        if ("error" in r)
+            issues.push({ code: "INVALID_ARGUMENT", argument: name, message: name + ": " + r.error });
+        else
+            args[name] = r.value;
+    }
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const name of required) {
+        if (args[name] === undefined) {
+            issues.push({ code: "MISSING_ARGUMENT", argument: name, message: "Missing required argument \"" + name + "\"" + (properties[name]?.description ? ": " + String(properties[name].description).split("\n")[0] : ".") });
+        }
+    }
+    if (issues.length > 0)
+        return { ok: false, outcome: argumentsError(op, issues) };
+    return { ok: true, call: { args, fields, maxChars: options.maxChars ?? DEFAULT_MAX_RESULT_CHARS } };
+}
+/** The isError result for bad arguments: one stable code, one issue per
+ * argument, and the way out. */
+export function argumentsError(op, issues) {
+    const structured = {
+        error: "InvalidArguments",
+        code: "INVALID_ARGUMENTS",
+        message: issues.length + (issues.length === 1 ? " problem" : " problems") + " with the arguments to " + op.tool + "; nothing was sent to the API.",
+        issues,
+        next_steps: [
+            "Fix the arguments listed in issues and call " + op.tool + " again.",
+            "read_docs {\"page\": \"" + op.tool + "\"} lists every argument with its type and whether it is required.",
+        ],
+    };
+    return { text: JSON.stringify(structured), isError: true, structured };
+}
+// ---- results: projection, size cap, envelopes ------------------------------------
+/** Keep only `paths` of a value: arrays item by item, objects by dotted
+ * path; scalars untouched. Same rule as the CLI's --fields. */
+export function projectFields(value, paths) {
+    if (paths === null)
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => projectFields(v, paths));
+    if (value === null || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const path of paths) {
+        let cursor = value;
+        for (const key of path) {
+            if (cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) {
+                cursor = undefined;
+                break;
+            }
+            cursor = cursor[key];
+        }
+        if (cursor === undefined)
+            continue;
+        let target = out;
+        for (const key of path.slice(0, -1)) {
+            const next = target[key];
+            if (next === undefined || next === null || typeof next !== "object" || Array.isArray(next))
+                target[key] = {};
+            target = target[key];
+        }
+        target[path[path.length - 1]] = cursor;
+    }
+    return out;
+}
+const fieldsHint = (perItem) => "Pass fields (dotted paths" + (perItem ? ", applied per item" : "") + ") to keep only the keys you need.";
+/** How many leading items fit under `budget` characters once serialized
+ * compactly with commas between them. At least one. */
+function itemsThatFit(items, budget) {
+    let used = 0;
+    let k = 0;
+    for (const item of items) {
+        const size = JSON.stringify(item).length + 1;
+        if (k > 0 && used + size > budget)
+            break;
+        used += size;
+        k++;
+    }
+    return Math.max(1, Math.min(k, items.length));
+}
+/** The result shape for a paginated tool: one page, a continuation signal,
+ * and the exact arguments that fetch the next page. Over the size cap, the
+ * page is cut to whole items with a `truncated` note; offset and
+ * last-id styles resume at the cut, cursor and page styles say what the
+ * caller must do instead. */
+export function pageOutcome(items, nextPage, options = {}) {
+    const fields = options.fields ?? null;
+    const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
+    const shown = projectFields(items, fields);
+    const full = { items: shown, hasMore: nextPage !== null, ...(nextPage !== null ? { nextPage } : {}) };
+    const text = JSON.stringify(full);
+    if (text.length <= maxChars) {
+        return { text, isError: false, structured: full };
+    }
+    const overhead = JSON.stringify({ items: [], hasMore: true, nextPage: nextPage ?? {}, truncated: { omitted: 0, of: 0, reason: "x".repeat(160), next_steps: ["x".repeat(220), "x".repeat(120)] } }).length;
+    const k = itemsThatFit(shown, Math.max(0, maxChars - overhead));
+    const omitted = shown.length - k;
+    const pg = options.pagination;
+    const args = options.args ?? {};
+    let resume = null;
+    if (pg?.style === "offset" && pg.offsetParam) {
+        const start = Number(args[pg.offsetParam]) || 0;
+        resume = { ...(nextPage ?? args), [pg.offsetParam]: start + k };
+    }
+    else if (pg?.style === "cursorFromLastId" && pg.cursorParam && pg.idField) {
+        const last = items[k - 1]?.[pg.idField];
+        if (last !== undefined && last !== null)
+            resume = { ...(nextPage ?? args), [pg.cursorParam]: last };
+    }
+    const steps = [];
+    if (resume !== null) {
+        steps.push("nextPage resumes at the first omitted item, so following it loses nothing.");
+    }
+    else {
+        steps.push("nextPage continues after this whole page, so the omitted items are skipped by it; call again with the same arguments" + (pg?.limitParam ? " and " + pg.limitParam + "=" + k : " and a smaller page size") + " to see them.");
+    }
+    steps.push(fieldsHint(true));
+    const structured = {
+        items: shown.slice(0, k),
+        hasMore: resume !== null ? true : nextPage !== null,
+        ...(resume !== null ? { nextPage: resume } : nextPage !== null ? { nextPage } : {}),
+        truncated: {
+            omitted,
+            of: shown.length,
+            reason: "This page is " + text.length.toLocaleString("en-US") + " characters; results are capped at " + maxChars.toLocaleString("en-US") + ". The first " + k + " of " + shown.length + " items are shown.",
+            next_steps: steps,
+        },
+    };
+    // Projected or cut, the page is still an object the loosened outputSchema
+    // admits, so it is structuredContent either way.
+    return { text: JSON.stringify(structured), isError: false, structured };
+}
+/** Placeholder for a value cut from an oversized object result. */
+const omittedMarker = (key, chars) => "[omitted: " + chars.toLocaleString("en-US") + " characters. Pass fields=[\"" + key + "\"] to fetch this key alone.]";
+export function dataOutcome(data, options = {}) {
+    const fields = options.fields ?? null;
+    const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
+    const value = data === undefined || data === null ? { ok: true } : projectFields(data, fields);
+    if (typeof value === "string") {
+        if (value.length <= maxChars)
+            return { text: value, isError: false, structured: value };
+        return { text: value.slice(0, maxChars) + "\n\n[truncated: " + (value.length - maxChars).toLocaleString("en-US") + " more characters; results are capped at " + maxChars.toLocaleString("en-US") + ".]", isError: false };
+    }
+    const text = JSON.stringify(value);
+    if (text.length <= maxChars) {
+        return { text, isError: false, structured: value };
+    }
+    if (Array.isArray(value)) {
+        const k = itemsThatFit(value, maxChars - 400);
+        const note = "\n\n[truncated: showing " + k + " of " + value.length + " items; the result is " + text.length.toLocaleString("en-US") + " characters and results are capped at " + maxChars.toLocaleString("en-US") + ". " + fieldsHint(true) + "]";
+        return { text: JSON.stringify(value.slice(0, k)) + note, isError: false };
+    }
+    if (typeof value === "object") {
+        // Drop the largest top-level values first until it fits. A dropped key
+        // is removed rather than replaced with a marker: a string where the
+        // schema promised an object would fail the client's validation of
+        // structuredContent. The `truncated` note names each omitted key and the
+        // argument that fetches it alone.
+        const entries = Object.entries(value).map(([key, v]) => ({ key, v, size: JSON.stringify(v)?.length ?? 4 }));
+        const bySize = [...entries].sort((a, b) => b.size - a.size);
+        const cut = new Map();
+        let size = text.length;
+        for (const e of bySize) {
+            if (size <= maxChars)
+                break;
+            cut.set(e.key, e.size);
+            size -= e.size;
+        }
+        const out = {};
+        for (const e of entries)
+            if (!cut.has(e.key))
+                out[e.key] = e.v;
+        out.truncated = {
+            omitted_keys: [...cut.keys()],
+            omitted: Object.fromEntries([...cut].map(([key, chars]) => [key, omittedMarker(key, chars)])),
+            reason: "The result is " + text.length.toLocaleString("en-US") + " characters; results are capped at " + maxChars.toLocaleString("en-US") + ".",
+            next_steps: [fieldsHint(false)],
+        };
+        return { text: JSON.stringify(out), isError: false, structured: out };
+    }
+    return { text, isError: false, structured: value };
+}
+// ---- binary results -------------------------------------------------------------
+/** Images up to this many bytes come back as an image content block the
+ * model can look at; larger ones follow the binary path. */
+export const MAX_IMAGE_BYTES = 4_000_000;
+/** Without a place to save, a binary up to this size is embedded as a
+ * base64 resource block; beyond it, the result describes the file. */
+export const MAX_EMBED_BYTES = 1_000_000;
+function toBase64(bytes) {
+    const B = globalThis.Buffer;
+    if (B)
+        return B.from(bytes).toString("base64");
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(binary);
+}
+const EXTENSIONS = {
+    "image/png": "png", "image/jpeg": "jpg", "image/gif": "gif", "image/webp": "webp", "image/svg+xml": "svg",
+    "application/pdf": "pdf", "application/zip": "zip", "application/gzip": "gz", "text/csv": "csv",
+    "application/json": "json", "text/plain": "txt", "application/octet-stream": "bin",
+};
+/** A file extension for a media type (bin when unknown). */
+export function extensionFor(mediaType) {
+    const base = mediaType.split(";")[0].trim().toLowerCase();
+    return EXTENSIONS[base] ?? base.split("/")[1]?.replace(/[^a-z0-9]+/g, "") ?? "bin";
+}
+/**
+ * A binary response as the agent should get it: an image block for images
+ * the model can look at, a saved file (path, type, size) when the server
+ * can write one, an embedded resource for small binaries otherwise, and
+ * a description when it is too large to carry. Never "{}".
+ */
+export async function binaryOutcome(blob, options = {}) {
+    const mediaType = (blob.type || "application/octet-stream").split(";")[0].trim().toLowerCase();
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    const name = (options.tool ?? "result") + "." + extensionFor(mediaType);
+    const summary = { media_type: mediaType, bytes: bytes.length };
+    if (mediaType.startsWith("image/") && bytes.length <= MAX_IMAGE_BYTES) {
+        return {
+            text: JSON.stringify(summary),
+            isError: false,
+            content: [{ type: "image", data: toBase64(bytes), mimeType: mediaType }, { type: "text", text: JSON.stringify(summary) }],
+        };
+    }
+    if (options.saveBinary) {
+        const path = await options.saveBinary(bytes, mediaType, name);
+        const saved = { ...summary, saved_to: path, next_steps: ["The file is on the machine running this MCP server; read it from saved_to."] };
+        return { text: JSON.stringify(saved), isError: false };
+    }
+    if (bytes.length <= MAX_EMBED_BYTES) {
+        return {
+            text: JSON.stringify(summary),
+            isError: false,
+            content: [
+                { type: "resource", resource: { uri: "result://" + name, mimeType: mediaType, blob: toBase64(bytes) } },
+                { type: "text", text: JSON.stringify(summary) },
+            ],
+        };
+    }
+    return {
+        text: JSON.stringify({ ...summary, omitted: true, next_steps: ["The response is a " + mediaType + " of " + bytes.length.toLocaleString("en-US") + " bytes, too large to return through a remote MCP server. Fetch it with the SDK or CLI, or through the package's local MCP server, which saves binaries to disk."] }),
+        isError: false,
+    };
+}
+function extractRetryAfter(e) {
+    const headers = e.headers;
+    const fromHeader = headers?.get?.("retry-after");
+    if (fromHeader)
+        return fromHeader;
+    const match = /retry after (\d+)s/i.exec(JSON.stringify(e.body ?? ""));
+    return match?.[1];
+}
+/** Classify an SDK error result by status: the code and what to do next. */
+export function classifyError(error, context = {}) {
+    const e = (error ?? {});
+    const message = e.message ?? String(error);
+    if (e.violations !== undefined)
+        return { code: "VALIDATION_FAILED", nextSteps: ["Fix the fields named in violations and call again."] };
+    if (e.name === "TransportError" || (typeof e.status !== "number" && /fetch|ECONN|ENOTFOUND|timed out|TLS|abort/i.test(message))) {
+        return { code: "NETWORK_ERROR", nextSteps: ["The API could not be reached (network, DNS, TLS or timeout). Retry once with backoff; do not loop."] };
+    }
+    const status = typeof e.status === "number" ? e.status : 0;
+    const auth = context.authHint ? context.authHint.trim().replace(/[.]?$/, ".") : null;
+    if (status === 401) {
+        return context.hadCredential
+            ? { code: "AUTH_INVALID", nextSteps: ["The credential was rejected; it may be expired or for another environment." + (auth ? " " + auth : "")] }
+            : { code: "NO_AUTH", nextSteps: ["No credential was sent." + (auth ? " " + auth : "")] };
+    }
+    if (status === 403)
+        return { code: "AUTH_INVALID", nextSteps: ["The credential lacks access to this operation; it is not a retryable error."] };
+    if (status === 402)
+        return { code: "PLAN_LIMIT", nextSteps: ["The account's plan stops here; the body may name where to lift the limit. Do not retry the same call as is."] };
+    if (status === 404)
+        return { code: "NOT_FOUND", nextSteps: notFoundNextSteps(message, e.body) };
+    if (status === 429) {
+        const retryAfter = extractRetryAfter(e);
+        return { code: "RATE_LIMITED", nextSteps: [retryAfter ? "Wait " + retryAfter + " seconds, then call again." : "Back off and retry once; the request was already retried with the server's Retry-After."] };
+    }
+    if (status === 400 || status === 409 || status === 413 || status === 422) {
+        return { code: "INVALID_REQUEST", nextSteps: ["Read body for the field the API named, fix that argument and call again."] };
+    }
+    if (status >= 500)
+        return { code: "SERVER_ERROR", nextSteps: ["Retry once with backoff. If it persists, report the request id from body."] };
+    return { code: "CALL_FAILED", nextSteps: [] };
+}
+/** Keep file-path 404s actionable even when the SDK's Error.message is only
+ * the OpenAPI response description and the precise message is in body. */
+function notFoundNextSteps(message, body) {
+    const record = body;
+    const apiMessage = record?.errors?.[0]?.message ?? record?.message ?? record?.error;
+    const combined = message + " " + (typeof apiMessage === "string" ? apiMessage : "");
+    if (/\bfiles_index\b/i.test(combined)) {
+        return ["Read files_index on the generation, choose an exact path it lists, then call again with that path."];
+    }
+    if (/\bfile\b/i.test(combined) && /\bpaths?\b/i.test(combined)) {
+        return ["Check the requested file path against the API's file listing, then call again with an exact path."];
+    }
+    return ["Check the resource id; list the resource first to find the right one."];
+}
+/** A typed API error as the agent should see it: name, a stable code, the
+ * message, status, the API's body, where to read more, and what to do. */
+export function errorOutcome(error, context = {}) {
+    const e = error;
+    const { code, nextSteps } = classifyError(error, context);
+    const structured = {
+        error: e?.name ?? "Error",
+        code,
+        message: e?.message,
+        ...(typeof e?.status === "number" ? { status: e.status } : {}),
+        ...(e?.body !== undefined ? { body: e.body } : {}),
+        ...(context.docsUrl ? { docs_url: context.docsUrl } : {}),
+        next_steps: nextSteps,
+    };
+    return { text: JSON.stringify(structured), isError: true, structured };
+}
+export function textError(text, code = "CALL_FAILED", nextSteps = []) {
+    const structured = { error: "Error", code, message: text, next_steps: nextSteps };
+    return { text: JSON.stringify(structured), isError: true, structured };
+}
+function docsPageUrl(source, pathOrFile) {
+    const base = source.docsUrl();
+    if (base === null)
+        return null;
+    try {
+        const baseUrl = new URL(base);
+        if (baseUrl.protocol !== "https:" && baseUrl.protocol !== "http:")
+            return null;
+        const target = /^https?:\/\//.test(pathOrFile)
+            ? new URL(pathOrFile)
+            : new URL(pathOrFile.replace(/^\/+/, ""), baseUrl.toString().replace(/\/+$/, "") + "/");
+        // llms.txt commonly contains absolute links, but a docs tool is not a
+        // general-purpose URL fetcher. Keeping every page on the configured
+        // origin prevents an agent from turning hosted MCP into an SSRF proxy.
+        if (target.origin !== baseUrl.origin || target.username || target.password)
+            return null;
+        return target.toString();
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchDocs(source, pathOrFile) {
+    const url = docsPageUrl(source, pathOrFile);
+    return url === null ? null : source.fetchText(url);
+}
+export function referenceText(op) {
+    const safety = operationSafety(op);
+    const example = op.exampleArguments ?? exampleArgumentsFromSchema(op.inputSchema);
+    const lines = [
+        op.tool + ": " + op.httpMethod + " " + op.path + (op.paginated ? " (paginated)" : ""),
+        ...(op.summary ? [op.summary] : []),
+        ...(op.description ? ["", op.description.trim()] : []),
+        "",
+        "Safety: " + safety + (safety === "destructive" ? " (execute requires confirm: true)" : ""),
+        ...(op.auth ? ["Authentication: " + op.auth] : []),
+    ];
+    if (op.params.length > 0) {
+        lines.push("", "Arguments:");
+        for (const p of op.params) {
+            lines.push("  " + p.name + " (" + (p.enum ? p.enum.join("|") : p.type) + (p.required ? ", required" : "") + ")" +
+                (p.description ? ": " + p.description.trim().split("\n")[0] : ""));
+        }
+    }
+    if (!hasOwnFieldsParam(op)) {
+        lines.push("", "Also: fields (array of dotted paths) keeps only those keys of the result" + (op.paginated ? ", per item" : "") + ".");
+    }
+    lines.push("", "Input schema:", "```json", JSON.stringify(toolInputSchema(op), null, 2), "```");
+    lines.push("", "Example arguments:", "```json", JSON.stringify(example, null, 2), "```");
+    if (op.outputSchema)
+        lines.push("", "Output schema:", "```json", JSON.stringify(op.outputSchema, null, 2), "```");
+    return lines.join("\n");
+}
+/** Query terms: lowercase words of two or more characters, with the
+ * snake/kebab/camel seams split so "createAccount" finds accounts_create. */
+function searchTerms(query) {
+    return [...new Set(query.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2))];
+}
+/** Relevance of one operation to the terms: the tool name counts most,
+ * then summary, path and argument names, then the description. The whole
+ * query as a phrase in the name or summary is a strong signal. */
+export function searchScore(op, query) {
+    const terms = searchTerms(query);
+    if (terms.length === 0)
+        return 0;
+    const tool = op.tool.toLowerCase();
+    const toolWords = tool.split("_");
+    const summary = (op.summary ?? "").toLowerCase();
+    const path = op.path.toLowerCase();
+    const params = op.params.map((p) => p.name.toLowerCase());
+    const description = (op.description ?? "").toLowerCase();
+    let score = 0;
+    for (const term of terms) {
+        if (toolWords.includes(term))
+            score += 10;
+        else if (tool.includes(term))
+            score += 6;
+        if (summary.split(/[^a-z0-9]+/).includes(term))
+            score += 5;
+        else if (summary.includes(term))
+            score += 3;
+        if (path.includes(term))
+            score += 3;
+        if (params.some((p) => p === term))
+            score += 3;
+        else if (params.some((p) => p.includes(term)))
+            score += 1;
+        if (description.includes(term))
+            score += 1;
+    }
+    const phrase = query.trim().toLowerCase();
+    if (phrase.length >= 3 && (tool.includes(phrase.replace(/[^a-z0-9]+/g, "_")) || summary.includes(phrase)))
+        score += 8;
+    return score;
+}
+export async function docsSearch(source, query, page = 1) {
+    const term = query.toLowerCase();
+    const sections = [];
+    const ranked = source.ops
+        .map((op) => ({ op, score: searchScore(op, query) }))
+        .filter((r) => r.score > 0)
+        .sort((a, b) => b.score - a.score || a.op.tool.localeCompare(b.op.tool));
+    const pageIndex = Math.max(1, Math.floor(page)) - 1;
+    const slice = ranked.slice(pageIndex * SEARCH_PAGE_SIZE, (pageIndex + 1) * SEARCH_PAGE_SIZE);
+    if (slice.length > 0) {
+        const more = ranked.length - (pageIndex + 1) * SEARCH_PAGE_SIZE;
+        sections.push("Reference matches (best first" + (ranked.length > SEARCH_PAGE_SIZE ? ", page " + (pageIndex + 1) + " of " + Math.ceil(ranked.length / SEARCH_PAGE_SIZE) : "") + "):\n" +
+            slice.map((r) => "- " + r.op.tool + ": " + (r.op.summary ?? r.op.httpMethod + " " + r.op.path)).join("\n") +
+            (more > 0 ? "\n(" + more + " more; pass page: " + (pageIndex + 2) + ")" : ""));
+    }
+    else if (ranked.length > 0) {
+        sections.push("No reference matches on page " + (pageIndex + 1) + "; there are " + Math.ceil(ranked.length / SEARCH_PAGE_SIZE) + " pages.");
+    }
+    const prose = await fetchDocs(source, "llms-full.txt");
+    if (prose !== null) {
+        let heading = "";
+        const proseMatches = [];
+        for (const line of prose.split("\n")) {
+            if (/^#{1,3} /.test(line))
+                heading = line.replace(/^#+ /, "").trim();
+            else if (line.toLowerCase().includes(term) && proseMatches.length < 15) {
+                proseMatches.push("- [" + heading + "] " + line.trim().slice(0, 160));
+            }
+        }
+        if (proseMatches.length > 0)
+            sections.push("Guide matches:\n" + proseMatches.join("\n"));
+    }
+    if (sections.length === 0) {
+        return {
+            text: "No matches for: " + query + (source.docsUrl() === null ? " (no docs site configured; only the API reference was searched)" : ""),
+            isError: false,
+        };
+    }
+    return { text: sections.join("\n\n"), isError: false };
+}
+export async function docsRead(source, page) {
+    const opMatch = findOperation(source.ops, page);
+    if (opMatch)
+        return { text: referenceText(opMatch), isError: false };
+    let target = page;
+    if (!/^https?:\/\//.test(target)) {
+        const index = await fetchDocs(source, "llms.txt");
+        const linked = index?.match(/\((https?:[^)]+)\)/g)?.map((m) => m.slice(1, -1)) ?? [];
+        const hit = linked.find((u) => u.toLowerCase().includes(target.toLowerCase()));
+        if (hit !== undefined)
+            target = hit;
+    }
+    const text = await fetchDocs(source, target);
+    if (text === null) {
+        return textError(source.docsUrl() === null
+            ? "No docs site is configured for this server, and no operation matches \"" + page + "\"."
+            : "Couldn't fetch \"" + page + "\". Use search_docs to find pages.", "NOT_FOUND", ["search_docs finds operations and guide pages."]);
+    }
+    return { text, isError: false };
+}
+/**
+ * Dispatch for the shared tools (search_docs, read_docs, execute); returns
+ * undefined for anything else so the caller can run its own tools.
+ * `runOperation` is how an execute call reaches the API; `source.ops` is
+ * the callable set, so a hidden operation is unknown here too.
+ */
+export async function callSharedTool(name, args, source, runOperation) {
+    if (name === "search_docs") {
+        if (typeof args.query !== "string")
+            return argumentsError({ tool: name }, [{ code: "MISSING_ARGUMENT", argument: "query", message: "search_docs requires a query string." }]);
+        const page = typeof args.page === "number" ? args.page : typeof args.page === "string" && /^\d+$/.test(args.page) ? Number(args.page) : 1;
+        return docsSearch(source, args.query, page);
+    }
+    if (name === "read_docs") {
+        return typeof args.page === "string" ? docsRead(source, args.page) : argumentsError({ tool: name }, [{ code: "MISSING_ARGUMENT", argument: "page", message: "read_docs requires a page string." }]);
+    }
+    if (name === "execute") {
+        if (typeof args.operation !== "string")
+            return argumentsError({ tool: name }, [{ code: "MISSING_ARGUMENT", argument: "operation", message: "execute requires an operation name." }]);
+        const target = findOperation(source.ops, args.operation);
+        if (!target)
+            return textError("Unknown operation: " + args.operation + ".", "NOT_FOUND", ["search_docs finds operations by name, path or description."]);
+        if (operationSafety(target) === "destructive" && args.confirm !== true) {
+            return textError("The destructive operation " + target.tool + " requires explicit confirmation.", "CONFIRMATION_REQUIRED", ["Review read_docs " + target.tool + ", then retry execute with confirm: true if the destructive effect is intended."]);
+        }
+        const opArgs = args.arguments !== null && typeof args.arguments === "object" && !Array.isArray(args.arguments)
+            ? args.arguments
+            : {};
+        return runOperation(target, opArgs);
+    }
+    return undefined;
+}
+/** A fetch for docs pages: markdown preferred, same-origin redirects only,
+ * a 10s deadline, and a 2 MB streaming cap. The caller already constrained
+ * the first URL to its configured docs origin; redirects must not escape it. */
+export const MAX_DOCS_TEXT_BYTES = 2_000_000;
+export async function fetchDocsText(url) {
+    try {
+        const allowedOrigin = new URL(url).origin;
+        let current = url;
+        const signal = AbortSignal.timeout(10_000);
+        for (let redirects = 0; redirects <= 3; redirects += 1) {
+            const response = await fetch(current, {
+                headers: { Accept: "text/markdown, text/plain, */*" },
+                redirect: "manual",
+                signal,
+            });
+            if (response.status >= 300 && response.status < 400) {
+                const location = response.headers.get("location");
+                if (!location || redirects === 3)
+                    return null;
+                const next = new URL(location, current);
+                if (next.origin !== allowedOrigin || next.username || next.password)
+                    return null;
+                current = next.toString();
+                continue;
+            }
+            if (!response.ok)
+                return null;
+            const declared = Number(response.headers.get("content-length"));
+            if (Number.isFinite(declared) && declared > MAX_DOCS_TEXT_BYTES)
+                return null;
+            if (!response.body)
+                return "";
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let bytes = 0;
+            let text = "";
+            for (;;) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                bytes += chunk.value.byteLength;
+                if (bytes > MAX_DOCS_TEXT_BYTES) {
+                    await reader.cancel();
+                    return null;
+                }
+                text += decoder.decode(chunk.value, { stream: true });
+            }
+            return text + decoder.decode();
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}