#!/usr/bin/env node /** * OpenAPI Spec Normalizer for Mintlify * * Transforms raw OpenAPI JSON specs into Mintlify-compatible format. * Replaces the legacy Java enhance() pipeline and applies MDX-safe * description transformations. * * Usage: * node normalize-spec.js

[options] * * Options: * --output Write to a specific output path * --in-place Overwrite the input file * --check Exit non-zero if changes would be made (for CI) * --diff Print a summary of changes without writing * * Examples: * node normalize-spec.js ../../temp/property-api-v2-raw.json property-api-v2-openapi3 * node normalize-spec.js ../../api_specs/property-api-v2.json property-api-v2-openapi3 --check */ const fs = require('fs'); const path = require('path'); // --------------------------------------------------------------------------- // CLI Argument Parsing // --------------------------------------------------------------------------- function parseArgs(argv) { const args = argv.slice(2); const opts = { inputFile: null, modelName: null, output: null, inPlace: false, check: false, diff: false }; const positional = []; for (let i = 0; i < args.length; i++) { if (args[i] === '--output' && i + 1 < args.length) { opts.output = args[++i]; } else if (args[i] === '--in-place') { opts.inPlace = true; } else if (args[i] === '--check' || args[i] === '--dry-run') { opts.check = true; } else if (args[i] === '--diff') { opts.diff = true; } else if (args[i].startsWith('--')) { console.error(`Unknown option: ${args[i]}`); process.exit(1); } else { positional.push(args[i]); } } if (positional.length < 2) { console.error('Usage: node normalize-spec.js

[options]'); process.exit(1); } opts.inputFile = path.resolve(positional[0]); opts.modelName = positional[1]; return opts; } // --------------------------------------------------------------------------- // Config Loading // --------------------------------------------------------------------------- function loadConfig(modelName) { const configPath = path.join(__dirname, 'config.json'); if (!fs.existsSync(configPath)) { console.error(`Config file not found: ${configPath}`); process.exit(1); } const configs = JSON.parse(fs.readFileSync(configPath, 'utf-8')); const config = configs.find(c => c.apiModelName === modelName); if (!config) { console.error(`No config found for model: ${modelName}`); console.error(`Available models: ${configs.map(c => c.apiModelName).join(', ')}`); process.exit(1); } return { hiddenEndpoints: config.hiddenEndpoints || [], sortOrder: config.sortOrder || {}, }; } // --------------------------------------------------------------------------- // Phase 2: Java enhance() equivalent // --------------------------------------------------------------------------- function removeHiddenEndpoints(spec, hiddenEndpoints) { const paths = spec.paths; if (!paths) return 0; let removed = 0; for (const hidden of hiddenEndpoints) { const pathObj = paths[hidden.path]; if (pathObj && pathObj[hidden.method]) { delete pathObj[hidden.method]; removed++; if (Object.keys(pathObj).length === 0) { delete paths[hidden.path]; } } } return removed; } function sortPaths(spec, sortOrder) { const paths = spec.paths; if (!paths) return; const entries = Object.entries(paths); const sortedKeys = Object.entries(sortOrder) .sort(([, a], [, b]) => a - b) .map(([key]) => key); // Sorted entries first, then remaining in original order const sorted = []; const remaining = []; for (const key of sortedKeys) { const entry = entries.find(([k]) => k === key); if (entry) sorted.push(entry); } for (const [key, val] of entries) { if (!sortedKeys.includes(key)) { remaining.push([key, val]); } } spec.paths = Object.fromEntries([...sorted, ...remaining]); } // --------------------------------------------------------------------------- // Phase 3: Description Transformations // --------------------------------------------------------------------------- /** * Convert HTML tables to markdown-style key-value bullet lists. * Handles the pattern: header row with bold labels, then data rows with pairs. */ function convertHtmlTables(text) { // Extract all tables and convert them return text.replace(/]*>[\s\S]*?<\/table>/gi, (tableHtml) => { const rows = []; const rowMatches = tableHtml.match(/]*>[\s\S]*?<\/tr>/gi) || []; for (const rowHtml of rowMatches) { const cells = []; const cellMatches = rowHtml.match(/]*>[\s\S]*?<\/t[dh]>/gi) || []; for (const cellHtml of cellMatches) { // Strip all HTML from cell content let cellText = cellHtml .replace(//gi, '').replace(/<\/strong>/gi, '') .replace(//gi, '').replace(/<\/b>/gi, '') .replace(/
/gi, '').replace(/<\/p>/gi, '') .replace(/<[^>]+>/g, '') .trim(); if (cellText) cells.push(cellText); } if (cells.length > 0) rows.push(cells); } if (rows.length === 0) return ''; // Check if first row looks like a header (bold labels typically) const result = []; if (rows.length > 1) { // First row is header — format as bold title const headerLabel = rows[0].join(' '); result.push(`**${headerLabel}:**`); // Remaining rows as bullet points with key: value for (let i = 1; i < rows.length; i++) { if (rows[i].length >= 2) { result.push(`- ${rows[i][0]}: \`${rows[i][1]}\``); } else if (rows[i].length === 1) { result.push(`- ${rows[i][0]}`); } } } else { // Single row — just bullet it result.push(`- ${rows[0].join(': ')}`); } return result.join('\n'); }); } /** * Convert HTML URL paragraphs to backtick-wrapped format. * Pattern:
Label

URL: GET ...path
*/ function convertUrlParagraphs(text) { // Match pattern:
Label
followed by
URL: ...
return text.replace( /
\s*([^<]+)<\/strong>\s*<\/p>\s*
\s*(?:URL:\s*)?(GET|POST|PUT|DELETE|PATCH)\s+([^<]+)<\/p>/gi, (_, label, method, url) => { return `**${label.trim()}:** \`${method.toUpperCase()} ${url.trim()}\``; } ); } function stripHtmlToMarkdown(text) { if (typeof text !== 'string') return text; // First handle complex structures before generic tag stripping text = convertHtmlTables(text); text = convertUrlParagraphs(text); // Fix orphaned HTML fragments like }, > BEFORE generic tag stripping text = text.replace(/<\/b>\}/g, ''); text = text.replace(/<\/[a-zA-Z]+>([}>])/g, '$1'); //
,
,
→ newline text = text.replace(//gi, '\n'); //
...
→ **...** (bold, not heading — Mintlify descriptions don't render headers) text = text.replace(/]*>([\s\S]*?)<\/h3>/gi, '**$1**'); // ... and ... → **...** text = text.replace(/([\s\S]*?)<\/b>/gi, '**$1**'); text = text.replace(/([\s\S]*?)<\/strong>/gi, '**$1**'); //
...
→ content with double newlines text = text.replace(/]*>([\s\S]*?)<\/p>/gi, '\n\n$1\n\n'); //
/
→ newline (ensures list starts on its own line) text = text.replace(/<[uo]l[^>]*>/gi, '\n'); //
→ newline + "- " (ensures each bullet is on its own line) text = text.replace(/]*>/gi, '\n- '); text = text.replace(/<\/li>/gi, ''); //
, → newline (ensures content after list starts on new line) text = text.replace(/<\/[uo]l>/gi, '\n'); // Remove any remaining HTML tags text = text.replace(/<[^>]+>/g, ''); // Fix orphaned HTML fragments like }, >, etc. text = text.replace(/<\/[a-zA-Z]+>}/g, ''); text = text.replace(/<\/[a-zA-Z]+>/g, ''); // Remove duplicate adjacent bold headings (e.g., **Title:****Title:**) text = text.replace(/\*\*([^*]+)\*\*\*\*\1\*\*/g, '**$1**'); // Collapse 3+ consecutive newlines to 2 text = text.replace(/\n{3,}/g, '\n\n'); // Clean up leading/trailing whitespace on each line text = text.split('\n').map(line => line.trimEnd()).join('\n'); // Trim overall text = text.trim(); return text; } function escapeCurlyBraces(text) { if (typeof text !== 'string') return text; // Wrap {word} patterns in backticks, but skip if already inside backticks // Strategy: split by backtick spans, only process non-backtick segments const parts = text.split(/(`[^`]*`)/); for (let i = 0; i < parts.length; i++) { // Even indices are outside backticks, odd are inside if (i % 2 === 0) { parts[i] = parts[i].replace(/\{([^}]+)\}/g, (match) => { return '`' + match + '`'; }); } } return parts.join(''); } function fixBulletParagraphSpacing(text) { if (typeof text !== 'string') return text; // After the last bullet item before a non-bullet paragraph, ensure \n\n // Use lookahead so we don't consume the next line (avoids duplication) text = text.replace(/(- [^\n]+)\n(?=[^\n-])/g, '$1\n\n'); return text; } function wrapBareUrls(text) { if (typeof text !== 'string') return text; // Split by backtick spans to avoid double-wrapping const parts = text.split(/(`[^`]*`)/); for (let i = 0; i < parts.length; i++) { if (i % 2 === 0) { // Wrap URLs not already in backticks or markdown links parts[i] = parts[i].replace( /(? '`' + url + '`' ); } } return parts.join(''); } /** * Recursively process all "description" fields in the JSON tree. */ function processDescriptions(obj) { if (obj === null || typeof obj !== 'object') return; if (Array.isArray(obj)) { for (const item of obj) processDescriptions(item); return; } for (const [key, value] of Object.entries(obj)) { if (key === 'description' && typeof value === 'string') { let desc = value; desc = stripHtmlToMarkdown(desc); // Phase 3, step 6-7 desc = wrapBareUrls(desc); // Phase 3, step 10 (before brace escaping so URLs with {param} are wrapped whole) desc = escapeCurlyBraces(desc); // Phase 3, step 8 desc = fixBulletParagraphSpacing(desc); // Phase 3, step 9 obj[key] = desc; } else if (typeof value === 'object') { processDescriptions(value); } } } // --------------------------------------------------------------------------- // Phase 4: Structural OpenAPI Transforms // --------------------------------------------------------------------------- const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch', 'options', 'head', 'trace']; function addXMintMetadata(spec) { const paths = spec.paths || {}; let added = 0; for (const pathObj of Object.values(paths)) { for (const method of HTTP_METHODS) { const op = pathObj[method]; if (op && op.operationId) { op['x-mint'] = { metadata: { title: op.operationId, sidebarTitle: op.operationId, }, }; added++; } } } return added; } function normalizeSecuritySchemes(spec) { if (!spec.components) spec.components = {}; const schemes = spec.components.securitySchemes || {}; // Get existing scheme name, or default to first key, or 'bearer_auth' const schemeName = Object.keys(schemes)[0] || 'bearer_auth'; spec.components.securitySchemes = { [schemeName]: { type: 'http', scheme: 'bearer', }, }; return schemeName; } function ensureTopLevelSecurity(spec, schemeName) { if (!spec.security) { spec.security = [{ [schemeName]: [] }]; return true; } return false; } function removePerOperationSecurity(spec) { const paths = spec.paths || {}; let removed = 0; for (const pathObj of Object.values(paths)) { for (const method of HTTP_METHODS) { const op = pathObj[method]; if (op && op.security) { delete op.security; removed++; } } } return removed; } /** * Ensure the top-level key order follows OpenAPI convention: * openapi, info, servers, tags, security, paths, components */ function reorderTopLevelKeys(spec) { const preferredOrder = ['openapi', 'info', 'servers', 'tags', 'security', 'paths', 'components']; const ordered = {}; for (const key of preferredOrder) { if (spec[key] !== undefined) { ordered[key] = spec[key]; } } // Add any remaining keys not in the preferred order for (const key of Object.keys(spec)) { if (!(key in ordered)) { ordered[key] = spec[key]; } } return ordered; } // --------------------------------------------------------------------------- // Main // --------------------------------------------------------------------------- function main() { const opts = parseArgs(process.argv); // Load input file if (!fs.existsSync(opts.inputFile)) { console.error(`Input file not found: ${opts.inputFile}`); process.exit(1); } const inputJson = fs.readFileSync(opts.inputFile, 'utf-8'); let spec = JSON.parse(inputJson); // Load config const config = loadConfig(opts.modelName); const changes = []; // Phase 2: Remove hidden endpoints const removedCount = removeHiddenEndpoints(spec, config.hiddenEndpoints); if (removedCount > 0) changes.push(`Removed ${removedCount} hidden endpoint(s)`); // Phase 2: Sort paths if (Object.keys(config.sortOrder).length > 0) { sortPaths(spec, config.sortOrder); changes.push(`Sorted paths per config (${Object.keys(config.sortOrder).length} ordered entries)`); } // Phase 3: Process all descriptions processDescriptions(spec); changes.push('Processed all description fields (HTML→Markdown, brace escaping, spacing, URLs)'); // Phase 4: Add x-mint metadata const mintCount = addXMintMetadata(spec); if (mintCount > 0) changes.push(`Added x-mint metadata to ${mintCount} operation(s)`); // Phase 4: Normalize securitySchemes const schemeName = normalizeSecuritySchemes(spec); changes.push(`Normalized securitySchemes to bearer token (scheme: ${schemeName})`); // Phase 4: Ensure top-level security const addedSecurity = ensureTopLevelSecurity(spec, schemeName); if (addedSecurity) changes.push('Added top-level security block'); // Phase 4: Remove per-operation security const removedSecurity = removePerOperationSecurity(spec); if (removedSecurity > 0) changes.push(`Removed ${removedSecurity} per-operation security block(s)`); // Reorder top-level keys spec = reorderTopLevelKeys(spec); // Serialize with 4-space indent const outputJson = JSON.stringify(spec, null, 4) + '\n'; // Check mode: compare with input if (opts.check) { if (outputJson === inputJson) { console.log('✓ Spec is already normalized.'); process.exit(0); } else { console.log('✗ Spec needs normalization. Changes:'); for (const c of changes) console.log(` - ${c}`); process.exit(1); } } // Diff mode if (opts.diff) { console.log('Changes that would be applied:'); for (const c of changes) console.log(` - ${c}`); process.exit(0); } // Determine output path let outputPath; if (opts.output) { outputPath = path.resolve(opts.output); } else if (opts.inPlace) { outputPath = opts.inputFile; } else { // Default: write to normalized-outputs/ directory const outputDir = path.join(__dirname, 'normalized-outputs'); if (!fs.existsSync(outputDir)) { fs.mkdirSync(outputDir, { recursive: true }); } const baseName = path.basename(opts.inputFile, '.json'); outputPath = path.join(outputDir, `${baseName}.normalized.json`); } // Ensure output directory exists const outputDir = path.dirname(outputPath); if (!fs.existsSync(outputDir)) { fs.mkdirSync(outputDir, { recursive: true }); } fs.writeFileSync(outputPath, outputJson, 'utf-8'); console.log(`✓ Normalized spec written to: ${outputPath}`); console.log(` Changes applied:`); for (const c of changes) console.log(` - ${c}`); const pathCount = Object.keys(spec.paths || {}).length; console.log(` Endpoints: ${pathCount}`); } main();

MCP clients

Python example

MCP tester