mcp-from-openapi 2.6.0 → 2.6.1

package/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   LoadError: () => LoadError,
   OpenAPIToolError: () => OpenAPIToolError,
   OpenAPIToolGenerator: () => OpenAPIToolGenerator,
+  OverlayError: () => OverlayError,
   ParameterResolver: () => ParameterResolver,
   ParseError: () => ParseError,
   RequestBuildError: () => RequestBuildError,
@@ -46,7 +47,9 @@ __export(index_exports, {
   SsrfError: () => SsrfError,
   ValidationError: () => ValidationError,
   Validator: () => Validator,
+  analyzeToolSet: () => analyzeToolSet,
   applyClientTarget: () => applyClientTarget,
+  applyOverlay: () => applyOverlay,
   assertUrlSafe: () => assertUrlSafe,
   buildHttpRequest: () => buildHttpRequest,
   collapseNestedUnions: () => collapseNestedUnions,
@@ -57,12 +60,14 @@ __export(index_exports, {
   demoteFormats: () => demoteFormats,
   enforceClosedObjects: () => enforceClosedObjects,
   ensureArrayItems: () => ensureArrayItems,
+  estimateToolTokens: () => estimateToolTokens,
   extractExtensionOverrides: () => extractExtensionOverrides,
   inferAnnotationsFromMethod: () => inferAnnotationsFromMethod,
   inlineLocalRefs: () => inlineLocalRefs,
   isBlockedAddress: () => isBlockedAddress,
   isBlockedHostname: () => isBlockedHostname,
   isReferenceObject: () => isReferenceObject,
+  lintDocument: () => lintDocument,
   normalizeSsrfOptions: () => normalizeSsrfOptions,
   requireAllProperties: () => requireAllProperties,
   resolveExtensionEnabled: () => resolveExtensionEnabled,
@@ -1005,6 +1010,96 @@ var SchemaBuilder = class {
     }
     return copy;
   }
+  // Copy-on-walk over every structural keyword (same key groups as
+  // truncateDepth): `visit` transforms each node top-down and must return a
+  // new node when it changes anything.
+  static walkCopy(node, visit, seen = /* @__PURE__ */ new Map()) {
+    if (!node || typeof node !== "object") return node;
+    const existing = seen.get(node);
+    if (existing) return existing;
+    const copy = visit({ ...node });
+    seen.set(node, copy);
+    for (const key of this.TRUNCATE_MAP_KEYS) {
+      const value = copy[key];
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const mapped = {};
+        for (const [name, sub] of Object.entries(value)) {
+          mapped[name] = this.walkCopy(sub, visit, seen);
+        }
+        copy[key] = mapped;
+      }
+    }
+    for (const key of this.TRUNCATE_SCHEMA_KEYS) {
+      const value = copy[key];
+      if (Array.isArray(value)) {
+        copy[key] = value.map((item) => this.walkCopy(item, visit, seen));
+      } else if (value !== null && typeof value === "object") {
+        copy[key] = this.walkCopy(value, visit, seen);
+      }
+    }
+    for (const key of this.TRUNCATE_LIST_KEYS) {
+      const value = copy[key];
+      if (Array.isArray(value)) {
+        copy[key] = value.map((member) => this.walkCopy(member, visit, seen));
+      }
+    }
+    return copy;
+  }
+  /**
+   * Limit every object node to its first `max` properties (declaration
+   * order). Dropped properties are pruned from `required` and counted in a
+   * note appended to the node's description.
+   */
+  static limitProperties(schema, max) {
+    const bound = Number.isFinite(max) ? Math.max(1, Math.floor(max)) : Number.MAX_SAFE_INTEGER;
+    return this.walkCopy(schema, (node) => {
+      const properties = node.properties;
+      if (!properties || typeof properties !== "object") return node;
+      const entries = Object.entries(properties);
+      if (entries.length <= bound) return node;
+      const kept = entries.slice(0, bound);
+      const keptNames = new Set(kept.map(([name]) => name));
+      const dropped = entries.length - bound;
+      const note = `[${dropped} additional propert${dropped === 1 ? "y" : "ies"} omitted: exceeds maxProperties]`;
+      const next = { ...node, properties: Object.fromEntries(kept) };
+      if (Array.isArray(node.required)) {
+        const required = node.required.filter((name) => keptNames.has(String(name)));
+        if (required.length > 0) {
+          next.required = required;
+        } else {
+          delete next.required;
+        }
+      }
+      next.description = node.description ? `${node.description} ${note}` : note;
+      return next;
+    });
+  }
+  /**
+   * Cap every description in the schema tree to `maxLength` characters,
+   * truncating with an ellipsis.
+   */
+  static capDescriptions(schema, maxLength) {
+    const bound = Number.isFinite(maxLength) ? Math.max(1, Math.floor(maxLength)) : Number.MAX_SAFE_INTEGER;
+    return this.walkCopy(schema, (node) => {
+      if (typeof node.description === "string" && node.description.length > bound) {
+        return { ...node, description: `${node.description.slice(0, bound - 1)}\u2026` };
+      }
+      return node;
+    });
+  }
+  /**
+   * Remove every `examples` array from the schema tree (a token-budget
+   * trimming step — validation keywords are untouched).
+   */
+  static stripExamples(schema) {
+    return this.walkCopy(schema, (node) => {
+      if ("examples" in node) {
+        const { examples: _examples, ...rest } = node;
+        return rest;
+      }
+      return node;
+    });
+  }
   /**
    * Simplify schema by removing unnecessary fields
    */
@@ -1445,6 +1540,557 @@ function applyClientTarget(schema, target) {
   return result;
 }
 
+// src/errors.ts
+var OpenAPIToolError = class extends Error {
+  context;
+  constructor(message, context) {
+    super(message);
+    this.name = this.constructor.name;
+    this.context = context;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var LoadError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var SsrfError = class extends LoadError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var ParseError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var ValidationError = class extends OpenAPIToolError {
+  errors;
+  constructor(message, context) {
+    super(message, context);
+    this.errors = context?.["errors"];
+  }
+};
+var GenerationError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var OverlayError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var RequestBuildError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var SchemaError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+
+// src/overlay.ts
+function parsePath(path) {
+  if (typeof path !== "string" || !path.startsWith("$")) {
+    throw new OverlayError(`Overlay target must be a JSONPath starting with '$'; received '${String(path)}'`, {
+      target: path
+    });
+  }
+  const segments = [];
+  let rest = path.slice(1);
+  while (rest.length > 0) {
+    let recursive = false;
+    if (rest.startsWith("..")) {
+      recursive = true;
+      rest = rest.slice(2);
+      const bare = rest.match(/^([A-Za-z_][\w-]*)/);
+      if (bare) {
+        segments.push({ kind: "child", name: bare[1], recursive });
+        rest = rest.slice(bare[0].length);
+        continue;
+      }
+    } else if (rest.startsWith(".")) {
+      rest = rest.slice(1);
+      if (rest.startsWith("*")) {
+        segments.push({ kind: "wildcard", recursive });
+        rest = rest.slice(1);
+        continue;
+      }
+      const bare = rest.match(/^([A-Za-z_][\w-]*)/);
+      if (bare) {
+        segments.push({ kind: "child", name: bare[1], recursive });
+        rest = rest.slice(bare[0].length);
+        continue;
+      }
+      throw new OverlayError(`Invalid JSONPath segment after '.' in '${path}'`, { target: path });
+    }
+    if (!rest.startsWith("[")) {
+      throw new OverlayError(`Invalid JSONPath segment at '${rest}' in '${path}'`, { target: path });
+    }
+    const bracket = matchBracket(rest, path);
+    const inner = bracket.inner.trim();
+    rest = bracket.rest;
+    if (inner === "*") {
+      segments.push({ kind: "wildcard", recursive });
+    } else if (/^-?\d+$/.test(inner)) {
+      segments.push({ kind: "index", index: parseInt(inner, 10), recursive });
+    } else if (/^'.*'$/.test(inner) || /^".*"$/.test(inner)) {
+      segments.push({ kind: "child", name: inner.slice(1, -1), recursive });
+    } else if (inner.startsWith("?(") && inner.endsWith(")")) {
+      segments.push(parseFilter(inner.slice(2, -1).trim(), path, recursive));
+    } else {
+      throw new OverlayError(`Unsupported JSONPath selector '[${inner}]' in '${path}'`, { target: path });
+    }
+  }
+  return segments;
+}
+function matchBracket(input, fullPath) {
+  let quote = null;
+  let depth = 0;
+  for (let i = 1; i < input.length; i++) {
+    const char = input[i];
+    if (quote) {
+      if (char === quote) quote = null;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === "[") {
+      depth++;
+    } else if (char === "]") {
+      if (depth === 0) {
+        return { inner: input.slice(1, i), rest: input.slice(i + 1) };
+      }
+      depth--;
+    }
+  }
+  throw new OverlayError(`Unterminated '[' selector in '${fullPath}'`, { target: fullPath });
+}
+function parseFilter(expr, path, recursive) {
+  const match = expr.match(/^@(?:\.([A-Za-z_][\w-]*)|\['([^']*)'\]|\["([^"]*)"\])\s*(?:(==|!=)\s*(.+))?$/);
+  if (!match) {
+    throw new OverlayError(`Unsupported filter expression '?(${expr})' in '${path}'`, { target: path });
+  }
+  const field = match[1] ?? match[2] ?? match[3];
+  const op = match[4];
+  if (!op) {
+    return { kind: "filter", field, op: "exists", recursive };
+  }
+  const raw = match[5].trim();
+  let literal;
+  if (/^'.*'$/.test(raw) || /^".*"$/.test(raw)) {
+    literal = raw.slice(1, -1);
+  } else if (/^-?\d+(\.\d+)?$/.test(raw)) {
+    literal = parseFloat(raw);
+  } else if (raw === "true" || raw === "false") {
+    literal = raw === "true";
+  } else {
+    throw new OverlayError(`Unsupported filter literal '${raw}' in '${path}'`, { target: path });
+  }
+  return { kind: "filter", field, op, literal, recursive };
+}
+function isContainer(value) {
+  return value !== null && typeof value === "object";
+}
+var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function descendants(match) {
+  const result = [];
+  const walk = (node) => {
+    if (!isContainer(node)) return;
+    if (Array.isArray(node)) {
+      node.forEach((item, index) => {
+        result.push({ parent: node, key: index, value: item });
+        walk(item);
+      });
+    } else {
+      for (const [key, value] of Object.entries(node)) {
+        result.push({ parent: node, key, value });
+        walk(value);
+      }
+    }
+  };
+  walk(match.value);
+  return result;
+}
+function dedupeMatches(matches) {
+  const seen = /* @__PURE__ */ new Map();
+  const result = [];
+  for (const match of matches) {
+    let keys = seen.get(match.parent);
+    if (!keys) {
+      keys = /* @__PURE__ */ new Set();
+      seen.set(match.parent, keys);
+    }
+    if (keys.has(match.key)) continue;
+    keys.add(match.key);
+    result.push(match);
+  }
+  return result;
+}
+function applySegment(matches, segment) {
+  const scope = segment.recursive ? matches.flatMap((m) => [m, ...descendants(m)]) : matches;
+  const next = [];
+  for (const match of scope) {
+    const node = match.value;
+    switch (segment.kind) {
+      case "child": {
+        if (isContainer(node) && !Array.isArray(node) && !UNSAFE_KEYS.has(segment.name) && Object.prototype.hasOwnProperty.call(node, segment.name)) {
+          next.push({ parent: node, key: segment.name, value: node[segment.name] });
+        }
+        break;
+      }
+      case "wildcard": {
+        if (Array.isArray(node)) {
+          node.forEach((item, index) => next.push({ parent: node, key: index, value: item }));
+        } else if (isContainer(node)) {
+          for (const [key, value] of Object.entries(node)) {
+            next.push({ parent: node, key, value });
+          }
+        }
+        break;
+      }
+      case "index": {
+        if (Array.isArray(node)) {
+          const index = segment.index < 0 ? node.length + segment.index : segment.index;
+          if (index >= 0 && index < node.length) {
+            next.push({ parent: node, key: index, value: node[index] });
+          }
+        }
+        break;
+      }
+      case "filter": {
+        const members = Array.isArray(node) ? node.map((item, index) => ({ parent: node, key: index, value: item })) : isContainer(node) ? Object.entries(node).map(([key, value]) => ({ parent: node, key, value })) : [];
+        for (const member of members) {
+          if (!isContainer(member.value) || Array.isArray(member.value)) continue;
+          const fieldValue = member.value[segment.field];
+          const keep = segment.op === "exists" ? fieldValue !== void 0 : segment.op === "==" ? fieldValue === segment.literal : fieldValue !== segment.literal;
+          if (keep) next.push(member);
+        }
+        break;
+      }
+    }
+  }
+  return next;
+}
+function deepMerge(target, update) {
+  for (const [key, value] of Object.entries(update)) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+    const existing = target[key];
+    if (isContainer(value) && !Array.isArray(value) && isContainer(existing) && !Array.isArray(existing)) {
+      deepMerge(existing, value);
+    } else {
+      target[key] = value;
+    }
+  }
+}
+function applyOverlay(document, overlay) {
+  if (!overlay || typeof overlay !== "object" || !Array.isArray(overlay.actions)) {
+    throw new OverlayError("Overlay document must have an actions array", {});
+  }
+  const result = JSON.parse(JSON.stringify(document));
+  for (const [index, action] of overlay.actions.entries()) {
+    if (!action || typeof action !== "object" || typeof action.target !== "string") {
+      throw new OverlayError(`Overlay action #${index} must have a string target`, { index });
+    }
+    if (action.update === void 0 && action.remove !== true) {
+      throw new OverlayError(`Overlay action #${index} needs 'update' or 'remove: true'`, {
+        index,
+        target: action.target
+      });
+    }
+    const segments = parsePath(action.target);
+    let matches = [{ parent: null, key: null, value: result }];
+    for (const segment of segments) {
+      matches = dedupeMatches(applySegment(matches, segment));
+    }
+    if (action.remove === true) {
+      const arrayRemovals = /* @__PURE__ */ new Map();
+      for (const match of matches) {
+        if (match.parent === null) {
+          throw new OverlayError("Overlay cannot remove the document root", { target: action.target });
+        }
+        if (Array.isArray(match.parent)) {
+          const indices = arrayRemovals.get(match.parent) ?? [];
+          indices.push(match.key);
+          arrayRemovals.set(match.parent, indices);
+        } else {
+          delete match.parent[match.key];
+        }
+      }
+      for (const [parent, indices] of arrayRemovals) {
+        for (const index2 of indices.sort((a, b) => b - a)) {
+          parent.splice(index2, 1);
+        }
+      }
+      continue;
+    }
+    for (const match of matches) {
+      const node = match.value;
+      if (Array.isArray(node)) {
+        node.push(action.update);
+      } else if (isContainer(node) && isContainer(action.update) && !Array.isArray(action.update)) {
+        deepMerge(node, action.update);
+      } else {
+        if (match.parent === null) {
+          throw new OverlayError("Overlay cannot replace the document root with a non-object", {
+            target: action.target
+          });
+        }
+        match.parent[match.key] = action.update;
+      }
+    }
+  }
+  return result;
+}
+
+// src/lint.ts
+var METHODS = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+var PAGINATION_PARAM = /^(page|limit|offset|cursor|per_page|pagesize|page_size|after|before)$/i;
+var DEEP_SCHEMA_THRESHOLD = 8;
+var WIDE_SCHEMA_THRESHOLD = 30;
+function measureSchema(node, seen = /* @__PURE__ */ new Map()) {
+  if (node === null || typeof node !== "object") {
+    return { depth: 0, widestObject: 0, hasArray: false };
+  }
+  if (seen.has(node)) {
+    return seen.get(node) ?? { depth: 0, widestObject: 0, hasArray: false };
+  }
+  seen.set(node, null);
+  const record = node;
+  let childDepth = 0;
+  let widestObject = 0;
+  let hasArray = record["type"] === "array" || Array.isArray(record["type"]) && record["type"].includes("array");
+  const visit = (child) => {
+    const shape2 = measureSchema(child, seen);
+    childDepth = Math.max(childDepth, shape2.depth);
+    widestObject = Math.max(widestObject, shape2.widestObject);
+    hasArray = hasArray || shape2.hasArray;
+  };
+  const properties = record["properties"];
+  if (properties && typeof properties === "object") {
+    widestObject = Math.max(widestObject, Object.keys(properties).length);
+    for (const child of Object.values(properties)) visit(child);
+  }
+  for (const key of ["items", "additionalProperties", "not", "contentSchema"]) {
+    const value = record[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) visit(value);
+    if (Array.isArray(value)) value.forEach(visit);
+  }
+  for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+    const value = record[key];
+    if (Array.isArray(value)) value.forEach(visit);
+  }
+  const shape = { depth: childDepth + 1, widestObject, hasArray };
+  seen.set(node, shape);
+  return shape;
+}
+function schemaHasExample(node, seen = /* @__PURE__ */ new Set()) {
+  if (node === null || typeof node !== "object" || seen.has(node)) return false;
+  seen.add(node);
+  const record = node;
+  if (record["example"] !== void 0 || record["examples"] !== void 0) return true;
+  const properties = record["properties"];
+  if (properties && typeof properties === "object") {
+    if (Object.values(properties).some((child) => schemaHasExample(child, seen))) return true;
+  }
+  for (const key of ["items", "additionalProperties", "not", "contentSchema"]) {
+    const value = record[key];
+    if (value && typeof value === "object" && !Array.isArray(value) && schemaHasExample(value, seen)) return true;
+    if (Array.isArray(value) && value.some((item) => schemaHasExample(item, seen))) return true;
+  }
+  for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+    const value = record[key];
+    if (Array.isArray(value) && value.some((member) => schemaHasExample(member, seen))) return true;
+  }
+  return false;
+}
+function hasAnyExample(content) {
+  if (!content) return false;
+  return Object.values(content).some((media) => {
+    if (!media || typeof media !== "object") return false;
+    const record = media;
+    if (record["example"] !== void 0 || record["examples"] !== void 0) return true;
+    return schemaHasExample(record["schema"]);
+  });
+}
+function lintDocument(document) {
+  const findings = [];
+  const operationIds = /* @__PURE__ */ new Map();
+  const paths = document.paths ?? {};
+  for (const [pathStr, pathItem] of Object.entries(paths).sort(([a], [b]) => a < b ? -1 : 1)) {
+    if (!pathItem || "$ref" in pathItem) continue;
+    const pathLevelParameters = (pathItem["parameters"] ?? []).filter(
+      (param) => !isReferenceObject(param)
+    );
+    for (const method of METHODS) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+      const label = `${method.toUpperCase()} ${pathStr}`;
+      if (!operation.operationId) {
+        findings.push({
+          severity: "warning",
+          code: "missing-operation-id",
+          message: "Operation has no operationId; the tool name will be generated from the method and path.",
+          path: label,
+          hint: "Add a short, action-oriented operationId (it becomes the tool name)."
+        });
+      } else {
+        const existing = operationIds.get(operation.operationId) ?? [];
+        existing.push(label);
+        operationIds.set(operation.operationId, existing);
+        if (operation.operationId.length > 64) {
+          findings.push({
+            severity: "info",
+            code: "long-operation-id",
+            message: `operationId '${operation.operationId.slice(0, 40)}\u2026' exceeds 64 characters and will be truncated with a hash suffix.`,
+            path: label,
+            hint: "Shorten the operationId below 64 characters to keep tool names readable."
+          });
+        }
+      }
+      const prose = `${operation.summary ?? ""} ${operation.description ?? ""}`.trim();
+      if (prose.length === 0) {
+        findings.push({
+          severity: "warning",
+          code: "missing-description",
+          message: "Operation has neither summary nor description; the model only sees the method and path.",
+          path: label,
+          hint: "Describe WHEN to use this operation and what it returns (or patch it in with an overlay)."
+        });
+      } else if (prose.length < 20) {
+        findings.push({
+          severity: "info",
+          code: "vague-description",
+          message: `Operation description is only ${prose.length} characters \u2014 likely too vague for reliable tool selection.`,
+          path: label,
+          hint: "Expand the description with the use case and key parameters."
+        });
+      }
+      const parameters = [
+        ...pathLevelParameters,
+        ...(operation.parameters ?? []).filter((param) => !isReferenceObject(param))
+      ];
+      const undescribed = parameters.filter((param) => !param.description).map((param) => param.name);
+      if (undescribed.length > 0) {
+        findings.push({
+          severity: "info",
+          code: "missing-parameter-description",
+          message: `Parameter(s) without description: ${undescribed.join(", ")}.`,
+          path: label,
+          hint: "Describe each parameter \u2014 models mis-fill undocumented arguments."
+        });
+      }
+      const responses = operation.responses ?? {};
+      const successCodes = Object.keys(responses).filter((code) => /^2(\d\d|XX)$/i.test(code));
+      if (successCodes.length === 0 && !responses["default"]) {
+        findings.push({
+          severity: "warning",
+          code: "missing-success-response",
+          message: "Operation declares no 2xx or default response; no output schema can be generated.",
+          path: label,
+          hint: "Add the success response with its schema."
+        });
+      }
+      let responseShape = { depth: 0, widestObject: 0, hasArray: false };
+      for (const code of [...successCodes, "default"]) {
+        const response = responses[code];
+        if (!response || typeof response !== "object" || isReferenceObject(response)) continue;
+        const content = response["content"];
+        if (!content) continue;
+        for (const media of Object.values(content)) {
+          const schema = media && typeof media === "object" ? media["schema"] : void 0;
+          const shape = measureSchema(schema);
+          responseShape = {
+            depth: Math.max(responseShape.depth, shape.depth),
+            widestObject: Math.max(responseShape.widestObject, shape.widestObject),
+            hasArray: responseShape.hasArray || shape.hasArray
+          };
+        }
+      }
+      if (method === "get" && responseShape.hasArray) {
+        const hasPagination = parameters.some((param) => param.in === "query" && PAGINATION_PARAM.test(param.name));
+        if (!hasPagination) {
+          findings.push({
+            severity: "warning",
+            code: "unpaginated-list",
+            message: "GET returns an array but declares no pagination parameter \u2014 responses can blow past client result limits (Claude Code caps tool results at 25K tokens).",
+            path: label,
+            hint: "Add limit/cursor/page parameters, or shape responses at the server."
+          });
+        }
+      }
+      const body = operation.requestBody;
+      const bodyContent = body && !isReferenceObject(body) ? body.content : void 0;
+      let requestShape = { depth: 0, widestObject: 0, hasArray: false };
+      for (const media of Object.values(bodyContent ?? {})) {
+        const schema = media && typeof media === "object" ? media["schema"] : void 0;
+        const shape = measureSchema(schema);
+        requestShape = {
+          depth: Math.max(requestShape.depth, shape.depth),
+          widestObject: Math.max(requestShape.widestObject, shape.widestObject),
+          hasArray: requestShape.hasArray || shape.hasArray
+        };
+      }
+      const maxDepth = Math.max(requestShape.depth, responseShape.depth);
+      if (maxDepth > DEEP_SCHEMA_THRESHOLD) {
+        findings.push({
+          severity: "warning",
+          code: "deep-schema",
+          message: `Schema nesting reaches depth ${maxDepth} (threshold ${DEEP_SCHEMA_THRESHOLD}) \u2014 deep schemas cost tokens and reduce accuracy.`,
+          path: label,
+          hint: "Flatten the schema, or bound generation with maxSchemaDepth."
+        });
+      }
+      const maxWidth = Math.max(requestShape.widestObject, responseShape.widestObject);
+      if (maxWidth > WIDE_SCHEMA_THRESHOLD) {
+        findings.push({
+          severity: "info",
+          code: "wide-schema",
+          message: `An object schema declares ${maxWidth} properties (threshold ${WIDE_SCHEMA_THRESHOLD}).`,
+          path: label,
+          hint: "Split the payload, or bound generation with maxProperties."
+        });
+      }
+      if (bodyContent && !hasAnyExample(bodyContent)) {
+        findings.push({
+          severity: "info",
+          code: "missing-request-example",
+          message: "Request body has no example \u2014 examples measurably improve complex-parameter accuracy.",
+          path: label,
+          hint: "Add a media-type example (and enable includeExamples), or patch one in with an overlay."
+        });
+      }
+    }
+  }
+  for (const [operationId, labels] of operationIds) {
+    if (labels.length > 1) {
+      findings.push({
+        severity: "error",
+        code: "duplicate-operation-id",
+        message: `operationId '${operationId}' is used by ${labels.length} operations: ${labels.join(", ")}.`,
+        path: labels[0],
+        hint: "Make operationIds unique \u2014 duplicates force hash-suffixed tool names."
+      });
+    }
+  }
+  const rank = { error: 0, warning: 1, info: 2 };
+  findings.sort(
+    (a, b) => rank[a.severity] - rank[b.severity] || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0) || (a.code < b.code ? -1 : 1)
+  );
+  return {
+    findings,
+    counts: {
+      error: findings.filter((f) => f.severity === "error").length,
+      warning: findings.filter((f) => f.severity === "warning").length,
+      info: findings.filter((f) => f.severity === "info").length
+    }
+  };
+}
+
 // src/validator.ts
 var Validator = class {
   /**
@@ -1576,7 +2222,7 @@ var Validator = class {
     if (operation.parameters) {
       this.validateParameters(operation.parameters, path, method, errors, warnings);
     }
-    const pathParams = path.match(/\{([^}]+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
+    const pathParams = path.match(/\{([^{}]+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
     const definedPathParams = new Set(
       operation.parameters?.filter((p) => p.in === "path").map((p) => p.name) ?? []
     );
@@ -1636,56 +2282,6 @@ var Validator = class {
   }
 };
 
-// src/errors.ts
-var OpenAPIToolError = class extends Error {
-  context;
-  constructor(message, context) {
-    super(message);
-    this.name = this.constructor.name;
-    this.context = context;
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-  }
-};
-var LoadError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-var SsrfError = class extends LoadError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-var ParseError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-var ValidationError = class extends OpenAPIToolError {
-  errors;
-  constructor(message, context) {
-    super(message, context);
-    this.errors = context?.["errors"];
-  }
-};
-var GenerationError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-var RequestBuildError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-var SchemaError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-
 // src/format-resolver.ts
 var BUILTIN_FORMAT_RESOLVERS = {
   // String formats
@@ -2084,6 +2680,103 @@ function applySecureDefaults(options) {
     }
   };
 }
+function hasUnboundedArray(node, seen = /* @__PURE__ */ new Set()) {
+  if (node === null || typeof node !== "object" || seen.has(node)) return false;
+  seen.add(node);
+  const record = node;
+  const type = record["type"];
+  const isArray = type === "array" || Array.isArray(type) && type.includes("array");
+  if (isArray && record["maxItems"] === void 0) return true;
+  const children = [];
+  const properties = record["properties"];
+  if (properties && typeof properties === "object") children.push(...Object.values(properties));
+  for (const key of ["items", "additionalProperties", "contentSchema"]) {
+    const value = record[key];
+    if (Array.isArray(value)) children.push(...value);
+    else if (value && typeof value === "object") children.push(value);
+  }
+  for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+    if (Array.isArray(record[key])) children.push(...record[key]);
+  }
+  return children.some((child) => hasUnboundedArray(child, seen));
+}
+function detectResponseHints(outputSchema, mapper) {
+  const paginationParams = [
+    ...new Set(mapper.filter((m) => m.type === "query" && !m.security && PAGINATION_PARAM.test(m.key)).map((m) => m.key))
+  ];
+  const unboundedArray = outputSchema !== void 0 && hasUnboundedArray(outputSchema);
+  if (!unboundedArray && paginationParams.length === 0) return void 0;
+  return {
+    ...unboundedArray && { unboundedArray: true },
+    ...paginationParams.length > 0 && { paginationParams },
+    ...unboundedArray && paginationParams.length === 0 && { largeResponseRisk: true }
+  };
+}
+function composeDescription(operation, method, pathStr, strategy) {
+  const fallback = `${method.toUpperCase()} ${pathStr}`;
+  const summary = operation.summary?.trim();
+  const description = operation.description?.trim();
+  switch (strategy) {
+    case "descriptionOnly":
+      return description || summary || fallback;
+    case "combined":
+      if (summary && description && summary !== description) {
+        return `${summary}
+
+${description}`;
+      }
+      return summary || description || fallback;
+    case "full": {
+      const parts = [];
+      if (summary) parts.push(summary);
+      if (description && description !== summary) parts.push(description);
+      if (operation.operationId) parts.push(`Operation: ${operation.operationId}`);
+      parts.push(fallback);
+      return parts.join("\n\n");
+    }
+    default:
+      return summary || description || fallback;
+  }
+}
+function propertyNames(schema, cap = 8) {
+  const properties = schema["properties"];
+  if (!properties || typeof properties !== "object") return "";
+  const names = Object.keys(properties);
+  const listed = names.slice(0, cap).join(", ");
+  return names.length > cap ? `${listed}, \u2026` : listed;
+}
+function summarizeOutputSchema(schema) {
+  const record = schema;
+  const variants = record["oneOf"];
+  if (Array.isArray(variants) && variants.length > 0) {
+    const first = variants[0];
+    const firstSummary = first && typeof first === "object" ? summarizeOutputSchema(first) : void 0;
+    return firstSummary ? `${firstSummary} (${variants.length} response variants)` : void 0;
+  }
+  const type = record["type"];
+  if (type === "object" || type === void 0 && record["properties"]) {
+    const names = propertyNames(record);
+    return names ? `object with fields: ${names}` : "object";
+  }
+  if (type === "array") {
+    const items = record["items"];
+    if (items && typeof items === "object" && !Array.isArray(items)) {
+      const itemRecord = items;
+      if (itemRecord["type"] === "object" || itemRecord["properties"]) {
+        const names = propertyNames(itemRecord);
+        return names ? `array of objects with fields: ${names}` : "array of objects";
+      }
+      if (typeof itemRecord["type"] === "string") {
+        return `array of ${itemRecord["type"]}`;
+      }
+    }
+    return "array";
+  }
+  if (typeof type === "string" && type !== "null") {
+    return type;
+  }
+  return void 0;
+}
 function globToRegExp(glob) {
   let pattern = "^";
   for (let i = 0; i < glob.length; i++) {
@@ -2106,6 +2799,13 @@ function globToRegExp(glob) {
 function matchesAnyGlob(path, globs) {
   return globs.some((glob) => globToRegExp(glob).test(path));
 }
+function trimUnderscores(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value[start] === "_") start++;
+  while (end > start && value[end - 1] === "_") end--;
+  return value.slice(start, end);
+}
 function fnv1aHex(input) {
   let hash = 2166136261;
   for (let i = 0; i < input.length; i++) {
@@ -2116,7 +2816,7 @@ function fnv1aHex(input) {
 }
 function normalizeToolName(raw, maxLength, fallbackSeed) {
   let hashSeed = raw;
-  let name = raw.replace(/[^A-Za-z0-9_.-]/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  let name = trimUnderscores(raw.replace(/[^A-Za-z0-9_.-]/g, "_").replace(/_+/g, "_"));
   if (name.length === 0) {
     hashSeed = fallbackSeed;
     name = `tool_${fnv1aHex(fallbackSeed)}`;
@@ -2149,8 +2849,15 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       validate: options.validate ?? true,
       followRedirects: options.followRedirects ?? true,
       refResolution: options.refResolution ?? {},
-      secureDefaults: options.secureDefaults ?? false
+      secureDefaults: options.secureDefaults ?? false,
+      overlays: options.overlays
     };
+    if (this.options.overlays) {
+      const overlays = Array.isArray(this.options.overlays) ? this.options.overlays : [this.options.overlays];
+      for (const overlay of overlays) {
+        this.document = applyOverlay(this.document, overlay);
+      }
+    }
   }
   /**
    * Create generator from a URL
@@ -2180,7 +2887,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       }
       return new _OpenAPIToolGenerator(document, options);
     } catch (error) {
-      if (error instanceof LoadError) {
+      if (error instanceof LoadError || error instanceof OverlayError) {
         throw error;
       }
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -2213,6 +2920,9 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       }
       return new _OpenAPIToolGenerator(document, options);
     } catch (error) {
+      if (error instanceof OverlayError) {
+        throw error;
+      }
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new LoadError(`Failed to load OpenAPI spec from file: ${errorMessage}`, {
         filePath,
@@ -2228,6 +2938,9 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       const document = yaml.parse(yamlString);
       return new _OpenAPIToolGenerator(document, options);
     } catch (error) {
+      if (error instanceof OverlayError) {
+        throw error;
+      }
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new ParseError(`Failed to parse YAML: ${errorMessage}`, {
         originalError: error
@@ -2254,6 +2967,16 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     const validator = new Validator();
     return validator.validate(this.document);
   }
+  /**
+   * Lint the loaded document for agent-readiness (missing operationIds,
+   * vague descriptions, unpaginated lists, oversized schemas, ...). Runs
+   * after overlays and dereferencing so findings reflect what tools would
+   * actually be generated from.
+   */
+  async lint() {
+    await this.initialize(false);
+    return lintDocument(this.getDocument());
+  }
   // NOTE: internal/private-address blocking + IPv4-mapped-IPv6 decoding now live
   // in `ssrf.ts` (`isBlockedHostname` / `isBlockedAddress` / `decodeIpv4MappedIpv6`),
   // shared by the spec-URL fetch (`fromURL`) and the `$ref` resolver below, and
@@ -2391,7 +3114,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   /**
    * Initialize the generator (dereference if needed, then validate)
    */
-  async initialize() {
+  async initialize(runValidation = this.options.validate) {
     if (this.options.dereference && !this.dereferencedDocument) {
       const cloned = JSON.parse(JSON.stringify(this.document));
       if (!_OpenAPIToolGenerator.hasExternalRefs(cloned)) {
@@ -2409,7 +3132,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
         }
       }
     }
-    if (this.options.validate) {
+    if (runValidation) {
       const validator = new Validator();
       const documentToValidate = this.dereferencedDocument ?? this.document;
       const result = await validator.validate(documentToValidate);
@@ -2507,7 +3230,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     const outputSchema = responseBuilder.build(operation.responses);
     const overrides = extractExtensionOverrides(operation);
     const name = this.generateToolName(pathStr, method, overrides.name ?? operation.operationId, options);
-    const description = overrides.description ?? (operation.summary || operation.description || `${method.toUpperCase()} ${pathStr}`);
+    const description = overrides.description ?? composeDescription(operation, method, pathStr, options.descriptionStrategy ?? "summaryOnly");
     const title = overrides.title ?? operation.summary;
     const inferred = options.inferAnnotations !== false ? inferAnnotationsFromMethod(method.toLowerCase()) : void 0;
     const annotations = inferred || overrides.annotations ? { ...inferred, ...overrides.annotations } : void 0;
@@ -2524,16 +3247,57 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     if (resolvedOutputSchema) {
       resolvedOutputSchema = SchemaBuilder.truncateDepth(resolvedOutputSchema, maxSchemaDepth);
     }
+    const applyTrim = (schema, isInputRoot) => {
+      let trimmed = schema;
+      if (options.stripExamples) trimmed = SchemaBuilder.stripExamples(trimmed);
+      if (options.maxDescriptionLength !== void 0) {
+        trimmed = SchemaBuilder.capDescriptions(trimmed, options.maxDescriptionLength);
+      }
+      if (options.maxProperties !== void 0) {
+        if (isInputRoot) {
+          const properties = trimmed.properties;
+          if (properties && typeof properties === "object") {
+            const limited = {};
+            for (const [key, value] of Object.entries(properties)) {
+              limited[key] = SchemaBuilder.limitProperties(value, options.maxProperties);
+            }
+            trimmed = { ...trimmed, properties: limited };
+          }
+        } else {
+          trimmed = SchemaBuilder.limitProperties(trimmed, options.maxProperties);
+        }
+      }
+      return trimmed;
+    };
+    if (options.stripExamples || options.maxProperties !== void 0 || options.maxDescriptionLength !== void 0) {
+      resolvedInputSchema = applyTrim(resolvedInputSchema, true);
+      if (resolvedOutputSchema) {
+        resolvedOutputSchema = applyTrim(resolvedOutputSchema, false);
+      }
+    }
     if (options.target) {
       resolvedInputSchema = applyClientTarget(resolvedInputSchema, options.target);
       if (resolvedOutputSchema) {
         resolvedOutputSchema = applyClientTarget(resolvedOutputSchema, options.target);
       }
     }
+    const responseHints = detectResponseHints(resolvedOutputSchema, mapper);
+    if (responseHints) {
+      metadata.responseHints = responseHints;
+    }
+    let finalDescription = description;
+    if (options.appendResponseSummary && resolvedOutputSchema) {
+      const summary = summarizeOutputSchema(resolvedOutputSchema);
+      if (summary) {
+        finalDescription = `${finalDescription}
+
+Returns: ${summary}`;
+      }
+    }
     return {
       name,
       ...title !== void 0 && { title },
-      description,
+      description: finalDescription,
       ...annotations && { annotations },
       inputSchema: resolvedInputSchema,
       outputSchema: resolvedOutputSchema,
@@ -2609,7 +3373,9 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     } else if (operationId) {
       rawName = operationId;
     } else {
-      const sanitized = path.replace(/\{([^}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+      const sanitized = trimUnderscores(
+        path.replace(/\{([^{}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_")
+      );
       rawName = `${method}_${sanitized}`;
     }
     return normalizeToolName(
@@ -2824,7 +3590,7 @@ var SecurityResolver = class {
   resolveDigestAuth(context) {
     const digest = context.digest;
     if (!digest) return void 0;
-    const quoted = (v) => String(v).replace(/[\r\n]/g, "").replace(/"/g, '\\"');
+    const quoted = (v) => String(v).replace(/[\r\n]/g, "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
     const token = (v) => String(v).replace(/[\r\n",]/g, "");
     const parts = [
       `username="${quoted(digest.username)}"`,
@@ -3285,6 +4051,44 @@ function toSdkTool(tool, wrapper) {
     }
   ];
 }
+
+// src/token-report.ts
+function estimateToolTokens(tool) {
+  const advertised = {
+    name: tool.name,
+    ...tool.title !== void 0 && { title: tool.title },
+    description: tool.description,
+    ...tool.annotations !== void 0 && { annotations: tool.annotations },
+    inputSchema: tool.inputSchema,
+    ...tool.outputSchema !== void 0 && { outputSchema: tool.outputSchema }
+  };
+  return Math.ceil(JSON.stringify(advertised).length / 4);
+}
+function analyzeToolSet(tools, options = {}) {
+  const tokenBudget = options.tokenBudget ?? 1e4;
+  const maxRecommendedTools = options.maxRecommendedTools ?? 40;
+  const perToolWarning = options.perToolWarning ?? 2e3;
+  const perTool = tools.map((tool) => ({ name: tool.name, tokens: estimateToolTokens(tool) })).sort((a, b) => b.tokens - a.tokens || (a.name < b.name ? -1 : 1));
+  const estimatedTokens = perTool.reduce((sum, entry) => sum + entry.tokens, 0);
+  const warnings = [];
+  if (tools.length > maxRecommendedTools) {
+    warnings.push(
+      `${tools.length} tools exceeds the ~${maxRecommendedTools}-tool range where model selection accuracy degrades \u2014 curate with filters (tags, paths, readOnlyOnly) or split into focused servers.`
+    );
+  }
+  if (estimatedTokens > tokenBudget) {
+    warnings.push(
+      `Estimated ${estimatedTokens} tokens of tool definitions exceeds the ${tokenBudget}-token budget \u2014 trim schemas (maxSchemaDepth, maxProperties) or reduce the tool count.`
+    );
+  }
+  const heavy = perTool.filter((entry) => entry.tokens > perToolWarning);
+  if (heavy.length > 0) {
+    warnings.push(
+      `${heavy.length} tool(s) exceed ${perToolWarning} tokens each (${heavy.slice(0, 3).map((entry) => `${entry.name}: ~${entry.tokens}`).join(", ")}${heavy.length > 3 ? ", \u2026" : ""}) \u2014 consider schema trimming for these.`
+    );
+  }
+  return { toolCount: tools.length, estimatedTokens, perTool, warnings };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BLOCKED_HOSTNAMES,
@@ -3293,6 +4097,7 @@ function toSdkTool(tool, wrapper) {
   LoadError,
   OpenAPIToolError,
   OpenAPIToolGenerator,
+  OverlayError,
   ParameterResolver,
   ParseError,
   RequestBuildError,
@@ -3303,7 +4108,9 @@ function toSdkTool(tool, wrapper) {
   SsrfError,
   ValidationError,
   Validator,
+  analyzeToolSet,
   applyClientTarget,
+  applyOverlay,
   assertUrlSafe,
   buildHttpRequest,
   collapseNestedUnions,
@@ -3314,12 +4121,14 @@ function toSdkTool(tool, wrapper) {
   demoteFormats,
   enforceClosedObjects,
   ensureArrayItems,
+  estimateToolTokens,
   extractExtensionOverrides,
   inferAnnotationsFromMethod,
   inlineLocalRefs,
   isBlockedAddress,
   isBlockedHostname,
   isReferenceObject,
+  lintDocument,
   normalizeSsrfOptions,
   requireAllProperties,
   resolveExtensionEnabled,