@typeship-ax/mcp 0.6.0 → 0.9.1

package/dist/mcp-protocol.js

@@ -15,6 +15,7 @@
  * Spec: https://modelcontextprotocol.io/specification/2026-07-28
  */
 import { dateKindOf, relativeDate } from "./dates.js";
+import { docsReadTarget, resolveDocsContentUrl, searchConnectedGuides } from "./docs.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
@@ -28,6 +29,30 @@ export const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
  * 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;
+/** Throw only from an application-owned credential resolver, before calling
+ * the API. The URL must show a sign-in/linking page, never a pre-authenticated
+ * resource, token or personal information. The page must verify the same user
+ * before linking. The runtime rechecks credentials on every subsequent call. */
+export class McpAccountLinkRequired extends Error {
+    url;
+    constructor(url) {
+        super("Connect your API account in the browser to continue.");
+        this.name = "McpAccountLinkRequired";
+        try {
+            const parsed = new URL(url);
+            if (url.length > 2048 || url !== url.trim() || /[\u0000-\u0020\u007F"\\]/.test(url) || parsed.username || parsed.password || parsed.hash ||
+                !(parsed.protocol === "https:" || parsed.protocol === "http:" && ["127.0.0.1", "[::1]", "localhost"].includes(parsed.hostname)) ||
+                [...parsed.searchParams.keys()].some(key => /^(access_token|refresh_token|client_secret|api_key|password|authorization)$/i.test(key)))
+                throw new Error();
+        }
+        catch {
+            throw new Error("Provide a public HTTPS account-linking page without credentials or a fragment (HTTP loopback is allowed for development).");
+        }
+        this.url = url;
+        Object.freeze(this);
+    }
+}
+const API_LINK_INPUT = "typeship_api_account";
 /** Does the operation take a file (multipart form or raw binary body)? */
 export function isUploadOp(op) {
     return op.bodyKind === "multipart" || op.bodyKind === "binary";
@@ -179,13 +204,45 @@ export async function handleRpc(server, incoming) {
             if (args === null || typeof args !== "object" || Array.isArray(args)) {
                 return rpcError(id, -32602, "tools/call arguments must be an object", 400);
             }
+            const responses = request.params?.inputResponses;
+            if (responses !== undefined && (responses === null || typeof responses !== "object" || Array.isArray(responses)))
+                return rpcError(id, -32602, "inputResponses must be an object", 400);
+            const response = responses && Object.hasOwn(responses, API_LINK_INPUT) ? responses[API_LINK_INPUT] : undefined;
+            if (response !== undefined) {
+                if (!response || typeof response !== "object" || Array.isArray(response) || !["accept", "decline", "cancel"].includes(response.action))
+                    return rpcError(id, -32602, "Invalid API account-link response", 400);
+                if (response.action !== "accept") {
+                    const cancelled = textError("API account linking was cancelled. No API request was made.", "ACCOUNT_LINK_CANCELLED");
+                    return complete({ content: [{ type: "text", text: cancelled.text }], isError: true });
+                }
+                // A client acknowledgment is not authorization. Only a fresh lookup
+                // of the server's linked credentials can let the operation proceed.
+            }
             const denied = server.beforeToolCall ? await server.beforeToolCall(name) : null;
             if (denied)
                 return denied;
             const started = Date.now();
-            const outcome = await server.callTool(name, args);
+            let outcome;
+            try {
+                outcome = await server.callTool(name, args);
+            }
+            catch (error) {
+                if (!(error instanceof McpAccountLinkRequired))
+                    throw error;
+                const caps = (request.params?._meta)[META_CLIENT_CAPS];
+                const urlMode = caps.elicitation?.url;
+                if (urlMode === null || typeof urlMode !== "object" || Array.isArray(urlMode)) {
+                    const unsupported = textError("Connect your API account using an MCP client that supports browser account-linking prompts (URL-mode elicitation), then retry.", "ACCOUNT_LINK_REQUIRED");
+                    return complete({ content: [{ type: "text", text: unsupported.text }], isError: true });
+                }
+                return { status: 200, message: { jsonrpc: "2.0", id, result: {
+                            resultType: "input_required",
+                            inputRequests: { [API_LINK_INPUT]: { method: "elicitation/create", params: { mode: "url", url: error.url, message: "Connect your API account in the browser to continue." } } },
+                            _meta: { [META_SERVER_INFO]: server.serverInfo },
+                        } } };
+            }
             if (outcome === undefined)
-                return rpcError(id, -32602, "Unknown tool: " + name, 400);
+                return rpcError(id, -32602, server.unknownToolMessage?.(name) ?? "Unknown tool: " + name, 400);
             if (server.afterToolCall)
                 await server.afterToolCall(name, outcome, Date.now() - started);
             // A tool that declares an outputSchema MUST return structuredContent,
@@ -275,8 +332,18 @@ export function exampleFromSchema(schema, field = "value", depth = 0) {
         return node.examples[0];
     if (node.default !== undefined)
         return node.default;
-    if (Array.isArray(node.enum) && node.enum.length > 0)
+    if (Array.isArray(node.enum) && node.enum.length > 0) {
+        if (typeof node.pattern === "string") {
+            try {
+                const pattern = new RegExp(node.pattern);
+                const matching = node.enum.find((value) => typeof value === "string" && pattern.test(value));
+                if (matching !== undefined)
+                    return matching;
+            }
+            catch { /* malformed patterns are ignored for examples */ }
+        }
         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];
@@ -316,7 +383,10 @@ export function exampleFromSchema(schema, field = "value", depth = 0) {
     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"
+        const min = typeof node.minLength === "number" ? node.minLength : 0;
+        const max = typeof node.maxLength === "number" ? node.maxLength : undefined;
+        const patterned = typeof node.pattern === "string" ? exampleMatchingPattern(node.pattern, min, max) : null;
+        let value = patterned ?? (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"
@@ -327,16 +397,47 @@ export function exampleFromSchema(schema, field = "value", depth = 0) {
                                         : 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;
+                                                    : "value");
         while (value.length < min)
             value += "x";
-        if (typeof node.maxLength === "number")
-            value = value.slice(0, node.maxLength);
+        if (max !== undefined)
+            value = value.slice(0, max);
         return value;
     }
     return null;
 }
+/** A useful value for the common API-id pattern (`^agt_`, `^src_[a-z0-9]+$`).
+ * Full regex generation would be surprising and heavyweight; an anchored
+ * literal prefix plus ordinary id suffix covers the schemas that use a
+ * pattern to communicate a typed identifier. Every candidate is checked by
+ * the actual RegExp before it is returned. */
+function exampleMatchingPattern(pattern, minLength, maxLength) {
+    let regex;
+    try {
+        regex = new RegExp(pattern);
+    }
+    catch {
+        return null;
+    }
+    const match = /^\^((?:\\.|[A-Za-z0-9_-])+)/.exec(pattern);
+    const prefix = match?.[1]?.replace(/\\(.)/g, "$1") ?? "";
+    const fit = (candidate) => {
+        let value = candidate;
+        while (value.length < minLength)
+            value += "x";
+        if (maxLength !== undefined)
+            value = value.slice(0, maxLength);
+        return value;
+    };
+    const candidates = [prefix + "123", prefix + "example", prefix, "resource.method", "example.value", "example_123", "example", "value"];
+    for (const candidate of candidates) {
+        const value = fit(candidate);
+        regex.lastIndex = 0;
+        if (regex.test(value))
+            return value;
+    }
+    return null;
+}
 export function exampleArgumentsFromSchema(inputSchema) {
     const value = exampleFromSchema(inputSchema, "arguments");
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
@@ -400,7 +501,7 @@ export const EXECUTE_TOOL = {
     inputSchema: {
         type: "object",
         properties: {
-            operation: { type: "string", description: "Operation tool name, e.g. accounts_create" },
+            operation: { type: "string", description: "Operation tool name returned by search_docs" },
             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." },
         },
@@ -433,36 +534,23 @@ export function parseIncludeList(value) {
  * 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) {
+export function toolDefinitions(ops, mode, omittedOps = []) {
     if (mode === "meta") {
+        const execute = structuredClone(EXECUTE_TOOL);
+        const operation = execute.inputSchema.properties.operation;
+        if (ops[0])
+            operation.examples = [ops[0].tool];
+        const coverage = omittedOps.length > 0
+            ? " Generated " + ops.length + " of " + (ops.length + omittedOps.length) + " operations; search_docs names operations omitted by the plan limit."
+            : "";
         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." },
+            { ...SEARCH_DOCS_TOOL, description: "Search this API's " + ops.length + " generated operations and, when a docs site is configured, its guides. Start here to find the operation you need." + coverage },
             { ...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,
+            execute,
         ];
     }
     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)
@@ -480,7 +568,16 @@ export function serverInstructions(input) {
     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.");
+    if (input.omittedOps?.length) {
+        const generated = input.generatedOperationCount ?? input.toolCount;
+        parts.push("Plan-limited generation: generated " + generated + " of " + (generated + input.omittedOps.length) + " operations. Omitted operations: " + input.omittedOps.map((op) => op.tool + " (" + op.httpMethod + " " + op.path + ")").join(", ") + ". Calling or searching for one returns PLAN_LIMIT with upgrade next_steps.");
+    }
     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).");
+    if (input.referenceResolution)
+        parts.push("Reference arguments marked in their schema accept either an ID or an exact case-insensitive name, slug, key or email; the server resolves one match through the named list tool, reports multiple candidates, and never guesses fuzzily.");
+    if (input.identityTool && input.ops.some((op) => op.params.some((param) => param.type === "string" && param.resolve !== false && userShapedReference(param.name)))) {
+        parts.push("User-shaped reference arguments also accept \"me\", resolved through " + input.identityTool + ".");
+    }
     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)
@@ -714,6 +811,175 @@ export function prepareCall(op, rawArgs, options = {}) {
         return { ok: false, outcome: argumentsError(op, issues) };
     return { ok: true, call: { args, fields, maxChars: options.maxChars ?? DEFAULT_MAX_RESULT_CHARS } };
 }
+function referenceError(code, message, argument, nextSteps, candidates) {
+    const structured = {
+        error: code === "REFERENCE_NOT_FOUND" ? "ReferenceNotFound" : code === "REFERENCE_AMBIGUOUS" ? "AmbiguousReference" : code === "REFERENCE_SCAN_LIMIT" ? "ReferenceScanLimit" : "ReferenceResolutionUnavailable",
+        code,
+        message,
+        argument,
+        ...(candidates ? { candidates } : {}),
+        next_steps: nextSteps,
+    };
+    return { text: JSON.stringify(structured), isError: true, structured };
+}
+function outcomeValue(outcome) {
+    if (outcome.structured !== undefined)
+        return outcome.structured;
+    try {
+        return JSON.parse(outcome.text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function referencePage(value) {
+    if (Array.isArray(value)) {
+        return { items: value.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item)), nextPage: null };
+    }
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    const direct = Array.isArray(record.items) ? record.items : undefined;
+    const arrays = direct ? [direct] : Object.entries(record)
+        .filter(([name, entry]) => name !== "request_id" && name !== "requestId" && Array.isArray(entry))
+        .map(([, entry]) => entry);
+    if (arrays.length !== 1)
+        return null;
+    return {
+        items: arrays[0].filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item)),
+        nextPage: record.nextPage && typeof record.nextPage === "object" && !Array.isArray(record.nextPage)
+            ? record.nextPage
+            : null,
+    };
+}
+function userShapedReference(name) {
+    const normalized = name.toLowerCase().replace(/[^a-z0-9]/g, "").replace(/id$/, "");
+    return ["user", "assignee", "owner", "member", "actor", "creator", "account", "profile"].includes(normalized);
+}
+function referenceMatchLabel(fields) {
+    return fields.length === 1 ? fields[0] : fields.slice(0, -1).join(", ") + " or " + fields.at(-1);
+}
+function looksLikeIdentifier(value, resolver) {
+    if (/\s/.test(value))
+        return false;
+    if (resolver.idPattern !== undefined) {
+        try {
+            return new RegExp(resolver.idPattern).test(value);
+        }
+        catch {
+            return false;
+        }
+    }
+    return /^\d+$/.test(value) ||
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value) ||
+        /^[a-z][a-z0-9]*_[a-z0-9][a-z0-9_-]*$/i.test(value) ||
+        /^[A-Z][A-Z0-9]{1,9}-\d+$/.test(value) ||
+        /^[A-Za-z0-9_-]{20,}$/.test(value);
+}
+function putReferenceCache(cache, key, value) {
+    cache.set(key, value);
+    while (cache.size > 256)
+        cache.delete(cache.keys().next().value);
+}
+function candidateRecord(item, resolver) {
+    return Object.fromEntries([resolver.id, ...resolver.match]
+        .filter((name, index, all) => all.indexOf(name) === index && item[name] !== undefined)
+        .map((name) => [name, item[name]]));
+}
+/** Resolve every eligible reference after validation/coercion and before the
+ * requested API call. Matching is exact (case-insensitive for strings),
+ * never fuzzy. Zero matches fail before the requested API call. */
+export async function resolveReferences(op, preparedArgs, options) {
+    const args = { ...preparedArgs };
+    const maxPages = Math.max(1, Math.floor(options.maxPages ?? 5));
+    for (const param of op.params) {
+        const raw = args[param.name];
+        if (typeof raw !== "string" || param.resolve === false)
+            continue;
+        const value = raw.trim();
+        if (value.toLowerCase() === "me" && userShapedReference(param.name) && options.identityTool) {
+            const identity = findOperation(options.ops, options.identityTool);
+            if (identity) {
+                const cacheKey = "me:" + identity.tool;
+                const cached = options.cache.get(cacheKey);
+                if (cached !== undefined) {
+                    args[param.name] = cached;
+                    continue;
+                }
+                const outcome = await options.runOperation(identity, {});
+                if (outcome.isError)
+                    return { ok: false, outcome };
+                const body = outcomeValue(outcome);
+                const id = body && typeof body === "object" && !Array.isArray(body) ? body.id : undefined;
+                if (typeof id !== "string" && typeof id !== "number") {
+                    return { ok: false, outcome: referenceError("NOT_AVAILABLE", `${identity.tool} did not return a top-level id, so "me" cannot be resolved for ${param.name}.`, param.name, ["Pass the caller's exact ID instead."]) };
+                }
+                putReferenceCache(options.cache, cacheKey, id);
+                args[param.name] = id;
+                continue;
+            }
+        }
+        const resolver = param.resolve && typeof param.resolve === "object" ? param.resolve : undefined;
+        if (!resolver || looksLikeIdentifier(value, resolver))
+            continue;
+        const source = findOperation(options.ops, resolver.via);
+        if (!source)
+            continue;
+        const cacheKey = source.tool + ":" + resolver.id + ":" + resolver.match.join(",") + ":" + value.toLowerCase();
+        const cached = options.cache.get(cacheKey);
+        if (cached !== undefined) {
+            args[param.name] = cached;
+            continue;
+        }
+        const matches = new Map();
+        let pageArgs = {};
+        for (const sourceParam of source.params) {
+            if (args[sourceParam.name] !== undefined && sourceParam.name !== param.name)
+                pageArgs[sourceParam.name] = args[sourceParam.name];
+        }
+        if (resolver.filterParam)
+            pageArgs[resolver.filterParam] = value;
+        if (!hasOwnFieldsParam(source))
+            pageArgs.fields = [resolver.id, ...resolver.match];
+        let exhausted = false;
+        for (let pageNumber = 1; pageNumber <= maxPages; pageNumber++) {
+            const outcome = await options.runOperation(source, pageArgs);
+            if (outcome.isError)
+                return { ok: false, outcome };
+            const page = referencePage(outcomeValue(outcome));
+            if (!page) {
+                return { ok: false, outcome: referenceError("NOT_AVAILABLE", `${source.tool} did not return one recognizable item array, so ${param.name} cannot be resolved by name.`, param.name, ["Pass the exact ID instead.", `Check the resolver hint for ${source.tool}.`]) };
+            }
+            for (const item of page.items) {
+                const id = item[resolver.id];
+                if (typeof id !== "string" && typeof id !== "number")
+                    continue;
+                const hit = resolver.match.some((field) => typeof item[field] === "string" && item[field].toLowerCase() === value.toLowerCase());
+                if (hit)
+                    matches.set(typeof id + ":" + String(id), { id, item });
+            }
+            if (matches.size > 1) {
+                const candidates = [...matches.values()].map(({ item }) => candidateRecord(item, resolver));
+                return { ok: false, outcome: referenceError("REFERENCE_AMBIGUOUS", `${JSON.stringify(raw)} matches multiple candidates for ${param.name}; nothing was sent to ${op.tool}.`, param.name, ["Choose one candidate ID and call again."], candidates) };
+            }
+            if (!page.nextPage) {
+                exhausted = true;
+                break;
+            }
+            pageArgs = { ...pageArgs, ...page.nextPage };
+        }
+        if (!exhausted) {
+            return { ok: false, outcome: referenceError("REFERENCE_SCAN_LIMIT", `${source.tool} still had more results after ${maxPages} pages, so ${JSON.stringify(raw)} could not be resolved unambiguously.`, param.name, ["Pass the exact ID instead.", `Narrow ${source.tool} with its filters, or declare a more selective resolver.`]) };
+        }
+        const match = [...matches.values()][0];
+        if (!match) {
+            return { ok: false, outcome: referenceError("REFERENCE_NOT_FOUND", `${JSON.stringify(raw)} did not exactly match any ${referenceMatchLabel(resolver.match)} from ${source.tool}; nothing was sent to ${op.tool}.`, param.name, [`Call ${source.tool} to choose an exact ${referenceMatchLabel(resolver.match)} or ID, then call again.`]) };
+        }
+        putReferenceCache(options.cache, cacheKey, match.id);
+        args[param.name] = match.id;
+    }
+    return { ok: true, args };
+}
 /** The isError result for bad arguments: one stable code, one issue per
  * argument, and the way out. */
 export function argumentsError(op, issues) {
@@ -786,12 +1052,17 @@ 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 full = {
+        items: shown,
+        hasMore: nextPage !== null,
+        ...(nextPage !== null ? { nextPage } : {}),
+        ...(options.requestId ? { request_id: options.requestId } : {}),
+    };
     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 overhead = JSON.stringify({ items: [], hasMore: true, nextPage: nextPage ?? {}, ...(options.requestId ? { request_id: options.requestId } : {}), 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;
@@ -818,6 +1089,7 @@ export function pageOutcome(items, nextPage, options = {}) {
         items: shown.slice(0, k),
         hasMore: resume !== null ? true : nextPage !== null,
         ...(resume !== null ? { nextPage: resume } : nextPage !== null ? { nextPage } : {}),
+        ...(options.requestId ? { request_id: options.requestId } : {}),
         truncated: {
             omitted,
             of: shown.length,
@@ -961,6 +1233,7 @@ export function classifyError(error, context = {}) {
         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 body = e.body;
     const auth = context.authHint ? context.authHint.trim().replace(/[.]?$/, ".") : null;
     if (status === 401) {
         return context.hadCredential
@@ -977,6 +1250,15 @@ export function classifyError(error, context = {}) {
         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 === 422 && body?.errors?.[0]?.code === "spec_error") {
+        return {
+            code: "SPEC_INVALID",
+            nextSteps: [
+                "The API rejected the spec it was given; its error message names the invalid part.",
+                context.docsUrl ? "Use search_docs with the error message, fix the spec, then call again." : "Fix the spec, then call again.",
+            ],
+        };
+    }
     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."] };
     }
@@ -1003,11 +1285,16 @@ function notFoundNextSteps(message, body) {
 export function errorOutcome(error, context = {}) {
     const e = error;
     const { code, nextSteps } = classifyError(error, context);
+    const bodyRequestId = e?.body && typeof e.body === "object" && !Array.isArray(e.body)
+        ? e.body.request_id ?? e.body.requestId
+        : undefined;
+    const requestId = e?.response?.requestId ?? (typeof bodyRequestId === "string" ? bodyRequestId : undefined);
     const structured = {
         error: e?.name ?? "Error",
         code,
         message: e?.message,
         ...(typeof e?.status === "number" ? { status: e.status } : {}),
+        ...(requestId ? { request_id: requestId } : {}),
         ...(e?.body !== undefined ? { body: e.body } : {}),
         ...(context.docsUrl ? { docs_url: context.docsUrl } : {}),
         next_steps: nextSteps,
@@ -1018,32 +1305,29 @@ 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);
+    const url = resolveDocsContentUrl(source.docsUrl(), source.docsIndexUrl?.() ?? null, pathOrFile);
     return url === null ? null : source.fetchText(url);
 }
+function coverageText(source) {
+    const omitted = source.omittedOps ?? [];
+    const generated = source.generatedOperationCount ?? source.ops.length;
+    return omitted.length > 0
+        ? "Coverage: generated " + generated + " of " + (generated + omitted.length) + " operations. Omitted by the plan limit: " + omitted.map((op) => op.tool + " (" + op.httpMethod + " " + op.path + ")").join(", ") + "."
+        : null;
+}
+function omittedPlanLimit(ops, requested) {
+    const structured = {
+        error: "PlanLimitError",
+        code: "PLAN_LIMIT",
+        message: requested
+            ? "The operation " + requested + " exists in the API Definition but was omitted from this generated package by its plan limit."
+            : "Matching operations exist in the API Definition but were omitted from this generated package by its plan limit.",
+        omitted_operations: ops.map((op) => ({ tool: op.tool, method: op.httpMethod, path: op.path })),
+        next_steps: ["Upgrade at https://typeship.dev/pricing and regenerate the package without the operation cap.", "Do not invent or retry an omitted operation against this generated package."],
+    };
+    return { text: JSON.stringify(structured), isError: true, structured };
+}
 export function referenceText(op) {
     const safety = operationSafety(op);
     const example = op.exampleArguments ?? exampleArgumentsFromSchema(op.inputSchema);
@@ -1114,12 +1398,18 @@ export function searchScore(op, query) {
     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 omittedRanked = (source.omittedOps ?? [])
+        .map((op) => ({ op, score: searchScore(op, query) }))
+        .filter((result) => result.score > 0)
+        .sort((a, b) => b.score - a.score || a.op.tool.localeCompare(b.op.tool));
+    const exactOmitted = findOperation(source.omittedOps ?? [], query);
+    if (exactOmitted)
+        return omittedPlanLimit([exactOmitted], exactOmitted.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) {
@@ -1131,47 +1421,56 @@ export async function docsSearch(source, query, page = 1) {
     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"));
+    const { guides, status } = await searchConnectedGuides(source.docsUrl(), source.docsIndexUrl?.() ?? null, (path) => fetchDocs(source, path), query);
+    const guideSlice = guides.slice(pageIndex * SEARCH_PAGE_SIZE, (pageIndex + 1) * SEARCH_PAGE_SIZE);
+    const proseMatchCount = guides.length;
+    if (guideSlice.length > 0) {
+        sections.push("Guide matches (best first, " + guides.length + " pages):\n" + guideSlice.map((match) => "- [" + match.title + (match.section ? " / " + match.section : "") + "](" + match.url + "): " + match.excerpt + "\n  read_docs " + JSON.stringify({ page: match.url })).join("\n"));
+    }
+    if (status === "unavailable")
+        sections.push("The docs site is unavailable; the API reference was still searched.");
+    const structured = {
+        schema_version: "1", query, page: pageIndex + 1,
+        reference: slice.map(({ op }) => ({ tool: op.tool, method: op.httpMethod, path: op.path, ...(op.summary ? { summary: op.summary } : {}), read_tool: { name: "read_docs", arguments: { page: op.tool } } })),
+        guides: guideSlice.map((match) => ({ ...match, read_tool: { name: "read_docs", arguments: { page: match.url } } })),
+        totals: { reference: ranked.length, guides: guides.length }, guides_status: status,
+    };
+    if (omittedRanked.length > 0 && ranked.length === 0 && proseMatchCount === 0) {
+        return omittedPlanLimit(omittedRanked.map((result) => result.op));
     }
+    if (omittedRanked.length > 0) {
+        sections.push("Operations omitted by the plan limit:\n" + omittedRanked.slice(0, SEARCH_PAGE_SIZE).map((result) => "- " + result.op.tool + ": " + (result.op.summary ?? result.op.httpMethod + " " + result.op.path)).join("\n"));
+    }
+    const coverage = coverageText(source);
     if (sections.length === 0) {
         return {
-            text: "No matches for: " + query + (source.docsUrl() === null ? " (no docs site configured; only the API reference was searched)" : ""),
+            text: (coverage ? coverage + "\n\n" : "") + "No matches for: " + query + (source.docsUrl() === null && (source.docsIndexUrl?.() ?? null) === null ? " (a docs URL was not provided at generate time; only the API reference was searched)" : ""),
             isError: false,
+            structured,
         };
     }
-    return { text: sections.join("\n\n"), isError: false };
+    return { text: [...(coverage ? [coverage] : []), ...sections].join("\n\n"), isError: false, structured };
 }
 export async function docsRead(source, page) {
     const opMatch = findOperation(source.ops, page);
+    const coverage = coverageText(source);
     if (opMatch)
-        return { text: referenceText(opMatch), isError: false };
+        return { text: [...(coverage ? [coverage] : []), referenceText(opMatch)].join("\n\n"), isError: false };
+    const omittedMatch = findOperation(source.omittedOps ?? [], page);
+    if (omittedMatch)
+        return omittedPlanLimit([omittedMatch], omittedMatch.tool);
     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;
+        target = docsReadTarget(index, source.docsUrl(), source.docsIndexUrl?.() ?? null, target);
     }
     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 + "\"."
+        return textError(source.docsUrl() === null && (source.docsIndexUrl?.() ?? null) === null
+            ? "A docs URL was not provided at generate time, and no generated 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 };
+    return { text: [...(coverage ? [coverage] : []), text].join("\n\n"), isError: false };
 }
 /**
  * Dispatch for the shared tools (search_docs, read_docs, execute); returns
@@ -1193,8 +1492,12 @@ export async function callSharedTool(name, args, source, runOperation) {
         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 (!target) {
+            const omitted = findOperation(source.omittedOps ?? [], args.operation);
+            return omitted
+                ? omittedPlanLimit([omitted], omitted.tool)
+                : 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."]);
         }
@@ -1205,58 +1508,3 @@ export async function callSharedTool(name, args, source, runOperation) {
     }
     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;
-    }
-}