fraim 2.0.273 → 2.0.274

package/dist/src/cli/commands/add-ide.js

@@ -144,41 +144,18 @@ const configureIDEMCP = async (ide, fraimKey) => {
     else {
         // For JSON configs - intelligent merging
         const newConfig = await (0, mcp_config_generator_1.generateMCPConfig)(ide.configType, fraimKey, {});
-        const newMCPServers = newConfig[serversKey] || newConfig.mcpServers || {};
-        // Merge MCP servers intelligently
-        const mergedMCPServers = { ...existingMCPServers };
-        const addedServers = [];
-        const updatedServers = [];
-        const skippedServers = [];
-        const alwaysUpdateServers = new Set(['fraim']);
-        for (const [serverName, serverConfig] of Object.entries(newMCPServers)) {
-            if (!existingMCPServers[serverName]) {
-                mergedMCPServers[serverName] = serverConfig;
-                addedServers.push(serverName);
-            }
-            else if (alwaysUpdateServers.has(serverName)) {
-                mergedMCPServers[serverName] = serverConfig;
-                updatedServers.push(serverName);
-            }
-            else {
-                skippedServers.push(serverName);
-            }
-        }
-        // Merge with existing config
-        const mergedConfig = {
-            ...existingConfig,
-            ...newConfig,
-            [serversKey]: mergedMCPServers
-        };
+        const { getAllMCPServerIds } = await Promise.resolve().then(() => __importStar(require('../mcp/mcp-server-registry')));
+        const baseServerIds = getAllMCPServerIds();
+        const mergeResult = (0, mcp_config_generator_1.mergeJsonMCPServers)(existingConfig, newConfig, serversKey, baseServerIds);
         // Write updated config
-        fs_1.default.writeFileSync(configPath, JSON.stringify(mergedConfig, null, 2));
-        addedServers.forEach(server => {
+        fs_1.default.writeFileSync(configPath, JSON.stringify(mergeResult.config, null, 2));
+        mergeResult.addedServers.forEach(server => {
             console.log(chalk_1.default.green(`  ✅ Added ${server} MCP server`));
         });
-        updatedServers.forEach(server => {
+        mergeResult.replacedServers.forEach(server => {
             console.log(chalk_1.default.blue(`  Updated ${server} MCP server`));
         });
-        skippedServers.forEach(server => {
+        mergeResult.skippedServers.forEach(server => {
             console.log(chalk_1.default.gray(`  ⏭️ Skipped ${server} (already exists)`));
         });
     }

package/dist/src/cli/commands/doctor.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.doctorCommand = void 0;
 exports.getAllChecks = getAllChecks;
+exports.runFixMcpRepair = runFixMcpRepair;
 const commander_1 = require("commander");
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -14,6 +15,7 @@ const workflow_checks_1 = require("../doctor/checks/workflow-checks");
 const ide_config_checks_1 = require("../doctor/checks/ide-config-checks");
 const mcp_connectivity_checks_1 = require("../doctor/checks/mcp-connectivity-checks");
 const scripts_checks_1 = require("../doctor/checks/scripts-checks");
+const add_ide_1 = require("./add-ide");
 // Read version from package.json
 const getFramVersion = () => {
     try {
@@ -59,19 +61,38 @@ function getAllChecks() {
         ...(0, scripts_checks_1.getScriptsChecks)()
     ];
 }
+async function runFixMcpRepair(options, repair = add_ide_1.runAddIDE) {
+    if (!options.fixMcp) {
+        return;
+    }
+    if (!options.json) {
+        await repair({ all: true });
+        return;
+    }
+    const originalLog = console.log;
+    try {
+        console.log = () => undefined;
+        await repair({ all: true });
+    }
+    finally {
+        console.log = originalLog;
+    }
+}
 exports.doctorCommand = new commander_1.Command('doctor')
     .description('Validate FRAIM installation and configuration')
     .option('--test-mcp', 'Test only MCP server connectivity')
     .option('--test-config', 'Validate only configuration files')
     .option('--test-jobs', 'Check only job status')
+    .option('--fix-mcp', 'Repair FRAIM-owned MCP server entries in detected IDE configs, then validate MCP connectivity')
     .option('--verbose', 'Show detailed output including successful checks')
     .option('--json', 'Output results as JSON')
     .action(async (cmdOptions) => {
     const startTime = Date.now();
     const options = {
-        testMcp: cmdOptions.testMcp,
+        testMcp: cmdOptions.testMcp || cmdOptions.fixMcp,
         testConfig: cmdOptions.testConfig,
         testJobs: cmdOptions.testJobs,
+        fixMcp: cmdOptions.fixMcp,
         verbose: cmdOptions.verbose,
         json: cmdOptions.json
     };
@@ -81,6 +102,7 @@ exports.doctorCommand = new commander_1.Command('doctor')
             testMcp: options.testMcp || false,
             testConfig: options.testConfig || false,
             testJobs: options.testJobs || false,
+            fixMcp: options.fixMcp || false,
             verbose: options.verbose || false,
             json: options.json || false
         }
@@ -94,11 +116,14 @@ exports.doctorCommand = new commander_1.Command('doctor')
         trackMetric('doctor.flags.test_config', 1);
     if (options.testJobs)
         trackMetric('doctor.flags.test_jobs', 1);
+    if (options.fixMcp)
+        trackMetric('doctor.flags.fix_mcp', 1);
     if (options.verbose)
         trackMetric('doctor.flags.verbose', 1);
     if (options.json)
         trackMetric('doctor.flags.json', 1);
     try {
+        await runFixMcpRepair(options);
         // Collect all checks
         const checks = getAllChecks();
         // Run checks

package/dist/src/cli/commands/sync.js

@@ -283,13 +283,18 @@ const runSync = async (options) => {
             console.error(chalk_1.default.red('Local sync requires a FRAIM project directory (fraim/ must exist).'));
             failSync(failHard, 'Local sync requires a project directory.');
         }
+        const localRegistryFiles = await (0, remote_sync_1.fetchRegistryFiles)(localUrl, 'local-dev');
         const result = await syncFromRemote({
             remoteUrl: localUrl,
             apiKey: 'local-dev',
             projectRoot,
-            skipUpdates: true
+            skipUpdates: true,
+            registryFiles: localRegistryFiles
         });
         if (result.success) {
+            // Local-dev sync bypasses Layer 1 (machine-level sync) below, but scripts
+            // still need to land in ~/.fraim/scripts/ or the reported count is a lie.
+            await (0, remote_sync_1.syncScriptsToUserDir)(localRegistryFiles);
             console.log(chalk_1.default.green(`Successfully synced ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, ${result.scriptsSynced} scripts, and ${result.docsSynced} docs from local server`));
             const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
             removeLegacyVersionFromConfig(fraimDir);

package/dist/src/cli/doctor/checks/mcp-connectivity-checks.js

@@ -55,7 +55,6 @@ const axios_1 = __importDefault(require("axios"));
 const toml = __importStar(require("toml"));
 const ide_detector_1 = require("../../setup/ide-detector");
 const fraim_mcp_latest_launcher_1 = require("../../mcp/fraim-mcp-latest-launcher");
-const command_resolution_1 = require("../../mcp/command-resolution");
 const fraim_mcp_diagnostics_1 = require("./fraim-mcp-diagnostics");
 // Cache the npm major version so execFileSync is called at most once per process.
 // Without caching, each IDE config check calls diagnoseFraimMcpLaunchPlan which calls
@@ -123,6 +122,58 @@ function getNpmMajorVersion() {
 function diagnoseFraimMcpLaunchPlan(fraimServer, platform = process.platform, npmMajorVersion = getNpmMajorVersion()) {
     const command = String(fraimServer?.command || '');
     const args = Array.isArray(fraimServer?.args) ? fraimServer.args.map(String) : [];
+    const fraimMcpShimName = platform === 'win32' ? 'fraim-mcp.cmd' : 'fraim-mcp.sh';
+    const fraimMcpShimPath = (0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)();
+    const fraimNpxShimPath = (0, fraim_mcp_latest_launcher_1.getFraimNpxShimPath)();
+    const looksLikeStableFraimShim = command
+        && path_1.default.basename(command).toLowerCase() === fraimMcpShimName
+        && path_1.default.basename(path_1.default.dirname(command)).toLowerCase() === 'bin';
+    const usesStableFraimShim = looksLikeStableFraimShim
+        && path_1.default.resolve(command) === path_1.default.resolve(fraimMcpShimPath);
+    if (usesStableFraimShim) {
+        const missingStableShim = [command, fraimNpxShimPath].find((value) => !fs_1.default.existsSync(value));
+        if (missingStableShim) {
+            return {
+                status: 'error',
+                message: 'FRAIM MCP config references a stable shim that is missing on disk',
+                suggestion: 'Run: fraim doctor --fix-mcp or fraim add-ide to repair local MCP config',
+                details: {
+                    launchPlanSource: 'stale-persisted-path',
+                    phase: 'preflight',
+                    command,
+                    args,
+                    stalePath: missingStableShim,
+                    expectedCommand: fraimMcpShimPath,
+                    companionNpxShim: fraimNpxShimPath
+                }
+            };
+        }
+        return {
+            status: 'passed',
+            message: 'FRAIM MCP config uses the stable FRAIM shim',
+            details: {
+                launchPlanSource: 'fraim-stable-shim',
+                command,
+                expectedCommand: fraimMcpShimPath,
+                companionNpxShim: fraimNpxShimPath
+            }
+        };
+    }
+    if (looksLikeStableFraimShim) {
+        return {
+            status: 'error',
+            message: 'FRAIM MCP config references a stable shim outside the expected FRAIM user bin directory',
+            suggestion: 'Run: fraim doctor --fix-mcp or fraim add-ide to repair local MCP config',
+            details: {
+                launchPlanSource: 'unexpected-stable-shim-path',
+                phase: 'preflight',
+                command,
+                args,
+                expectedCommand: fraimMcpShimPath,
+                companionNpxShim: fraimNpxShimPath
+            }
+        };
+    }
     const usesDirectLatest = command.toLowerCase().includes('npx')
         && args.some((arg) => arg === 'fraim@latest');
     if (usesDirectLatest) {
@@ -152,6 +203,30 @@ function diagnoseFraimMcpLaunchPlan(fraimServer, platform = process.platform, np
             }
         };
     }
+    const absolutePathValues = [command, ...args]
+        .filter((value) => value && path_1.default.isAbsolute(value));
+    const stalePath = absolutePathValues.find((value) => {
+        const lower = value.toLowerCase();
+        return lower.includes(`${path_1.default.sep}temp${path_1.default.sep}`)
+            || lower.includes(`${path_1.default.sep}tmp${path_1.default.sep}`)
+            || lower.includes('fraim-deleted-launcher')
+            || !fs_1.default.existsSync(value);
+    });
+    if (stalePath) {
+        return {
+            status: 'error',
+            message: 'FRAIM MCP config persists a stale runtime or temporary launcher path',
+            suggestion: 'Run: fraim doctor --fix-mcp or fraim add-ide to repair local MCP config',
+            details: {
+                launchPlanSource: 'stale-persisted-path',
+                phase: 'preflight',
+                command,
+                args,
+                stalePath,
+                expectedCommand: fraimMcpShimPath
+            }
+        };
+    }
     return null;
 }
 /**
@@ -868,10 +943,9 @@ async function testStdioMCPServer(serverName, command, args) {
  * Exported separately so callers can obtain just the runtime checks if needed.
  */
 function getStdioMCPRuntimeChecks() {
-    const npx = (0, command_resolution_1.resolveManagedCommand)('npx');
-    // For the fraim MCP server we use the latest launcher so the test
-    // exercises the same path that IDE configs use.
-    const fraimLauncherPath = (0, fraim_mcp_latest_launcher_1.getFraimMcpLatestLauncherPath)();
+    (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
+    const npx = (0, fraim_mcp_latest_launcher_1.getFraimNpxShimPath)();
+    const fraimMcp = (0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)();
     return [
         {
             name: 'git stdio runtime check',
@@ -889,7 +963,7 @@ function getStdioMCPRuntimeChecks() {
             name: 'fraim stdio runtime check',
             category: 'mcpConnectivity',
             critical: false,
-            run: () => testStdioMCPServer('fraim', process.execPath, [fraimLauncherPath])
+            run: () => testStdioMCPServer('fraim', fraimMcp, [])
         }
     ];
 }

package/dist/src/cli/doctor/checks/scripts-checks.js

@@ -168,7 +168,7 @@ function checkPythonAvailability() {
             }
             if (process.platform === 'win32') {
                 // Primary probe: py launcher (not subject to App Execution Alias)
-                const pyResult = (0, child_process_1.spawnSync)('py', ['--version'], { timeout: 1500, encoding: 'utf8' });
+                const pyResult = (0, child_process_1.spawnSync)('py --version', { timeout: 1500, encoding: 'utf8', shell: true });
                 if (pyResult.status === 0) {
                     const version = (pyResult.stdout || pyResult.stderr || '').trim();
                     return {

package/dist/src/cli/mcp/fraim-mcp-latest-launcher.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFraimMcpLatestLauncherPath = getFraimMcpLatestLauncherPath;
+exports.getFraimMcpShimPath = getFraimMcpShimPath;
+exports.getFraimNpxShimPath = getFraimNpxShimPath;
 exports.ensureFraimMcpLatestLauncher = ensureFraimMcpLatestLauncher;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
@@ -113,24 +115,122 @@ process.exit(status);
 function getFraimMcpLatestLauncherPath() {
     return path_1.default.join(process.env.FRAIM_USER_DIR || path_1.default.join(os_1.default.homedir(), '.fraim'), 'bin', 'fraim-mcp-latest.js');
 }
+function getFraimMcpShimPath() {
+    return path_1.default.join(process.env.FRAIM_USER_DIR || path_1.default.join(os_1.default.homedir(), '.fraim'), 'bin', process.platform === 'win32' ? 'fraim-mcp.cmd' : 'fraim-mcp.sh');
+}
+function getFraimNpxShimPath() {
+    return path_1.default.join(process.env.FRAIM_USER_DIR || path_1.default.join(os_1.default.homedir(), '.fraim'), 'bin', process.platform === 'win32' ? 'fraim-npx.cmd' : 'fraim-npx.sh');
+}
+const windowsFraimMcpShimSource = `@echo off
+setlocal
+for %%I in ("%~dp0..") do set "FRAIM_USER_DIR_VALUE=%%~fI"
+where node >nul 2>nul
+if not errorlevel 1 (
+  node "%FRAIM_USER_DIR_VALUE%\\bin\\fraim-mcp-latest.js" %*
+  exit /b %ERRORLEVEL%
+)
+if exist "%FRAIM_USER_DIR_VALUE%\\node\\node.exe" (
+  set "PATH=%FRAIM_USER_DIR_VALUE%\\node;%PATH%"
+  "%FRAIM_USER_DIR_VALUE%\\node\\node.exe" "%FRAIM_USER_DIR_VALUE%\\bin\\fraim-mcp-latest.js" %*
+  exit /b %ERRORLEVEL%
+)
+for /f "delims=" %%D in ('dir /b /ad /o-n "%FRAIM_USER_DIR_VALUE%\\node\\node-v*" 2^>nul') do (
+  if exist "%FRAIM_USER_DIR_VALUE%\\node\\%%D\\node.exe" (
+    set "PATH=%FRAIM_USER_DIR_VALUE%\\node\\%%D;%PATH%"
+    "%FRAIM_USER_DIR_VALUE%\\node\\%%D\\node.exe" "%FRAIM_USER_DIR_VALUE%\\bin\\fraim-mcp-latest.js" %*
+    exit /b %ERRORLEVEL%
+  )
+)
+echo [fraim-mcp] Could not find node on PATH or in "%FRAIM_USER_DIR_VALUE%\\node" 1>&2
+exit /b 1
+`;
+const windowsFraimNpxShimSource = `@echo off
+setlocal
+for %%I in ("%~dp0..") do set "FRAIM_USER_DIR_VALUE=%%~fI"
+where npx >nul 2>nul
+if not errorlevel 1 (
+  npx %*
+  exit /b %ERRORLEVEL%
+)
+if exist "%FRAIM_USER_DIR_VALUE%\\node\\npx.cmd" (
+  "%FRAIM_USER_DIR_VALUE%\\node\\npx.cmd" %*
+  exit /b %ERRORLEVEL%
+)
+for /f "delims=" %%D in ('dir /b /ad /o-n "%FRAIM_USER_DIR_VALUE%\\node\\node-v*" 2^>nul') do (
+  if exist "%FRAIM_USER_DIR_VALUE%\\node\\%%D\\npx.cmd" (
+    "%FRAIM_USER_DIR_VALUE%\\node\\%%D\\npx.cmd" %*
+    exit /b %ERRORLEVEL%
+  )
+)
+echo [fraim-npx] Could not find npx on PATH or in "%FRAIM_USER_DIR_VALUE%\\node" 1>&2
+exit /b 1
+`;
+const posixFraimMcpShimSource = `#!/usr/bin/env sh
+set -eu
+SHIM_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+FRAIM_USER_DIR_VALUE=$(dirname "$SHIM_DIR")
+LAUNCHER="$FRAIM_USER_DIR_VALUE/bin/fraim-mcp-latest.js"
+
+if command -v node >/dev/null 2>&1; then
+  exec node "$LAUNCHER" "$@"
+fi
+if [ -x "$FRAIM_USER_DIR_VALUE/node/bin/node" ]; then
+  PATH="$FRAIM_USER_DIR_VALUE/node/bin:$PATH"
+  export PATH
+  exec "$FRAIM_USER_DIR_VALUE/node/bin/node" "$LAUNCHER" "$@"
+fi
+if [ -x "$FRAIM_USER_DIR_VALUE/node/node" ]; then
+  PATH="$FRAIM_USER_DIR_VALUE/node:$PATH"
+  export PATH
+  exec "$FRAIM_USER_DIR_VALUE/node/node" "$LAUNCHER" "$@"
+fi
+
+echo "[fraim-mcp] Could not find node on PATH or in $FRAIM_USER_DIR_VALUE/node" >&2
+exit 1
+`;
+const posixFraimNpxShimSource = `#!/usr/bin/env sh
+set -eu
+SHIM_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+FRAIM_USER_DIR_VALUE=$(dirname "$SHIM_DIR")
+
+if command -v npx >/dev/null 2>&1; then
+  exec npx "$@"
+fi
+if [ -x "$FRAIM_USER_DIR_VALUE/node/bin/npx" ]; then
+  exec "$FRAIM_USER_DIR_VALUE/node/bin/npx" "$@"
+fi
+if [ -x "$FRAIM_USER_DIR_VALUE/node/npx" ]; then
+  exec "$FRAIM_USER_DIR_VALUE/node/npx" "$@"
+fi
+
+echo "[fraim-npx] Could not find npx on PATH or in $FRAIM_USER_DIR_VALUE/node" >&2
+exit 1
+`;
+const writeFileIfChanged = (filePath, content, mode) => {
+    if (!fs_1.default.existsSync(filePath) || fs_1.default.readFileSync(filePath, 'utf8') !== content) {
+        fs_1.default.writeFileSync(filePath, content, 'utf8');
+    }
+    if (mode !== undefined) {
+        try {
+            fs_1.default.chmodSync(filePath, mode);
+        }
+        catch {
+            // Best effort only. Some filesystems do not support POSIX modes.
+        }
+    }
+};
 function ensureFraimMcpLatestLauncher() {
     const launcherPath = getFraimMcpLatestLauncherPath();
     const launcherDir = path_1.default.dirname(launcherPath);
     fs_1.default.mkdirSync(launcherDir, { recursive: true });
-    if (!fs_1.default.existsSync(launcherPath) || fs_1.default.readFileSync(launcherPath, 'utf8') !== launcherSource) {
-        fs_1.default.writeFileSync(launcherPath, launcherSource, 'utf8');
-        if (process.platform !== 'win32') {
-            try {
-                fs_1.default.chmodSync(launcherPath, 0o755);
-            }
-            catch {
-                // Best effort only. IDE configs invoke this through node, so chmod is not required.
-            }
-        }
-    }
+    writeFileIfChanged(launcherPath, launcherSource, process.platform === 'win32' ? undefined : 0o755);
+    const fraimMcpShimPath = getFraimMcpShimPath();
+    const fraimNpxShimPath = getFraimNpxShimPath();
+    writeFileIfChanged(fraimMcpShimPath, process.platform === 'win32' ? windowsFraimMcpShimSource : posixFraimMcpShimSource, process.platform === 'win32' ? undefined : 0o755);
+    writeFileIfChanged(fraimNpxShimPath, process.platform === 'win32' ? windowsFraimNpxShimSource : posixFraimNpxShimSource, process.platform === 'win32' ? undefined : 0o755);
     return {
-        command: process.execPath,
-        args: [launcherPath],
+        command: fraimMcpShimPath,
+        args: [],
         path: launcherPath
     };
 }

package/dist/src/cli/mcp/mcp-server-registry.js

@@ -16,19 +16,25 @@ exports.BASE_MCP_SERVERS = [
         id: 'git',
         name: 'Git',
         description: 'Git repository operations (commit, branch, merge, etc.)',
-        buildServer: () => ({
-            command: (0, command_resolution_1.resolveManagedCommand)('npx'),
-            args: ['-y', '@cyanheads/git-mcp-server']
-        })
+        buildServer: () => {
+            (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
+            return {
+                command: (0, fraim_mcp_latest_launcher_1.getFraimNpxShimPath)(),
+                args: ['-y', '@cyanheads/git-mcp-server']
+            };
+        }
     },
     {
         id: 'playwright',
         name: 'Playwright',
         description: 'Browser automation and testing',
-        buildServer: () => ({
-            command: (0, command_resolution_1.resolveManagedCommand)('npx'),
-            args: ['-y', '@playwright/mcp']
-        })
+        buildServer: () => {
+            (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
+            return {
+                command: (0, fraim_mcp_latest_launcher_1.getFraimNpxShimPath)(),
+                args: ['-y', '@playwright/mcp']
+            };
+        }
     },
     {
         id: 'fraim',

package/dist/src/cli/setup/mcp-config-generator.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateMCPConfig = exports.generateWindsurfMCPServers = exports.generateCopilotCliMCPServers = exports.generateGeminiCliMCPServers = exports.generateVSCodeMCPServers = exports.generateGrokMCPServers = exports.generateCodexMCPServers = exports.generateKiroMCPServers = exports.generateClaudeCodeMCPServers = exports.generateClaudeMCPServers = exports.generateStandardMCPServers = exports.mergeTomlMCPServers = exports.extractTomlMcpServerBlock = void 0;
+exports.generateMCPConfig = exports.generateWindsurfMCPServers = exports.generateCopilotCliMCPServers = exports.generateGeminiCliMCPServers = exports.generateVSCodeMCPServers = exports.generateGrokMCPServers = exports.generateCodexMCPServers = exports.generateKiroMCPServers = exports.generateClaudeCodeMCPServers = exports.generateClaudeMCPServers = exports.generateStandardMCPServers = exports.mergeJsonMCPServers = exports.mergeTomlMCPServers = exports.extractTomlMcpServerBlock = void 0;
 const mcp_server_builder_1 = require("../mcp/mcp-server-builder");
 const ide_formats_1 = require("../mcp/ide-formats");
 const normalizeTokens = (tokenInput) => {
@@ -91,6 +91,47 @@ const mergeTomlMCPServers = (existingContent, generatedContent, servers) => {
     };
 };
 exports.mergeTomlMCPServers = mergeTomlMCPServers;
+const mergeJsonMCPServers = (existingConfig, generatedConfig, serversKey, servers) => {
+    const existingServers = existingConfig?.[serversKey] || {};
+    const generatedServers = generatedConfig?.[serversKey] || generatedConfig?.mcpServers || {};
+    const mergedServers = { ...existingServers };
+    const addedServers = [];
+    const replacedServers = [];
+    const skippedServers = [];
+    for (const server of servers) {
+        if (!Object.prototype.hasOwnProperty.call(generatedServers, server)) {
+            skippedServers.push(server);
+            continue;
+        }
+        const generatedServer = generatedServers[server];
+        const existingServer = existingServers[server];
+        if (!existingServer) {
+            mergedServers[server] = generatedServer;
+            addedServers.push(server);
+            continue;
+        }
+        if (JSON.stringify(existingServer) === JSON.stringify(generatedServer)) {
+            skippedServers.push(server);
+            continue;
+        }
+        mergedServers[server] = generatedServer;
+        replacedServers.push(server);
+    }
+    return {
+        config: {
+            ...existingConfig,
+            ...generatedConfig,
+            [serversKey]: {
+                ...(generatedConfig?.[serversKey] || {}),
+                ...mergedServers
+            }
+        },
+        addedServers,
+        replacedServers,
+        skippedServers
+    };
+};
+exports.mergeJsonMCPServers = mergeJsonMCPServers;
 // Helper function to add all provider servers with their configs
 const addProviderServers = async (builder, tokens, providerConfigs) => {
     for (const [providerId, token] of Object.entries(tokens)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.273",
+  "version": "2.0.274",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {