mcp-from-openapi 2.6.0 → 2.6.1

package/lint.d.ts

@@ -0,0 +1,33 @@
+import type { OpenAPIDocument } from './types';
+export type LintSeverity = 'error' | 'warning' | 'info';
+/**
+ * One agent-readiness finding. `path` names the operation (`GET /users`);
+ * `hint` says how to fix it — in the spec or via generate options/overlays.
+ */
+export interface LintFinding {
+    severity: LintSeverity;
+    /** Stable kebab-case finding code */
+    code: string;
+    message: string;
+    path: string;
+    hint?: string;
+}
+export interface LintResult {
+    /** Sorted: errors first, then warnings, then infos; by path within each */
+    findings: LintFinding[];
+    counts: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+}
+/** Query-parameter names that read as pagination controls (shared with response hints) */
+export declare const PAGINATION_PARAM: RegExp;
+/**
+ * Lint an OpenAPI document for agent-readiness: the spec-quality gaps that
+ * measurably degrade tool-calling accuracy (missing operationIds, absent or
+ * vague descriptions, unpaginated list endpoints, oversized schemas, missing
+ * examples). Small spec fixes routinely take tool-call success rates from
+ * mediocre to near-perfect — each finding carries a concrete hint.
+ */
+export declare function lintDocument(document: OpenAPIDocument): LintResult;

package/overlay.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A single Overlay action (OpenAPI Overlay Specification 1.0.0).
+ */
+export interface OverlayAction {
+    /** JSONPath expression selecting the nodes to act on (see supported subset below) */
+    target: string;
+    /** Human note; ignored by the processor */
+    description?: string;
+    /**
+     * Value merged into each matched node: objects deep-merge, arrays append
+     * the value, primitives are replaced.
+     */
+    update?: unknown;
+    /** Remove each matched node from its parent instead of updating */
+    remove?: boolean;
+}
+/**
+ * An OpenAPI Overlay document. Applied to specs at load time (before
+ * dereferencing and validation), overlays keep spec curation — agent-tuned
+ * descriptions, `x-mcp` flags — in a small separate file that survives every
+ * regeneration of the source spec.
+ */
+export interface OverlayDocument {
+    /** Overlay Specification version (1.x) */
+    overlay: string;
+    info?: {
+        title?: string;
+        version?: string;
+    };
+    /** URL of the spec this overlay targets; informational here */
+    extends?: string;
+    actions: OverlayAction[];
+}
+/**
+ * Apply an OpenAPI Overlay 1.0 document to a spec, returning a NEW document
+ * (the input is never mutated). Actions run in order; targets that match
+ * nothing are skipped silently, per the Overlay specification.
+ *
+ * Update semantics: object targets deep-merge the update, array targets
+ * append it, primitive targets are replaced. `remove: true` deletes matched
+ * nodes (array elements are spliced, preserving order).
+ */
+export declare function applyOverlay<T extends object>(document: T, overlay: OverlayDocument): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "Production-ready library for converting OpenAPI specifications into MCP tool definitions",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -49,9 +49,9 @@
     }
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^15.3.5",
+    "@apidevtools/json-schema-ref-parser": "^15.5.1",
     "openapi-types": "^12.1.3",
-    "yaml": "^2.8.3"
+    "yaml": "^2.9.0"
   },
   "peerDependencies": {
     "zod": "^4.0.0"

package/schema-builder.d.ts

@@ -127,6 +127,23 @@ export declare class SchemaBuilder {
     /** Keys whose value is an array of schemas */
     private static readonly TRUNCATE_LIST_KEYS;
     private static truncateDepthRecursive;
+    private static walkCopy;
+    /**
+     * 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: JsonSchema, max: number): JsonSchema;
+    /**
+     * Cap every description in the schema tree to `maxLength` characters,
+     * truncating with an ellipsis.
+     */
+    static capDescriptions(schema: JsonSchema, maxLength: number): JsonSchema;
+    /**
+     * Remove every `examples` array from the schema tree (a token-budget
+     * trimming step — validation keywords are untouched).
+     */
+    static stripExamples(schema: JsonSchema): JsonSchema;
     /**
      * Simplify schema by removing unnecessary fields
      */

package/token-report.d.ts

@@ -0,0 +1,65 @@
+import type { McpOpenAPITool } from './types';
+/**
+ * Per-tool token estimate for the definition a client ships to the model.
+ */
+export interface ToolTokenEstimate {
+    name: string;
+    /** Estimated tokens for the full advertised definition */
+    tokens: number;
+}
+/**
+ * Context-budget report for a generated tool set.
+ */
+export interface ToolSetReport {
+    toolCount: number;
+    /** Sum of all per-tool estimates */
+    estimatedTokens: number;
+    /** Every tool, heaviest first */
+    perTool: ToolTokenEstimate[];
+    /** Human-readable budget warnings (empty when the set is comfortably sized) */
+    warnings: string[];
+}
+/**
+ * Thresholds for {@link analyzeToolSet} warnings.
+ */
+export interface AnalyzeToolSetOptions {
+    /**
+     * Estimated-token budget for the whole tool set before a warning fires.
+     * ~1,000 tokens per tool is typical; ecosystem guidance flags pain beyond
+     * ~10K tokens of definitions.
+     * @default 10000
+     */
+    tokenBudget?: number;
+    /**
+     * Tool count beyond which model selection accuracy measurably degrades
+     * (public evaluations put the cliff at ~30-40 tools).
+     * @default 40
+     */
+    maxRecommendedTools?: number;
+    /**
+     * Per-tool estimate that marks a single tool as disproportionately heavy.
+     * @default 2000
+     */
+    perToolWarning?: number;
+}
+/**
+ * Estimate the context-window cost of ONE tool definition — the fields a
+ * client advertises to the model (name, title, description, annotations,
+ * input/output schemas), serialized as JSON.
+ *
+ * The estimate is `ceil(chars / 4)` — the common BPE average for JSON-heavy
+ * English text. It is a sizing signal for curation decisions, not a
+ * tokenizer: real counts vary by model within roughly ±20%.
+ */
+export declare function estimateToolTokens(tool: McpOpenAPITool): number;
+/**
+ * Analyze a generated tool set's context-window bill: per-tool estimates
+ * (heaviest first), the total, and curation warnings when the set crosses
+ * the thresholds where agent accuracy is known to degrade.
+ *
+ * ```ts
+ * const report = analyzeToolSet(await generator.generateTools());
+ * report.warnings.forEach((w) => console.warn(w));
+ * ```
+ */
+export declare function analyzeToolSet(tools: McpOpenAPITool[], options?: AnalyzeToolSetOptions): ToolSetReport;

package/types.d.ts

@@ -292,6 +292,24 @@ export interface ToolMetadata {
      * Contains annotations, cache config, codecall config, tags, etc.
      */
     frontmcp?: FrontMcpExtensionData;
+    /**
+     * Response-shaping signals for consumers that paginate, truncate, or cache:
+     * present only when there is something to know.
+     */
+    responseHints?: ResponseHints;
+}
+/**
+ * Detected response-shaping signals. Clients cap tool results hard (Claude
+ * Code: 25K tokens) — these hints tell a consumer WHICH tools need paging or
+ * truncation before the first oversized response happens.
+ */
+export interface ResponseHints {
+    /** The success response contains an array without `maxItems` */
+    unboundedArray?: boolean;
+    /** Query parameters that look like pagination controls (limit, cursor, ...) */
+    paginationParams?: string[];
+    /** Unbounded array AND no pagination controls: truncate or shape server-side */
+    largeResponseRisk?: boolean;
 }
 /**
  * FrontMCP extension data extracted from x-frontmcp in OpenAPI operations.
@@ -461,6 +479,14 @@ export interface LoadOptions {
      * @default true (false when `secureDefaults` is set)
      */
     followRedirects?: boolean;
+    /**
+     * OpenAPI Overlay 1.0 document(s) applied to the spec at load time, BEFORE
+     * dereferencing and validation, in order. Overlays keep curation
+     * (agent-tuned descriptions, `x-mcp` flags) in a separate file that
+     * survives spec regeneration. See `applyOverlay` for the supported
+     * JSONPath subset.
+     */
+    overlays?: import('./overlay').OverlayDocument | import('./overlay').OverlayDocument[];
     /**
      * Opt into the strictest loading posture in one flag: redirects are not
      * followed and external `$ref` resolution is disabled entirely
@@ -562,6 +588,43 @@ export interface GenerateOptions {
      * @default 10
      */
     maxSchemaDepth?: number;
+    /**
+     * How the tool description is assembled from the operation:
+     * - `summaryOnly` (default): summary, else description, else `METHOD path`
+     * - `descriptionOnly`: description, else summary, else `METHOD path`
+     * - `combined`: summary + blank line + description (whichever exist)
+     * - `full`: summary, description, `Operation: <id>`, and `METHOD path`
+     * An `x-mcp`-family description override always wins over the strategy.
+     * @default 'summaryOnly'
+     */
+    descriptionStrategy?: 'summaryOnly' | 'descriptionOnly' | 'combined' | 'full';
+    /**
+     * Append a compact `Returns: ...` line to each tool description,
+     * summarizing the output schema (top-level shape and field names) — cheap
+     * context that measurably improves result-handling without shipping the
+     * whole response schema in prose.
+     * @default false
+     */
+    appendResponseSummary?: boolean;
+    /**
+     * Limit object nodes in generated schemas to their first N properties
+     * (declaration order). Dropped properties are pruned from `required` and
+     * counted in a description note. The ROOT of `inputSchema` is exempt: its
+     * properties are mapper-backed parameters, so the cap applies inside each
+     * parameter subtree (and throughout output schemas). Unset = no limit.
+     */
+    maxProperties?: number;
+    /**
+     * Cap every description in generated schemas to N characters (ellipsis
+     * truncation). Unset = no cap.
+     */
+    maxDescriptionLength?: number;
+    /**
+     * Remove all `examples` arrays from generated schemas — a token-budget
+     * trimming step that leaves validation keywords untouched.
+     * @default false
+     */
+    stripExamples?: boolean;
     /**
      * Include OpenAPI parameter-level and media-type-level `example`/`examples`
      * values in generated schemas (as JSON Schema `examples` arrays). These