mcp-from-openapi 2.6.0 → 2.7.0

package/README.md

@@ -2,10 +2,14 @@
 
 > Convert OpenAPI specifications into MCP tool definitions with automatic parameter conflict resolution
 
-[![npm version](https://badge.fury.io/js/mcp-from-openapi.svg)](https://www.npmjs.com/package/mcp-from-openapi)
+[![npm version](https://img.shields.io/npm/v/mcp-from-openapi.svg)](https://www.npmjs.com/package/mcp-from-openapi)
+[![npm downloads](https://img.shields.io/npm/dm/mcp-from-openapi.svg)](https://www.npmjs.com/package/mcp-from-openapi)
+[![CI](https://github.com/agentfront/mcp-from-openapi/actions/workflows/push.yml/badge.svg)](https://github.com/agentfront/mcp-from-openapi/actions/workflows/push.yml)
+[![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/agentfront/mcp-from-openapi/actions/workflows/push.yml)
+[![CodeQL](https://github.com/agentfront/mcp-from-openapi/actions/workflows/codeql.yml/badge.svg)](https://github.com/agentfront/mcp-from-openapi/actions/workflows/codeql.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/license/apache-2-0)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
+[![node](https://img.shields.io/node/v/mcp-from-openapi.svg)](https://nodejs.org/)
 
 ## What This Solves
 
@@ -52,6 +56,8 @@ Now you know exactly how to build the HTTP request.
 
 - **Built-in Request Builder** -- `buildHttpRequest()` applies the full OpenAPI serialization table (form/deepObject/pipeDelimited queries, label/matrix paths, multipart, binary, `wholeBody`) so you never hand-write request assembly
 - **Client Compatibility Targets** -- `target: 'claude' | 'openai' | 'gemini' | 'strict'` emits schemas each client actually accepts (inlined refs, closed objects, collapsed unions, demoted formats)
+- **Context-Budget Reports** -- `analyzeToolSet()` estimates the token bill per tool and warns at the thresholds where agent accuracy degrades
+- **Overlays & Lint** -- apply [OpenAPI Overlay](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/curation.md) curation files at load time; `lint()` flags the spec gaps that hurt tool-calling accuracy
 - **Curation-Grade Filtering** -- Filter by tag, method, path glob (`/admin/**`), operationId, a `readOnlyOnly` safety switch, and `x-mcp` extension flags with root < path < operation precedence
 - **Smart Parameter Handling** -- Automatic conflict detection and resolution across path, query, header, cookie, and body; `allOf` bodies flatten, union and binary bodies map cleanly (`wholeBody`, `binary` markers)
 - **Complete Schemas** -- Input schema combines all parameters; output schema from responses (with oneOf unions); clean JSON Schema 2020-12 output (`nullable` unions, normalized `examples`)
@@ -146,6 +152,11 @@ for (const tool of await generator.generateTools({ target: "claude" })) {
 | [Parameter Conflicts](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/parameter-conflicts.md) | How conflict detection and resolution works                       |
 | [Request Builder](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/request-builder.md)         | `buildHttpRequest` — full OpenAPI parameter serialization         |
 | [Client Targets](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/client-targets.md)           | Per-client schema dialects (Claude, OpenAI, Gemini)               |
+| [Curation](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/curation.md)                       | Token budgets, overlays, lint, trimming, response hints           |
+| [Type Signatures](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/type-signatures.md)         | TypeScript call contracts for code-execution surfaces             |
+| [Modern MCP Fields](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/modern-mcp-fields.md)     | Tool `_meta`, icons, `x-mcp-header`, elicitation descriptors      |
+| [Arazzo Workflows](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/arazzo.md)                 | fromArazzo() — Arazzo 1.0 workflows as consolidated MCP tools     |
+| [Tested Examples](https://github.com/agentfront/mcp-from-openapi/tree/main/examples)                        | Runnable examples, each executed as an e2e test on every CI run   |
 | [Response Schemas](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/response-schemas.md)       | Output schemas, status codes, oneOf unions                        |
 | [Annotations & Extensions](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/annotations.md)    | Tool title, annotation inference, `x-mcp` extension family        |
 | [Security](https://github.com/agentfront/mcp-from-openapi/blob/main/docs/security.md)                       | SecurityResolver, all auth types, custom resolvers                |
@@ -167,7 +178,18 @@ for (const tool of await generator.generateTools({ target: "claude" })) {
 
 ## Contributing
 
-Contributions are welcome! Please see our [issues page](https://github.com/agentfront/mcp-from-openapi/issues).
+Contributions are welcome! Start with the
+[contributing guide](https://github.com/agentfront/mcp-from-openapi/blob/main/CONTRIBUTING.md);
+this project follows the
+[Contributor Covenant](https://github.com/agentfront/mcp-from-openapi/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and feature requests go through the
+[issue templates](https://github.com/agentfront/mcp-from-openapi/issues/new/choose).
+
+## Security
+
+Report vulnerabilities privately — see the
+[security policy](https://github.com/agentfront/mcp-from-openapi/blob/main/SECURITY.md).
+When loading untrusted specs, use `secureDefaults: true`.
 
 ## Related Projects
 

package/annotations.d.ts

@@ -1,4 +1,4 @@
-import type { HTTPMethod, OperationObject, ToolAnnotations } from './types';
+import type { HTTPMethod, OperationObject, ToolAnnotations, ToolIcon } from './types';
 /**
  * Tool-level overrides read from the `x-mcp` extension family on an operation.
  */
@@ -25,6 +25,15 @@ export interface ExtensionToolOverrides {
      * Annotation overrides, merged field-by-field over inferred values.
      */
     annotations?: ToolAnnotations;
+    /**
+     * MCP `_meta` entries supplied by the extension (merged key-by-key across
+     * layers, emitted on the tool's `_meta` even when `emitMeta` is off).
+     */
+    meta?: Record<string, unknown>;
+    /**
+     * Tool icons supplied by the extension (later layers replace wholesale).
+     */
+    icons?: ToolIcon[];
 }
 /**
  * Default MCP tool annotations per HTTP method, derived from HTTP semantics
@@ -34,6 +43,12 @@ export interface ExtensionToolOverrides {
  * from a spec target one known API backend, a closed world.
  */
 export declare function inferAnnotationsFromMethod(method: HTTPMethod): ToolAnnotations;
+/**
+ * Whether an icon source URI matches the documented `ToolIcon.src` scheme
+ * contract (`https:` or `data:` only, case-insensitive). Shared by extension
+ * icon sanitization and the generator's `info['x-logo']` inheritance.
+ */
+export declare function isAllowedIconSrc(src: string): boolean;
 /**
  * Resolve whether an operation is enabled for tool generation, honoring the
  * `x-mcp` extension at every level with harsha-compatible precedence:

package/arazzo-expressions.d.ts

@@ -0,0 +1,19 @@
+import type { ExpressionValueIR, PayloadExpressionIR, RuntimeExpressionAST } from './arazzo-types';
+/**
+ * Parse a runtime expression into its structured form. Throws `ArazzoError`
+ * (with the document path in `context.path`) on any grammar violation.
+ */
+export declare function parseRuntimeExpression(raw: string, docPath?: string): RuntimeExpressionAST;
+/**
+ * Interpret a step/parameter value: non-strings are literals; strings that
+ * start with a known expression root must parse as expressions; strings with
+ * embedded `{$...}` become templates; everything else is a literal (`"$50"`
+ * has no known root and stays literal).
+ */
+export declare function parseExpressionValue(value: unknown, docPath?: string): ExpressionValueIR;
+/**
+ * Walk a request-body payload and record every string that parses to an
+ * expression or template, keyed by its RFC 6901 pointer (`''` = the payload
+ * itself is the value).
+ */
+export declare function collectPayloadExpressions(payload: unknown, docPath?: string): PayloadExpressionIR[];

package/arazzo-types.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Arazzo 1.0 document and workflow-IR type definitions.
+ *
+ * The document types cover the subset of the Arazzo Specification 1.0
+ * (https://spec.openapis.org/arazzo/v1.0.0.html) that `fromArazzo()` reads.
+ * The IR types describe the pure, JSON-serializable workflow representation
+ * embedded on `metadata.workflow` — executors drive HTTP from it and never
+ * need a second spec pass. This library never executes steps or evaluates
+ * criteria.
+ */
+import type { HTTPMethod, JsonSchema, ParameterMapper, SchemaObject, SecurityRequirement, ServerInfo } from './types';
+/** Arazzo `info` object. */
+export interface ArazzoInfo {
+    title: string;
+    summary?: string;
+    description?: string;
+    version: string;
+}
+/** A source description entry (`sourceDescriptions[]`). */
+export interface ArazzoSourceDescription {
+    /** Unique name matching `[A-Za-z0-9_-]+`. */
+    name: string;
+    /** URL/location of the source document — never fetched by this library. */
+    url: string;
+    type?: 'openapi' | 'arazzo';
+}
+/** Root Arazzo 1.0 document. */
+export interface ArazzoDocument {
+    /** Version string matching `1.0.x`. */
+    arazzo: string;
+    info: ArazzoInfo;
+    sourceDescriptions: ArazzoSourceDescription[];
+    workflows: ArazzoWorkflow[];
+    components?: ArazzoComponents;
+}
+/** A workflow (`workflows[]`). */
+export interface ArazzoWorkflow {
+    /** Unique id matching `[A-Za-z0-9_-]+`. */
+    workflowId: string;
+    summary?: string;
+    description?: string;
+    /** JSON Schema for workflow inputs; may `$ref` into `#/components/inputs`. */
+    inputs?: SchemaObject;
+    dependsOn?: string[];
+    steps: ArazzoStep[];
+    successActions?: Array<ArazzoSuccessAction | ArazzoReusableObject>;
+    failureActions?: Array<ArazzoFailureAction | ArazzoReusableObject>;
+    /** Output name → runtime expression. */
+    outputs?: Record<string, string>;
+    parameters?: Array<ArazzoParameter | ArazzoReusableObject>;
+}
+/** A step: exactly one of `operationId` / `operationPath` / `workflowId`. */
+export interface ArazzoStep {
+    /** Unique id within the workflow, matching `[A-Za-z0-9_-]+`. */
+    stepId: string;
+    description?: string;
+    operationId?: string;
+    operationPath?: string;
+    workflowId?: string;
+    parameters?: Array<ArazzoParameter | ArazzoReusableObject>;
+    requestBody?: ArazzoRequestBody;
+    successCriteria?: ArazzoCriterion[];
+    onSuccess?: Array<ArazzoSuccessAction | ArazzoReusableObject>;
+    onFailure?: Array<ArazzoFailureAction | ArazzoReusableObject>;
+    /** Output name → runtime expression. */
+    outputs?: Record<string, string>;
+}
+/** A parameter applied to a step or workflow. */
+export interface ArazzoParameter {
+    name: string;
+    /** Required for operation steps; forbidden on workflowId steps. */
+    in?: 'path' | 'query' | 'header' | 'cookie';
+    /** Literal value or runtime expression (string form). */
+    value: unknown;
+}
+/** Step request body. */
+export interface ArazzoRequestBody {
+    contentType?: string;
+    /** Literal payload; strings may embed `{$...}` template expressions. */
+    payload?: unknown;
+    replacements?: ArazzoPayloadReplacement[];
+}
+/** A targeted replacement inside `payload`. */
+export interface ArazzoPayloadReplacement {
+    /** JSON Pointer (or XPath for XML payloads) into the payload. */
+    target: string;
+    value: unknown;
+}
+/** Criterion `type`: shorthand or the Criterion Expression Type Object. */
+export type ArazzoCriterionType = 'simple' | 'regex' | 'jsonpath' | 'xpath' | {
+    type: 'jsonpath' | 'xpath';
+    version: string;
+};
+/** A success criterion — this library never evaluates conditions. */
+export interface ArazzoCriterion {
+    /** Runtime expression providing evaluation context (required for non-simple types). */
+    context?: string;
+    condition: string;
+    type?: ArazzoCriterionType;
+}
+/** `onSuccess` / workflow `successActions` entry. */
+export interface ArazzoSuccessAction {
+    name: string;
+    type: 'end' | 'goto';
+    workflowId?: string;
+    stepId?: string;
+    criteria?: ArazzoCriterion[];
+}
+/** `onFailure` / workflow `failureActions` entry. */
+export interface ArazzoFailureAction {
+    name: string;
+    type: 'end' | 'retry' | 'goto';
+    workflowId?: string;
+    stepId?: string;
+    /** Seconds to wait before retrying. */
+    retryAfter?: number;
+    retryLimit?: number;
+    criteria?: ArazzoCriterion[];
+}
+/** Reusable Object: a `$components.…` reference with an optional value override. */
+export interface ArazzoReusableObject {
+    /** Runtime expression, e.g. `$components.parameters.page`. */
+    reference: string;
+    /** Overrides the referenced parameter's `value`. */
+    value?: unknown;
+}
+/** Arazzo `components`. */
+export interface ArazzoComponents {
+    inputs?: Record<string, SchemaObject>;
+    parameters?: Record<string, ArazzoParameter>;
+    successActions?: Record<string, ArazzoSuccessAction>;
+    failureActions?: Record<string, ArazzoFailureAction>;
+}
+/** Root of a parsed runtime expression. */
+export type RuntimeExpressionType = 'url' | 'method' | 'statusCode' | 'request' | 'response' | 'message' | 'inputs' | 'outputs' | 'steps' | 'workflows' | 'sourceDescriptions' | 'components';
+/**
+ * Structured form of an Arazzo runtime expression. `raw` always preserves
+ * the exact original text.
+ */
+export interface RuntimeExpressionAST {
+    type: RuntimeExpressionType;
+    raw: string;
+    /** Dot segments after the root: `$steps.s1.outputs.id` → `['s1','outputs','id']`. */
+    path: string[];
+    /** For `request` / `response` roots: which part is referenced. */
+    source?: 'header' | 'query' | 'path' | 'body';
+    /** Header/query/path parameter name for `request` / `response` source refs. */
+    name?: string;
+    /** JSON Pointer after `#` on body refs: `$response.body#/items/0/id` → `/items/0/id`. */
+    pointer?: string;
+}
+/** A value that is a literal, a whole expression, or a `{$...}`-templated string. */
+export type ExpressionValueIR = {
+    kind: 'literal';
+    value: unknown;
+} | {
+    kind: 'expression';
+    expression: RuntimeExpressionAST;
+} | {
+    kind: 'template';
+    raw: string;
+    parts: Array<string | RuntimeExpressionAST>;
+};
+/** A parameter in the IR — components inlined, value parsed. */
+export interface StepParameterIR {
+    name: string;
+    in?: 'path' | 'query' | 'header' | 'cookie';
+    value: ExpressionValueIR;
+}
+/** A criterion in the IR — the condition is raw text, never evaluated. */
+export interface CriterionIR {
+    context?: RuntimeExpressionAST;
+    condition: string;
+    type: 'simple' | 'regex' | 'jsonpath' | 'xpath';
+    /** Present when the document used a Criterion Expression Type Object. */
+    version?: string;
+}
+/** A flow action in the IR (success or failure family). */
+export interface ActionIR {
+    name: string;
+    kind: 'success' | 'failure';
+    type: 'end' | 'goto' | 'retry';
+    workflowId?: string;
+    stepId?: string;
+    retryAfter?: number;
+    retryLimit?: number;
+    criteria?: CriterionIR[];
+}
+/** An expression located inside a request payload (RFC 6901 pointer). */
+export interface PayloadExpressionIR {
+    /** `''` means the whole payload is the expression value. */
+    pointer: string;
+    value: ExpressionValueIR;
+}
+/** A `replacements[]` entry in the IR. */
+export interface PayloadReplacementIR {
+    target: string;
+    value: ExpressionValueIR;
+}
+/** Step request body in the IR: verbatim payload + located substitutions. */
+export interface StepRequestBodyIR {
+    contentType?: string;
+    payload?: unknown;
+    payloadExpressions?: PayloadExpressionIR[];
+    replacements?: PayloadReplacementIR[];
+}
+/**
+ * Embedded essentials of a step's resolved operation — the subset of the
+ * per-operation tool an executor needs (`mapper` feeds `buildHttpRequest`).
+ */
+export interface StepOperationIR {
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    mapper: ParameterMapper[];
+    security?: SecurityRequirement[];
+    servers?: ServerInfo[];
+}
+interface StepIRBase {
+    stepId: string;
+    description?: string;
+    parameters?: StepParameterIR[];
+    successCriteria?: CriterionIR[];
+    onSuccess?: ActionIR[];
+    onFailure?: ActionIR[];
+    outputs?: Record<string, RuntimeExpressionAST>;
+}
+/** A step that invokes one HTTP operation from a source description. */
+export interface OperationStepIR extends StepIRBase {
+    kind: 'operation';
+    /** Source description name the operation was resolved from. */
+    source: string;
+    /** OpenAPI path in that source. */
+    path: string;
+    method: HTTPMethod;
+    operationId?: string;
+    operation: StepOperationIR;
+    requestBody?: StepRequestBodyIR;
+}
+/** A step that invokes another workflow in the same Arazzo document. */
+export interface NestedWorkflowStepIR extends StepIRBase {
+    kind: 'workflow';
+    workflowId: string;
+}
+/** Discriminated step union (`kind`). */
+export type WorkflowStepIR = OperationStepIR | NestedWorkflowStepIR;
+/** The complete serializable workflow IR carried on `metadata.workflow`. */
+export interface WorkflowIR {
+    /** The document's `arazzo` version, e.g. `'1.0.0'`. */
+    arazzoVersion: string;
+    workflowId: string;
+    summary?: string;
+    description?: string;
+    /** Normalized workflow inputs (components `$ref`s resolved). */
+    inputSchema?: JsonSchema;
+    dependsOn?: string[];
+    parameters?: StepParameterIR[];
+    steps: WorkflowStepIR[];
+    successActions?: ActionIR[];
+    failureActions?: ActionIR[];
+    outputs?: Record<string, RuntimeExpressionAST>;
+}
+export {};

package/arazzo.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Arazzo 1.0 → consolidated MCP tools.
+ *
+ * `fromArazzo()` parses an Arazzo workflow document against caller-supplied
+ * OpenAPI sources and emits ONE `McpOpenAPITool` per workflow: the workflow
+ * inputs become the tool's input schema, the workflow outputs derive the
+ * output schema, and a pure, JSON-serializable IR (`metadata.workflow`)
+ * carries the step sequence — each operation step embedding its resolved
+ * schemas and mapper so an executor needs no second spec pass. This library
+ * never fetches source URLs, performs HTTP, or evaluates expressions.
+ */
+import { OpenAPIToolGenerator } from './generator';
+import type { GenerateOptions, LoadOptions, McpOpenAPITool, OpenAPIDocument } from './types';
+import type { ArazzoDocument } from './arazzo-types';
+/**
+ * The `GenerateOptions` subset that applies to Arazzo output — schema-shaping
+ * and naming options. Operation-filtering options have no meaning here.
+ */
+export type ArazzoGenerateOptions = Pick<GenerateOptions, 'target' | 'maxSchemaDepth' | 'maxProperties' | 'maxDescriptionLength' | 'stripExamples' | 'includeExamples' | 'resolveFormats' | 'formatResolvers' | 'preferredStatusCodes' | 'includeAllResponses' | 'maxToolNameLength' | 'includeSecurityInInput' | 'emitTypeSignatures'>;
+/** Options for {@link fromArazzo}. */
+export interface FromArazzoOptions {
+    /**
+     * Source description name → resolved OpenAPI document or pre-built
+     * generator. Source URLs are NEVER fetched — the caller supplies resolved
+     * documents for every source the workflows use.
+     */
+    sources: Record<string, OpenAPIDocument | OpenAPIToolGenerator>;
+    /**
+     * Schema-affecting options, applied to the per-step embedded schemas AND
+     * the consolidated workflow schemas.
+     */
+    generateOptions?: ArazzoGenerateOptions;
+    /**
+     * Load options for internally-constructed generators (raw documents only).
+     */
+    loadOptions?: Pick<LoadOptions, 'dereference' | 'validate' | 'baseUrl' | 'overlays'>;
+}
+/**
+ * Convert an Arazzo 1.0 workflow document (object or YAML/JSON string) into
+ * consolidated MCP tools — one per workflow, in document order. Source URLs
+ * are never fetched; supply every used source via `options.sources`. Throws
+ * `ArazzoError` (with a JSON-Pointer `path`) on malformed documents,
+ * unresolvable references, or cyclic workflows.
+ */
+export declare function fromArazzo(document: ArazzoDocument | string, options: FromArazzoOptions): Promise<McpOpenAPITool[]>;

package/elicitation.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Security elicitation descriptors.
+ *
+ * Derives MCP-elicitation-compatible `{ message, requestedSchema }` request
+ * descriptors from a tool's resolved security data, so a server can ask the
+ * user for missing credentials in the shape `elicitInput` expects. Pure data
+ * derivation — transport policy is the consumer's. Note the MCP guidance:
+ * servers SHOULD NOT elicit secrets over untrusted paths; prefer dedicated
+ * credential flows where available.
+ */
+import type { McpOpenAPITool } from './types';
+/** A flat string property in an elicitation `requestedSchema`. */
+export interface ElicitationField {
+    type: 'string';
+    title?: string;
+    description?: string;
+}
+/** MCP elicitation request descriptor derived from a tool's security data. */
+export interface SecurityElicitation {
+    /**
+     * OpenAPI security scheme name (as declared in `components.securitySchemes`).
+     */
+    scheme: string;
+    /**
+     * Human-readable prompt (`ElicitRequest.message`).
+     */
+    message: string;
+    /**
+     * Flat requested schema — primitive string properties only, per MCP
+     * elicitation rules.
+     */
+    requestedSchema: {
+        type: 'object';
+        properties: Record<string, ElicitationField>;
+        required: string[];
+    };
+}
+/**
+ * Derive credential-elicitation descriptors from a generated tool — one per
+ * distinct security scheme, in mapper order. Falls back to
+ * `metadata.security` for hand-built tools without security mapper entries.
+ * Returns `[]` when the tool declares no security.
+ */
+export declare function deriveSecurityElicitations(tool: McpOpenAPITool): SecurityElicitation[];

package/errors.d.ts

@@ -43,6 +43,13 @@ export declare class ValidationError extends OpenAPIToolError {
 export declare class GenerationError extends OpenAPIToolError {
     constructor(message: string, context?: Record<string, any>);
 }
+/**
+ * Error thrown when an OpenAPI Overlay document is malformed or its JSONPath
+ * target uses unsupported syntax
+ */
+export declare class OverlayError extends OpenAPIToolError {
+    constructor(message: string, context?: Record<string, any>);
+}
 /**
  * Error thrown when an HTTP request cannot be built from a tool's mapper
  * (missing required parameters, unserializable values, injection attempts)
@@ -50,6 +57,14 @@ export declare class GenerationError extends OpenAPIToolError {
 export declare class RequestBuildError extends OpenAPIToolError {
     constructor(message: string, context?: Record<string, any>);
 }
+/**
+ * Error thrown when an Arazzo document is malformed or cannot be resolved
+ * against its sources. `path` is a JSON Pointer into the Arazzo document.
+ */
+export declare class ArazzoError extends OpenAPIToolError {
+    readonly path?: string;
+    constructor(message: string, context?: Record<string, any>);
+}
 /**
  * Error thrown when a schema is invalid
  */