@frontmcp/adapters 0.5.0 → 0.6.0

package/src/openapi/openapi.types.d.ts

@@ -1,6 +1,330 @@
-import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
-import { OpenAPIV3 } from 'openapi-types';
-import type { LoadOptions, GenerateOptions, McpOpenAPITool, SecurityContext } from 'mcp-from-openapi';
+import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+import type { LoadOptions, GenerateOptions, McpOpenAPITool, SecurityContext, ToolMetadata } from 'mcp-from-openapi';
+import type { FrontMcpLogger, ToolAnnotations, ToolExample, ToolUIConfig, FrontMcpContext } from '@frontmcp/sdk';
+/**
+ * Context available when injecting values at request time
+ */
+export interface InputTransformContext {
+    /** FrontMCP request context with authInfo, sessionId, traceId, etc. */
+    ctx: FrontMcpContext;
+    /** Environment variables */
+    env: NodeJS.ProcessEnv;
+    /** The OpenAPI tool being executed */
+    tool: McpOpenAPITool;
+}
+/**
+ * Single input transform configuration.
+ * Removes an input from the schema and injects its value at request time.
+ */
+export interface InputTransform {
+    /**
+     * The input key (property name in inputSchema) to transform.
+     * This input will be removed from the schema visible to AI/users.
+     */
+    inputKey: string;
+    /**
+     * Value injector function called at request time.
+     * Returns the value to inject for this input.
+     */
+    inject: (ctx: InputTransformContext) => unknown | Promise<unknown>;
+}
+/**
+ * Input transform configuration options.
+ * Supports global, per-tool, and dynamic transforms.
+ */
+export interface InputTransformOptions {
+    /**
+     * Global transforms applied to ALL tools.
+     * Use for common patterns like tenant headers.
+     */
+    global?: InputTransform[];
+    /**
+     * Per-tool transforms keyed by tool name.
+     * These are combined with global transforms.
+     */
+    perTool?: Record<string, InputTransform[]>;
+    /**
+     * Dynamic transform generator function.
+     * Called for each tool to generate transforms programmatically.
+     * Useful when transforms depend on tool metadata.
+     */
+    generator?: (tool: McpOpenAPITool) => InputTransform[];
+}
+/**
+ * The OpenAPI extension key for FrontMCP metadata.
+ * Add this to operations in your OpenAPI spec to configure tool behavior.
+ *
+ * @example OpenAPI YAML
+ * ```yaml
+ * paths:
+ *   /users:
+ *     get:
+ *       operationId: listUsers
+ *       summary: List all users
+ *       x-frontmcp:
+ *         annotations:
+ *           readOnlyHint: true
+ *           idempotentHint: true
+ *         cache:
+ *           ttl: 300
+ *         tags:
+ *           - users
+ * ```
+ */
+export declare const FRONTMCP_EXTENSION_KEY = "x-frontmcp";
+/**
+ * Cache configuration for tools.
+ */
+export interface FrontMcpCacheConfig {
+    /**
+     * Time-to-live in seconds for cached responses.
+     */
+    ttl?: number;
+    /**
+     * If true, cache window slides on each access.
+     * If false, cache expires at fixed time from first access.
+     */
+    slideWindow?: boolean;
+}
+/**
+ * CodeCall configuration for tools.
+ */
+export interface FrontMcpCodeCallConfig {
+    /**
+     * Whether this tool can be used via CodeCall.
+     * @default true
+     */
+    enabledInCodeCall?: boolean;
+    /**
+     * If true, this tool stays visible in `list_tools`
+     * even when CodeCall is hiding most tools.
+     * @default false
+     */
+    visibleInListTools?: boolean;
+}
+/**
+ * Tool annotations that hint at tool behavior.
+ * These map directly to MCP ToolAnnotations.
+ */
+export interface FrontMcpAnnotations {
+    /**
+     * A human-readable title for the tool.
+     */
+    title?: string;
+    /**
+     * If true, the tool does not modify its environment.
+     * @default false
+     */
+    readOnlyHint?: boolean;
+    /**
+     * If true, the tool may perform destructive updates.
+     * If false, the tool performs only additive updates.
+     * (Meaningful only when readOnlyHint == false)
+     * @default true
+     */
+    destructiveHint?: boolean;
+    /**
+     * If true, calling repeatedly with same args has no additional effect.
+     * (Meaningful only when readOnlyHint == false)
+     * @default false
+     */
+    idempotentHint?: boolean;
+    /**
+     * If true, tool may interact with external entities (open world).
+     * If false, tool's domain is closed (e.g., memory tool).
+     * @default true
+     */
+    openWorldHint?: boolean;
+}
+/**
+ * FrontMCP extension schema for OpenAPI operations.
+ * Add `x-frontmcp` to any operation to configure tool behavior.
+ *
+ * @example
+ * ```yaml
+ * x-frontmcp:
+ *   annotations:
+ *     readOnlyHint: true
+ *     idempotentHint: true
+ *   cache:
+ *     ttl: 300
+ *   codecall:
+ *     enabledInCodeCall: true
+ *     visibleInListTools: true
+ *   tags:
+ *     - users
+ *     - public-api
+ *   hideFromDiscovery: false
+ * ```
+ */
+export interface FrontMcpExtension {
+    /**
+     * Tool annotations for AI behavior hints.
+     */
+    annotations?: FrontMcpAnnotations;
+    /**
+     * Cache configuration for response caching.
+     */
+    cache?: FrontMcpCacheConfig;
+    /**
+     * CodeCall-specific configuration.
+     */
+    codecall?: FrontMcpCodeCallConfig;
+    /**
+     * Tags/labels for categorization and filtering.
+     */
+    tags?: string[];
+    /**
+     * If true, hide tool from discovery/listing.
+     * @default false
+     */
+    hideFromDiscovery?: boolean;
+    /**
+     * Usage examples for the tool.
+     */
+    examples?: Array<{
+        description: string;
+        input: Record<string, unknown>;
+        output?: unknown;
+    }>;
+}
+/**
+ * How to generate tool descriptions from OpenAPI operations.
+ * - 'summaryOnly': Use only the operation summary (default, current behavior)
+ * - 'descriptionOnly': Use only the operation description
+ * - 'combined': Combine summary and description (summary first, then description)
+ * - 'full': Include summary, description, and operation ID
+ */
+export type DescriptionMode = 'summaryOnly' | 'descriptionOnly' | 'combined' | 'full';
+/**
+ * Transform configuration for modifying generated tools.
+ * Can override or augment any tool property.
+ */
+export interface ToolTransform {
+    /**
+     * Override or transform the tool name.
+     * - string: Replace the name entirely
+     * - function: Transform the existing name
+     */
+    name?: string | ((originalName: string, tool: McpOpenAPITool) => string);
+    /**
+     * Override or transform the tool description.
+     * - string: Replace the description entirely
+     * - function: Transform with access to original description and tool metadata
+     *
+     * @example
+     * ```typescript
+     * // Combine summary and description
+     * description: (original, tool) => {
+     *   const summary = tool.metadata.operationSummary || '';
+     *   const desc = tool.metadata.operationDescription || '';
+     *   return summary && desc ? `${summary}\n\n${desc}` : original;
+     * }
+     * ```
+     */
+    description?: string | ((originalDescription: string, tool: McpOpenAPITool) => string);
+    /**
+     * Annotations to add or merge with existing tool annotations.
+     * These hint at tool behavior for AI clients.
+     *
+     * @example
+     * ```typescript
+     * annotations: {
+     *   readOnlyHint: true,      // Tool doesn't modify state
+     *   openWorldHint: true,     // Tool interacts with external systems
+     *   destructiveHint: false,  // Tool doesn't delete data
+     *   idempotentHint: true,    // Repeated calls have same effect
+     * }
+     * ```
+     */
+    annotations?: ToolAnnotations;
+    /**
+     * UI configuration for the tool (forms, rendering hints).
+     */
+    ui?: ToolUIConfig;
+    /**
+     * If true, hide the tool from tool discovery/listing.
+     * The tool can still be called directly.
+     */
+    hideFromDiscovery?: boolean;
+    /**
+     * Tags to add to the tool for categorization.
+     */
+    tags?: string[];
+    /**
+     * Usage examples to add to the tool.
+     */
+    examples?: ToolExample[];
+}
+/**
+ * Tool transform configuration options.
+ * Supports global, per-tool, and dynamic transforms.
+ */
+export interface ToolTransformOptions {
+    /**
+     * Global transforms applied to ALL tools.
+     * Use for common patterns like adding readOnlyHint to all GET operations.
+     */
+    global?: ToolTransform;
+    /**
+     * Per-tool transforms keyed by tool name.
+     * Takes precedence over global transforms for overlapping properties.
+     */
+    perTool?: Record<string, ToolTransform>;
+    /**
+     * Dynamic transform generator function.
+     * Called for each tool to generate transforms programmatically.
+     * Useful when transforms depend on tool metadata (e.g., HTTP method).
+     *
+     * @example
+     * ```typescript
+     * generator: (tool) => {
+     *   // Mark all GET operations as read-only
+     *   if (tool.metadata.method === 'get') {
+     *     return {
+     *       annotations: { readOnlyHint: true, destructiveHint: false },
+     *     };
+     *   }
+     *   // Mark DELETE operations as destructive
+     *   if (tool.metadata.method === 'delete') {
+     *     return {
+     *       annotations: { destructiveHint: true },
+     *     };
+     *   }
+     *   return undefined;
+     * }
+     * ```
+     */
+    generator?: (tool: McpOpenAPITool) => ToolTransform | undefined;
+}
+/**
+ * Extended tool metadata that includes adapter-specific fields.
+ * This extends the base ToolMetadata from mcp-from-openapi with
+ * fields used for transforms and extensions.
+ */
+export interface ExtendedToolMetadata extends ToolMetadata {
+    /**
+     * Adapter-specific runtime configuration.
+     * Contains transforms and other metadata added during tool processing.
+     */
+    adapter?: {
+        /** Input transforms to apply at request time */
+        inputTransforms?: InputTransform[];
+        /** Tool transform configuration */
+        toolTransform?: ToolTransform;
+        /** Security schemes that are included in tool input (user provides) */
+        securitySchemesInInput?: string[];
+        /** Security schemes resolved from context (authProviderMapper, etc.) */
+        securitySchemesFromContext?: string[];
+    };
+}
+/**
+ * McpOpenAPITool with extended metadata type.
+ * Use this type when accessing adapter-extended metadata.
+ */
+export interface ExtendedMcpOpenAPITool extends Omit<McpOpenAPITool, 'metadata'> {
+    metadata: ExtendedToolMetadata;
+}
 interface BaseOptions {
     /**
      * The name of the adapter.
@@ -28,10 +352,10 @@ interface BaseOptions {
      * For example, mapping tenantId from authenticated session payload to
      * a specific header, this key will be hidden to mcp clients
      * and filled by the adapter before sending the request to the API.
-     * @param authInfo
+     * @param ctx - FrontMCP request context with authInfo, sessionId, traceId, etc.
      * @param headers
      */
-    headersMapper?: (authInfo: AuthInfo, headers: Headers) => Headers;
+    headersMapper?: (ctx: FrontMcpContext, headers: Headers) => Headers;
     /**
      * This can be used to map request information to specific
      * body values as required by the API.
@@ -39,10 +363,10 @@ interface BaseOptions {
      * a specific property in the body, this key will be hidden to mcp clients
      * and filled by the adapter before sending the request to the API.
      *
-     * @param authInfo
+     * @param ctx - FrontMCP request context with authInfo, sessionId, traceId, etc.
      * @param body
      */
-    bodyMapper?: (authInfo: AuthInfo, body: Record<string, unknown>) => Record<string, unknown>;
+    bodyMapper?: (ctx: FrontMcpContext, body: Record<string, unknown>) => Record<string, unknown>;
     /**
      * Custom security resolver for resolving authentication from context.
      * This allows you to map different auth providers to different tools/security schemes.
@@ -54,7 +378,8 @@ interface BaseOptions {
      *
      * @example
      * ```typescript
-     * securityResolver: (tool, authInfo) => {
+     * securityResolver: (tool, ctx) => {
+     *   const authInfo = ctx.authInfo;
      *   // Use GitHub token for GitHub API tools
      *   if (tool.name.startsWith('github_')) {
      *     return { jwt: authInfo.user?.githubToken };
@@ -68,7 +393,7 @@ interface BaseOptions {
      * }
      * ```
      */
-    securityResolver?: (tool: McpOpenAPITool, authInfo: AuthInfo) => SecurityContext | Promise<SecurityContext>;
+    securityResolver?: (tool: McpOpenAPITool, ctx: FrontMcpContext) => SecurityContext | Promise<SecurityContext>;
     /**
      * Map security scheme names to auth provider extractors.
      * This allows different security schemes to use different auth providers.
@@ -80,15 +405,15 @@ interface BaseOptions {
      * ```typescript
      * authProviderMapper: {
      *   // GitHub OAuth security scheme
-     *   'GitHubAuth': (authInfo) => authInfo.user?.githubToken,
+     *   'GitHubAuth': (ctx) => ctx.authInfo.user?.githubToken,
      *   // Google OAuth security scheme
-     *   'GoogleAuth': (authInfo) => authInfo.user?.googleToken,
+     *   'GoogleAuth': (ctx) => ctx.authInfo.user?.googleToken,
      *   // API Key security scheme
-     *   'ApiKeyAuth': (authInfo) => authInfo.user?.apiKey,
+     *   'ApiKeyAuth': (ctx) => ctx.authInfo.user?.apiKey,
      * }
      * ```
      */
-    authProviderMapper?: Record<string, (authInfo: AuthInfo) => string | undefined>;
+    authProviderMapper?: Record<string, (ctx: FrontMcpContext) => string | undefined>;
     /**
      * Static authentication configuration when not using dynamic auth from context.
      * Useful for server-to-server APIs with static credentials.
@@ -112,12 +437,158 @@ interface BaseOptions {
      * @see GenerateOptions from mcp-from-openapi
      */
     generateOptions?: GenerateOptions;
+    /**
+     * Specify which security schemes should be included in the tool's input schema.
+     * Use this for per-scheme control over authentication handling.
+     *
+     * - Schemes in this list → included in input (user/AI provides the value)
+     * - Schemes NOT in this list → resolved from context (authProviderMapper, staticAuth, etc.)
+     *
+     * This allows hybrid authentication where some schemes come from user input
+     * and others come from the session/context.
+     *
+     * @example
+     * ```typescript
+     * // OpenAPI spec has: GitHubAuth (Bearer), ApiKeyAuth (API key)
+     * // You want: GitHubAuth from session, ApiKeyAuth from user input
+     *
+     * const adapter = new OpenapiAdapter({
+     *   name: 'my-api',
+     *   baseUrl: 'https://api.example.com',
+     *   spec: mySpec,
+     *
+     *   // ApiKeyAuth will be in tool input schema
+     *   securitySchemesInInput: ['ApiKeyAuth'],
+     *
+     *   // GitHubAuth will be resolved from context
+     *   authProviderMapper: {
+     *     'GitHubAuth': (ctx) => ctx.authInfo?.user?.githubToken,
+     *   },
+     * });
+     * ```
+     */
+    securitySchemesInInput?: string[];
+    /**
+     * Input schema transforms for hiding inputs and injecting values at request time.
+     *
+     * Use cases:
+     * - Hide tenant headers from AI/users and inject from session
+     * - Hide internal correlation IDs and inject from environment
+     * - Remove API-internal fields that should be computed server-side
+     *
+     * @example
+     * ```typescript
+     * inputTransforms: {
+     *   global: [
+     *     { inputKey: 'X-Tenant-Id', inject: (ctx) => ctx.authInfo.user?.tenantId },
+     *   ],
+     *   perTool: {
+     *     'createUser': [
+     *       { inputKey: 'createdBy', inject: (ctx) => ctx.authInfo.user?.email },
+     *     ],
+     *   },
+     *   generator: (tool) => {
+     *     if (['post', 'put', 'patch'].includes(tool.metadata.method)) {
+     *       return [{ inputKey: 'X-Correlation-Id', inject: () => crypto.randomUUID() }];
+     *     }
+     *     return [];
+     *   },
+     * }
+     * ```
+     */
+    inputTransforms?: InputTransformOptions;
+    /**
+     * Tool transforms for modifying generated tools (description, annotations, UI, etc.).
+     *
+     * Use cases:
+     * - Add annotations (readOnlyHint, openWorldHint) based on HTTP method
+     * - Override tool descriptions with combined summary + description
+     * - Add UI configuration for tool forms
+     * - Hide internal tools from discovery
+     *
+     * @example
+     * ```typescript
+     * toolTransforms: {
+     *   global: {
+     *     annotations: { openWorldHint: true },
+     *   },
+     *   perTool: {
+     *     'createUser': {
+     *       annotations: { destructiveHint: false },
+     *       tags: ['user-management'],
+     *     },
+     *   },
+     *   generator: (tool) => {
+     *     if (tool.metadata.method === 'get') {
+     *       return { annotations: { readOnlyHint: true } };
+     *     }
+     *     if (tool.metadata.method === 'delete') {
+     *       return { annotations: { destructiveHint: true } };
+     *     }
+     *     return undefined;
+     *   },
+     * }
+     * ```
+     */
+    toolTransforms?: ToolTransformOptions;
+    /**
+     * How to generate tool descriptions from OpenAPI operations.
+     * - 'summaryOnly': Use only summary (default)
+     * - 'descriptionOnly': Use only description
+     * - 'combined': Summary followed by description
+     * - 'full': Summary, description, and operation details
+     *
+     * @default 'summaryOnly'
+     */
+    descriptionMode?: DescriptionMode;
+    /**
+     * Logger instance for adapter diagnostics.
+     * Optional - if not provided, the SDK will inject it automatically via setLogger().
+     */
+    logger?: FrontMcpLogger;
+    /**
+     * Timeout for HTTP requests in milliseconds.
+     * If a request takes longer than this, it will be aborted.
+     * @default 30000 (30 seconds)
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Maximum request body size in bytes.
+     * Requests with bodies larger than this will be rejected before sending.
+     * @default 10485760 (10MB)
+     */
+    maxRequestSize?: number;
+    /**
+     * Maximum response size in bytes.
+     * Responses larger than this will be rejected.
+     * The check is performed first on Content-Length header (if present),
+     * then on actual response size.
+     * @default 10485760 (10MB)
+     */
+    maxResponseSize?: number;
 }
 interface SpecOptions extends BaseOptions {
     /**
-     * The OpenAPI specification the OpenAPI specification.
+     * The OpenAPI specification as a JSON object.
+     *
+     * Accepts:
+     * - `OpenAPIV3.Document` (typed)
+     * - `OpenAPIV3_1.Document` (typed)
+     * - Plain object from `import spec from './openapi.json'`
+     *
+     * @example
+     * ```typescript
+     * // From typed constant
+     * import { OpenAPIV3 } from 'openapi-types';
+     * const spec: OpenAPIV3.Document = { ... };
+     * new OpenapiAdapter({ spec, ... })
+     *
+     * // From JSON import
+     * import openapiJson from './my-openapi.json';
+     * new OpenapiAdapter({ spec: openapiJson, ... })
+     * ```
      */
-    spec: OpenAPIV3.Document;
+    spec: OpenAPIV3.Document | OpenAPIV3_1.Document | object;
 }
 interface UrlOptions extends BaseOptions {
     /**

package/src/openapi/openapi.types.js

@@ -1,3 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRONTMCP_EXTENSION_KEY = void 0;
+// ============================================================================
+// OpenAPI Extension Types (x-frontmcp)
+// ============================================================================
+/**
+ * The OpenAPI extension key for FrontMCP metadata.
+ * Add this to operations in your OpenAPI spec to configure tool behavior.
+ *
+ * @example OpenAPI YAML
+ * ```yaml
+ * paths:
+ *   /users:
+ *     get:
+ *       operationId: listUsers
+ *       summary: List all users
+ *       x-frontmcp:
+ *         annotations:
+ *           readOnlyHint: true
+ *           idempotentHint: true
+ *         cache:
+ *           ttl: 300
+ *         tags:
+ *           - users
+ * ```
+ */
+exports.FRONTMCP_EXTENSION_KEY = 'x-frontmcp';
 //# sourceMappingURL=openapi.types.js.map

package/src/openapi/openapi.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.types.js","sourceRoot":"","sources":["../../../src/openapi/openapi.types.ts"],"names":[],"mappings":"","sourcesContent":["import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';\nimport { OpenAPIV3 } from 'openapi-types';\nimport type { LoadOptions, GenerateOptions, McpOpenAPITool, SecurityContext } from 'mcp-from-openapi';\n\ninterface BaseOptions {\n  /**\n   * The name of the adapter.\n   * This is used to identify the adapter in the MCP configuration.\n   * Also used to prefix tools if conflicted with other adapters in the same app.\n   */\n  name: string;\n\n  /**\n   * The base URL of the API.\n   * This is used to construct the full URL for each request.\n   * For example, if the API is hosted at https://api.example.com/v1,\n   * the baseUrl should be set to https://api.example.com/v1.\n   * This overrides the baseUrl in LoadOptions.\n   */\n  baseUrl: string;\n\n  /**\n   * Additional headers to be sent with each request.\n   * This can be used to set authentication headers,\n   * such as Authorization or API Key.\n   */\n  additionalHeaders?: Record<string, string>;\n\n  /**\n   * This can be used to map request information to specific\n   * headers as required by the API.\n   * For example, mapping tenantId from authenticated session payload to\n   * a specific header, this key will be hidden to mcp clients\n   * and filled by the adapter before sending the request to the API.\n   * @param authInfo\n   * @param headers\n   */\n  headersMapper?: (authInfo: AuthInfo, headers: Headers) => Headers;\n\n  /**\n   * This can be used to map request information to specific\n   * body values as required by the API.\n   * For example, mapping tenantId from authenticated session payload to\n   * a specific property in the body, this key will be hidden to mcp clients\n   * and filled by the adapter before sending the request to the API.\n   *\n   * @param authInfo\n   * @param body\n   */\n  bodyMapper?: (authInfo: AuthInfo, body: Record<string, unknown>) => Record<string, unknown>;\n\n  /**\n   * Custom security resolver for resolving authentication from context.\n   * This allows you to map different auth providers to different tools/security schemes.\n   *\n   * Use this when:\n   * - You have multiple auth providers (e.g., GitHub OAuth, Google OAuth, API keys)\n   * - Different tools need different authentication\n   * - You need custom logic to select the right auth provider\n   *\n   * @example\n   * ```typescript\n   * securityResolver: (tool, authInfo) => {\n   *   // Use GitHub token for GitHub API tools\n   *   if (tool.name.startsWith('github_')) {\n   *     return { jwt: authInfo.user?.githubToken };\n   *   }\n   *   // Use Google token for Google API tools\n   *   if (tool.name.startsWith('google_')) {\n   *     return { jwt: authInfo.user?.googleToken };\n   *   }\n   *   // Default to main JWT token\n   *   return { jwt: authInfo.token };\n   * }\n   * ```\n   */\n  securityResolver?: (\n    tool: McpOpenAPITool,\n    authInfo: AuthInfo\n  ) => SecurityContext | Promise<SecurityContext>;\n\n  /**\n   * Map security scheme names to auth provider extractors.\n   * This allows different security schemes to use different auth providers.\n   *\n   * Use this when your OpenAPI spec has multiple security schemes\n   * and each should use a different auth provider from the context.\n   *\n   * @example\n   * ```typescript\n   * authProviderMapper: {\n   *   // GitHub OAuth security scheme\n   *   'GitHubAuth': (authInfo) => authInfo.user?.githubToken,\n   *   // Google OAuth security scheme\n   *   'GoogleAuth': (authInfo) => authInfo.user?.googleToken,\n   *   // API Key security scheme\n   *   'ApiKeyAuth': (authInfo) => authInfo.user?.apiKey,\n   * }\n   * ```\n   */\n  authProviderMapper?: Record<string, (authInfo: AuthInfo) => string | undefined>;\n\n  /**\n   * Static authentication configuration when not using dynamic auth from context.\n   * Useful for server-to-server APIs with static credentials.\n   *\n   * @example\n   * ```typescript\n   * staticAuth: {\n   *   jwt: process.env.API_JWT_TOKEN,\n   *   apiKey: process.env.API_KEY,\n   * }\n   * ```\n   */\n  staticAuth?: Partial<SecurityContext>;\n\n  /**\n   * Options for loading the OpenAPI specification\n   * @see LoadOptions from mcp-from-openapi\n   */\n  loadOptions?: Omit<LoadOptions, 'baseUrl'>; // baseUrl is in BaseOptions\n\n  /**\n   * Options for generating tools from the OpenAPI specification\n   * @see GenerateOptions from mcp-from-openapi\n   */\n  generateOptions?: GenerateOptions;\n}\n\ninterface SpecOptions extends BaseOptions {\n  /**\n   * The OpenAPI specification the OpenAPI specification.\n   */\n  spec: OpenAPIV3.Document;\n}\n\ninterface UrlOptions extends BaseOptions {\n  /**\n   * The URL of the OpenAPI specification.\n   * Can be a local file path or a remote URL.\n   */\n  url: string;\n}\n\nexport type OpenApiAdapterOptions = SpecOptions | UrlOptions;\n"]}
+{"version":3,"file":"openapi.types.js","sourceRoot":"","sources":["../../../src/openapi/openapi.types.ts"],"names":[],"mappings":";;;AA+DA,+EAA+E;AAC/E,uCAAuC;AACvC,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;GAoBG;AACU,QAAA,sBAAsB,GAAG,YAAY,CAAC","sourcesContent":["import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';\nimport type { LoadOptions, GenerateOptions, McpOpenAPITool, SecurityContext, ToolMetadata } from 'mcp-from-openapi';\nimport type { FrontMcpLogger, ToolAnnotations, ToolExample, ToolUIConfig, FrontMcpContext } from '@frontmcp/sdk';\n\n// ============================================================================\n// Input Transform Types\n// ============================================================================\n\n/**\n * Context available when injecting values at request time\n */\nexport interface InputTransformContext {\n  /** FrontMCP request context with authInfo, sessionId, traceId, etc. */\n  ctx: FrontMcpContext;\n  /** Environment variables */\n  env: NodeJS.ProcessEnv;\n  /** The OpenAPI tool being executed */\n  tool: McpOpenAPITool;\n}\n\n/**\n * Single input transform configuration.\n * Removes an input from the schema and injects its value at request time.\n */\nexport interface InputTransform {\n  /**\n   * The input key (property name in inputSchema) to transform.\n   * This input will be removed from the schema visible to AI/users.\n   */\n  inputKey: string;\n\n  /**\n   * Value injector function called at request time.\n   * Returns the value to inject for this input.\n   */\n  inject: (ctx: InputTransformContext) => unknown | Promise<unknown>;\n}\n\n/**\n * Input transform configuration options.\n * Supports global, per-tool, and dynamic transforms.\n */\nexport interface InputTransformOptions {\n  /**\n   * Global transforms applied to ALL tools.\n   * Use for common patterns like tenant headers.\n   */\n  global?: InputTransform[];\n\n  /**\n   * Per-tool transforms keyed by tool name.\n   * These are combined with global transforms.\n   */\n  perTool?: Record<string, InputTransform[]>;\n\n  /**\n   * Dynamic transform generator function.\n   * Called for each tool to generate transforms programmatically.\n   * Useful when transforms depend on tool metadata.\n   */\n  generator?: (tool: McpOpenAPITool) => InputTransform[];\n}\n\n// ============================================================================\n// OpenAPI Extension Types (x-frontmcp)\n// ============================================================================\n\n/**\n * The OpenAPI extension key for FrontMCP metadata.\n * Add this to operations in your OpenAPI spec to configure tool behavior.\n *\n * @example OpenAPI YAML\n * ```yaml\n * paths:\n *   /users:\n *     get:\n *       operationId: listUsers\n *       summary: List all users\n *       x-frontmcp:\n *         annotations:\n *           readOnlyHint: true\n *           idempotentHint: true\n *         cache:\n *           ttl: 300\n *         tags:\n *           - users\n * ```\n */\nexport const FRONTMCP_EXTENSION_KEY = 'x-frontmcp';\n\n/**\n * Cache configuration for tools.\n */\nexport interface FrontMcpCacheConfig {\n  /**\n   * Time-to-live in seconds for cached responses.\n   */\n  ttl?: number;\n\n  /**\n   * If true, cache window slides on each access.\n   * If false, cache expires at fixed time from first access.\n   */\n  slideWindow?: boolean;\n}\n\n/**\n * CodeCall configuration for tools.\n */\nexport interface FrontMcpCodeCallConfig {\n  /**\n   * Whether this tool can be used via CodeCall.\n   * @default true\n   */\n  enabledInCodeCall?: boolean;\n\n  /**\n   * If true, this tool stays visible in `list_tools`\n   * even when CodeCall is hiding most tools.\n   * @default false\n   */\n  visibleInListTools?: boolean;\n}\n\n/**\n * Tool annotations that hint at tool behavior.\n * These map directly to MCP ToolAnnotations.\n */\nexport interface FrontMcpAnnotations {\n  /**\n   * A human-readable title for the tool.\n   */\n  title?: string;\n\n  /**\n   * If true, the tool does not modify its environment.\n   * @default false\n   */\n  readOnlyHint?: boolean;\n\n  /**\n   * If true, the tool may perform destructive updates.\n   * If false, the tool performs only additive updates.\n   * (Meaningful only when readOnlyHint == false)\n   * @default true\n   */\n  destructiveHint?: boolean;\n\n  /**\n   * If true, calling repeatedly with same args has no additional effect.\n   * (Meaningful only when readOnlyHint == false)\n   * @default false\n   */\n  idempotentHint?: boolean;\n\n  /**\n   * If true, tool may interact with external entities (open world).\n   * If false, tool's domain is closed (e.g., memory tool).\n   * @default true\n   */\n  openWorldHint?: boolean;\n}\n\n/**\n * FrontMCP extension schema for OpenAPI operations.\n * Add `x-frontmcp` to any operation to configure tool behavior.\n *\n * @example\n * ```yaml\n * x-frontmcp:\n *   annotations:\n *     readOnlyHint: true\n *     idempotentHint: true\n *   cache:\n *     ttl: 300\n *   codecall:\n *     enabledInCodeCall: true\n *     visibleInListTools: true\n *   tags:\n *     - users\n *     - public-api\n *   hideFromDiscovery: false\n * ```\n */\nexport interface FrontMcpExtension {\n  /**\n   * Tool annotations for AI behavior hints.\n   */\n  annotations?: FrontMcpAnnotations;\n\n  /**\n   * Cache configuration for response caching.\n   */\n  cache?: FrontMcpCacheConfig;\n\n  /**\n   * CodeCall-specific configuration.\n   */\n  codecall?: FrontMcpCodeCallConfig;\n\n  /**\n   * Tags/labels for categorization and filtering.\n   */\n  tags?: string[];\n\n  /**\n   * If true, hide tool from discovery/listing.\n   * @default false\n   */\n  hideFromDiscovery?: boolean;\n\n  /**\n   * Usage examples for the tool.\n   */\n  examples?: Array<{\n    description: string;\n    input: Record<string, unknown>;\n    output?: unknown;\n  }>;\n}\n\n// ============================================================================\n// Tool Transform Types\n// ============================================================================\n\n/**\n * How to generate tool descriptions from OpenAPI operations.\n * - 'summaryOnly': Use only the operation summary (default, current behavior)\n * - 'descriptionOnly': Use only the operation description\n * - 'combined': Combine summary and description (summary first, then description)\n * - 'full': Include summary, description, and operation ID\n */\nexport type DescriptionMode = 'summaryOnly' | 'descriptionOnly' | 'combined' | 'full';\n\n/**\n * Transform configuration for modifying generated tools.\n * Can override or augment any tool property.\n */\nexport interface ToolTransform {\n  /**\n   * Override or transform the tool name.\n   * - string: Replace the name entirely\n   * - function: Transform the existing name\n   */\n  name?: string | ((originalName: string, tool: McpOpenAPITool) => string);\n\n  /**\n   * Override or transform the tool description.\n   * - string: Replace the description entirely\n   * - function: Transform with access to original description and tool metadata\n   *\n   * @example\n   * ```typescript\n   * // Combine summary and description\n   * description: (original, tool) => {\n   *   const summary = tool.metadata.operationSummary || '';\n   *   const desc = tool.metadata.operationDescription || '';\n   *   return summary && desc ? `${summary}\\n\\n${desc}` : original;\n   * }\n   * ```\n   */\n  description?: string | ((originalDescription: string, tool: McpOpenAPITool) => string);\n\n  /**\n   * Annotations to add or merge with existing tool annotations.\n   * These hint at tool behavior for AI clients.\n   *\n   * @example\n   * ```typescript\n   * annotations: {\n   *   readOnlyHint: true,      // Tool doesn't modify state\n   *   openWorldHint: true,     // Tool interacts with external systems\n   *   destructiveHint: false,  // Tool doesn't delete data\n   *   idempotentHint: true,    // Repeated calls have same effect\n   * }\n   * ```\n   */\n  annotations?: ToolAnnotations;\n\n  /**\n   * UI configuration for the tool (forms, rendering hints).\n   */\n  ui?: ToolUIConfig;\n\n  /**\n   * If true, hide the tool from tool discovery/listing.\n   * The tool can still be called directly.\n   */\n  hideFromDiscovery?: boolean;\n\n  /**\n   * Tags to add to the tool for categorization.\n   */\n  tags?: string[];\n\n  /**\n   * Usage examples to add to the tool.\n   */\n  examples?: ToolExample[];\n}\n\n/**\n * Tool transform configuration options.\n * Supports global, per-tool, and dynamic transforms.\n */\nexport interface ToolTransformOptions {\n  /**\n   * Global transforms applied to ALL tools.\n   * Use for common patterns like adding readOnlyHint to all GET operations.\n   */\n  global?: ToolTransform;\n\n  /**\n   * Per-tool transforms keyed by tool name.\n   * Takes precedence over global transforms for overlapping properties.\n   */\n  perTool?: Record<string, ToolTransform>;\n\n  /**\n   * Dynamic transform generator function.\n   * Called for each tool to generate transforms programmatically.\n   * Useful when transforms depend on tool metadata (e.g., HTTP method).\n   *\n   * @example\n   * ```typescript\n   * generator: (tool) => {\n   *   // Mark all GET operations as read-only\n   *   if (tool.metadata.method === 'get') {\n   *     return {\n   *       annotations: { readOnlyHint: true, destructiveHint: false },\n   *     };\n   *   }\n   *   // Mark DELETE operations as destructive\n   *   if (tool.metadata.method === 'delete') {\n   *     return {\n   *       annotations: { destructiveHint: true },\n   *     };\n   *   }\n   *   return undefined;\n   * }\n   * ```\n   */\n  generator?: (tool: McpOpenAPITool) => ToolTransform | undefined;\n}\n\n// ============================================================================\n// Extended Metadata Types (internal)\n// ============================================================================\n\n/**\n * Extended tool metadata that includes adapter-specific fields.\n * This extends the base ToolMetadata from mcp-from-openapi with\n * fields used for transforms and extensions.\n */\nexport interface ExtendedToolMetadata extends ToolMetadata {\n  /**\n   * Adapter-specific runtime configuration.\n   * Contains transforms and other metadata added during tool processing.\n   */\n  adapter?: {\n    /** Input transforms to apply at request time */\n    inputTransforms?: InputTransform[];\n    /** Tool transform configuration */\n    toolTransform?: ToolTransform;\n    /** Security schemes that are included in tool input (user provides) */\n    securitySchemesInInput?: string[];\n    /** Security schemes resolved from context (authProviderMapper, etc.) */\n    securitySchemesFromContext?: string[];\n  };\n}\n\n/**\n * McpOpenAPITool with extended metadata type.\n * Use this type when accessing adapter-extended metadata.\n */\nexport interface ExtendedMcpOpenAPITool extends Omit<McpOpenAPITool, 'metadata'> {\n  metadata: ExtendedToolMetadata;\n}\n\ninterface BaseOptions {\n  /**\n   * The name of the adapter.\n   * This is used to identify the adapter in the MCP configuration.\n   * Also used to prefix tools if conflicted with other adapters in the same app.\n   */\n  name: string;\n\n  /**\n   * The base URL of the API.\n   * This is used to construct the full URL for each request.\n   * For example, if the API is hosted at https://api.example.com/v1,\n   * the baseUrl should be set to https://api.example.com/v1.\n   * This overrides the baseUrl in LoadOptions.\n   */\n  baseUrl: string;\n\n  /**\n   * Additional headers to be sent with each request.\n   * This can be used to set authentication headers,\n   * such as Authorization or API Key.\n   */\n  additionalHeaders?: Record<string, string>;\n\n  /**\n   * This can be used to map request information to specific\n   * headers as required by the API.\n   * For example, mapping tenantId from authenticated session payload to\n   * a specific header, this key will be hidden to mcp clients\n   * and filled by the adapter before sending the request to the API.\n   * @param ctx - FrontMCP request context with authInfo, sessionId, traceId, etc.\n   * @param headers\n   */\n  headersMapper?: (ctx: FrontMcpContext, headers: Headers) => Headers;\n\n  /**\n   * This can be used to map request information to specific\n   * body values as required by the API.\n   * For example, mapping tenantId from authenticated session payload to\n   * a specific property in the body, this key will be hidden to mcp clients\n   * and filled by the adapter before sending the request to the API.\n   *\n   * @param ctx - FrontMCP request context with authInfo, sessionId, traceId, etc.\n   * @param body\n   */\n  bodyMapper?: (ctx: FrontMcpContext, body: Record<string, unknown>) => Record<string, unknown>;\n\n  /**\n   * Custom security resolver for resolving authentication from context.\n   * This allows you to map different auth providers to different tools/security schemes.\n   *\n   * Use this when:\n   * - You have multiple auth providers (e.g., GitHub OAuth, Google OAuth, API keys)\n   * - Different tools need different authentication\n   * - You need custom logic to select the right auth provider\n   *\n   * @example\n   * ```typescript\n   * securityResolver: (tool, ctx) => {\n   *   const authInfo = ctx.authInfo;\n   *   // Use GitHub token for GitHub API tools\n   *   if (tool.name.startsWith('github_')) {\n   *     return { jwt: authInfo.user?.githubToken };\n   *   }\n   *   // Use Google token for Google API tools\n   *   if (tool.name.startsWith('google_')) {\n   *     return { jwt: authInfo.user?.googleToken };\n   *   }\n   *   // Default to main JWT token\n   *   return { jwt: authInfo.token };\n   * }\n   * ```\n   */\n  securityResolver?: (tool: McpOpenAPITool, ctx: FrontMcpContext) => SecurityContext | Promise<SecurityContext>;\n\n  /**\n   * Map security scheme names to auth provider extractors.\n   * This allows different security schemes to use different auth providers.\n   *\n   * Use this when your OpenAPI spec has multiple security schemes\n   * and each should use a different auth provider from the context.\n   *\n   * @example\n   * ```typescript\n   * authProviderMapper: {\n   *   // GitHub OAuth security scheme\n   *   'GitHubAuth': (ctx) => ctx.authInfo.user?.githubToken,\n   *   // Google OAuth security scheme\n   *   'GoogleAuth': (ctx) => ctx.authInfo.user?.googleToken,\n   *   // API Key security scheme\n   *   'ApiKeyAuth': (ctx) => ctx.authInfo.user?.apiKey,\n   * }\n   * ```\n   */\n  authProviderMapper?: Record<string, (ctx: FrontMcpContext) => string | undefined>;\n\n  /**\n   * Static authentication configuration when not using dynamic auth from context.\n   * Useful for server-to-server APIs with static credentials.\n   *\n   * @example\n   * ```typescript\n   * staticAuth: {\n   *   jwt: process.env.API_JWT_TOKEN,\n   *   apiKey: process.env.API_KEY,\n   * }\n   * ```\n   */\n  staticAuth?: Partial<SecurityContext>;\n\n  /**\n   * Options for loading the OpenAPI specification\n   * @see LoadOptions from mcp-from-openapi\n   */\n  loadOptions?: Omit<LoadOptions, 'baseUrl'>; // baseUrl is in BaseOptions\n\n  /**\n   * Options for generating tools from the OpenAPI specification\n   * @see GenerateOptions from mcp-from-openapi\n   */\n  generateOptions?: GenerateOptions;\n\n  /**\n   * Specify which security schemes should be included in the tool's input schema.\n   * Use this for per-scheme control over authentication handling.\n   *\n   * - Schemes in this list → included in input (user/AI provides the value)\n   * - Schemes NOT in this list → resolved from context (authProviderMapper, staticAuth, etc.)\n   *\n   * This allows hybrid authentication where some schemes come from user input\n   * and others come from the session/context.\n   *\n   * @example\n   * ```typescript\n   * // OpenAPI spec has: GitHubAuth (Bearer), ApiKeyAuth (API key)\n   * // You want: GitHubAuth from session, ApiKeyAuth from user input\n   *\n   * const adapter = new OpenapiAdapter({\n   *   name: 'my-api',\n   *   baseUrl: 'https://api.example.com',\n   *   spec: mySpec,\n   *\n   *   // ApiKeyAuth will be in tool input schema\n   *   securitySchemesInInput: ['ApiKeyAuth'],\n   *\n   *   // GitHubAuth will be resolved from context\n   *   authProviderMapper: {\n   *     'GitHubAuth': (ctx) => ctx.authInfo?.user?.githubToken,\n   *   },\n   * });\n   * ```\n   */\n  securitySchemesInInput?: string[];\n\n  /**\n   * Input schema transforms for hiding inputs and injecting values at request time.\n   *\n   * Use cases:\n   * - Hide tenant headers from AI/users and inject from session\n   * - Hide internal correlation IDs and inject from environment\n   * - Remove API-internal fields that should be computed server-side\n   *\n   * @example\n   * ```typescript\n   * inputTransforms: {\n   *   global: [\n   *     { inputKey: 'X-Tenant-Id', inject: (ctx) => ctx.authInfo.user?.tenantId },\n   *   ],\n   *   perTool: {\n   *     'createUser': [\n   *       { inputKey: 'createdBy', inject: (ctx) => ctx.authInfo.user?.email },\n   *     ],\n   *   },\n   *   generator: (tool) => {\n   *     if (['post', 'put', 'patch'].includes(tool.metadata.method)) {\n   *       return [{ inputKey: 'X-Correlation-Id', inject: () => crypto.randomUUID() }];\n   *     }\n   *     return [];\n   *   },\n   * }\n   * ```\n   */\n  inputTransforms?: InputTransformOptions;\n\n  /**\n   * Tool transforms for modifying generated tools (description, annotations, UI, etc.).\n   *\n   * Use cases:\n   * - Add annotations (readOnlyHint, openWorldHint) based on HTTP method\n   * - Override tool descriptions with combined summary + description\n   * - Add UI configuration for tool forms\n   * - Hide internal tools from discovery\n   *\n   * @example\n   * ```typescript\n   * toolTransforms: {\n   *   global: {\n   *     annotations: { openWorldHint: true },\n   *   },\n   *   perTool: {\n   *     'createUser': {\n   *       annotations: { destructiveHint: false },\n   *       tags: ['user-management'],\n   *     },\n   *   },\n   *   generator: (tool) => {\n   *     if (tool.metadata.method === 'get') {\n   *       return { annotations: { readOnlyHint: true } };\n   *     }\n   *     if (tool.metadata.method === 'delete') {\n   *       return { annotations: { destructiveHint: true } };\n   *     }\n   *     return undefined;\n   *   },\n   * }\n   * ```\n   */\n  toolTransforms?: ToolTransformOptions;\n\n  /**\n   * How to generate tool descriptions from OpenAPI operations.\n   * - 'summaryOnly': Use only summary (default)\n   * - 'descriptionOnly': Use only description\n   * - 'combined': Summary followed by description\n   * - 'full': Summary, description, and operation details\n   *\n   * @default 'summaryOnly'\n   */\n  descriptionMode?: DescriptionMode;\n\n  /**\n   * Logger instance for adapter diagnostics.\n   * Optional - if not provided, the SDK will inject it automatically via setLogger().\n   */\n  logger?: FrontMcpLogger;\n\n  /**\n   * Timeout for HTTP requests in milliseconds.\n   * If a request takes longer than this, it will be aborted.\n   * @default 30000 (30 seconds)\n   */\n  requestTimeoutMs?: number;\n\n  /**\n   * Maximum request body size in bytes.\n   * Requests with bodies larger than this will be rejected before sending.\n   * @default 10485760 (10MB)\n   */\n  maxRequestSize?: number;\n\n  /**\n   * Maximum response size in bytes.\n   * Responses larger than this will be rejected.\n   * The check is performed first on Content-Length header (if present),\n   * then on actual response size.\n   * @default 10485760 (10MB)\n   */\n  maxResponseSize?: number;\n}\n\ninterface SpecOptions extends BaseOptions {\n  /**\n   * The OpenAPI specification as a JSON object.\n   *\n   * Accepts:\n   * - `OpenAPIV3.Document` (typed)\n   * - `OpenAPIV3_1.Document` (typed)\n   * - Plain object from `import spec from './openapi.json'`\n   *\n   * @example\n   * ```typescript\n   * // From typed constant\n   * import { OpenAPIV3 } from 'openapi-types';\n   * const spec: OpenAPIV3.Document = { ... };\n   * new OpenapiAdapter({ spec, ... })\n   *\n   * // From JSON import\n   * import openapiJson from './my-openapi.json';\n   * new OpenapiAdapter({ spec: openapiJson, ... })\n   * ```\n   */\n  spec: OpenAPIV3.Document | OpenAPIV3_1.Document | object;\n}\n\ninterface UrlOptions extends BaseOptions {\n  /**\n   * The URL of the OpenAPI specification.\n   * Can be a local file path or a remote URL.\n   */\n  url: string;\n}\n\nexport type OpenApiAdapterOptions = SpecOptions | UrlOptions;\n"]}

package/src/openapi/openapi.utils.d.ts

@@ -7,6 +7,14 @@ export interface RequestConfig {
     headers: Headers;
     body?: Record<string, unknown>;
 }
+/**
+ * Validate and normalize a base URL.
+ *
+ * @param url - URL to validate
+ * @returns Validated URL object
+ * @throws Error if URL is invalid or uses unsupported protocol
+ */
+export declare function validateBaseUrl(url: string): URL;
 /**
  * Build HTTP request from OpenAPI tool and input parameters
  *
@@ -24,12 +32,20 @@ export declare function buildRequest(tool: McpOpenAPITool, input: Record<string,
  * @param additionalHeaders - Additional static headers to add
  */
 export declare function applyAdditionalHeaders(headers: Headers, additionalHeaders?: Record<string, string>): void;
+/**
+ * Options for response parsing
+ */
+export interface ParseResponseOptions {
+    /** Maximum response size in bytes (default: 10MB) */
+    maxResponseSize?: number;
+}
 /**
  * Parse API response based on content type
  *
  * @param response - Fetch response
+ * @param options - Optional parsing options
  * @returns Parsed response data
  */
-export declare function parseResponse(response: Response): Promise<{
+export declare function parseResponse(response: Response, options?: ParseResponseOptions): Promise<{
     data: unknown;
 }>;