mcp-from-openapi 2.6.0 → 2.7.0

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/naming-presets.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Naming presets.
+ *
+ * `dottedNaming` produces two-segment `ns.method` tool names whose halves are
+ * valid JavaScript identifiers — the shape code-execution surfaces (FrontMCP
+ * CodeCall) bind as ergonomic namespaces: a tool named `billing.listInvoices`
+ * becomes `await billing.listInvoices({...})` in sandbox code. Names with any
+ * other shape (no dot, or a half that is not an identifier) still work via
+ * `callTool('name', input)` but get no namespace binding.
+ */
+import type { NamingStrategy } from './types';
+/**
+ * Namespace identifiers reserved by FrontMCP CodeCall's sandbox globals —
+ * a namespace equal to one of these would shadow (or be shadowed by) a
+ * sandbox binding, so `dottedNaming` suffixes it with `_`.
+ */
+export declare const CODECALL_RESERVED_NAMESPACES: readonly string[];
+/** Options for the {@link dottedNaming} preset. */
+export interface DottedNamingOptions {
+    /**
+     * Where the namespace half comes from: the operation's first tag, or the
+     * first path segment. `'tag'` falls back to the first path segment when the
+     * operation has no tags, then to `'api'`.
+     * @default 'tag'
+     */
+    namespaceFrom?: 'tag' | 'firstPathSegment';
+    /**
+     * Additional reserved namespace names, merged with
+     * {@link CODECALL_RESERVED_NAMESPACES}.
+     */
+    reservedNamespaces?: string[];
+}
+/**
+ * Naming preset producing two-segment `ns.method` tool names bindable by
+ * code-execution namespaces (e.g. FrontMCP CodeCall's `await ns.method({...})`).
+ *
+ * The namespace half comes from the operation's first tag (or first path
+ * segment); the method half from the operationId (an `x-mcp` family name
+ * override arrives through the operationId argument), falling back to the
+ * HTTP method plus the path. Both halves are sanitized to identifiers, so the
+ * emitted name contains exactly one dot.
+ *
+ * Collision dedup in `generateTools()` appends `_<hash>` to the method half,
+ * which keeps the name namespace-parseable. Hash truncation can remove the
+ * dot when the namespace half alone approaches `maxToolNameLength` (≥ 55
+ * chars at the default cap of 64) — such names remain valid MCP names but
+ * lose namespace binding.
+ */
+export declare function dottedNaming(options?: DottedNamingOptions): NamingStrategy;

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.7.0",
   "description": "Production-ready library for converting OpenAPI specifications into MCP tool definitions",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -49,20 +49,22 @@
     }
   },
   "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"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@swc/core": "~1.5.7",
     "@swc/helpers": "^0.5.18",
     "@swc/jest": "~0.2.38",
     "@types/jest": "^29.5.0",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^24.0.0",
+    "ajv": "^8.17.0",
     "esbuild": "^0.27.2",
     "jest": "^29.7.0",
     "tslib": "^2.8.1",

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/type-signature.d.ts

@@ -0,0 +1,43 @@
+/**
+ * TypeScript call-signature emission.
+ *
+ * Renders a tool's final JSON Schemas (2020-12, post client-target transforms)
+ * as TypeScript type text for code-execution surfaces such as FrontMCP
+ * CodeCall, which present tools as importable typed functions instead of raw
+ * tool JSON. The emitted return type is always the UNWRAPPED OpenAPI response
+ * type — consumers that wrap results (e.g. `{status, ok, data, error}`) must
+ * wrap the type themselves.
+ */
+import type { JsonSchema } from './types';
+/** TypeScript rendering of one tool's call contract. */
+export interface ToolTypeScriptInfo {
+    /**
+     * One-line arrow type with inline anonymous types, e.g.
+     * `(input: { id: string; limit?: number }) => Promise<{ name: string }>`
+     */
+    signature: string;
+    /**
+     * Self-contained declaration text: JSDoc from schema descriptions, named
+     * `<ToolName>Input` / `<ToolName>Output` types, and a `declare function`.
+     */
+    declaration: string;
+}
+/** Options for the type-signature printer. */
+export interface TypeSignatureOptions {
+    /**
+     * Nesting depth beyond which types collapse to `unknown`.
+     * @default 8
+     */
+    maxDepth?: number;
+}
+/**
+ * Derive a PascalCase TypeScript identifier from an MCP tool name
+ * (`[A-Za-z0-9_.-]`). Empty results become `Tool`; a leading digit is
+ * prefixed with `T` (`3d.scan` → `T3dScan`).
+ */
+export declare function toPascalIdentifier(toolName: string): string;
+/**
+ * Render a tool's TypeScript signature and self-contained declaration from
+ * its final (post-transform) schemas. Pure and deterministic.
+ */
+export declare function emitToolTypeScript(toolName: string, description: string | undefined, inputSchema: JsonSchema, outputSchema: JsonSchema | undefined, options?: TypeSignatureOptions): ToolTypeScriptInfo;

package/types.d.ts

@@ -84,6 +84,23 @@ export interface ToolAnnotations {
      */
     openWorldHint?: boolean;
 }
+/**
+ * Tool icon (MCP spec 2025-11-25).
+ */
+export interface ToolIcon {
+    /**
+     * Icon URI (`https:` or `data:`).
+     */
+    src: string;
+    /**
+     * MIME type, e.g. `image/png`.
+     */
+    mimeType?: string;
+    /**
+     * Sizes the icon is available in, e.g. `['48x48', 'any']`.
+     */
+    sizes?: string[];
+}
 /**
  * Main MCP Tool definition generated from OpenAPI.
  *
@@ -111,6 +128,21 @@ export interface McpOpenAPITool<TMeta extends ToolMetadata = ToolMetadata> {
      * precedence).
      */
     annotations?: ToolAnnotations;
+    /**
+     * MCP `_meta` (spec 2025-06-18): namespaced, client-visible metadata.
+     * Contains the `dev.agentfront.openapi/operation` entry when
+     * `GenerateOptions.emitMeta` is set, plus any `meta` object supplied via
+     * the `x-mcp` / `x-frontmcp` extensions (emitted even when the flag is
+     * off). Extension keys under `dev.agentfront.openapi/` are ignored, and
+     * pollution-gadget keys are stripped recursively.
+     */
+    _meta?: Record<string, unknown>;
+    /**
+     * Tool icons (MCP spec 2025-11-25). From `x-frontmcp.icons` /
+     * `x-mcp.icons`, or the document's `info['x-logo']` when
+     * `GenerateOptions.inheritDocumentIcons` is set.
+     */
+    icons?: ToolIcon[];
     /**
      * Combined input schema including all parameters
      * (path, query, header, cookie, body)
@@ -292,6 +324,39 @@ 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;
+    /**
+     * TypeScript rendering of the tool's call contract — present when
+     * `GenerateOptions.emitTypeSignatures` is set. Computed on the FINAL
+     * schemas (after formats, depth truncation, trimming, and client-target
+     * transforms). The return type is the UNWRAPPED response type.
+     */
+    typescript?: import('./type-signature').ToolTypeScriptInfo;
+    /**
+     * Arazzo workflow IR — present only on tools produced by `fromArazzo()`.
+     * When set, `path`/`method` are non-HTTP placeholders
+     * (`arazzo:<workflowId>` / `'post'`); executors must drive requests from
+     * `workflow.steps[*].operation.mapper`, never from this tool's (empty)
+     * top-level mapper.
+     */
+    workflow?: import('./arazzo-types').WorkflowIR;
+}
+/**
+ * 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.
@@ -333,6 +398,14 @@ export interface FrontMcpExtensionData {
         input: Record<string, unknown>;
         output?: unknown;
     }>;
+    /**
+     * MCP `_meta` entries to emit on the tool.
+     */
+    meta?: Record<string, unknown>;
+    /**
+     * Tool icons to emit on the tool.
+     */
+    icons?: ToolIcon[];
 }
 /**
  * Security requirement definition
@@ -461,6 +534,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 +643,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
@@ -628,6 +746,35 @@ export interface GenerateOptions {
      * When used without `resolveFormats`, only custom resolvers are applied.
      */
     formatResolvers?: Record<string, FormatResolver>;
+    /**
+     * Emit a TypeScript rendering of each tool's call contract as
+     * `metadata.typescript = { signature, declaration }`. The signature is a
+     * one-line arrow type with inline anonymous types; the declaration is a
+     * self-contained block with named `<ToolName>Input` / `<ToolName>Output`
+     * types and JSDoc from schema descriptions. Computed on the FINAL schemas
+     * (after format resolution, depth truncation, trimming, and client-target
+     * transforms). The return type is the unwrapped OpenAPI response type —
+     * consumers that wrap results must wrap the type themselves.
+     * @default false
+     */
+    emitTypeSignatures?: boolean;
+    /**
+     * Emit `_meta['dev.agentfront.openapi/operation']` on every tool with the
+     * source operation's coordinates: `{ path, method, operationId?, tags?,
+     * deprecated?, specTitle?, specVersion? }` (reverse-DNS key per MCP `_meta`
+     * conventions). Extension-supplied `meta` (`x-mcp` / `x-frontmcp`) merges
+     * on top and is emitted even when this flag is off.
+     * @default false
+     */
+    emitMeta?: boolean;
+    /**
+     * When an operation has no extension-supplied icons, fall back to the
+     * document's `info['x-logo']` (Redoc convention) as a single icon applied
+     * to every tool. Off by default so one logo doesn't silently inflate all
+     * tool definitions.
+     * @default false
+     */
+    inheritDocumentIcons?: boolean;
 }
 /**
  * A function that enriches a JSON Schema based on its format field.
@@ -639,21 +786,24 @@ export type FormatResolver = (schema: JsonSchema) => JsonSchema;
  */
 export interface NamingStrategy {
     /**
-     * Resolver function for parameter name conflicts
+     * Resolver function for parameter name conflicts.
      * @param paramName - Original parameter name
      * @param location - Parameter location
      * @param index - Index of conflicting parameter (0-based)
      * @returns New parameter name
+     * @default a location-prefix resolver (`headerX_Trace`-style)
      */
-    conflictResolver: (paramName: string, location: ParameterLocation, index: number) => string;
+    conflictResolver?: (paramName: string, location: ParameterLocation, index: number) => string;
     /**
      * Function to generate tool names
      * @param path - OpenAPI path
      * @param method - HTTP method
-     * @param operationId - Operation ID if available
+     * @param operationId - Operation ID if available (an `x-mcp` family name
+     *   override arrives through this argument in place of the operationId)
+     * @param operation - The full operation object (for tag-aware strategies)
      * @returns Tool name
      */
-    toolNameGenerator?: (path: string, method: HTTPMethod, operationId?: string) => string;
+    toolNameGenerator?: (path: string, method: HTTPMethod, operationId?: string, operation?: OperationObject) => string;
 }
 /**
  * Validation result

package/validator.d.ts

@@ -14,6 +14,11 @@ export declare class Validator {
     /**
      * Validate paths
      */
+    /**
+     * Resolve a local `#/components/parameters/<name>` reference (JSON Pointer
+     * tokens decoded). Returns undefined for external or dangling references.
+     */
+    private resolveParameterRef;
     private validatePaths;
     /**
      * Validate an operation