mcp-from-openapi 2.6.1 → 2.8.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.6.1",
+  "version": "2.8.0",
   "description": "Production-ready library for converting OpenAPI specifications into MCP tool definitions",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -28,7 +28,7 @@
   },
   "homepage": "https://github.com/agentfront/mcp-from-openapi#readme",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.19.0"
   },
   "type": "commonjs",
   "main": "./index.js",
@@ -49,7 +49,7 @@
     }
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^15.5.1",
+    "@apidevtools/json-schema-ref-parser": "^16.0.2",
     "openapi-types": "^12.1.3",
     "yaml": "^2.9.0"
   },
@@ -57,14 +57,16 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@swc/core": "~1.5.7",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@swc/core": "~1.16.1",
     "@swc/helpers": "^0.5.18",
     "@swc/jest": "~0.2.38",
-    "@types/jest": "^29.5.0",
+    "@types/jest": "^30.0.0",
     "@types/json-schema": "^7.0.15",
-    "@types/node": "^24.0.0",
-    "esbuild": "^0.27.2",
-    "jest": "^29.7.0",
+    "@types/node": "^26.4.1",
+    "ajv": "^8.17.0",
+    "esbuild": "^0.28.2",
+    "jest": "^30.5.1",
     "tslib": "^2.8.1",
     "typescript": "^5.0.0",
     "zod": "^4.0.0"

package/ssrf.d.ts

@@ -26,7 +26,8 @@
  *     guard and the socket share one DNS resolution. This closes the
  *     DNS-rebinding TOCTOU where the client would otherwise re-resolve the
  *     hostname at connect time and reach a different (internal) address. The
- *     original hostname is preserved for the `Host` header and TLS SNI;
+ *     original hostname is preserved for the `Host` header and TLS SNI, and
+ *     every request opens a fresh socket (never a pooled keep-alive one);
  *   - re-validates every redirect hop ({@link safeFetch}) instead of letting the
  *     HTTP client follow 3xx blindly.
  *
@@ -154,8 +155,9 @@ export declare function makePinnedLookup(pinned: ResolvedAddress[]): (_hostname:
 /**
  * Node transport that pins the connection to the validated address(es) via a
  * custom `lookup`, preserving the original hostname for the `Host` header and
- * TLS SNI. Manual redirects only (no `lookup` re-resolution between hops).
- * Exported for tests.
+ * TLS SNI. Each request uses a one-off agent so a shared keep-alive pool can't
+ * hand it a socket connected elsewhere. Manual redirects only (no `lookup`
+ * re-resolution between hops). Exported for tests.
  */
 export declare function nodePinnedTransport(modules: NodeHttpModules): SsrfTransport;
 /**

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)
@@ -297,6 +329,21 @@ export interface ToolMetadata {
      * 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
@@ -351,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
@@ -691,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.
@@ -702,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