@typeship-ax/mcp 0.6.0 → 0.9.1

package/src/mcp-protocol.ts

@@ -16,6 +16,7 @@
  */
 
 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
@@ -76,6 +77,28 @@ export interface ToolOutcome {
   content?: ContentBlock[];
 }
 
+/** 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 {
+  readonly url: string;
+  constructor(url: string) {
+    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";
+
 /** The subset of an operation spec (ops.ts / the hosted manifest) the
  * protocol layer reads. */
 export interface OpLike {
@@ -92,7 +115,14 @@ export interface OpLike {
   /** GraphQL ops accept a raw selection-set override. */
   select: boolean;
   graphql?: { kind: string };
-  params: { name: string; type: string; required: boolean; enum?: string[]; description?: string }[];
+  params: {
+    name: string;
+    type: string;
+    required: boolean;
+    enum?: string[];
+    description?: string;
+    resolve?: false | ReferenceResolver;
+  }[];
   inputSchema: Record<string, unknown>;
   outputSchema?: Record<string, unknown>;
   /** Canonical effect classification shared by generated docs, CLI, and MCP. */
@@ -109,6 +139,16 @@ export interface OpLike {
   bodyKind?: string | null;
 }
 
+/** Fully proved lookup metadata carried in ops.ts / the hosted manifest. */
+export interface ReferenceResolver {
+  via: string;
+  match: string[];
+  id: string;
+  idPattern?: string;
+  filterParam?: string;
+  inferred?: boolean;
+}
+
 /** Does the operation take a file (multipart form or raw binary body)? */
 export function isUploadOp(op: OpLike): boolean {
   return op.bodyKind === "multipart" || op.bodyKind === "binary";
@@ -151,9 +191,14 @@ export interface McpServer {
   listTools(): ToolDefinition[];
   /**
    * Run a tool. Return undefined for an unknown tool (the client gets
-   * -32602), a ToolOutcome otherwise. Throwing yields -32603.
+   * -32602), a ToolOutcome otherwise. McpAccountLinkRequired requests a
+   * browser interaction; other exceptions yield -32603.
    */
   callTool(name: string, args: Record<string, unknown>): Promise<ToolOutcome | undefined>;
+  /** Optional actionable wording for an unknown tool name. The protocol
+   * code remains -32602; compact tool surfaces can explain how to call an
+   * operation without pretending that operation is absent. */
+  unknownToolMessage?(name: string): string;
   /** Called before a tool runs; a non-null outcome is sent instead
    * (rate limiting, entitlement). */
   beforeToolCall?(name: string): Promise<RpcOutcome | null> | RpcOutcome | null;
@@ -307,11 +352,38 @@ export async function handleRpc(server: McpServer, incoming: unknown): Promise<R
       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 as Record<string, unknown>)[API_LINK_INPUT] : undefined;
+      if (response !== undefined) {
+        if (!response || typeof response !== "object" || Array.isArray(response) || !["accept", "decline", "cancel"].includes((response as { action: string }).action)) return rpcError(id, -32602, "Invalid API account-link response", 400);
+        if ((response as { action: string }).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);
-      if (outcome === undefined) return rpcError(id, -32602, "Unknown tool: " + name, 400);
+      let outcome: ToolOutcome | undefined;
+      try { outcome = await server.callTool(name, args); }
+      catch (error) {
+        if (!(error instanceof McpAccountLinkRequired)) throw error;
+        const caps = (request.params?._meta as Record<string, unknown>)[META_CLIENT_CAPS] as { elicitation?: { url?: unknown } };
+        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, 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,
       // and clients enforce it: a successful result without it fails the
@@ -396,7 +468,16 @@ export function exampleFromSchema(schema: unknown, field = "value", depth = 0):
   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];
+  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) as unknown[] | null;
   if (variants) {
     const useful = variants.find((v) => v && typeof v === "object" && (v as Record<string, unknown>).type !== "null") ?? variants[0];
@@ -432,7 +513,10 @@ export function exampleFromSchema(schema: unknown, 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"
@@ -443,15 +527,39 @@ export function exampleFromSchema(schema: unknown, 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: string, minLength: number, maxLength?: number): string | null {
+  let regex: RegExp;
+  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: string): string => {
+    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: Record<string, unknown>): Record<string, unknown> {
   const value = exampleFromSchema(inputSchema, "arguments");
   return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
@@ -523,7 +631,7 @@ export const EXECUTE_TOOL: ToolDefinition = {
   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." },
     },
@@ -569,42 +677,23 @@ export function parseIncludeList(value: string | undefined | null): string[] | u
  * 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: OpLike[], mode: "operations" | "meta"): ToolDefinition[] {
+export function toolDefinitions(ops: OpLike[], mode: "operations" | "meta", omittedOps: OpLike[] = []): ToolDefinition[] {
   if (mode === "meta") {
+    const execute = structuredClone(EXECUTE_TOOL);
+    const operation = (execute.inputSchema.properties as Record<string, Record<string, unknown>>).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: ToolDefinition[]): { tools: number; chars: number; approxTokens: number } {
-  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: OpLike[],
-  requested: "operations" | "meta" | "auto" = "auto",
-): { mode: "operations" | "meta"; tools: number; chars: number; approxTokens: number } {
-  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: OpLike[], wanted: string): OpLike | undefined {
@@ -621,8 +710,14 @@ export function missingArguments(op: OpLike, args: Record<string, unknown>): str
 
 export interface InstructionsInput {
   title: string;
+  /** Callable operations, used to advertise only capabilities the surface has. */
+  ops: OpLike[];
   /** Operations the server serves (after read-only / include filtering). */
   toolCount: number;
+  /** Operations present in the Definition but absent from this capped generation. */
+  omittedOps?: OpLike[];
+  /** Count generated before read-only or include filters narrow this server. */
+  generatedOperationCount?: number;
   mode: "operations" | "meta";
   readOnly?: boolean;
   /** Write operations hidden by read-only mode. */
@@ -631,6 +726,8 @@ export interface InstructionsInput {
   authHint?: string | null;
   /** The tool that returns the caller (the CLI's whoami target), when the API has one. */
   identityTool?: string | null;
+  /** At least one argument accepts an exact human reference as well as an ID. */
+  referenceResolution?: boolean;
   /** Upload operations are exposed (local server): their file arguments take paths. */
   uploads?: boolean;
   /** Project-supplied text, appended verbatim. */
@@ -645,7 +742,15 @@ export function serverInstructions(input: InstructionsInput): string {
   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) parts.push(input.authHint.trim().replace(/[.]?$/, "."));
@@ -873,6 +978,194 @@ export function prepareCall(
   return { ok: true, call: { args, fields, maxChars: options.maxChars ?? DEFAULT_MAX_RESULT_CHARS } };
 }
 
+/** One caller/session's resolved names. Hosted transports must scope this
+ * map by caller credential; generated stdio servers naturally have one map
+ * per process. */
+export type ReferenceCache = Map<string, string | number>;
+
+export interface ResolveReferencesOptions {
+  /** Operations available to act as declared/inferred resolvers. */
+  ops: OpLike[];
+  /** Operation returning the authenticated caller, for user-shaped "me". */
+  identityTool?: string | null;
+  cache: ReferenceCache;
+  /** Raw operation runner: validates and calls, but does not resolve again. */
+  runOperation(op: OpLike, args: Record<string, unknown>): Promise<ToolOutcome>;
+  /** Hard bound for list scans. Default 5. */
+  maxPages?: number;
+}
+
+export type ResolveReferencesResult =
+  | { ok: true; args: Record<string, unknown> }
+  | { ok: false; outcome: ToolOutcome };
+
+function referenceError(
+  code: "REFERENCE_NOT_FOUND" | "REFERENCE_AMBIGUOUS" | "REFERENCE_SCAN_LIMIT" | "NOT_AVAILABLE",
+  message: string,
+  argument: string,
+  nextSteps: string[],
+  candidates?: Record<string, unknown>[],
+): ToolOutcome {
+  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: ToolOutcome): unknown {
+  if (outcome.structured !== undefined) return outcome.structured;
+  try { return JSON.parse(outcome.text); } catch { return undefined; }
+}
+
+function referencePage(value: unknown): { items: Record<string, unknown>[]; nextPage: Record<string, unknown> | null } | null {
+  if (Array.isArray(value)) {
+    return { items: value.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object" && !Array.isArray(item)), nextPage: null };
+  }
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  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 as unknown[]);
+  if (arrays.length !== 1) return null;
+  return {
+    items: arrays[0]!.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object" && !Array.isArray(item)),
+    nextPage: record.nextPage && typeof record.nextPage === "object" && !Array.isArray(record.nextPage)
+      ? record.nextPage as Record<string, unknown>
+      : null,
+  };
+}
+
+function userShapedReference(name: string): boolean {
+  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: string[]): string {
+  return fields.length === 1 ? fields[0]! : fields.slice(0, -1).join(", ") + " or " + fields.at(-1);
+}
+
+function looksLikeIdentifier(value: string, resolver: ReferenceResolver): boolean {
+  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: ReferenceCache, key: string, value: string | number): void {
+  cache.set(key, value);
+  while (cache.size > 256) cache.delete(cache.keys().next().value!);
+}
+
+function candidateRecord(item: Record<string, unknown>, resolver: ReferenceResolver): Record<string, unknown> {
+  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: OpLike,
+  preparedArgs: Record<string, unknown>,
+  options: ResolveReferencesOptions,
+): Promise<ResolveReferencesResult> {
+  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 as Record<string, unknown>).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<string, { id: string | number; item: Record<string, unknown> }>();
+    let pageArgs: Record<string, unknown> = {};
+    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] as string).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: { tool: string }, issues: ArgumentIssue[]): ToolOutcome {
@@ -920,6 +1213,9 @@ export function projectFields(value: unknown, paths: string[][] | null): unknown
 export interface ResultOptions {
   fields?: string[][] | null;
   maxChars?: number;
+  /** Request identifier for a page that is reshaped into the MCP paging
+   * envelope. Ordinary object results already retain their body field. */
+  requestId?: string;
   /** For paginated results that must be cut: the op's pagination config and
    * the call's arguments let some styles resume exactly where the cut fell. */
   pagination?: OpLike["pagination"];
@@ -951,13 +1247,18 @@ export function pageOutcome(items: unknown[], nextPage: Record<string, unknown>
   const fields = options.fields ?? null;
   const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
   const shown = projectFields(items, fields) as unknown[];
-  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;
@@ -981,6 +1282,7 @@ export function pageOutcome(items: unknown[], nextPage: Record<string, unknown>
     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,
@@ -1123,7 +1425,9 @@ export async function binaryOutcome(blob: Blob, options: BinaryOptions = {}): Pr
  * generated CLI's error envelope). Additive only. */
 export type ErrorCode =
   | "NO_AUTH" | "AUTH_INVALID" | "PLAN_LIMIT" | "NOT_FOUND" | "INVALID_REQUEST" | "RATE_LIMITED"
-  | "SERVER_ERROR" | "NETWORK_ERROR" | "VALIDATION_FAILED" | "INVALID_ARGUMENTS" | "CONFIRMATION_REQUIRED" | "NOT_AVAILABLE" | "CALL_FAILED";
+  | "SPEC_INVALID" | "SERVER_ERROR" | "NETWORK_ERROR" | "VALIDATION_FAILED" | "INVALID_ARGUMENTS" | "CONFIRMATION_REQUIRED"
+  | "REFERENCE_NOT_FOUND" | "REFERENCE_AMBIGUOUS" | "REFERENCE_SCAN_LIMIT" | "NOT_AVAILABLE" | "CALL_FAILED"
+  | "ACCOUNT_LINK_REQUIRED" | "ACCOUNT_LINK_CANCELLED";
 
 export interface ErrorContext {
   /** One sentence on how to supply a credential on this transport. */
@@ -1151,6 +1455,7 @@ export function classifyError(error: unknown, context: ErrorContext = {}): { cod
     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 as { errors?: { code?: string; message?: string }[] } | undefined;
   const auth = context.authHint ? context.authHint.trim().replace(/[.]?$/, ".") : null;
   if (status === 401) {
     return context.hadCredential
@@ -1164,6 +1469,15 @@ export function classifyError(error: unknown, context: ErrorContext = {}): { cod
     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."] };
   }
@@ -1189,13 +1503,18 @@ function notFoundNextSteps(message: string, body: unknown): string[] {
 /** 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: unknown, context: ErrorContext = {}): ToolOutcome {
-  const e = error as { name?: string; message?: string; status?: number; body?: unknown };
+  const e = error as { name?: string; message?: string; status?: number; body?: unknown; response?: { requestId?: string } };
   const { code, nextSteps } = classifyError(error, context);
+  const bodyRequestId = e?.body && typeof e.body === "object" && !Array.isArray(e.body)
+    ? (e.body as Record<string, unknown>).request_id ?? (e.body as Record<string, unknown>).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,
@@ -1212,36 +1531,44 @@ export function textError(text: string, code: ErrorCode = "CALL_FAILED", nextSte
 
 export interface DocsSource {
   ops: OpLike[];
+  /** Operations omitted from a capped generation. */
+  omittedOps?: OpLike[];
+  /** Count generated before runtime surface filters. */
+  generatedOperationCount?: number;
   /** Base URL of the docs site, or null when none is configured. */
   docsUrl(): string | null;
+  /** Exact llms.txt URL when it is not at <docsUrl>/llms.txt. */
+  docsIndexUrl?(): string | null;
   /** Fetch a URL's text, or null on any failure. */
   fetchText(url: string): Promise<string | null>;
 }
 
-function docsPageUrl(source: DocsSource, pathOrFile: string): string | null {
-  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: DocsSource, pathOrFile: string): Promise<string | null> {
-  const url = docsPageUrl(source, pathOrFile);
+  const url = resolveDocsContentUrl(source.docsUrl(), source.docsIndexUrl?.() ?? null, pathOrFile);
   return url === null ? null : source.fetchText(url);
 }
 
+function coverageText(source: DocsSource): string | null {
+  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: OpLike[], requested?: string): ToolOutcome {
+  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: OpLike): string {
   const safety = operationSafety(op);
   const example = op.exampleArguments ?? exampleArgumentsFromSchema(op.inputSchema);
@@ -1306,12 +1633,17 @@ export function searchScore(op: OpLike, query: string): number {
 }
 
 export async function docsSearch(source: DocsSource, query: string, page = 1): Promise<ToolOutcome> {
-  const term = query.toLowerCase();
   const sections: string[] = [];
   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) {
@@ -1322,44 +1654,55 @@ export async function docsSearch(source: DocsSource, query: string, page = 1): P
   } 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: string[] = [];
-    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: DocsSource, page: string): Promise<ToolOutcome> {
   const opMatch = findOperation(source.ops, page);
-  if (opMatch) return { text: referenceText(opMatch), isError: false };
+  const coverage = coverageText(source);
+  if (opMatch) 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 };
 }
 
 /**
@@ -1385,7 +1728,12 @@ export async function callSharedTool(
   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 (!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.",
@@ -1400,52 +1748,3 @@ export async function callSharedTool(
   }
   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: string): Promise<string | null> {
-  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;
-  }
-}