@frontmcp/adapters 0.5.1 → 0.6.0

package/src/openapi/openapi.frontmcp-schema.js

@@ -0,0 +1,358 @@
+"use strict";
+/**
+ * Zod schemas for x-frontmcp OpenAPI extension validation.
+ *
+ * The x-frontmcp extension allows embedding FrontMCP-specific configuration
+ * directly in OpenAPI specs. This module provides versioned schema validation
+ * to ensure only valid data is used and invalid fields are warned about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrontMcpExampleSchema = exports.FrontMcpCodeCallSchema = exports.FrontMcpCacheSchema = exports.FrontMcpAnnotationsSchema = exports.SUPPORTED_VERSIONS = exports.FRONTMCP_SCHEMA_VERSION = void 0;
+exports.validateFrontMcpExtension = validateFrontMcpExtension;
+const zod_1 = require("zod");
+/**
+ * Current schema version for x-frontmcp extension.
+ * Increment when making breaking changes to the schema.
+ */
+exports.FRONTMCP_SCHEMA_VERSION = '1.0';
+/**
+ * Supported schema versions.
+ */
+exports.SUPPORTED_VERSIONS = ['1.0'];
+// ============================================================================
+// Annotations Schema (v1.0)
+// ============================================================================
+/**
+ * Tool annotations schema - hints about tool behavior for AI clients.
+ */
+exports.FrontMcpAnnotationsSchema = zod_1.z.object({
+    /** Human-readable title for the tool */
+    title: zod_1.z.string().optional(),
+    /** If true, the tool does not modify its environment */
+    readOnlyHint: zod_1.z.boolean().optional(),
+    /** If true, the tool may perform destructive updates */
+    destructiveHint: zod_1.z.boolean().optional(),
+    /** If true, calling repeatedly with same args has no additional effect */
+    idempotentHint: zod_1.z.boolean().optional(),
+    /** If true, tool may interact with external entities */
+    openWorldHint: zod_1.z.boolean().optional(),
+});
+// ============================================================================
+// Cache Schema (v1.0)
+// ============================================================================
+/**
+ * Cache configuration schema.
+ */
+exports.FrontMcpCacheSchema = zod_1.z.object({
+    /** Time-to-live in seconds for cached responses */
+    ttl: zod_1.z.number().int().positive().optional(),
+    /** If true, cache window slides on each access */
+    slideWindow: zod_1.z.boolean().optional(),
+});
+// ============================================================================
+// CodeCall Schema (v1.0)
+// ============================================================================
+/**
+ * CodeCall plugin configuration schema.
+ */
+exports.FrontMcpCodeCallSchema = zod_1.z.object({
+    /** Whether this tool can be used via CodeCall */
+    enabledInCodeCall: zod_1.z.boolean().optional(),
+    /** If true, stays visible in list_tools when CodeCall is active */
+    visibleInListTools: zod_1.z.boolean().optional(),
+});
+// ============================================================================
+// Example Schema (v1.0)
+// ============================================================================
+/**
+ * Tool usage example schema.
+ */
+exports.FrontMcpExampleSchema = zod_1.z.object({
+    /** Description of the example */
+    description: zod_1.z.string(),
+    /** Example input values */
+    input: zod_1.z.record(zod_1.z.string(), zod_1.z.any()),
+    /** Expected output (optional) */
+    output: zod_1.z.any().optional(),
+});
+// ============================================================================
+// Known Fields for Validation
+// ============================================================================
+/** Known field names for validation */
+const KNOWN_EXTENSION_FIELDS = new Set([
+    'version',
+    'annotations',
+    'cache',
+    'codecall',
+    'tags',
+    'hideFromDiscovery',
+    'examples',
+]);
+const KNOWN_ANNOTATION_FIELDS = new Set([
+    'title',
+    'readOnlyHint',
+    'destructiveHint',
+    'idempotentHint',
+    'openWorldHint',
+]);
+const KNOWN_CACHE_FIELDS = new Set(['ttl', 'slideWindow']);
+const KNOWN_CODECALL_FIELDS = new Set(['enabledInCodeCall', 'visibleInListTools']);
+// ============================================================================
+// Schema Validation Functions
+// ============================================================================
+/**
+ * Validate and parse x-frontmcp extension data.
+ *
+ * This function:
+ * 1. Detects the schema version (defaults to current)
+ * 2. Validates each field against the appropriate schema
+ * 3. Returns only valid fields, ignoring invalid ones
+ * 4. Collects warnings for invalid/unknown fields
+ *
+ * @param rawData - Raw x-frontmcp data from OpenAPI spec
+ * @param toolName - Tool name for error context
+ * @param logger - Logger for warnings
+ * @returns Validation result with valid data and warnings
+ */
+function validateFrontMcpExtension(rawData, toolName, logger) {
+    const warnings = [];
+    // Handle null/undefined
+    if (rawData === null || rawData === undefined) {
+        return { success: true, data: null, warnings: [] };
+    }
+    // Must be an object
+    if (typeof rawData !== 'object' || Array.isArray(rawData)) {
+        warnings.push(`x-frontmcp must be an object, got ${Array.isArray(rawData) ? 'array' : typeof rawData}`);
+        logger.warn(`[${toolName}] Invalid x-frontmcp extension: ${warnings[0]}`);
+        return { success: false, data: null, warnings };
+    }
+    const data = rawData;
+    // Detect version
+    const version = typeof data['version'] === 'string' ? data['version'] : exports.FRONTMCP_SCHEMA_VERSION;
+    // Check if version is supported
+    if (!exports.SUPPORTED_VERSIONS.includes(version)) {
+        warnings.push(`Unsupported x-frontmcp version '${version}'. Supported versions: ${exports.SUPPORTED_VERSIONS.join(', ')}`);
+        logger.warn(`[${toolName}] ${warnings[0]}`);
+        return { success: false, data: null, warnings };
+    }
+    // Extract valid fields and collect warnings
+    const validData = extractValidFields(data, version, warnings);
+    if (warnings.length > 0) {
+        logger.warn(`[${toolName}] x-frontmcp extension has invalid fields that were ignored:`);
+        warnings.forEach((w) => logger.warn(`  - ${w}`));
+    }
+    return {
+        success: true,
+        data: validData,
+        warnings,
+    };
+}
+/**
+ * Extract valid fields from x-frontmcp data, collecting warnings for invalid fields.
+ */
+function extractValidFields(data, version, warnings) {
+    const result = {
+        version: version,
+    };
+    // Warn about unknown top-level fields
+    for (const key of Object.keys(data)) {
+        if (!KNOWN_EXTENSION_FIELDS.has(key)) {
+            warnings.push(`Unknown field '${key}' in x-frontmcp (will be ignored)`);
+        }
+    }
+    // Validate annotations
+    if (data['annotations'] !== undefined) {
+        const annotationsResult = exports.FrontMcpAnnotationsSchema.safeParse(data['annotations']);
+        if (annotationsResult.success) {
+            result.annotations = annotationsResult.data;
+        }
+        else {
+            const issues = formatZodIssues(annotationsResult.error.issues, 'annotations');
+            warnings.push(...issues);
+            // Try to extract valid annotation fields
+            result.annotations = extractValidAnnotations(data['annotations'], warnings);
+        }
+    }
+    // Validate cache
+    if (data['cache'] !== undefined) {
+        const cacheResult = exports.FrontMcpCacheSchema.safeParse(data['cache']);
+        if (cacheResult.success) {
+            result.cache = cacheResult.data;
+        }
+        else {
+            const issues = formatZodIssues(cacheResult.error.issues, 'cache');
+            warnings.push(...issues);
+            // Try to extract valid cache fields
+            result.cache = extractValidCache(data['cache'], warnings);
+        }
+    }
+    // Validate codecall
+    if (data['codecall'] !== undefined) {
+        const codecallResult = exports.FrontMcpCodeCallSchema.safeParse(data['codecall']);
+        if (codecallResult.success) {
+            result.codecall = codecallResult.data;
+        }
+        else {
+            const issues = formatZodIssues(codecallResult.error.issues, 'codecall');
+            warnings.push(...issues);
+            // Try to extract valid codecall fields
+            result.codecall = extractValidCodeCall(data['codecall'], warnings);
+        }
+    }
+    // Validate tags
+    if (data['tags'] !== undefined) {
+        const tagsSchema = zod_1.z.array(zod_1.z.string());
+        const tagsResult = tagsSchema.safeParse(data['tags']);
+        if (tagsResult.success) {
+            result.tags = tagsResult.data;
+        }
+        else {
+            warnings.push(`Invalid 'tags': expected array of strings`);
+            // Try to extract valid tags
+            result.tags = extractValidTags(data['tags']);
+        }
+    }
+    // Validate hideFromDiscovery
+    if (data['hideFromDiscovery'] !== undefined) {
+        if (typeof data['hideFromDiscovery'] === 'boolean') {
+            result.hideFromDiscovery = data['hideFromDiscovery'];
+        }
+        else {
+            warnings.push(`Invalid 'hideFromDiscovery': expected boolean, got ${typeof data['hideFromDiscovery']}`);
+        }
+    }
+    // Validate examples
+    if (data['examples'] !== undefined) {
+        const examplesSchema = zod_1.z.array(exports.FrontMcpExampleSchema);
+        const examplesResult = examplesSchema.safeParse(data['examples']);
+        if (examplesResult.success) {
+            result.examples = examplesResult.data;
+        }
+        else {
+            warnings.push(`Invalid 'examples': some examples have invalid format`);
+            // Try to extract valid examples
+            result.examples = extractValidExamples(data['examples'], warnings);
+        }
+    }
+    return result;
+}
+/**
+ * Extract valid annotation fields.
+ */
+function extractValidAnnotations(data, warnings) {
+    if (typeof data !== 'object' || data === null)
+        return undefined;
+    const obj = data;
+    const result = {};
+    for (const field of KNOWN_ANNOTATION_FIELDS) {
+        if (obj[field] !== undefined) {
+            if (field === 'title' && typeof obj[field] === 'string') {
+                result.title = obj[field];
+            }
+            else if (field !== 'title' && typeof obj[field] === 'boolean') {
+                result[field] = obj[field];
+            }
+        }
+    }
+    // Warn about unknown annotation fields
+    for (const key of Object.keys(obj)) {
+        if (!KNOWN_ANNOTATION_FIELDS.has(key)) {
+            warnings.push(`Unknown field 'annotations.${key}' (will be ignored)`);
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * Extract valid cache fields.
+ */
+function extractValidCache(data, warnings) {
+    if (typeof data !== 'object' || data === null)
+        return undefined;
+    const obj = data;
+    const result = {};
+    if (typeof obj['ttl'] === 'number' && Number.isInteger(obj['ttl']) && obj['ttl'] > 0) {
+        result.ttl = obj['ttl'];
+    }
+    else if (obj['ttl'] !== undefined) {
+        warnings.push(`Invalid 'cache.ttl': expected positive integer`);
+    }
+    if (typeof obj['slideWindow'] === 'boolean') {
+        result.slideWindow = obj['slideWindow'];
+    }
+    else if (obj['slideWindow'] !== undefined) {
+        warnings.push(`Invalid 'cache.slideWindow': expected boolean`);
+    }
+    // Warn about unknown cache fields
+    for (const key of Object.keys(obj)) {
+        if (!KNOWN_CACHE_FIELDS.has(key)) {
+            warnings.push(`Unknown field 'cache.${key}' (will be ignored)`);
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * Extract valid codecall fields.
+ */
+function extractValidCodeCall(data, warnings) {
+    if (typeof data !== 'object' || data === null)
+        return undefined;
+    const obj = data;
+    const result = {};
+    if (typeof obj['enabledInCodeCall'] === 'boolean') {
+        result.enabledInCodeCall = obj['enabledInCodeCall'];
+    }
+    else if (obj['enabledInCodeCall'] !== undefined) {
+        warnings.push(`Invalid 'codecall.enabledInCodeCall': expected boolean`);
+    }
+    if (typeof obj['visibleInListTools'] === 'boolean') {
+        result.visibleInListTools = obj['visibleInListTools'];
+    }
+    else if (obj['visibleInListTools'] !== undefined) {
+        warnings.push(`Invalid 'codecall.visibleInListTools': expected boolean`);
+    }
+    // Warn about unknown codecall fields
+    for (const key of Object.keys(obj)) {
+        if (!KNOWN_CODECALL_FIELDS.has(key)) {
+            warnings.push(`Unknown field 'codecall.${key}' (will be ignored)`);
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * Extract valid tags from array.
+ */
+function extractValidTags(data) {
+    if (!Array.isArray(data))
+        return undefined;
+    const validTags = data.filter((item) => typeof item === 'string');
+    return validTags.length > 0 ? validTags : undefined;
+}
+/**
+ * Extract valid examples from array.
+ */
+function extractValidExamples(data, warnings) {
+    if (!Array.isArray(data))
+        return undefined;
+    const validExamples = [];
+    for (let i = 0; i < data.length; i++) {
+        const item = data[i];
+        const result = exports.FrontMcpExampleSchema.safeParse(item);
+        if (result.success) {
+            validExamples.push(result.data);
+        }
+        else {
+            warnings.push(`Invalid example at index ${i}: ${formatZodIssues(result.error.issues, `examples[${i}]`).join(', ')}`);
+        }
+    }
+    return validExamples.length > 0 ? validExamples : undefined;
+}
+/**
+ * Format Zod validation issues into readable messages.
+ */
+function formatZodIssues(issues, prefix) {
+    return issues.map((issue) => {
+        const path = issue.path.length > 0 ? `${prefix}.${issue.path.join('.')}` : prefix;
+        return `Invalid '${path}': ${issue.message}`;
+    });
+}
+//# sourceMappingURL=openapi.frontmcp-schema.js.map

package/src/openapi/openapi.frontmcp-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.frontmcp-schema.js","sourceRoot":"","sources":["../../../src/openapi/openapi.frontmcp-schema.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Zod schemas for x-frontmcp OpenAPI extension validation.\n *\n * The x-frontmcp extension allows embedding FrontMCP-specific configuration\n * directly in OpenAPI specs. This module provides versioned schema validation\n * to ensure only valid data is used and invalid fields are warned about.\n */\n\nimport { z } from 'zod';\nimport type { FrontMcpLogger } from '@frontmcp/sdk';\n\n/**\n * Current schema version for x-frontmcp extension.\n * Increment when making breaking changes to the schema.\n */\nexport const FRONTMCP_SCHEMA_VERSION = '1.0' as const;\n\n/**\n * Supported schema versions.\n */\nexport const SUPPORTED_VERSIONS = ['1.0'] as const;\nexport type FrontMcpSchemaVersion = (typeof SUPPORTED_VERSIONS)[number];\n\n// ============================================================================\n// Annotations Schema (v1.0)\n// ============================================================================\n\n/**\n * Tool annotations schema - hints about tool behavior for AI clients.\n */\nexport const FrontMcpAnnotationsSchema = z.object({\n  /** Human-readable title for the tool */\n  title: z.string().optional(),\n  /** If true, the tool does not modify its environment */\n  readOnlyHint: z.boolean().optional(),\n  /** If true, the tool may perform destructive updates */\n  destructiveHint: z.boolean().optional(),\n  /** If true, calling repeatedly with same args has no additional effect */\n  idempotentHint: z.boolean().optional(),\n  /** If true, tool may interact with external entities */\n  openWorldHint: z.boolean().optional(),\n});\n\nexport type FrontMcpAnnotations = z.infer<typeof FrontMcpAnnotationsSchema>;\n\n// ============================================================================\n// Cache Schema (v1.0)\n// ============================================================================\n\n/**\n * Cache configuration schema.\n */\nexport const FrontMcpCacheSchema = z.object({\n  /** Time-to-live in seconds for cached responses */\n  ttl: z.number().int().positive().optional(),\n  /** If true, cache window slides on each access */\n  slideWindow: z.boolean().optional(),\n});\n\nexport type FrontMcpCache = z.infer<typeof FrontMcpCacheSchema>;\n\n// ============================================================================\n// CodeCall Schema (v1.0)\n// ============================================================================\n\n/**\n * CodeCall plugin configuration schema.\n */\nexport const FrontMcpCodeCallSchema = z.object({\n  /** Whether this tool can be used via CodeCall */\n  enabledInCodeCall: z.boolean().optional(),\n  /** If true, stays visible in list_tools when CodeCall is active */\n  visibleInListTools: z.boolean().optional(),\n});\n\nexport type FrontMcpCodeCall = z.infer<typeof FrontMcpCodeCallSchema>;\n\n// ============================================================================\n// Example Schema (v1.0)\n// ============================================================================\n\n/**\n * Tool usage example schema.\n */\nexport const FrontMcpExampleSchema = z.object({\n  /** Description of the example */\n  description: z.string(),\n  /** Example input values */\n  input: z.record(z.string(), z.any()),\n  /** Expected output (optional) */\n  output: z.any().optional(),\n});\n\nexport type FrontMcpExample = z.infer<typeof FrontMcpExampleSchema>;\n\n// ============================================================================\n// Known Fields for Validation\n// ============================================================================\n\n/** Known field names for validation */\nconst KNOWN_EXTENSION_FIELDS = new Set([\n  'version',\n  'annotations',\n  'cache',\n  'codecall',\n  'tags',\n  'hideFromDiscovery',\n  'examples',\n]);\n\nconst KNOWN_ANNOTATION_FIELDS = new Set([\n  'title',\n  'readOnlyHint',\n  'destructiveHint',\n  'idempotentHint',\n  'openWorldHint',\n]);\n\nconst KNOWN_CACHE_FIELDS = new Set(['ttl', 'slideWindow']);\nconst KNOWN_CODECALL_FIELDS = new Set(['enabledInCodeCall', 'visibleInListTools']);\n\n// ============================================================================\n// Validated Extension Type (after parsing)\n// ============================================================================\n\n/**\n * Validated x-frontmcp extension data.\n * This is the output after schema validation.\n */\nexport interface ValidatedFrontMcpExtension {\n  version: FrontMcpSchemaVersion;\n  annotations?: FrontMcpAnnotations;\n  cache?: FrontMcpCache;\n  codecall?: FrontMcpCodeCall;\n  tags?: string[];\n  hideFromDiscovery?: boolean;\n  examples?: FrontMcpExample[];\n}\n\n// ============================================================================\n// Validation Result\n// ============================================================================\n\nexport interface FrontMcpValidationResult {\n  /** Whether validation succeeded (may still have warnings) */\n  success: boolean;\n  /** Validated data (only valid fields) */\n  data: ValidatedFrontMcpExtension | null;\n  /** Validation warnings (invalid fields that were ignored) */\n  warnings: string[];\n}\n\n// ============================================================================\n// Schema Validation Functions\n// ============================================================================\n\n/**\n * Validate and parse x-frontmcp extension data.\n *\n * This function:\n * 1. Detects the schema version (defaults to current)\n * 2. Validates each field against the appropriate schema\n * 3. Returns only valid fields, ignoring invalid ones\n * 4. Collects warnings for invalid/unknown fields\n *\n * @param rawData - Raw x-frontmcp data from OpenAPI spec\n * @param toolName - Tool name for error context\n * @param logger - Logger for warnings\n * @returns Validation result with valid data and warnings\n */\nexport function validateFrontMcpExtension(\n  rawData: unknown,\n  toolName: string,\n  logger: FrontMcpLogger,\n): FrontMcpValidationResult {\n  const warnings: string[] = [];\n\n  // Handle null/undefined\n  if (rawData === null || rawData === undefined) {\n    return { success: true, data: null, warnings: [] };\n  }\n\n  // Must be an object\n  if (typeof rawData !== 'object' || Array.isArray(rawData)) {\n    warnings.push(`x-frontmcp must be an object, got ${Array.isArray(rawData) ? 'array' : typeof rawData}`);\n    logger.warn(`[${toolName}] Invalid x-frontmcp extension: ${warnings[0]}`);\n    return { success: false, data: null, warnings };\n  }\n\n  const data = rawData as Record<string, unknown>;\n\n  // Detect version\n  const version = typeof data['version'] === 'string' ? data['version'] : FRONTMCP_SCHEMA_VERSION;\n\n  // Check if version is supported\n  if (!SUPPORTED_VERSIONS.includes(version as FrontMcpSchemaVersion)) {\n    warnings.push(`Unsupported x-frontmcp version '${version}'. Supported versions: ${SUPPORTED_VERSIONS.join(', ')}`);\n    logger.warn(`[${toolName}] ${warnings[0]}`);\n    return { success: false, data: null, warnings };\n  }\n\n  // Extract valid fields and collect warnings\n  const validData = extractValidFields(data, version, warnings);\n\n  if (warnings.length > 0) {\n    logger.warn(`[${toolName}] x-frontmcp extension has invalid fields that were ignored:`);\n    warnings.forEach((w) => logger.warn(`  - ${w}`));\n  }\n\n  return {\n    success: true,\n    data: validData,\n    warnings,\n  };\n}\n\n/**\n * Extract valid fields from x-frontmcp data, collecting warnings for invalid fields.\n */\nfunction extractValidFields(\n  data: Record<string, unknown>,\n  version: string,\n  warnings: string[],\n): ValidatedFrontMcpExtension {\n  const result: ValidatedFrontMcpExtension = {\n    version: version as FrontMcpSchemaVersion,\n  };\n\n  // Warn about unknown top-level fields\n  for (const key of Object.keys(data)) {\n    if (!KNOWN_EXTENSION_FIELDS.has(key)) {\n      warnings.push(`Unknown field '${key}' in x-frontmcp (will be ignored)`);\n    }\n  }\n\n  // Validate annotations\n  if (data['annotations'] !== undefined) {\n    const annotationsResult = FrontMcpAnnotationsSchema.safeParse(data['annotations']);\n    if (annotationsResult.success) {\n      result.annotations = annotationsResult.data;\n    } else {\n      const issues = formatZodIssues(annotationsResult.error.issues, 'annotations');\n      warnings.push(...issues);\n      // Try to extract valid annotation fields\n      result.annotations = extractValidAnnotations(data['annotations'], warnings);\n    }\n  }\n\n  // Validate cache\n  if (data['cache'] !== undefined) {\n    const cacheResult = FrontMcpCacheSchema.safeParse(data['cache']);\n    if (cacheResult.success) {\n      result.cache = cacheResult.data;\n    } else {\n      const issues = formatZodIssues(cacheResult.error.issues, 'cache');\n      warnings.push(...issues);\n      // Try to extract valid cache fields\n      result.cache = extractValidCache(data['cache'], warnings);\n    }\n  }\n\n  // Validate codecall\n  if (data['codecall'] !== undefined) {\n    const codecallResult = FrontMcpCodeCallSchema.safeParse(data['codecall']);\n    if (codecallResult.success) {\n      result.codecall = codecallResult.data;\n    } else {\n      const issues = formatZodIssues(codecallResult.error.issues, 'codecall');\n      warnings.push(...issues);\n      // Try to extract valid codecall fields\n      result.codecall = extractValidCodeCall(data['codecall'], warnings);\n    }\n  }\n\n  // Validate tags\n  if (data['tags'] !== undefined) {\n    const tagsSchema = z.array(z.string());\n    const tagsResult = tagsSchema.safeParse(data['tags']);\n    if (tagsResult.success) {\n      result.tags = tagsResult.data;\n    } else {\n      warnings.push(`Invalid 'tags': expected array of strings`);\n      // Try to extract valid tags\n      result.tags = extractValidTags(data['tags']);\n    }\n  }\n\n  // Validate hideFromDiscovery\n  if (data['hideFromDiscovery'] !== undefined) {\n    if (typeof data['hideFromDiscovery'] === 'boolean') {\n      result.hideFromDiscovery = data['hideFromDiscovery'];\n    } else {\n      warnings.push(`Invalid 'hideFromDiscovery': expected boolean, got ${typeof data['hideFromDiscovery']}`);\n    }\n  }\n\n  // Validate examples\n  if (data['examples'] !== undefined) {\n    const examplesSchema = z.array(FrontMcpExampleSchema);\n    const examplesResult = examplesSchema.safeParse(data['examples']);\n    if (examplesResult.success) {\n      result.examples = examplesResult.data;\n    } else {\n      warnings.push(`Invalid 'examples': some examples have invalid format`);\n      // Try to extract valid examples\n      result.examples = extractValidExamples(data['examples'], warnings);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Extract valid annotation fields.\n */\nfunction extractValidAnnotations(data: unknown, warnings: string[]): FrontMcpAnnotations | undefined {\n  if (typeof data !== 'object' || data === null) return undefined;\n\n  const obj = data as Record<string, unknown>;\n  const result: FrontMcpAnnotations = {};\n\n  for (const field of KNOWN_ANNOTATION_FIELDS) {\n    if (obj[field] !== undefined) {\n      if (field === 'title' && typeof obj[field] === 'string') {\n        result.title = obj[field] as string;\n      } else if (field !== 'title' && typeof obj[field] === 'boolean') {\n        (result as Record<string, unknown>)[field] = obj[field];\n      }\n    }\n  }\n\n  // Warn about unknown annotation fields\n  for (const key of Object.keys(obj)) {\n    if (!KNOWN_ANNOTATION_FIELDS.has(key)) {\n      warnings.push(`Unknown field 'annotations.${key}' (will be ignored)`);\n    }\n  }\n\n  return Object.keys(result).length > 0 ? result : undefined;\n}\n\n/**\n * Extract valid cache fields.\n */\nfunction extractValidCache(data: unknown, warnings: string[]): FrontMcpCache | undefined {\n  if (typeof data !== 'object' || data === null) return undefined;\n\n  const obj = data as Record<string, unknown>;\n  const result: FrontMcpCache = {};\n\n  if (typeof obj['ttl'] === 'number' && Number.isInteger(obj['ttl']) && obj['ttl'] > 0) {\n    result.ttl = obj['ttl'];\n  } else if (obj['ttl'] !== undefined) {\n    warnings.push(`Invalid 'cache.ttl': expected positive integer`);\n  }\n\n  if (typeof obj['slideWindow'] === 'boolean') {\n    result.slideWindow = obj['slideWindow'];\n  } else if (obj['slideWindow'] !== undefined) {\n    warnings.push(`Invalid 'cache.slideWindow': expected boolean`);\n  }\n\n  // Warn about unknown cache fields\n  for (const key of Object.keys(obj)) {\n    if (!KNOWN_CACHE_FIELDS.has(key)) {\n      warnings.push(`Unknown field 'cache.${key}' (will be ignored)`);\n    }\n  }\n\n  return Object.keys(result).length > 0 ? result : undefined;\n}\n\n/**\n * Extract valid codecall fields.\n */\nfunction extractValidCodeCall(data: unknown, warnings: string[]): FrontMcpCodeCall | undefined {\n  if (typeof data !== 'object' || data === null) return undefined;\n\n  const obj = data as Record<string, unknown>;\n  const result: FrontMcpCodeCall = {};\n\n  if (typeof obj['enabledInCodeCall'] === 'boolean') {\n    result.enabledInCodeCall = obj['enabledInCodeCall'];\n  } else if (obj['enabledInCodeCall'] !== undefined) {\n    warnings.push(`Invalid 'codecall.enabledInCodeCall': expected boolean`);\n  }\n\n  if (typeof obj['visibleInListTools'] === 'boolean') {\n    result.visibleInListTools = obj['visibleInListTools'];\n  } else if (obj['visibleInListTools'] !== undefined) {\n    warnings.push(`Invalid 'codecall.visibleInListTools': expected boolean`);\n  }\n\n  // Warn about unknown codecall fields\n  for (const key of Object.keys(obj)) {\n    if (!KNOWN_CODECALL_FIELDS.has(key)) {\n      warnings.push(`Unknown field 'codecall.${key}' (will be ignored)`);\n    }\n  }\n\n  return Object.keys(result).length > 0 ? result : undefined;\n}\n\n/**\n * Extract valid tags from array.\n */\nfunction extractValidTags(data: unknown): string[] | undefined {\n  if (!Array.isArray(data)) return undefined;\n\n  const validTags = data.filter((item): item is string => typeof item === 'string');\n  return validTags.length > 0 ? validTags : undefined;\n}\n\n/**\n * Extract valid examples from array.\n */\nfunction extractValidExamples(data: unknown, warnings: string[]): FrontMcpExample[] | undefined {\n  if (!Array.isArray(data)) return undefined;\n\n  const validExamples: FrontMcpExample[] = [];\n\n  for (let i = 0; i < data.length; i++) {\n    const item = data[i];\n    const result = FrontMcpExampleSchema.safeParse(item);\n    if (result.success) {\n      validExamples.push(result.data);\n    } else {\n      warnings.push(\n        `Invalid example at index ${i}: ${formatZodIssues(result.error.issues, `examples[${i}]`).join(', ')}`,\n      );\n    }\n  }\n\n  return validExamples.length > 0 ? validExamples : undefined;\n}\n\n/** Zod issue shape for formatting */\ninterface ZodIssue {\n  path: PropertyKey[];\n  message: string;\n}\n\n/**\n * Format Zod validation issues into readable messages.\n */\nfunction formatZodIssues(issues: ZodIssue[], prefix: string): string[] {\n  return issues.map((issue) => {\n    const path = issue.path.length > 0 ? `${prefix}.${issue.path.join('.')}` : prefix;\n    return `Invalid '${path}': ${issue.message}`;\n  });\n}\n"]}

package/src/openapi/openapi.security.d.ts

@@ -1,5 +1,5 @@
 import { type McpOpenAPITool, type SecurityContext } from 'mcp-from-openapi';
-import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import type { FrontMcpContext } from '@frontmcp/sdk';
 import type { OpenApiAdapterOptions } from './openapi.types';
 /**
  * Security scheme information extracted from OpenAPI spec
@@ -21,14 +21,14 @@ export interface SecurityValidationResult {
     securityRiskScore: 'low' | 'medium' | 'high';
 }
 /**
- * Resolve security context from FrontMCP auth info with support for multiple auth providers
+ * Resolve security context from FrontMCP context with support for multiple auth providers
  *
  * @param tool - OpenAPI tool to resolve security for
- * @param authInfo - FrontMCP authentication info
+ * @param ctx - FrontMCP request context with authInfo, sessionId, traceId, etc.
  * @param options - Adapter options with auth configuration
  * @returns Security context for resolver
  */
-export declare function createSecurityContextFromAuth(tool: McpOpenAPITool, authInfo: AuthInfo, options: Pick<OpenApiAdapterOptions, 'securityResolver' | 'authProviderMapper' | 'staticAuth'>): Promise<SecurityContext>;
+export declare function createSecurityContextFromAuth(tool: McpOpenAPITool, ctx: FrontMcpContext, options: Pick<OpenApiAdapterOptions, 'securityResolver' | 'authProviderMapper' | 'staticAuth'>): Promise<SecurityContext>;
 /**
  * Extract all security schemes used by a set of tools
  *
@@ -43,14 +43,14 @@ export declare function extractSecuritySchemes(tools: McpOpenAPITool[]): Set<str
  * @param options - Adapter options
  * @returns Validation result with errors and warnings
  */
-export declare function validateSecurityConfiguration(tools: McpOpenAPITool[], options: Pick<OpenApiAdapterOptions, 'securityResolver' | 'authProviderMapper' | 'staticAuth' | 'generateOptions'>): SecurityValidationResult;
+export declare function validateSecurityConfiguration(tools: McpOpenAPITool[], options: Pick<OpenApiAdapterOptions, 'securityResolver' | 'authProviderMapper' | 'staticAuth' | 'generateOptions' | 'securitySchemesInInput'>): SecurityValidationResult;
 /**
  * Resolve security for an OpenAPI tool with validation
  *
  * @param tool - OpenAPI tool with mapper
- * @param authInfo - FrontMCP authentication info
+ * @param ctx - FrontMCP request context with authInfo, sessionId, traceId, etc.
  * @param options - Adapter options with auth configuration
  * @returns Resolved security (headers, query params, etc.)
  * @throws Error if security cannot be resolved
  */
-export declare function resolveToolSecurity(tool: McpOpenAPITool, authInfo: AuthInfo, options: Pick<OpenApiAdapterOptions, 'securityResolver' | 'authProviderMapper' | 'staticAuth'>): Promise<import("mcp-from-openapi").ResolvedSecurity>;
+export declare function resolveToolSecurity(tool: McpOpenAPITool, ctx: FrontMcpContext, options: Pick<OpenApiAdapterOptions, 'securityResolver' | 'authProviderMapper' | 'staticAuth'>): Promise<import("mcp-from-openapi").ResolvedSecurity>;

package/src/openapi/openapi.security.js

@@ -6,17 +6,17 @@ exports.validateSecurityConfiguration = validateSecurityConfiguration;
 exports.resolveToolSecurity = resolveToolSecurity;
 const mcp_from_openapi_1 = require("mcp-from-openapi");
 /**
- * Resolve security context from FrontMCP auth info with support for multiple auth providers
+ * Resolve security context from FrontMCP context with support for multiple auth providers
  *
  * @param tool - OpenAPI tool to resolve security for
- * @param authInfo - FrontMCP authentication info
+ * @param ctx - FrontMCP request context with authInfo, sessionId, traceId, etc.
  * @param options - Adapter options with auth configuration
  * @returns Security context for resolver
  */
-async function createSecurityContextFromAuth(tool, authInfo, options) {
+async function createSecurityContextFromAuth(tool, ctx, options) {
     // 1. Use custom security resolver if provided (highest priority)
     if (options.securityResolver) {
-        return await options.securityResolver(tool, authInfo);
+        return await options.securityResolver(tool, ctx);
     }
     // 2. Use auth provider mapper if provided
     if (options.authProviderMapper) {
@@ -29,21 +29,74 @@ async function createSecurityContextFromAuth(tool, authInfo, options) {
             }
         }
         // Map each security scheme to its auth provider
+        // Process all schemes - first matching token for each auth type (jwt, apiKey, basic, oauth2Token)
         for (const scheme of securitySchemes) {
             const authExtractor = options.authProviderMapper[scheme];
             if (authExtractor) {
-                const token = authExtractor(authInfo);
-                if (token) {
-                    // Store in jwt field for http bearer auth
-                    // For other auth types, you can extend this logic
-                    context.jwt = token;
-                    break; // Use first matching provider
+                try {
+                    const token = authExtractor(ctx);
+                    // Validate return type - must be string or undefined/null
+                    if (token !== undefined && token !== null && typeof token !== 'string') {
+                        throw new Error(`authProviderMapper['${scheme}'] must return a string or undefined, ` + `but returned: ${typeof token}`);
+                    }
+                    // Reject empty string tokens explicitly - indicates misconfiguration
+                    if (token === '') {
+                        throw new Error(`authProviderMapper['${scheme}'] returned empty string. ` +
+                            `Return undefined/null if no token is available, or provide a valid token.`);
+                    }
+                    if (token) {
+                        // Route token to correct context field based on scheme type
+                        // Look up the scheme info from the mapper to determine type
+                        const schemeMapper = tool.mapper.find((m) => m.security?.scheme === scheme);
+                        const schemeType = schemeMapper?.security?.type?.toLowerCase();
+                        const httpScheme = schemeMapper?.security?.httpScheme?.toLowerCase();
+                        // Route based on security scheme type (first token for each type wins)
+                        if (schemeType === 'apikey') {
+                            if (!context.apiKey) {
+                                context.apiKey = token;
+                            }
+                        }
+                        else if (schemeType === 'http' && httpScheme === 'basic') {
+                            if (!context.basic) {
+                                context.basic = token;
+                            }
+                        }
+                        else if (schemeType === 'oauth2') {
+                            if (!context.oauth2Token) {
+                                context.oauth2Token = token;
+                            }
+                        }
+                        else {
+                            // Default to jwt for http bearer and unknown types
+                            if (!context.jwt) {
+                                context.jwt = token;
+                            }
+                        }
+                        // Continue checking other schemes - don't break
+                        // This allows validation to see all configured providers
+                    }
+                }
+                catch (err) {
+                    // Re-throw validation errors as-is
+                    if (err instanceof Error && err.message.includes('authProviderMapper')) {
+                        throw err;
+                    }
+                    // Wrap other errors with context
+                    const errorMessage = err instanceof Error ? err.message : String(err);
+                    throw new Error(`authProviderMapper['${scheme}'] threw an error: ${errorMessage}`);
                 }
             }
         }
-        // If no provider matched but we have a default token, use it
-        if (!context.jwt && authInfo.token) {
-            context.jwt = authInfo.token;
+        // If no auth was set from providers, fall back to ctx.authInfo.token
+        // Only fall back if ALL auth fields are empty (not just jwt)
+        const hasAnyAuth = context.jwt || context.apiKey || context.basic || context.oauth2Token;
+        const authToken = ctx.authInfo?.token;
+        if (!hasAnyAuth && authToken) {
+            // Validate type before assignment to prevent non-string values
+            if (typeof authToken !== 'string') {
+                throw new Error(`authInfo.token must be a string, but got: ${typeof authToken}`);
+            }
+            context.jwt = authToken;
         }
         return context;
     }
@@ -53,7 +106,7 @@ async function createSecurityContextFromAuth(tool, authInfo, options) {
     }
     // 4. Default: use main JWT token from auth context
     return (0, mcp_from_openapi_1.createSecurityContext)({
-        jwt: authInfo?.token,
+        jwt: ctx.authInfo?.token,
     });
 }
 /**
@@ -110,12 +163,23 @@ function validateSecurityConfiguration(tools, options) {
         // If static auth is provided, assume it covers all schemes
         return result;
     }
+    // Get schemes that will be provided via input (don't need mapping)
+    const schemesInInput = new Set(options.securitySchemesInInput || []);
     // Check authProviderMapper (low risk - context-based auth)
-    if (options.authProviderMapper) {
-        result.securityRiskScore = 'low';
-        // Validate that all schemes have mappings
+    if (options.authProviderMapper || schemesInInput.size > 0) {
+        result.securityRiskScore = schemesInInput.size > 0 ? 'medium' : 'low';
+        // Log info about per-scheme control
+        if (schemesInInput.size > 0) {
+            result.warnings.push(`INFO: Per-scheme security control enabled. Schemes in input: ${Array.from(schemesInInput).join(', ')}`);
+        }
+        // Validate that all schemes have mappings (except those in input)
         for (const scheme of securitySchemes) {
-            if (!options.authProviderMapper[scheme]) {
+            // Skip schemes that will be provided via input
+            if (schemesInInput.has(scheme)) {
+                continue;
+            }
+            // Check if there's a mapping for this scheme
+            if (!options.authProviderMapper?.[scheme]) {
                 result.valid = false;
                 result.missingMappings.push(scheme);
             }
@@ -138,14 +202,14 @@ function validateSecurityConfiguration(tools, options) {
  * Resolve security for an OpenAPI tool with validation
  *
  * @param tool - OpenAPI tool with mapper
- * @param authInfo - FrontMCP authentication info
+ * @param ctx - FrontMCP request context with authInfo, sessionId, traceId, etc.
  * @param options - Adapter options with auth configuration
  * @returns Resolved security (headers, query params, etc.)
  * @throws Error if security cannot be resolved
  */
-async function resolveToolSecurity(tool, authInfo, options) {
+async function resolveToolSecurity(tool, ctx, options) {
     const securityResolver = new mcp_from_openapi_1.SecurityResolver();
-    const securityContext = await createSecurityContextFromAuth(tool, authInfo, options);
+    const securityContext = await createSecurityContextFromAuth(tool, ctx, options);
     // Validate that we have auth for this tool
     const hasAuth = securityContext.jwt ||
         securityContext.apiKey ||
@@ -154,18 +218,22 @@ async function resolveToolSecurity(tool, authInfo, options) {
         (securityContext.apiKeys && Object.keys(securityContext.apiKeys).length > 0) ||
         (securityContext.customHeaders && Object.keys(securityContext.customHeaders).length > 0);
     // Check if this tool requires security
-    const requiresSecurity = tool.mapper.some((m) => m.security && m.required);
+    // A tool requires security ONLY if a mapper has security with required=true
+    // Optional security schemes (required=false or undefined) should not block requests
+    const requiresSecurity = tool.mapper.some((m) => m.security && m.required === true);
     if (requiresSecurity && !hasAuth) {
-        // Extract security scheme names
-        const schemes = tool.mapper
-            .filter((m) => m.security && m.required)
-            .map((m) => m.security?.scheme ?? 'unknown')
-            .join(', ');
+        // Extract required security scheme names for error message
+        const requiredSchemes = tool.mapper
+            .filter((m) => m.security && m.required === true)
+            .map((m) => m.security?.scheme ?? 'unknown');
+        const uniqueSchemes = [...new Set(requiredSchemes)];
+        const schemesStr = uniqueSchemes.join(', ') || 'unknown';
+        const firstScheme = uniqueSchemes[0] || 'BearerAuth';
         throw new Error(`Authentication required for tool '${tool.name}' but no auth configuration found.\n` +
-            `Required security schemes: ${schemes}\n` +
+            `Required security schemes: ${schemesStr}\n` +
             `Solutions:\n` +
-            `  1. Add authProviderMapper: { '${schemes.split(',')[0].trim()}': (authInfo) => authInfo.user?.token }\n` +
-            `  2. Add securityResolver: (tool, authInfo) => ({ jwt: authInfo.token })\n` +
+            `  1. Add authProviderMapper: { '${firstScheme}': (ctx) => ctx.authInfo.user?.token }\n` +
+            `  2. Add securityResolver: (tool, ctx) => ({ jwt: ctx.authInfo.token })\n` +
             `  3. Add staticAuth: { jwt: process.env.API_TOKEN }\n` +
             `  4. Set generateOptions.includeSecurityInInput: true (not recommended for production)`);
     }