genexus-mcp 3.2.1 → 3.2.3

package/cli/lib/config.js

@@ -22,6 +22,28 @@ function generateConfig(gxPath, kbPath) {
     };
 }
 
+function generateNeutralConfig(gxPath, { workerPath, gatewayMode = 'stdio-isolated', resolutionPolicy = 'strict' } = {}) {
+    return {
+        ConfigSchemaVersion: 2,
+        GatewayMode: gatewayMode,
+        GeneXus: {
+            InstallationPath: gxPath,
+            WorkerExecutable: workerPath || path.join(path.dirname(getGatewayExePath()), 'worker', 'GxMcp.Worker.exe')
+        },
+        Server: {
+            HttpPort: 0,
+            McpStdio: true,
+            SessionIdleTimeoutMinutes: 10,
+            WorkerIdleTimeoutMinutes: 5,
+            EmitStructuredContent: false,
+            TerseResponses: true
+        },
+        Environment: {
+            ResolutionPolicy: resolutionPolicy
+        }
+    };
+}
+
 function getGatewayExePath() {
     if (process.env.GENEXUS_MCP_GATEWAY_EXE) {
         return process.env.GENEXUS_MCP_GATEWAY_EXE;
@@ -381,9 +403,9 @@ function stripJsonComments(text) {
     return out;
 }
 
-function readJsonFileSafe(filePath) {
+function readJsonFileSafe(filePath, fileSystem = fs) {
     try {
-        const raw = fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '');
+        const raw = fileSystem.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '');
         if (!raw.trim()) return {};
         try {
             return JSON.parse(raw);
@@ -406,69 +428,151 @@ function readJsonFileSafe(filePath) {
 
 // Atomic write: stage to a temp file then rename over the target, so a crash
 // mid-write can never leave a client's config truncated.
-function writeFileAtomic(filePath, content) {
+function writeFileAtomic(filePath, content, fileSystem = fs) {
     const tmp = `${filePath}.tmp-${process.pid}`;
-    fs.writeFileSync(tmp, content);
+    fileSystem.writeFileSync(tmp, content);
     try {
-        fs.renameSync(tmp, filePath);
+        fileSystem.renameSync(tmp, filePath);
     } catch (err) {
-        try { fs.rmSync(tmp, { force: true }); } catch { /* ignore */ }
+        try { fileSystem.rmSync(tmp, { force: true }); } catch { /* ignore */ }
         throw err;
     }
 }
 
 // Back up a client config once per process run before the first mutation, so the
 // user has a restore point (the old build-from-source install.ps1 did this; the
-// CLI now owns it). Best-effort \u2014 a failed backup never blocks the write.
+// CLI now owns it). A failed backup blocks the mutation so the result remains
+// recoverable.
 // After writing a new backup, prune old .bak files for the same config so at
 // most BAK_KEEP_COUNT backups exist (oldest removed first).
 const BAK_KEEP_COUNT = 5;
 const _backedUpThisRun = new Set();
-function backupClientConfigOnce(filePath) {
-    if (!fs.existsSync(filePath)) return null;
+function backupClientConfigOnce(filePath, fileSystem = fs) {
+    if (!fileSystem.existsSync(filePath)) return null;
     // Case-fold the dedupe key only on Windows; lowercasing on a case-sensitive
     // filesystem could merge two genuinely distinct paths.
     const resolved = path.resolve(filePath);
     const key = process.platform === 'win32' ? resolved.toLowerCase() : resolved;
     if (_backedUpThisRun.has(key)) return null;
-    try {
-        const d = new Date();
+    const d = new Date();
         const stamp = d.toISOString().replace(/[-:T]/g, '').slice(0, 14);
-        const bak = `${filePath}.${stamp}.bak`;
-        fs.copyFileSync(filePath, bak);
+        let bak = `${filePath}.${stamp}.bak`;
+        let suffix = 1;
+        while (fileSystem.existsSync(bak)) bak = `${filePath}.${stamp}-${suffix++}.bak`;
+        fileSystem.copyFileSync(filePath, bak);
         _backedUpThisRun.add(key);
         // Prune: keep only the BAK_KEEP_COUNT most-recent .bak files for this config.
         try {
             const dir = path.dirname(resolved);
             const base = path.basename(resolved);
             const bakPattern = new RegExp(`^${base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.\\d{14}\\.bak$`);
-            const existing = fs.readdirSync(dir)
+            const existing = fileSystem.readdirSync(dir)
                 .filter(f => bakPattern.test(f))
                 .map(f => path.join(dir, f))
                 .sort(); // ISO timestamp stamps sort lexicographically = chronologically
             if (existing.length > BAK_KEEP_COUNT) {
                 const toRemove = existing.slice(0, existing.length - BAK_KEEP_COUNT);
                 for (const old of toRemove) {
-                    try { fs.rmSync(old, { force: true }); } catch { /* best-effort */ }
+                    try { fileSystem.rmSync(old, { force: true }); } catch { /* best-effort */ }
                 }
             }
         } catch { /* pruning is best-effort; never block the backup */ }
-        return bak;
-    } catch {
-        return null;
-    }
+    return bak;
 }
 
 // Write JSON to a client config: back up, serialize, write atomically.
-function writeClientJson(filePath, obj) {
-    backupClientConfigOnce(filePath);
-    writeFileAtomic(filePath, JSON.stringify(obj, null, 2));
+function writeClientJson(filePath, obj, fileSystem = fs) {
+    backupClientConfigOnce(filePath, fileSystem);
+    writeFileAtomic(filePath, JSON.stringify(obj, null, 2), fileSystem);
 }
 
 // Write raw text to a client config (e.g. Codex TOML): back up + write atomically.
-function writeClientText(filePath, content) {
-    backupClientConfigOnce(filePath);
-    writeFileAtomic(filePath, content);
+function writeClientText(filePath, content, fileSystem = fs) {
+    backupClientConfigOnce(filePath, fileSystem);
+    writeFileAtomic(filePath, content, fileSystem);
+}
+
+function copyFileAtomic(sourcePath, targetPath, fileSystem = fs) {
+    const tmp = `${targetPath}.tmp-${process.pid}`;
+    fileSystem.copyFileSync(sourcePath, tmp);
+    try {
+        fileSystem.renameSync(tmp, targetPath);
+    } catch (err) {
+        try { fileSystem.rmSync(tmp, { force: true }); } catch { /* ignore */ }
+        throw err;
+    }
+}
+
+function migrateLegacyConfig(sourcePath, targetPath, { rejectNonMigratable = false, fileSystem = fs } = {}) {
+    const source = path.resolve(sourcePath);
+    const target = path.resolve(targetPath);
+    const legacy = readJsonFileSafe(source, fileSystem);
+    if (!legacy || typeof legacy !== 'object') {
+        const err = new Error(`Legacy config is missing or invalid: ${source}`);
+        err.code = 'INVALID_CONFIG';
+        throw err;
+    }
+
+    const env = legacy.Environment && typeof legacy.Environment === 'object' ? legacy.Environment : {};
+    const notMigrated = ['KBPath', 'KBs', 'DefaultKb', 'ActiveKb']
+        .filter((key) => Object.prototype.hasOwnProperty.call(env, key))
+        .map((key) => `Environment.${key}`);
+    if (rejectNonMigratable && notMigrated.length > 0) {
+        const err = new Error(`Migration rejected non-migratable fields: ${notMigrated.join(', ')}.`);
+        err.code = 'NON_MIGRATABLE_FIELDS';
+        err.notMigrated = notMigrated;
+        throw err;
+    }
+
+    const migrated = {
+        ConfigSchemaVersion: 2,
+        GatewayMode: legacy.GatewayMode || 'stdio-isolated',
+        GeneXus: { ...(legacy.GeneXus && typeof legacy.GeneXus === 'object' ? legacy.GeneXus : {}) },
+        Server: { ...(legacy.Server && typeof legacy.Server === 'object' ? legacy.Server : {}) },
+        Environment: {
+            ResolutionPolicy: env.ResolutionPolicy || 'strict'
+        }
+    };
+    const backupPath = (() => {
+        let candidate = `${source}.pre-migrate.bak`;
+        let suffix = 1;
+        while (fileSystem.existsSync(candidate)) candidate = `${source}.pre-migrate-${suffix++}.bak`;
+        return candidate;
+    })();
+    const targetExisted = fileSystem.existsSync(target);
+    const targetBackup = targetExisted ? `${target}.rollback-${process.pid}-${Date.now()}.bak` : null;
+    let wroteTarget = false;
+    try {
+        copyFileAtomic(source, backupPath, fileSystem);
+        if (targetExisted) copyFileAtomic(target, targetBackup, fileSystem);
+        fileSystem.mkdirSync(path.dirname(target), { recursive: true });
+        writeFileAtomic(target, JSON.stringify(migrated, null, 2), fileSystem);
+        wroteTarget = true;
+        const readBack = process.env.GENEXUS_MCP_MIGRATE_FAIL_READBACK
+            ? null
+            : readJsonFileSafe(target, fileSystem);
+        if (!readBack || readBack.ConfigSchemaVersion !== 2 || JSON.stringify(readBack) !== JSON.stringify(migrated)) {
+            throw new Error('Migration read-back verification failed.');
+        }
+        if (targetBackup) {
+            try { fileSystem.rmSync(targetBackup, { force: true }); } catch { /* best effort */ }
+        }
+        return { sourcePath: source, targetPath: target, backupPath, readBack: true, migrated: Object.keys(migrated), notMigrated, rolledBack: false };
+    } catch (err) {
+        let rolledBack = false;
+        try {
+            if (targetExisted && targetBackup) copyFileAtomic(targetBackup, target, fileSystem);
+            else if (wroteTarget) fileSystem.rmSync(target, { force: true });
+            rolledBack = true;
+        } catch { /* report rollback failure */ }
+        if (targetBackup) {
+            try { fileSystem.rmSync(targetBackup, { force: true }); } catch { /* best effort */ }
+        }
+        err.rollback = { rolledBack };
+        err.backupPath = backupPath;
+        err.notMigrated = notMigrated;
+        throw err;
+    }
 }
 
 function resolveConfigPathNoMutate(cwd) {
@@ -869,6 +973,7 @@ function patchClientConfig(targetConfigPath, opts = {}) {
     // user only finds out when each one fails with "Failed to connect".
     const serverName = opts.serverName || DEFAULT_MCP_SERVER_NAME;
     const force = Boolean(opts.force);
+    const fileSystem = opts.fs || fs;
     const onlyExisting = opts.onlyExisting !== false;
     const candidates = filterClientTargets(getClientConfigTargets(), {
         ids: opts.ids,
@@ -923,11 +1028,16 @@ function patchClientConfig(targetConfigPath, opts = {}) {
             continue;
         }
         try {
-            fs.mkdirSync(path.dirname(client.path), { recursive: true });
-            applyClientEntry(client, getLauncher(client), targetConfigPath, { serverName, force });
+            fileSystem.mkdirSync(path.dirname(client.path), { recursive: true });
+            applyClientEntry(client, getLauncher(client), targetConfigPath, {
+                serverName,
+                force,
+                globalConfig: Boolean(opts.globalConfig),
+                fs: fileSystem
+            });
             // Read-back: confirm the entry is actually present and the file still
             // parses, so a silently-corrupted write is reported as a failure.
-            if (!readClientCommandEntry(client, serverName)) {
+            if (!readClientCommandEntry(client, serverName, { fs: fileSystem })) {
                 throw new Error(`post-write verification failed (${serverName} entry not found after write)`);
             }
             patched.push(client.name);
@@ -978,8 +1088,8 @@ function removeClientEntry(client, opts = {}) {
     return getClientAdapter(client.format).remove(client, opts);
 }
 
-function applyMcpServersJson(filePath, launcher, targetConfigPath, { serverName = DEFAULT_MCP_SERVER_NAME, force = false } = {}) {
-    const parsed = fs.existsSync(filePath) ? readJsonFileSafe(filePath) : {};
+function applyMcpServersJson(filePath, launcher, targetConfigPath, { serverName = DEFAULT_MCP_SERVER_NAME, force = false, globalConfig = false, fs: fileSystem = fs } = {}) {
+    const parsed = fileSystem.existsSync(filePath) ? readJsonFileSafe(filePath, fileSystem) : {};
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
     cfgObj.mcpServers = cfgObj.mcpServers || {};
@@ -989,7 +1099,11 @@ function applyMcpServersJson(filePath, launcher, targetConfigPath, { serverName
         err.code = 'MCP_SERVER_COLLISION';
         throw err;
     }
-    cfgObj.mcpServers[serverName] = { ...launcher, env: { GX_CONFIG_PATH: targetConfigPath } };
+    const serverEntry = { ...launcher };
+    if (globalConfig && targetConfigPath) {
+        serverEntry.env = { ...(serverEntry.env || {}), GX_CONFIG_PATH: targetConfigPath };
+    }
+    cfgObj.mcpServers[serverName] = serverEntry;
     // If registering default genexus18mcp, clean up legacy genexus/genexus18 entries only if they are not foreign HTTP servers
     if (serverName === DEFAULT_MCP_SERVER_NAME) {
         if (cfgObj.mcpServers.genexus && !isThirdPartyMcpEntry(cfgObj.mcpServers.genexus)) {
@@ -1003,10 +1117,10 @@ function applyMcpServersJson(filePath, launcher, targetConfigPath, { serverName
             delete cfgObj.mcpServers.genexus18;
         }
     }
-    writeClientJson(filePath, cfgObj);
+    writeClientJson(filePath, cfgObj, fileSystem);
 }
 
-function removeMcpServersJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME } = {}) {
+function removeMcpServersJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME, fs: fileSystem = fs } = {}) {
     const parsed = readJsonFileSafe(filePath);
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
@@ -1026,14 +1140,14 @@ function removeMcpServersJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME }
         }
     }
     if (!removedAny) return false;
-    writeClientJson(filePath, cfgObj);
+    writeClientJson(filePath, cfgObj, fileSystem);
     return true;
 }
 
 // VS Code native MCP lives in User\mcp.json and uses a top-level `servers` map
 // with `type: "stdio"` (distinct from the `mcpServers` shape Claude/Cursor use).
-function applyVsCodeServersJson(filePath, launcher, targetConfigPath, { serverName = DEFAULT_MCP_SERVER_NAME, force = false } = {}) {
-    const parsed = fs.existsSync(filePath) ? readJsonFileSafe(filePath) : {};
+function applyVsCodeServersJson(filePath, launcher, targetConfigPath, { serverName = DEFAULT_MCP_SERVER_NAME, force = false, globalConfig = false, fs: fileSystem = fs } = {}) {
+    const parsed = fileSystem.existsSync(filePath) ? readJsonFileSafe(filePath, fileSystem) : {};
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
     cfgObj.servers = cfgObj.servers || {};
@@ -1043,11 +1157,14 @@ function applyVsCodeServersJson(filePath, launcher, targetConfigPath, { serverNa
         err.code = 'MCP_SERVER_COLLISION';
         throw err;
     }
-    cfgObj.servers[serverName] = {
+    const serverEntry = {
         type: 'stdio',
-        ...launcher,
-        env: { GX_CONFIG_PATH: targetConfigPath }
+        ...launcher
     };
+    if (globalConfig && targetConfigPath) {
+        serverEntry.env = { ...(serverEntry.env || {}), GX_CONFIG_PATH: targetConfigPath };
+    }
+    cfgObj.servers[serverName] = serverEntry;
     if (serverName === DEFAULT_MCP_SERVER_NAME) {
         if (cfgObj.servers.genexus && !isThirdPartyMcpEntry(cfgObj.servers.genexus)) {
             delete cfgObj.servers.genexus;
@@ -1058,10 +1175,10 @@ function applyVsCodeServersJson(filePath, launcher, targetConfigPath, { serverNa
     } else if (serverName === 'genexus' && cfgObj.servers.genexus18 && !isThirdPartyMcpEntry(cfgObj.servers.genexus18)) {
         delete cfgObj.servers.genexus18;
     }
-    writeClientJson(filePath, cfgObj);
+    writeClientJson(filePath, cfgObj, fileSystem);
 }
 
-function removeVsCodeServersJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME } = {}) {
+function removeVsCodeServersJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME, fs: fileSystem = fs } = {}) {
     const parsed = readJsonFileSafe(filePath);
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
@@ -1081,7 +1198,7 @@ function removeVsCodeServersJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAM
         }
     }
     if (!removedAny) return false;
-    writeClientJson(filePath, cfgObj);
+    writeClientJson(filePath, cfgObj, fileSystem);
     return true;
 }
 
@@ -1102,8 +1219,8 @@ function getOpenCodeMcpContainer(cfgObj) {
     };
 }
 
-function applyOpenCodeJson(filePath, launcher, targetConfigPath, { serverName = DEFAULT_MCP_SERVER_NAME, force = false } = {}) {
-    const parsed = fs.existsSync(filePath) ? readJsonFileSafe(filePath) : {};
+function applyOpenCodeJson(filePath, launcher, targetConfigPath, { serverName = DEFAULT_MCP_SERVER_NAME, force = false, globalConfig = false, fs: fileSystem = fs } = {}) {
+    const parsed = fileSystem.existsSync(filePath) ? readJsonFileSafe(filePath, fileSystem) : {};
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
     // OpenCode configs carry a top-level $schema for editor validation; set it when
@@ -1116,12 +1233,15 @@ function applyOpenCodeJson(filePath, launcher, targetConfigPath, { serverName =
         err.code = 'MCP_SERVER_COLLISION';
         throw err;
     }
-    servers[serverName] = {
+    const serverEntry = {
         type: 'local',
         command: [launcher.command, ...(launcher.args || [])],
-        environment: { GX_CONFIG_PATH: targetConfigPath },
         ...(nested ? { disabled: false } : { enabled: true })
     };
+    if (globalConfig && targetConfigPath) {
+        serverEntry.environment = { GX_CONFIG_PATH: targetConfigPath };
+    }
+    servers[serverName] = serverEntry;
     if (serverName === DEFAULT_MCP_SERVER_NAME) {
         if (servers.genexus && !isThirdPartyMcpEntry(servers.genexus)) delete servers.genexus;
         if (servers.genexus18 && !isThirdPartyMcpEntry(servers.genexus18)) delete servers.genexus18;
@@ -1142,10 +1262,10 @@ function applyOpenCodeJson(filePath, launcher, targetConfigPath, { serverName =
             if (mcp[serverName] && !isThirdPartyMcpEntry(mcp[serverName])) delete mcp[serverName];
         }
     }
-    writeClientJson(filePath, cfgObj);
+    writeClientJson(filePath, cfgObj, fileSystem);
 }
 
-function removeOpenCodeJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME } = {}) {
+function removeOpenCodeJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME, fs: fileSystem = fs } = {}) {
     const parsed = readJsonFileSafe(filePath);
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
@@ -1177,7 +1297,7 @@ function removeOpenCodeJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME } =
         }
     }
     if (!removedAny) return false;
-    writeClientJson(filePath, cfgObj);
+    writeClientJson(filePath, cfgObj, fileSystem);
     return true;
 }
 
@@ -1231,7 +1351,7 @@ function stripCodexServerBlocks(content, serverName) {
 // [mcp_servers.genexus*] blocks and append fresh ones. Brittle on hand-edited
 // files that put other keys after our blocks without a blank line, but
 // adequate for the typical machine-managed config.
-function applyCodexToml(filePath, launcher, targetConfigPath, { serverName = DEFAULT_MCP_SERVER_NAME, force = false } = {}) {
+function applyCodexToml(filePath, launcher, targetConfigPath, { serverName = DEFAULT_MCP_SERVER_NAME, force = false, globalConfig = false } = {}) {
     let existing = '';
     if (fs.existsSync(filePath)) existing = fs.readFileSync(filePath, 'utf8');
     const existingEntry = extractCodexTomlEntry(existing, serverName);
@@ -1263,9 +1383,11 @@ function applyCodexToml(filePath, launcher, targetConfigPath, { serverName = DEF
     lines.push(`[mcp_servers.${serverName}]`);
     lines.push(`command = ${tomlString(launcher.command)}`);
     lines.push(`args = [${args.map(tomlString).join(', ')}]`);
-    lines.push('');
-    lines.push(`[mcp_servers.${serverName}.env]`);
-    lines.push(`GX_CONFIG_PATH = ${tomlString(targetConfigPath)}`);
+    if (globalConfig && targetConfigPath) {
+        lines.push('');
+        lines.push(`[mcp_servers.${serverName}.env]`);
+        lines.push(`GX_CONFIG_PATH = ${tomlString(targetConfigPath)}`);
+    }
     lines.push('');
     writeClientText(filePath, stripped + lines.join('\n'));
 }
@@ -1321,12 +1443,12 @@ function normalizeExePath(p) {
     return s;
 }
 
-function readClientCommandEntry(client, serverName = DEFAULT_MCP_SERVER_NAME) {
+function readClientCommandEntry(client, serverName = DEFAULT_MCP_SERVER_NAME, { fs: fileSystem = fs } = {}) {
     if (client.writeSupported === false) return null;
-    if (!fs.existsSync(client.path)) return null;
+    if (!fileSystem.existsSync(client.path)) return null;
     try {
         if (client.format === 'mcpServers') {
-            const parsed = readJsonFileSafe(client.path);
+            const parsed = readJsonFileSafe(client.path, fileSystem);
             if (!parsed || typeof parsed !== 'object') return null;
             let entry = parsed.mcpServers && parsed.mcpServers[serverName];
             if (!entry && serverName === DEFAULT_MCP_SERVER_NAME) {
@@ -1345,7 +1467,7 @@ function readClientCommandEntry(client, serverName = DEFAULT_MCP_SERVER_NAME) {
             };
         }
         if (client.format === 'opencode') {
-            const parsed = readJsonFileSafe(client.path);
+            const parsed = readJsonFileSafe(client.path, fileSystem);
             if (!parsed || typeof parsed !== 'object') return null;
             let entry = parsed.mcp?.servers?.[serverName] || parsed.mcp?.[serverName];
             if (!entry && serverName === DEFAULT_MCP_SERVER_NAME) {
@@ -1374,7 +1496,7 @@ function readClientCommandEntry(client, serverName = DEFAULT_MCP_SERVER_NAME) {
             };
         }
         if (client.format === 'vscode-servers') {
-            const parsed = readJsonFileSafe(client.path);
+            const parsed = readJsonFileSafe(client.path, fileSystem);
             if (!parsed || typeof parsed !== 'object') return null;
             let entry = parsed.servers && parsed.servers[serverName];
             if (!entry && serverName === DEFAULT_MCP_SERVER_NAME) {
@@ -1729,13 +1851,31 @@ function applyLauncherConfigOrExit({ cwd, stderr, quiet }) {
         return { ok: true };
     }
 
-    if (!directoryLooksLikeKnowledgeBase(cwd)) {
-        log('[genexus-mcp] ERROR: Zero-config failed because current directory is not a GeneXus KB.');
-        log(`[genexus-mcp] CWD: ${cwd}`);
+    const discoveredGxPath = discoverGeneXusInstallation();
+    if (!discoveredGxPath) {
+        log('[genexus-mcp] ERROR: No config.json found and GeneXus installation auto-discovery failed.');
         log('[genexus-mcp] Fix with: npx genexus-mcp init --interactive');
         return { ok: false };
     }
 
+    const userMcpDir = path.join(os.homedir(), '.genexus-mcp');
+    const userMcpConfigPath = path.join(userMcpDir, 'config.json');
+
+
+    if (!directoryLooksLikeKnowledgeBase(cwd)) {
+        if (fs.existsSync(userMcpConfigPath)) {
+            process.env.GX_CONFIG_PATH = userMcpConfigPath;
+            return { ok: true };
+        }
+        log(`[genexus-mcp] Auto-discovered GeneXus at: ${discoveredGxPath}`);
+        log(`[genexus-mcp] Current directory is not a GeneXus KB. Generating neutral user config at: ${userMcpConfigPath}`);
+        fs.mkdirSync(userMcpDir, { recursive: true });
+        const neutralConfig = generateNeutralConfig(discoveredGxPath);
+        writeFileAtomic(userMcpConfigPath, JSON.stringify(neutralConfig, null, 2));
+        process.env.GX_CONFIG_PATH = userMcpConfigPath;
+        return { ok: true };
+    }
+
     const kbIdentity = readGeneXusKbIdentity(cwd);
     if (!kbIdentity.major) {
         log('[genexus-mcp] ERROR: Zero-config could not determine the KB GeneXus major safely.');
@@ -1776,6 +1916,7 @@ function applyLauncherConfigOrExit({ cwd, stderr, quiet }) {
 
 module.exports = {
     generateConfig,
+    generateNeutralConfig,
     getGatewayExePath,
     getToolDefinitionsPath,
     getGeneXusVersionCatalog,
@@ -1787,6 +1928,7 @@ module.exports = {
     directoryLooksLikeKnowledgeBase,
     readJsonFileSafe,
     resolveConfigPathNoMutate,
+    migrateLegacyConfig,
     createConfigFile,
     patchClientConfig,
     unpatchClientConfig,