mcp-from-openapi 2.5.1 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Production-ready library for converting OpenAPI specifications into MCP tool definitions",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",

package/parameter-resolver.d.ts

@@ -2,12 +2,23 @@ import type { JSONSchema } from 'zod/v4/core';
 /** JSON Schema type from Zod v4 */
 type JsonSchema = JSONSchema.JSONSchema;
 import type { ParameterMapper, ParameterObject, NamingStrategy, SecurityRequirement } from './types';
+/**
+ * Options controlling parameter resolution behavior
+ */
+export interface ParameterResolverOptions {
+    /**
+     * Include parameter-level and media-type-level example(s) in the
+     * generated input schema (as JSON Schema `examples` arrays).
+     */
+    includeExamples?: boolean;
+}
 /**
  * Resolves parameters and handles naming conflicts
  */
 export declare class ParameterResolver {
     private namingStrategy;
-    constructor(namingStrategy?: NamingStrategy);
+    private includeExamples;
+    constructor(namingStrategy?: NamingStrategy, options?: ParameterResolverOptions);
     /**
      * Default conflict resolver: prefix with location
      */
@@ -15,7 +26,7 @@ export declare class ParameterResolver {
     /**
      * Resolve all parameters for an operation
      */
-    resolve(operation: any, pathParameters?: ParameterObject[], securityRequirements?: SecurityRequirement[], includeSecurityInInput?: boolean): {
+    resolve(operation: any, pathParameters?: ParameterObject[], securityRequirements?: SecurityRequirement[], includeSecurityInInput?: boolean | string[]): {
         inputSchema: JsonSchema;
         mapper: ParameterMapper[];
     };
@@ -36,4 +47,14 @@ export declare class ParameterResolver {
      */
     private processSecurityRequirements;
 }
+/**
+ * Collect concrete example values from OpenAPI `example` / `examples` fields
+ * (parameter or media-type level). The `examples` map wins over the singular
+ * `example` (they are mutually exclusive per OpenAPI); `$ref` entries are
+ * skipped because example refs are not dereferenced into values here.
+ * Returns undefined when nothing usable is present.
+ *
+ * Internal helper shared with ResponseBuilder (not part of the public barrel).
+ */
+export declare function collectExampleValues(example: unknown, examples?: Record<string, unknown> | unknown[]): unknown[] | undefined;
 export {};

package/request-builder.d.ts

@@ -0,0 +1,52 @@
+import type { McpOpenAPITool } from './types';
+/**
+ * Options for {@link buildHttpRequest}.
+ */
+export interface BuildHttpRequestOptions {
+    /**
+     * Base URL for the request. Overrides the tool's `metadata.servers[0].url`.
+     * Must be empty (relative request) or an http/https URL.
+     */
+    baseUrl?: string;
+}
+/**
+ * The composed HTTP request. Pure data — nothing has been sent.
+ */
+export interface BuiltHttpRequest {
+    /** Fully composed URL: base + expanded path + encoded query string */
+    url: string;
+    /** Uppercase HTTP method */
+    method: string;
+    /**
+     * Request headers, including a composed `Cookie` header (when cookie
+     * parameters exist) and `content-type` (when the body is not multipart —
+     * multipart bodies must let the HTTP client set the boundary itself).
+     */
+    headers: Record<string, string>;
+    /** Query parameters as sent (unencoded values, one array per key) */
+    query: Record<string, string[]>;
+    /** Cookie parameters (also folded into the `Cookie` header) */
+    cookies: Record<string, string>;
+    /** Selected request body content type (also in headers, except multipart) */
+    contentType?: string;
+    /**
+     * Serialized body ready for fetch: a JSON/form-urlencoded/text string, a
+     * `FormData` for multipart, the raw value for binary bodies, or undefined.
+     */
+    body?: unknown;
+    /** Structured body value before serialization (object/array/primitive) */
+    rawBody?: unknown;
+}
+/**
+ * Build an HTTP request from a generated tool and its input values — the
+ * mapper applied in full: style/explode serialization (form, spaceDelimited,
+ * pipeDelimited, deepObject, simple, label, matrix), `allowReserved`,
+ * whole-body and binary bodies, JSON / form-urlencoded / multipart / text
+ * serialization, cookies, and header-injection guards.
+ *
+ * Pure function: nothing is sent, no runtime context is consulted. Security
+ * mapper entries are applied only when their value is present in `input`
+ * (with scheme-aware formatting); missing security values never throw —
+ * frameworks resolve credentials separately (see SecurityResolver).
+ */
+export declare function buildHttpRequest(tool: McpOpenAPITool, input: Record<string, unknown>, options?: BuildHttpRequestOptions): BuiltHttpRequest;

package/response-builder.d.ts

@@ -8,6 +8,7 @@ import type { GenerateOptions, ResponsesObject } from './types';
 export declare class ResponseBuilder {
     private preferredStatusCodes;
     private includeAllResponses;
+    private includeExamples;
     constructor(options?: GenerateOptions);
     /**
      * Build output schema from responses

package/schema-builder.d.ts

@@ -110,6 +110,23 @@ export declare class SchemaBuilder {
      * Flatten nested oneOf/anyOf/allOf schemas
      */
     static flatten(schema: JsonSchema, maxDepth?: number): JsonSchema;
+    /**
+     * Truncate a schema tree to a maximum nesting depth.
+     *
+     * The root sits at depth 0; descending into `properties` values, `items`,
+     * `additionalProperties`, composition members (`allOf`/`anyOf`/`oneOf`), or
+     * `not` increments the depth. Nodes at `maxDepth` keep their scalar keywords
+     * (type, description, format, ...) but have their child schemas stripped and
+     * a truncation note appended to the description.
+     */
+    static truncateDepth(schema: JsonSchema, maxDepth: number): JsonSchema;
+    /** Keys whose value is a map of schemas (JSON Schema 2020-12) */
+    private static readonly TRUNCATE_MAP_KEYS;
+    /** Keys whose value is a single schema (or, for `items`, a tuple array) */
+    private static readonly TRUNCATE_SCHEMA_KEYS;
+    /** Keys whose value is an array of schemas */
+    private static readonly TRUNCATE_LIST_KEYS;
+    private static truncateDepthRecursive;
     /**
      * Simplify schema by removing unnecessary fields
      */

package/sdk.d.ts

@@ -0,0 +1,22 @@
+import type { JsonSchema, McpOpenAPITool, ToolAnnotations } from './types';
+/**
+ * A `registerTool`-shaped config for the official MCP TypeScript SDK.
+ * `TSchema` is whatever the schema wrapper returns — the raw `JsonSchema`
+ * when no wrapper is used, or the SDK's wrapped schema type.
+ */
+export interface SdkToolConfig<TSchema = JsonSchema> {
+    title?: string;
+    description: string;
+    inputSchema: TSchema;
+    outputSchema?: TSchema;
+    annotations?: ToolAnnotations;
+}
+/**
+ * Schema wrapper — pass the SDK v2 `fromJsonSchema` here so schemas are
+ * advertised verbatim and validated by the SDK's JSON Schema validator.
+ */
+export interface SdkSchemaWrapper<TSchema> {
+    fromJsonSchema: (schema: JsonSchema) => TSchema;
+}
+export declare function toSdkTool(tool: McpOpenAPITool): [name: string, config: SdkToolConfig];
+export declare function toSdkTool<TSchema>(tool: McpOpenAPITool, wrapper: SdkSchemaWrapper<TSchema>): [name: string, config: SdkToolConfig<TSchema>];

package/types.d.ts

@@ -49,20 +49,68 @@ export declare function isReferenceObject(obj: any): obj is ReferenceObject;
  * Convert OpenAPI schema to JsonSchema
  * Note: OpenAPI 3.0 uses a subset of JSON Schema Draft 4
  * OpenAPI 3.1 uses JSON Schema Draft 2020-12
+ *
+ * Normalizations applied for clean JSON Schema 2020-12 output (MCP's default
+ * dialect since spec revision 2025-11-25):
+ * - OpenAPI 3.0 `nullable: true` -> `type: [..., 'null']` union
+ * - OpenAPI 3.0 boolean `exclusiveMinimum`/`exclusiveMaximum` -> numeric form
+ * - OpenAPI `example` (singular) -> `examples` array (2020-12 keyword)
+ * - OpenAPI-only `xml` metadata is dropped
  */
 export declare function toJsonSchema(schema: SchemaObject | ReferenceObject): JsonSchema;
 /**
- * Main MCP Tool definition generated from OpenAPI
+ * MCP tool annotations — behavior hints for clients (MCP spec 2025-03-26).
+ * Hints are advisory: clients must not treat them as security guarantees.
+ */
+export interface ToolAnnotations {
+    /**
+     * Legacy display-name slot inside annotations. Prefer the tool-level `title`.
+     */
+    title?: string;
+    /**
+     * Tool only reads data, never modifies state.
+     */
+    readOnlyHint?: boolean;
+    /**
+     * Tool may perform destructive updates (delete, overwrite).
+     */
+    destructiveHint?: boolean;
+    /**
+     * Calling repeatedly with the same arguments has no additional effect.
+     */
+    idempotentHint?: boolean;
+    /**
+     * Tool interacts with an open world of external entities.
+     */
+    openWorldHint?: boolean;
+}
+/**
+ * Main MCP Tool definition generated from OpenAPI.
+ *
+ * `TMeta` lets embedding frameworks extend the metadata contract without
+ * casting — e.g. `McpOpenAPITool<ToolMetadata & { adapter: AdapterState }>`.
  */
-export interface McpOpenAPITool {
+export interface McpOpenAPITool<TMeta extends ToolMetadata = ToolMetadata> {
     /**
      * Unique tool name (from operationId or generated)
      */
     name: string;
+    /**
+     * Human-readable display name (MCP `Tool.title`, spec 2025-06-18).
+     * From extension overrides or the operation summary.
+     */
+    title?: string;
     /**
      * Tool description (from operation summary/description)
      */
     description: string;
+    /**
+     * MCP tool annotations. Inferred from HTTP method semantics by default
+     * (see `GenerateOptions.inferAnnotations`) and overridable via the
+     * `x-speakeasy-mcp` / `x-mcp` / `x-frontmcp` extensions (in ascending
+     * precedence).
+     */
+    annotations?: ToolAnnotations;
     /**
      * Combined input schema including all parameters
      * (path, query, header, cookie, body)
@@ -80,7 +128,7 @@ export interface McpOpenAPITool {
     /**
      * Additional metadata about the tool
      */
-    metadata: ToolMetadata;
+    metadata: TMeta;
 }
 /**
  * Maps input schema properties to their actual request locations
@@ -110,10 +158,23 @@ export interface ParameterMapper {
      * Whether to explode arrays/objects
      */
     explode?: boolean;
+    /**
+     * Whether RFC 3986 reserved characters may appear unencoded in the value
+     * (query parameters only, OpenAPI `allowReserved`)
+     */
+    allowReserved?: boolean;
     /**
      * Custom serialization info
      */
     serialization?: SerializationInfo;
+    /**
+     * When true, this input value IS the entire request body — set for
+     * non-object bodies (arrays, primitives, binary) and for `oneOf`/`anyOf`
+     * union bodies that cannot be flattened into named properties. Consumers
+     * building requests must send the value directly as the body instead of
+     * wrapping it in an object keyed by `key`.
+     */
+    wholeBody?: boolean;
     /**
      * Security scheme information (if this is an auth parameter)
      * This allows frameworks to resolve auth from context, env vars, etc.
@@ -129,9 +190,16 @@ export interface SerializationInfo {
      */
     contentType?: string;
     /**
-     * Encoding rules
+     * Encoding rules from the request body's media type (OpenAPI `encoding`).
+     * For a flattened body-property parameter this contains only that
+     * property's entry; for a whole-body parameter it is the full map.
      */
     encoding?: Record<string, EncodingObject>;
+    /**
+     * File-upload marker: the parameter schema declares binary content
+     * (`format: binary`), e.g. a multipart file part or a raw binary body.
+     */
+    binary?: boolean;
 }
 /**
  * Security parameter information for framework-agnostic auth resolution
@@ -231,15 +299,10 @@ export interface ToolMetadata {
  */
 export interface FrontMcpExtensionData {
     /**
-     * Tool annotations for AI behavior hints.
+     * Tool annotations for AI behavior hints (same contract as the tool-level
+     * `annotations` field).
      */
-    annotations?: {
-        title?: string;
-        readOnlyHint?: boolean;
-        destructiveHint?: boolean;
-        idempotentHint?: boolean;
-        openWorldHint?: boolean;
-    };
+    annotations?: ToolAnnotations;
     /**
      * Cache configuration for response caching.
      */
@@ -395,9 +458,18 @@ export interface LoadOptions {
      * Whether to follow HTTP redirects when fetching the spec URL. Each redirect
      * hop is re-validated against the SSRF guard before being followed (a 3xx to
      * an internal target is refused), so following is safe by default.
-     * @default true
+     * @default true (false when `secureDefaults` is set)
      */
     followRedirects?: boolean;
+    /**
+     * Opt into the strictest loading posture in one flag: redirects are not
+     * followed and external `$ref` resolution is disabled entirely
+     * (`refResolution.allowedProtocols: []`) — the right default when loading
+     * untrusted specs. Explicitly-set `followRedirects`/`refResolution` values
+     * still win over the preset.
+     * @default false
+     */
+    secureDefaults?: boolean;
     /**
      * Controls spec-loading security: external `$ref` resolution AND the host
      * policy for the initial spec-URL fetch. By default `file://` is blocked,
@@ -430,6 +502,38 @@ export interface GenerateOptions {
      * Custom filter function
      */
     filterFn?: (operation: OperationWithContext) => boolean;
+    /**
+     * Include only operations carrying at least one of these OpenAPI tags
+     */
+    includeTags?: string[];
+    /**
+     * Exclude operations carrying any of these OpenAPI tags
+     */
+    excludeTags?: string[];
+    /**
+     * Include only these HTTP methods
+     */
+    includeMethods?: HTTPMethod[];
+    /**
+     * Exclude these HTTP methods
+     */
+    excludeMethods?: HTTPMethod[];
+    /**
+     * Include only paths matching at least one of these globs.
+     * `*` matches within a path segment, `**` across segments, `?` one character
+     * (e.g. `/users/*`, `/admin/**`).
+     */
+    includePaths?: string[];
+    /**
+     * Exclude paths matching any of these globs
+     */
+    excludePaths?: string[];
+    /**
+     * Safety switch: include only operations whose effective annotations say
+     * `readOnlyHint: true` (HTTP-method inference merged with extension
+     * overrides, regardless of `inferAnnotations`).
+     */
+    readOnlyOnly?: boolean;
     /**
      * Naming strategy for resolving conflicts
      */
@@ -451,22 +555,63 @@ export interface GenerateOptions {
      */
     includeAllResponses?: boolean;
     /**
-     * Maximum depth for dereferencing schemas
+     * Maximum schema nesting depth retained in generated input/output schemas.
+     * Structures nested deeper than this are truncated: child schemas are
+     * stripped and a truncation note is appended to the node's description.
+     * Clamped to a minimum of 1 so the root schema always keeps its properties.
      * @default 10
      */
     maxSchemaDepth?: number;
     /**
-     * Whether to include examples in schemas
+     * Include OpenAPI parameter-level and media-type-level `example`/`examples`
+     * values in generated schemas (as JSON Schema `examples` arrays). These
+     * override schema-level examples where present. Schema-level `example`
+     * keywords are always normalized to `examples` regardless of this option.
      * @default false
      */
     includeExamples?: boolean;
     /**
-     * Whether to include security requirements as input parameters
-     * If false, security is only in mapper (frameworks resolve from context/env/etc.)
-     * If true, security is added to inputSchema as explicit parameters
+     * Whether to include security requirements as input parameters.
+     * - `false` (default): security lives only in the mapper (frameworks
+     *   resolve credentials from context/env/vaults)
+     * - `true`: every security scheme is added to inputSchema as a required
+     *   string property
+     * - `string[]`: only the named schemes appear in inputSchema; the rest stay
+     *   mapper-only (all schemes are always present in the mapper)
      * @default false
      */
-    includeSecurityInInput?: boolean;
+    includeSecurityInInput?: boolean | string[];
+    /**
+     * Target client schema dialect. Every MCP client accepts a different JSON
+     * Schema subset; setting a target applies the transforms that make the
+     * generated input/output schemas valid for it: `strict` (safe baseline —
+     * local $refs inlined, arrays get `items`, root compositions collapsed),
+     * `claude` (= strict), `openai` (strict + closed objects), `gemini`
+     * (strict + all unions collapsed + unsupported formats demoted).
+     * See `applyClientTarget` for standalone use.
+     */
+    target?: import('./client-targets').ClientTarget;
+    /**
+     * Infer MCP tool annotations from HTTP method semantics:
+     * GET/HEAD/OPTIONS/TRACE -> read-only + idempotent; PUT/DELETE ->
+     * destructive + idempotent; POST/PATCH -> destructive, not idempotent.
+     * `openWorldHint` defaults to false (a known API backend is a closed world).
+     * Extension overrides (`x-speakeasy-mcp`, `x-mcp`, `x-frontmcp`) are applied
+     * on top of the inferred values regardless of this flag.
+     * @default true
+     */
+    inferAnnotations?: boolean;
+    /**
+     * Maximum length for generated tool names. Names longer than this are
+     * truncated and given a short hash suffix derived from the full name, so
+     * truncated names stay unique and stable across regenerations.
+     *
+     * MCP tool names may be 1-128 characters of `[A-Za-z0-9_.-]` (values above
+     * 128 are clamped to 128). The default of 64 matches the strictest common
+     * client limits (Claude / Bedrock cap tool names at 64 characters).
+     * @default 64
+     */
+    maxToolNameLength?: number;
     /**
      * Enable built-in format-to-schema resolution.
      * Enriches schemas with concrete constraints (patterns, descriptions, min/max)