@loop_ouroboros/mcp-hub-lite 1.0.2 → 1.1.0

package/dist/server/src/utils/logger/log-modules.js

@@ -21,18 +21,17 @@ export const LOG_MODULES = {
     // Core system modules
     SERVER: { module: 'Server' },
     DEV_SERVER: { module: 'DevServer' },
+    RUNNER: { module: 'Runner' },
     // Config management
     CONFIG_MANAGER: { module: 'ConfigManager' },
     CONFIG_LOADER: { module: 'ConfigLoader' },
-    CONFIG_CHANGES: { module: 'System Config Changes' },
-    // Session management
-    SESSION_MANAGER: { module: 'SessionManager' },
-    SESSION: { module: 'Session' },
-    SESSION_API: { module: 'Session API' },
-    SESSION_TRACKER: { module: 'SessionTracker' },
+    CONFIG_SAVER: { module: 'ConfigSaver' },
+    CONFIG_CHANGES: { module: 'SystemConfigManager' },
+    SERVER_CONFIG_MANAGER: { module: 'ServerConfigManager' },
     // Connection management
     CONNECTION_MANAGER: { module: 'ConnectionManager' },
     HUB_MANAGER: { module: 'HubManager' },
+    SERVER_SELECTOR: { module: 'ServerSelector' },
     // Gateway related
     GATEWAY: { module: 'Gateway' },
     GATEWAY_SERVICE: { module: 'GatewayService' },
@@ -40,6 +39,7 @@ export const LOG_MODULES = {
     HUB_TOOLS: { module: 'HubTools' },
     SYSTEM_TOOL: { module: 'SystemTool' },
     TOOL_LIST: { module: 'ToolList' },
+    TOOL_LIST_GENERATOR: { module: 'ToolListGenerator' },
     // Gateway request handlers
     INITIALIZE_HANDLER: { module: 'Initialize' },
     SYSTEM_TOOLS_HANDLER: { module: 'SystemTools' },
@@ -47,6 +47,8 @@ export const LOG_MODULES = {
     TOOLS_HANDLER: { module: 'Tools' },
     // Search service
     SEARCH: { module: 'Search' },
+    // Error handling
+    ERROR_HANDLER: { module: 'ErrorHandler' },
     // Communication
     COMMUNICATION: { module: 'Communication' },
     CONTEXT: { module: 'Context' },

package/dist/server/src/utils/parameter-validator.d.ts

@@ -0,0 +1,10 @@
+import type { JsonSchema } from '../../shared/models/tool.model.js';
+/**
+ * Validates tool arguments against the provided JSON schema
+ *
+ * @param args - The tool arguments to validate
+ * @param schema - The JSON schema to validate against
+ * @returns null if valid, or an error message string if invalid
+ */
+export declare function validateParameters(args: Record<string, unknown>, schema: JsonSchema): string | null;
+//# sourceMappingURL=parameter-validator.d.ts.map

package/dist/server/src/utils/parameter-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameter-validator.d.ts","sourceRoot":"","sources":["../../../../src/utils/parameter-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,UAAU,GACjB,MAAM,GAAG,IAAI,CAyBf"}

package/dist/server/src/utils/parameter-validator.js

@@ -0,0 +1,53 @@
+/**
+ * Validates tool arguments against the provided JSON schema
+ *
+ * @param args - The tool arguments to validate
+ * @param schema - The JSON schema to validate against
+ * @returns null if valid, or an error message string if invalid
+ */
+export function validateParameters(args, schema) {
+    // Check required fields
+    if (schema.required && Array.isArray(schema.required)) {
+        for (const requiredField of schema.required) {
+            if (!(requiredField in args)) {
+                return `Missing required parameter: '${requiredField}'. Required parameters: [${schema.required.join(', ')}]`;
+            }
+        }
+    }
+    // Check parameter types (basic validation)
+    if (schema.properties) {
+        for (const [paramName, paramSchema] of Object.entries(schema.properties)) {
+            if (paramName in args) {
+                const argValue = args[paramName];
+                const expectedType = paramSchema.type;
+                if (expectedType && !isValidType(argValue, expectedType)) {
+                    return `Invalid type for parameter '${paramName}'. Expected: ${expectedType}, got: ${typeof argValue}`;
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Validates if a value matches the expected type
+ *
+ * @param value - The value to validate
+ * @param expectedType - The expected JSON schema type
+ * @returns true if valid, false otherwise
+ */
+function isValidType(value, expectedType) {
+    switch (expectedType) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number';
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'object':
+            return typeof value === 'object' && value !== null && !Array.isArray(value);
+        case 'array':
+            return Array.isArray(value);
+        default:
+            return true; // Cannot validate unknown types, so pass by default
+    }
+}

package/dist/server/src/utils/process-tree.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Windows Process Tree Utility Module
+ *
+ * This module provides process tree management utilities specifically for Windows.
+ * It handles the case where shell: true spawns cmd.exe which then spawns
+ * the actual working process (like node.exe, python.exe, etc.).
+ *
+ * On non-Windows platforms, all methods return safe default values
+ * and don't perform any actual operations.
+ */
+/**
+ * Gets all child process IDs for a given parent PID on Windows.
+ *
+ * @param pid - Parent process ID
+ @returns Promise resolving to array of child PID
+ */
+export declare function getChildren(pid: number): Promise<number[]>;
+/**
+ * Gets the entire process tree (all descendants) for a given PID.
+ * Includes the original PID at the beginning of the array.
+ *
+ * @param pid - Root process ID
+ * @returns Array of all process IDs in the tree
+ */
+export declare function getProcessTree(pid: number): Promise<number[]>;
+/**
+ * Checks if any process in the process tree is still running.
+ *
+ * @param pid - Root process ID
+ * @returns True if any process in the tree is running
+ */
+export declare function isAnyInTreeRunning(pid: number): Promise<boolean>;
+/**
+ * Tries to find the actual working process PID in the tree.
+ * This looks for processes that are likely the actual worker
+ * (node.exe, python.exe, etc.) rather than shell processes.
+ *
+ * @param pid - Root process ID
+ * @returns Working process PID if found, undefined otherwise
+ */
+export declare function getWorkingProcessPid(pid: number): Promise<number | undefined>;
+/**
+ * Kills the entire process tree.
+ *
+ * @param pid - Root process ID
+ * @param signal - Signal to send (default: SIGTERM)
+ */
+export declare function killProcessTree(pid: number, signal?: NodeJS.Signals): Promise<void>;
+//# sourceMappingURL=process-tree.d.ts.map

package/dist/server/src/utils/process-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-tree.d.ts","sourceRoot":"","sources":["../../../../src/utils/process-tree.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBhE;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAqBnE;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBtE;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAkCnF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,MAAM,CAAC,OAAmB,GACjC,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/server/src/utils/process-tree.js

@@ -0,0 +1,285 @@
+import { spawn } from 'child_process';
+import { logger, LOG_MODULES } from './logger.js';
+/**
+ * Windows Process Tree Utility Module
+ *
+ * This module provides process tree management utilities specifically for Windows.
+ * It handles the case where shell: true spawns cmd.exe which then spawns
+ * the actual working process (like node.exe, python.exe, etc.).
+ *
+ * On non-Windows platforms, all methods return safe default values
+ * and don't perform any actual operations.
+ */
+/**
+ * Gets all child process IDs for a given parent PID on Windows.
+ *
+ * @param pid - Parent process ID
+ @returns Promise resolving to array of child PID
+ */
+export async function getChildren(pid) {
+    if (process.platform !== 'win32') {
+        return [];
+    }
+    try {
+        const result = await executePowerShellCommand(`Get-CimInstance Win32_Process | Where-Object { $_.ParentProcessId -eq ${pid} } | Select-Object -ExpandProperty ProcessId`);
+        const pids = parsePidList(result);
+        return pids;
+    }
+    catch (error) {
+        logger.debug(`Failed to get children for PID ${pid}:`, error, LOG_MODULES.STDIO_TRANSPORT);
+        return [];
+    }
+}
+/**
+ * Gets the entire process tree (all descendants) for a given PID.
+ * Includes the original PID at the beginning of the array.
+ *
+ * @param pid - Root process ID
+ * @returns Array of all process IDs in the tree
+ */
+export async function getProcessTree(pid) {
+    if (process.platform !== 'win32') {
+        return [pid];
+    }
+    const tree = [pid];
+    const queue = [pid];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const children = await getChildren(current);
+        for (const child of children) {
+            if (!tree.includes(child)) {
+                tree.push(child);
+                queue.push(child);
+            }
+        }
+    }
+    return tree;
+}
+/**
+ * Checks if any process in the process tree is still running.
+ *
+ * @param pid - Root process ID
+ * @returns True if any process in the tree is running
+ */
+export async function isAnyInTreeRunning(pid) {
+    if (process.platform !== 'win32') {
+        return isProcessRunning(pid);
+    }
+    try {
+        const tree = await getProcessTree(pid);
+        for (const processId of tree) {
+            if (isProcessRunning(processId)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch (error) {
+        logger.debug(`Error checking process tree for PID ${pid}:`, error, LOG_MODULES.STDIO_TRANSPORT);
+        return isProcessRunning(pid);
+    }
+}
+/**
+ * Tries to find the actual working process PID in the tree.
+ * This looks for processes that are likely the actual worker
+ * (node.exe, python.exe, etc.) rather than shell processes.
+ *
+ * @param pid - Root process ID
+ * @returns Working process PID if found, undefined otherwise
+ */
+export async function getWorkingProcessPid(pid) {
+    if (process.platform !== 'win32') {
+        return pid;
+    }
+    try {
+        const tree = await getProcessTree(pid);
+        // If only the root process is in the tree, return it
+        if (tree.length === 1) {
+            return pid;
+        }
+        // Get process names for all PIDs in the tree
+        const processInfo = await getProcessInfo(tree);
+        // Filter out shell processes (cmd.exe, powershell.exe, etc.)
+        const workerProcesses = processInfo.filter((info) => !isShellProcess(info.name));
+        if (workerProcesses.length > 0) {
+            // Prefer the deepest (last) worker process in the tree
+            return workerProcesses[workerProcesses.length - 1].pid;
+        }
+        // If no worker processes found, return the last process in the tree
+        return tree[tree.length - 1];
+    }
+    catch (error) {
+        logger.debug(`Error finding working process for PID ${pid}:`, error, LOG_MODULES.STDIO_TRANSPORT);
+        return pid;
+    }
+}
+/**
+ * Kills the entire process tree.
+ *
+ * @param pid - Root process ID
+ * @param signal - Signal to send (default: SIGTERM)
+ */
+export async function killProcessTree(pid, signal = 'SIGTERM') {
+    if (process.platform !== 'win32') {
+        // On non-Windows, just kill the single process
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // Process might already be dead
+        }
+        return;
+    }
+    try {
+        const tree = await getProcessTree(pid);
+        // Kill processes in reverse order (children first, parent last)
+        for (let i = tree.length - 1; i >= 0; i--) {
+            const processId = tree[i];
+            try {
+                process.kill(processId, signal);
+            }
+            catch {
+                // Process might already be dead
+            }
+        }
+    }
+    catch (error) {
+        logger.debug(`Error killing process tree for PID ${pid}:`, error, LOG_MODULES.STDIO_TRANSPORT);
+        // Fallback: try to kill just the root process
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // Process might already be dead
+        }
+    }
+}
+// ==================== Internal Helper Functions ====================
+/**
+ * Checks if a single process is running.
+ *
+ * @param pid - Process ID
+ * @returns True if process is running
+ */
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Executes a PowerShell command and returns the output.
+ *
+ * @param command - PowerShell command
+ * @returns Command output
+ */
+async function executePowerShellCommand(command) {
+    return new Promise((resolve, reject) => {
+        const ps = spawn('powershell.exe', ['-Command', command], {
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let stdout = '';
+        let stderr = '';
+        ps.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        ps.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+        ps.on('close', (code) => {
+            if (code === 0) {
+                resolve(stdout.trim());
+            }
+            else {
+                reject(new Error(`PowerShell command failed: ${stderr || stdout}`));
+            }
+        });
+        ps.on('error', (error) => {
+            reject(error);
+        });
+    });
+}
+/**
+ * Parses a list of PIDs from command output.
+ *
+ * @param output - Command output
+ * * @returns Array of PIDs
+ */
+function parsePidList(output) {
+    const lines = output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    const pids = [];
+    for (const line of lines) {
+        const pid = parseInt(line, 10);
+        if (!isNaN(pid) && pid > 0) {
+            pids.push(pid);
+        }
+    }
+    return pids;
+}
+/**
+ * Gets process information for multiple PIDs.
+ *
+ * @param pids - Array of process IDs
+ * @returns Array of process info objects
+ */
+async function getProcessInfo(pids) {
+    if (pids.length === 0) {
+        return [];
+    }
+    const result = await executePowerShellCommand(`Get-CimInstance Win32_Process | Where-Object { ${pids.map((pid) => `$_.ProcessId -eq ${pid}`).join(' -or ')} } | Select-Object ProcessId, Name | ConvertTo-Csv -NoTypeInformation`);
+    return parseProcessInfoCsv(result);
+}
+/**
+ * Parses process info from CSV output.
+ *
+ * @param csvOutput - CSV output from PowerShell
+ * @ *returns Array of process info
+ */
+function parseProcessInfoCsv(csvOutput) {
+    const lines = csvOutput
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (lines.length < 2) {
+        return [];
+    }
+    const info = [];
+    // Skip header line
+    for (let i = 1; i < lines.length; i++) {
+        const parts = lines[i].split(',').map((p) => p.trim().replace(/^"|"$/g, ''));
+        if (parts.length >= 2) {
+            const pid = parseInt(parts[0], 10);
+            if (!isNaN(pid) && pid > 0) {
+                info.push({
+                    pid,
+                    name: parts[1].toLowerCase()
+                });
+            }
+        }
+    }
+    return info;
+}
+/**
+ * Checks if a process name is a shell process.
+ *
+ * @param processName - Process name (should be lowercase)
+ * @returns True if it's a shell process
+ */
+function isShellProcess(processName) {
+    const shellProcesses = [
+        'cmd.exe',
+        'powershell.exe',
+        'pwsh.exe',
+        'command.com',
+        'sh.exe',
+        'bash.exe'
+    ];
+    return shellProcesses.includes(processName.toLowerCase());
+}

package/dist/server/src/utils/request-context.d.ts

@@ -50,22 +50,4 @@ export declare const requestContext: AsyncLocalStorage<SessionContext>;
  * ```
  */
 export declare function getSessionContext(): SessionContext | undefined;
-/**
- * Retrieves the current request's working directory (cwd).
- *
- * This is a convenience function that extracts the cwd property from the
- * current request's session context. It's commonly used in file operations
- * that need to respect the session's current working directory.
- *
- * @returns {string | undefined} The current request's working directory, or undefined if not available
- *
- * @example
- * ```typescript
- * const cwd = getSessionCwd();
- * if (cwd) {
- *   const fullPath = path.join(cwd, relativePath);
- * }
- * ```
- */
-export declare function getSessionCwd(): string | undefined;
 //# sourceMappingURL=request-context.d.ts.map

package/dist/server/src/utils/request-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../../../src/utils/request-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAE7E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,mCAA0C,CAAC;AAEtE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD"}
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../../../src/utils/request-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAE7E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,mCAA0C,CAAC;AAEtE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D"}

package/dist/server/src/utils/request-context.js

@@ -51,23 +51,3 @@ export const requestContext = new AsyncLocalStorage();
 export function getSessionContext() {
     return requestContext.getStore();
 }
-/**
- * Retrieves the current request's working directory (cwd).
- *
- * This is a convenience function that extracts the cwd property from the
- * current request's session context. It's commonly used in file operations
- * that need to respect the session's current working directory.
- *
- * @returns {string | undefined} The current request's working directory, or undefined if not available
- *
- * @example
- * ```typescript
- * const cwd = getSessionCwd();
- * if (cwd) {
- *   const fullPath = path.join(cwd, relativePath);
- * }
- * ```
- */
-export function getSessionCwd() {
-    return requestContext.getStore()?.cwd;
-}

package/dist/server/src/utils/sort-utils.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Object key sorting utilities for consistent configuration.
+ */
+/**
+ * Sorts object keys alphabetically using localeCompare.
+ * Returns a new object with sorted keys, preserving the original object.
+ *
+ * @param obj - Object to sort
+ * @returns New object with sorted keys
+ */
+export declare function sortObjectKeys<T extends Record<string, unknown>>(obj: T): T;
+/**
+ * Sorts object keys alphabetically, case-insensitive.
+ * Returns a new object with sorted keys, preserving the original object and original key case.
+ *
+ * @param obj - Object to sort
+ * @returns New object with sorted keys (case-insensitive sort)
+ */
+export declare function sortObjectKeysCaseInsensitive<T extends Record<string, unknown>>(obj: T): T;
+/**
+ * Recursively sorts all object keys in a nested structure.
+ * Returns a new object with all nested keys sorted, preserving the original object.
+ *
+ * @param obj - Object to sort recursively
+ * @returns New object with all nested keys sorted
+ */
+export declare function sortObjectKeysDeep<T>(obj: T): T;
+/**
+ * Sorts env and headers objects in a server configuration.
+ * This is a convenience function for server template/instance configurations.
+ * Also normalizes URL fields by removing trailing slashes.
+ *
+ * @param config - Server configuration object with optional env and headers
+ * @returns New object with sorted env and headers keys and normalized URLs
+ */
+export declare function sortServerConfigEnvHeaders<T extends {
+    env?: Record<string, string>;
+    headers?: Record<string, string>;
+}>(config: T): T;
+//# sourceMappingURL=sort-utils.d.ts.map

package/dist/server/src/utils/sort-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort-utils.d.ts","sourceRoot":"","sources":["../../../../src/utils/sort-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAoDH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAW3E;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAa1F;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAmB/C;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,CAAC,SAAS;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EAC5E,MAAM,EAAE,CAAC,GAAG,CAAC,CAcd"}

package/dist/server/src/utils/sort-utils.js

@@ -0,0 +1,131 @@
+/**
+ * Object key sorting utilities for consistent configuration.
+ */
+/**
+ * Normalizes a URL string by removing trailing slashes.
+ *
+ * @param url - The URL to normalize
+ * @returns Normalized URL
+ */
+function normalizeUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+/**
+ * Normalizes URL fields in a configuration object.
+ * Currently handles:
+ * - url fields at any level
+ * - proxy.url fields
+ *
+ * @param obj - Object to normalize
+ * @returns New object with normalized URLs
+ */
+function normalizeConfigUrls(obj) {
+    if (!obj) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => normalizeConfigUrls(item));
+    }
+    if (typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === 'url' && typeof value === 'string') {
+                result[key] = normalizeUrl(value);
+            }
+            else if (key === 'proxy' && typeof value === 'object' && value !== null) {
+                const proxy = value;
+                if (typeof proxy.url === 'string') {
+                    result[key] = { ...proxy, url: normalizeUrl(proxy.url) };
+                }
+                else {
+                    result[key] = normalizeConfigUrls(value);
+                }
+            }
+            else {
+                result[key] = normalizeConfigUrls(value);
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Sorts object keys alphabetically using localeCompare.
+ * Returns a new object with sorted keys, preserving the original object.
+ *
+ * @param obj - Object to sort
+ * @returns New object with sorted keys
+ */
+export function sortObjectKeys(obj) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+        return obj;
+    }
+    const sortedObj = {};
+    const keys = Object.keys(obj).sort((a, b) => a.localeCompare(b));
+    for (const key of keys) {
+        sortedObj[key] = obj[key];
+    }
+    return sortedObj;
+}
+/**
+ * Sorts object keys alphabetically, case-insensitive.
+ * Returns a new object with sorted keys, preserving the original object and original key case.
+ *
+ * @param obj - Object to sort
+ * @returns New object with sorted keys (case-insensitive sort)
+ */
+export function sortObjectKeysCaseInsensitive(obj) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+        return obj;
+    }
+    const sortedObj = {};
+    const keys = Object.keys(obj).sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }));
+    for (const key of keys) {
+        sortedObj[key] = obj[key];
+    }
+    return sortedObj;
+}
+/**
+ * Recursively sorts all object keys in a nested structure.
+ * Returns a new object with all nested keys sorted, preserving the original object.
+ *
+ * @param obj - Object to sort recursively
+ * @returns New object with all nested keys sorted
+ */
+export function sortObjectKeysDeep(obj) {
+    if (!obj) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => sortObjectKeysDeep(item));
+    }
+    if (typeof obj === 'object') {
+        const sortedObj = {};
+        const keys = Object.keys(obj).sort((a, b) => a.localeCompare(b));
+        for (const key of keys) {
+            sortedObj[key] = sortObjectKeysDeep(obj[key]);
+        }
+        return sortedObj;
+    }
+    return obj;
+}
+/**
+ * Sorts env and headers objects in a server configuration.
+ * This is a convenience function for server template/instance configurations.
+ * Also normalizes URL fields by removing trailing slashes.
+ *
+ * @param config - Server configuration object with optional env and headers
+ * @returns New object with sorted env and headers keys and normalized URLs
+ */
+export function sortServerConfigEnvHeaders(config) {
+    // First normalize URLs
+    const normalized = normalizeConfigUrls(config);
+    const result = { ...normalized };
+    if (result.env) {
+        result.env = sortObjectKeysCaseInsensitive(result.env);
+    }
+    if (result.headers) {
+        result.headers = sortObjectKeysCaseInsensitive(result.headers);
+    }
+    return result;
+}