mcp-from-openapi 2.5.1 → 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.5.1",
+  "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/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,40 @@ 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;
+    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/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/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

@@ -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
@@ -224,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.
@@ -231,15 +317,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 +476,26 @@ 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;
+    /**
+     * 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
+     * (`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 +528,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 +581,100 @@ 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
+     * 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
+     * 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)