genexus-mcp 3.2.1 → 3.2.2

package/README.md

@@ -96,8 +96,9 @@ Before you start, make sure you have:
 
 - ✅ **Windows** (GeneXus is Windows-only)
 - ✅ **A supported GeneXus SDK** installed locally (see [`docs/generated/supported-versions.md`](docs/generated/supported-versions.md); pass another install path explicitly when needed)
+- ✅ **GeneXus 18** installed locally (the primary supported SDK; other catalogued majors are also supported)
 - ✅ **A Knowledge Base created with a supported GeneXus major** and opened at least once in the IDE (so it's initialized)
-- ✅ **Node.js 18+** — check with `node --version` in a terminal; install from [nodejs.org](https://nodejs.org/) if missing
+- ✅ **Node.js 22+** — check with `node --version` in a terminal; install from [nodejs.org](https://nodejs.org/) if missing
 - ✅ **An MCP-compatible AI client** — [Claude Desktop](https://claude.ai/download), [Claude Code](https://claude.com/claude-code), Cursor, Antigravity, etc.
 
 You do **not** need to clone this repo or install anything globally — `npx` handles it.
@@ -208,7 +209,7 @@ Paths to give to IT for the ASR / Defender exclusion list:
 <InstallDir>\worker\GxMcp.Worker.exe
 ```
 
-Re-run the same one-liner later to **upgrade** — it detects the installed version (`version.txt` in the install dir) and downloads only if a newer release is available. Use `-Force` to reinstall the same version, `-Version v2.3.0` to pin a specific tag, `-NoClient` to skip AI client registration. Node.js 18+ must be installed for client registration; without it the script still extracts the binaries but you'll need to edit the client config (`claude_desktop_config.json` etc.) manually.
+Re-run the same one-liner later to **upgrade** — it detects the installed version (`version.txt` in the install dir) and downloads only if a newer release is available. Use `-Force` to reinstall the same version, `-Version v2.3.0` to pin a specific tag, `-NoClient` to skip AI client registration. Node.js 22+ must be installed for client registration; without it the script still extracts the binaries but you'll need to edit the client config (`claude_desktop_config.json` etc.) manually.
 
 ---
 
@@ -243,7 +244,7 @@ Once installed, here's what unlocks. Try these as your first prompts:
 - *"Read the Documentation part of the transaction Customer and rewrite it in markdown."*
 
 **Analysis**
-- *"Explain what the procedure ProcessShipment does, step by step."*
+- *"Explain what the procedure ProcessShipment does."* — `genexus_analyze mode=explain` is a compatibility-only envelope and returns `NotImplemented`; use `mode=summary`, `mode=context`, or `genexus_read` for supported analysis and source.
 - *"What SQL does the query in WebPanel CustomerList generate?"*
 - *"Summarize the structure of the Sales module."*
 
@@ -362,7 +363,7 @@ produced by `DataSelectorStructurePart.ToString()` on U16.
 - `genexus_merge` — 2- or 3-way object merge (`IMergeService`)
 
 **Analysis, docs & API**
-- `genexus_analyze` — cross-object semantic analysis (impact, dependencies, complexity, naming, code_metrics, summary, explain, `kb_stats` = KB activity/freshness, `table_relations` = table↔transaction relations + redundant attrs, …)
+- `genexus_analyze` — cross-object semantic analysis (impact, dependencies, complexity, naming, code_metrics, summary, `kb_stats` = KB activity/freshness, `table_relations` = table↔transaction relations + redundant attrs, …). `mode=explain` is compatibility-only: it preserves the legacy response envelope and returns `NotImplemented`; use `mode=summary`, `mode=context`, or `genexus_read` instead.
 - `genexus_doc` — generate wiki / dependency graphs / health reports
 - `genexus_api` — introspect REST endpoints exposed by HTTP procedures
 - `genexus_security` — audit KB security: `audit_gam` (env/GAM props), `scan_secrets` (regex over Source), `scan_native` (the SDK's own Security Scanner, `ISecurityScannerService`)
@@ -580,8 +581,8 @@ graph LR
 Want to contribute or run a local dev build?
 
 1. Clone this repo on Windows.
-2. Run `.\setup.bat` — checks prerequisites, builds the C# components, and auto-registers the local build with detected AI clients.
-3. If GeneXus or your KB aren't auto-detected, follow the prompts.
+2. Run `.\build.ps1` to restore and build the C# components and package the local artifacts. The script checks for the required .NET SDK and GeneXus 18 installation.
+3. If GeneXus is installed outside the default path, set `$env:GX_PATH` to its installation folder before running the build. A Knowledge Base is only needed for runtime testing.
 
 ### Bundled AI skills (`.gemini/skills/`)
 

package/cli/commands/axi.js

@@ -5,10 +5,12 @@ const fs = require('fs');
 const {
     getGatewayExePath,
     getToolDefinitionsPath,
+    generateNeutralConfig,
     resolveConfigPathNoMutate,
     readJsonFileSafe,
     directoryLooksLikeKnowledgeBase,
     createConfigFile,
+    migrateLegacyConfig,
     patchClientConfig,
     unpatchClientConfig,
     getClientConfigTargets,
@@ -946,6 +948,109 @@ async function handleToolsList(options, ctx) {
     };
 }
 
+async function handleConfigCreate(options, ctx) {
+    if (options.kb) {
+        return { exitCode: ctx.EXIT_CODES.USAGE, envelope: usageEnvelope('--kb is not allowed when creating a neutral runtime config.', ctx.EXIT_CODES.USAGE) };
+    }
+
+    const required = [
+        ['--config-scope', options.configScope],
+        ['--output', options.output],
+        ['--gx', options.gx],
+        ['--worker', options.worker],
+        ['--gateway-mode', options.gatewayMode],
+        ['--resolution-policy', options.resolutionPolicy]
+    ];
+    const missing = required.filter(([, value]) => !value).map(([flag]) => flag);
+    if (missing.length > 0) {
+        return {
+            exitCode: ctx.EXIT_CODES.USAGE,
+            envelope: usageEnvelope(`config create requires: ${missing.join(', ')}.`, ctx.EXIT_CODES.USAGE)
+        };
+    }
+    if (options.configScope !== 'neutral') {
+        return {
+            exitCode: ctx.EXIT_CODES.USAGE,
+            envelope: usageEnvelope('--config-scope must be `neutral` for config create.', ctx.EXIT_CODES.USAGE)
+        };
+    }
+
+    const outputPath = path.resolve(options.output);
+    try {
+        fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+        const config = generateNeutralConfig(options.gx, {
+            workerPath: options.worker,
+            gatewayMode: options.gatewayMode,
+            resolutionPolicy: options.resolutionPolicy
+        });
+        fs.writeFileSync(outputPath, JSON.stringify(config, null, 2));
+        return {
+            exitCode: ctx.EXIT_CODES.OK,
+            envelope: {
+                ok: {
+                    action: 'config.create',
+                    configScope: 'neutral',
+                    configPath: outputPath,
+                    clientsPatchedCount: 0,
+                    config
+                },
+                help: [],
+                meta: { clientRegistration: 'not_attempted', kbCatalog: 'not_created' }
+            }
+        };
+    } catch (err) {
+        return {
+            exitCode: ctx.EXIT_CODES.ERROR,
+            envelope: operationalErrorEnvelope(`Could not write neutral config: ${err.message}`, ctx.EXIT_CODES.ERROR)
+        };
+    }
+}
+
+async function handleConfigMigrate(options, ctx) {
+    const sourcePath = options.fromPath || resolveConfigPathNoMutate(ctx.cwd);
+    if (!sourcePath) {
+        return { exitCode: ctx.EXIT_CODES.USAGE, envelope: usageEnvelope('config migrate requires --from <legacy-config> (or a config.json in the current directory).', ctx.EXIT_CODES.USAGE) };
+    }
+    const targetPath = options.output || `${sourcePath}.neutral.json`;
+    if (path.resolve(sourcePath) === path.resolve(targetPath)) {
+        return { exitCode: ctx.EXIT_CODES.USAGE, envelope: usageEnvelope('config migrate requires --output to differ from --from; the legacy source is never overwritten.', ctx.EXIT_CODES.USAGE) };
+    }
+    try {
+        const receipt = migrateLegacyConfig(sourcePath, targetPath, { rejectNonMigratable: Boolean(options.rejectNonMigratable) });
+        return {
+            exitCode: ctx.EXIT_CODES.OK,
+            envelope: {
+                ok: { action: 'config.migrate', ...receipt },
+                help: receipt.notMigrated.length > 0
+                    ? ['KB fields were not migrated. Keep using `kb add`, `kb remove`, and `kb switch` against the legacy config, or select a KB explicitly through MCP.']
+                    : []
+            }
+        };
+    } catch (err) {
+        if (err.code === 'NON_MIGRATABLE_FIELDS') {
+            return {
+                exitCode: ctx.EXIT_CODES.USAGE,
+                envelope: {
+                    ...usageEnvelope(err.message, ctx.EXIT_CODES.USAGE),
+                    meta: { exitCode: ctx.EXIT_CODES.USAGE, notMigrated: err.notMigrated || [] }
+                }
+            };
+        }
+        return {
+            exitCode: ctx.EXIT_CODES.ERROR,
+            envelope: {
+                error: {
+                    code: 'operation_error',
+                    message: sanitizeOperationalMessage(`Configuration migration failed: ${err.message}`),
+                    rollback: err.rollback || { rolledBack: false }
+                },
+                help: err.backupPath ? [`The source backup was written to ${err.backupPath}.`] : [],
+                meta: { exitCode: ctx.EXIT_CODES.ERROR, notMigrated: err.notMigrated || [] }
+            }
+        };
+    }
+}
+
 async function handleConfigShow(options, ctx) {
     const configPath = resolveConfigPathNoMutate(ctx.cwd);
     if (!configPath) {
@@ -1631,7 +1736,8 @@ async function handleInit(options, ctx) {
                 ids,
                 onlyExisting: !options.allClients,
                 serverName: options.serverName || DEFAULT_MCP_SERVER_NAME,
-                force: options.force
+                force: options.force,
+                globalConfig: Boolean(options.globalConfig)
             });
         }
 
@@ -2026,11 +2132,11 @@ async function handleClients(subcommand, options, ctx) {
     }
 
     if (sub === 'add' || sub === 'remove') {
-        const ids = resolveClientIds(options);
+        const ids = options.allClients ? listSupportedClientIds() : resolveClientIds(options);
         if (sub === 'add' && (!ids || ids.length === 0)) {
             return {
                 exitCode: ctx.EXIT_CODES.USAGE,
-                envelope: usageEnvelope('`clients add` requires --clients <csv> (e.g. --clients antigravity,vscode).', ctx.EXIT_CODES.USAGE)
+                envelope: usageEnvelope('`clients add` requires --clients <csv> or --all-clients.', ctx.EXIT_CODES.USAGE)
             };
         }
         const validation = validateClientIds(ids);
@@ -2056,7 +2162,8 @@ async function handleClients(subcommand, options, ctx) {
                     ids,
                     onlyExisting: false,
                     serverName,
-                    force: options.force
+                    force: options.force,
+                    globalConfig: Boolean(options.globalConfig)
                 });
             } catch (err) {
                 return {
@@ -2265,8 +2372,8 @@ function commandHelpMap() {
             examples: ['genexus-mcp tools list', 'genexus-mcp tools list --query read --fields name,category --format json']
         },
         config: {
-            usage: 'genexus-mcp config show [--full] [--fields f1,f2] [--format ...]',
-            examples: ['genexus-mcp config show', 'genexus-mcp config show --full --format json']
+            usage: 'genexus-mcp config show [--full] [--fields f1,f2] [--format ...] OR genexus-mcp config create --config-scope neutral --output <path> --gx <path> --worker <path> --gateway-mode <mode> --resolution-policy <policy> OR genexus-mcp config migrate --from <legacy.json> --output <neutral.json> [--reject-non-migratable]',
+            examples: ['genexus-mcp config show', 'genexus-mcp config create --config-scope neutral --output ./config.json --gx <path> --worker <path> --gateway-mode stdio-isolated --resolution-policy strict', 'genexus-mcp config migrate --from ./config.json --output ./.genexus-mcp/config.json']
         },
         init: {
             usage: 'genexus-mcp init [--kb <path>] [--gx <path>] [--server-name <name>] [--force] [--no-write-clients] [--clients <csv>] [--all-clients] [--no-smoke] [--warm] [--format ...] OR genexus-mcp init --interactive',
@@ -2386,7 +2493,7 @@ async function handleHelp(targetCommand, ctx) {
                 bin: binPath,
                 command: 'genexus-mcp',
                 description: 'GeneXus MCP launcher and AXI-oriented utility CLI',
-                commands: ['home', 'axi home', 'status', 'doctor', 'tools list', 'config show', 'layout status', 'layout run', 'layout inspect', 'init', 'whoami', 'uninstall', 'kb list', 'kb add', 'kb remove', 'kb switch', 'llm help', 'update', 'help'],
+                commands: ['home', 'axi home', 'status', 'doctor', 'tools list', 'config show', 'config create', 'layout status', 'layout run', 'layout inspect', 'init', 'whoami', 'uninstall', 'kb list', 'kb add', 'kb remove', 'kb switch', 'llm help', 'update', 'help'],
                 defaults: { format: 'toon', limit: 100 }
             },
             help: [
@@ -2488,6 +2595,8 @@ module.exports = {
     handleDoctor,
     handleToolsList,
     handleConfigShow,
+    handleConfigCreate,
+    handleConfigMigrate,
     handleInit,
     handleWhoami,
     handleUninstall,

package/cli/docs.test.js

@@ -0,0 +1,29 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const repoRoot = path.join(__dirname, '..');
+const read = (file) => fs.readFileSync(path.join(repoRoot, file), 'utf8');
+
+function requiredNodeMajor() {
+    const range = JSON.parse(read('package.json')).engines.node;
+    const match = range.match(/>=([0-9]+)/);
+    assert.ok(match, `Unable to determine Node.js minimum from engines.node: ${range}`);
+    return match[1];
+}
+
+test('onboarding docs stay aligned with package prerequisites', () => {
+    const nodeMajor = requiredNodeMajor();
+    const readme = read('README.md');
+    const spanish = read('docs/GETTING_STARTED.es.md');
+    const portuguese = read('docs/GETTING_STARTED.pt-br.md');
+
+    assert.match(readme, new RegExp(`Node\\.js ${nodeMajor}\\+`));
+    assert.match(spanish, new RegExp(`Node\\.js ${nodeMajor} o superior`));
+    assert.match(portuguese, new RegExp(`Node\\.js ${nodeMajor} ou superior`));
+    assert.doesNotMatch(readme, /setup\.bat/);
+    assert.match(readme, /`\.\\build\.ps1`/);
+    assert.match(readme, /\*\*Windows\*\* \(GeneXus is Windows-only\)/);
+    assert.match(readme, /GeneXus 18.*installed locally/);
+});

package/cli/index.js

@@ -15,6 +15,8 @@ const {
     handleDoctor,
     handleToolsList,
     handleConfigShow,
+    handleConfigCreate,
+    handleConfigMigrate,
     handleInit,
     handleWhoami,
     handleUninstall,
@@ -97,8 +99,8 @@ function parseArgs(argv) {
         tokens.shift();
     }
 
-    if (result.command === 'config' && tokens[0] === 'show') {
-        result.subcommand = 'show';
+    if (result.command === 'config' && ['show', 'create', 'migrate'].includes(tokens[0])) {
+        result.subcommand = tokens[0];
         tokens.shift();
     }
 
@@ -175,6 +177,45 @@ function parseArgs(argv) {
                 else result.unknownFlags.push('--gx requires a value');
                 break;
             }
+            case 'from': {
+                const val = takeValue();
+                if (val) result.options.fromPath = val;
+                else result.unknownFlags.push('--from requires a value');
+                break;
+            }
+            case 'reject-non-migratable':
+                result.options.rejectNonMigratable = true;
+                break;
+            case 'output': {
+                const val = takeValue();
+                if (val) result.options.output = val;
+                else result.unknownFlags.push('--output requires a value');
+                break;
+            }
+            case 'worker': {
+                const val = takeValue();
+                if (val) result.options.worker = val;
+                else result.unknownFlags.push('--worker requires a value');
+                break;
+            }
+            case 'config-scope': {
+                const val = takeValue();
+                if (val) result.options.configScope = val;
+                else result.unknownFlags.push('--config-scope requires a value');
+                break;
+            }
+            case 'gateway-mode': {
+                const val = takeValue();
+                if (val) result.options.gatewayMode = val;
+                else result.unknownFlags.push('--gateway-mode requires a value');
+                break;
+            }
+            case 'resolution-policy': {
+                const val = takeValue();
+                if (val) result.options.resolutionPolicy = val;
+                else result.unknownFlags.push('--resolution-policy requires a value');
+                break;
+            }
             case 'name': {
                 const val = takeValue();
                 if (val) result.options.name = val;
@@ -290,6 +331,12 @@ function parseArgs(argv) {
             case 'interactive':
                 result.options.interactive = true;
                 break;
+            case 'global-config':
+                result.options.globalConfig = true;
+                break;
+            case 'neutral':
+                result.options.neutral = true;
+                break;
             case 'write-clients':
                 result.options.writeClients = true;
                 break;
@@ -466,7 +513,7 @@ function withCommandMeta(envelope, commandName) {
 function resolveMetaCommand(parsed, targetHelp) {
     if (targetHelp || parsed.command === 'help') return 'help';
     if (parsed.command === 'tools') return 'tools.list';
-    if (parsed.command === 'config') return 'config.show';
+    if (parsed.command === 'config') return parsed.subcommand ? `config.${parsed.subcommand}` : 'config';
     if (parsed.command === 'axi' || parsed.command === 'home') return 'home';
     if (parsed.command === 'llm') return 'llm.help';
     if (parsed.command === 'layout') {
@@ -556,15 +603,19 @@ async function main(argv) {
             result = await handleToolsList(parsed.options, ctx);
             break;
         case 'config':
-            if (parsed.subcommand !== 'show') {
+            if (!['show', 'create', 'migrate'].includes(parsed.subcommand)) {
                 writeStructured(
                     process.stdout,
-                    withCommandMeta(usageEnvelope('config requires subcommand `show`.', EXIT_CODES.USAGE), resolveMetaCommand(parsed)),
+                    withCommandMeta(usageEnvelope('config requires subcommand `show`, `create`, or `migrate`.', EXIT_CODES.USAGE), resolveMetaCommand(parsed)),
                     parsed.options.format
                 );
                 return EXIT_CODES.USAGE;
             }
-            result = await handleConfigShow(parsed.options, ctx);
+            result = parsed.subcommand === 'create'
+                ? await handleConfigCreate(parsed.options, ctx)
+                : parsed.subcommand === 'migrate'
+                    ? await handleConfigMigrate(parsed.options, ctx)
+                : await handleConfigShow(parsed.options, ctx);
             break;
         case 'llm':
             if (parsed.subcommand && parsed.subcommand !== 'help') {

package/cli/lib/client-adapters.test.js

@@ -11,6 +11,10 @@ const {
     CodexTomlAdapter,
     ClientConfigManager
 } = require('./client-adapters');
+const {
+    generateNeutralConfig,
+    applyLauncherConfigOrExit
+} = require('./config');
 
 test('getClientAdapter returns correct strategy for each format', () => {
     assert.ok(getClientAdapter('mcpServers') instanceof McpServersJsonAdapter);
@@ -19,7 +23,7 @@ test('getClientAdapter returns correct strategy for each format', () => {
     assert.ok(getClientAdapter('codex-toml') instanceof CodexTomlAdapter);
 });
 
-test('ClientConfigManager applies and reads mcpServers format cleanly', () => {
+test('ClientConfigManager applies and reads mcpServers format cleanly without GX_CONFIG_PATH by default', () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-cli-test-'));
     const configPath = path.join(tmpDir, 'mcp.json');
     const client = { id: 'test-cursor', name: 'Test Cursor', format: 'mcpServers', path: configPath };
@@ -27,13 +31,22 @@ test('ClientConfigManager applies and reads mcpServers format cleanly', () => {
 
     try {
         const manager = new ClientConfigManager();
+        // Decoupled default
         manager.apply(client, launcher, 'C:\\MyKb\\config.json', { serverName: 'genexus18mcp' });
 
-        const raw = fs.readFileSync(configPath, 'utf8');
-        const parsed = JSON.parse(raw);
+        let raw = fs.readFileSync(configPath, 'utf8');
+        let parsed = JSON.parse(raw);
         assert.ok(parsed.mcpServers);
         assert.ok(parsed.mcpServers.genexus18mcp);
         assert.equal(parsed.mcpServers.genexus18mcp.command, 'node');
+        assert.equal(parsed.mcpServers.genexus18mcp.env, undefined);
+
+        // With globalConfig: true
+        manager.apply(client, launcher, 'C:\\MyKb\\config.json', { serverName: 'genexus18mcp', globalConfig: true, force: true });
+        raw = fs.readFileSync(configPath, 'utf8');
+        parsed = JSON.parse(raw);
+        assert.ok(parsed.mcpServers.genexus18mcp.env);
+        assert.equal(parsed.mcpServers.genexus18mcp.env.GX_CONFIG_PATH, 'C:\\MyKb\\config.json');
 
         const readEntry = manager.read(client, 'genexus18mcp');
         assert.ok(readEntry);
@@ -48,3 +61,170 @@ test('ClientConfigManager applies and reads mcpServers format cleanly', () => {
         try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { }
     }
 });
+
+test('ClientConfigManager applies vscode-servers format cleanly without GX_CONFIG_PATH by default', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-cli-test-'));
+    const configPath = path.join(tmpDir, 'mcp.json');
+    const client = { id: 'test-vscode', name: 'Test VSCode', format: 'vscode-servers', path: configPath };
+    const launcher = { command: 'node', args: ['run.js'] };
+
+    try {
+        const manager = new ClientConfigManager();
+        // Decoupled default
+        manager.apply(client, launcher, 'C:\\MyKb\\config.json', { serverName: 'genexus18mcp' });
+
+        let raw = fs.readFileSync(configPath, 'utf8');
+        let parsed = JSON.parse(raw);
+        assert.ok(parsed.servers);
+        assert.ok(parsed.servers.genexus18mcp);
+        assert.equal(parsed.servers.genexus18mcp.command, 'node');
+        assert.equal(parsed.servers.genexus18mcp.env, undefined);
+
+        // With globalConfig: true
+        manager.apply(client, launcher, 'C:\\MyKb\\config.json', { serverName: 'genexus18mcp', globalConfig: true, force: true });
+        raw = fs.readFileSync(configPath, 'utf8');
+        parsed = JSON.parse(raw);
+        assert.ok(parsed.servers.genexus18mcp.env);
+        assert.equal(parsed.servers.genexus18mcp.env.GX_CONFIG_PATH, 'C:\\MyKb\\config.json');
+    } finally {
+        try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { }
+    }
+});
+
+test('ClientConfigManager applies opencode format cleanly without GX_CONFIG_PATH by default', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-cli-test-'));
+    const configPath = path.join(tmpDir, 'opencode.json');
+    const client = { id: 'test-opencode', name: 'Test OpenCode', format: 'opencode', path: configPath };
+    const launcher = { command: 'node', args: ['run.js'] };
+
+    try {
+        const manager = new ClientConfigManager();
+        // Decoupled default
+        manager.apply(client, launcher, 'C:\\MyKb\\config.json', { serverName: 'genexus18mcp' });
+
+        let raw = fs.readFileSync(configPath, 'utf8');
+        let parsed = JSON.parse(raw);
+        assert.ok(parsed.mcp);
+        assert.ok(parsed.mcp.genexus18mcp);
+        assert.equal(parsed.mcp.genexus18mcp.environment, undefined);
+
+        // With globalConfig: true
+        manager.apply(client, launcher, 'C:\\MyKb\\config.json', { serverName: 'genexus18mcp', globalConfig: true, force: true });
+        raw = fs.readFileSync(configPath, 'utf8');
+        parsed = JSON.parse(raw);
+        assert.ok(parsed.mcp.genexus18mcp.environment);
+        assert.equal(parsed.mcp.genexus18mcp.environment.GX_CONFIG_PATH, 'C:\\MyKb\\config.json');
+    } finally {
+        try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { }
+    }
+});
+
+test('ClientConfigManager applies codex-toml format cleanly without GX_CONFIG_PATH by default', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-cli-test-'));
+    const configPath = path.join(tmpDir, 'config.toml');
+    const client = { id: 'test-codex', name: 'Test Codex', format: 'codex-toml', path: configPath };
+    const launcher = { command: 'node', args: ['run.js'] };
+
+    try {
+        const manager = new ClientConfigManager();
+        // Decoupled default
+        manager.apply(client, launcher, 'C:\\MyKb\\config.json', { serverName: 'genexus18mcp' });
+
+        let raw = fs.readFileSync(configPath, 'utf8');
+        assert.ok(raw.includes('[mcp_servers.genexus18mcp]'));
+        assert.ok(!raw.includes('GX_CONFIG_PATH'));
+
+        // With globalConfig: true
+        manager.apply(client, launcher, 'C:\\MyKb\\config.json', { serverName: 'genexus18mcp', globalConfig: true, force: true });
+        raw = fs.readFileSync(configPath, 'utf8');
+        assert.ok(raw.includes('[mcp_servers.genexus18mcp.env]'));
+        assert.ok(raw.includes('GX_CONFIG_PATH'));
+    } finally {
+        try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { }
+    }
+});
+
+test('generateNeutralConfig produces valid shape without KB fields', () => {
+    const cfg = generateNeutralConfig('C:\\GeneXus18');
+    assert.equal(cfg.ConfigSchemaVersion, 2);
+    assert.equal(cfg.GatewayMode, 'stdio-isolated');
+    assert.equal(cfg.GeneXus.InstallationPath, 'C:\\GeneXus18');
+    assert.ok(cfg.GeneXus.WorkerExecutable.endsWith(path.join('worker', 'GxMcp.Worker.exe')));
+    assert.equal(cfg.Server.McpStdio, true);
+    assert.equal(cfg.Server.TransportMode, undefined);
+    assert.equal(cfg.Server.HttpPort, 0);
+    assert.equal(cfg.Environment.ResolutionPolicy, 'strict');
+    assert.equal(cfg.Environment.KBs, undefined);
+    assert.equal(cfg.Environment.KBPath, undefined);
+});
+
+test('all client adapters preserve unrelated servers and emit no structural KB overrides', () => {
+    const cases = [
+        { format: 'mcpServers', file: 'claude.json', root: { mcpServers: { unrelated: { command: 'other' } } } },
+        { format: 'mcpServers', file: 'gemini.json', root: { mcpServers: { unrelated: { command: 'other' } } } },
+        { format: 'mcpServers', file: 'antigravity.json', root: { mcpServers: { unrelated: { command: 'other' } } } },
+        { format: 'vscode-servers', file: 'vscode.json', root: { servers: { unrelated: { type: 'stdio', command: 'other' } } } },
+        { format: 'opencode', file: 'opencode.json', root: { $schema: 'custom', mcp: { unrelated: { type: 'local', command: ['other'] } } } },
+        { format: 'codex-toml', file: 'config.toml', root: '[mcp_servers.unrelated]\ncommand = "other"\n' }
+    ];
+    const launcher = { command: 'gateway.exe', args: [] };
+    for (const entry of cases) {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-adapter-matrix-'));
+        try {
+            const configPath = path.join(tmpDir, entry.file);
+            fs.writeFileSync(configPath, typeof entry.root === 'string' ? entry.root : JSON.stringify(entry.root, null, 2));
+            new ClientConfigManager().apply({ format: entry.format, path: configPath }, launcher, path.join(tmpDir, 'neutral.json'), { serverName: 'genexus18mcp' });
+            const raw = fs.readFileSync(configPath, 'utf8');
+            assert.equal(/DefaultKb|ActiveKb|KBs/.test(raw), false, entry.format);
+            if (entry.format === 'codex-toml') {
+                assert.match(raw, /\[mcp_servers\.unrelated\]/);
+                assert.match(raw, /\[mcp_servers\.genexus18mcp\]/);
+            } else {
+                const parsed = JSON.parse(raw);
+                const servers = entry.format === 'vscode-servers' ? parsed.servers : entry.format === 'opencode' ? parsed.mcp : parsed.mcpServers;
+                const original = entry.format === 'vscode-servers' ? entry.root.servers : entry.format === 'opencode' ? entry.root.mcp : entry.root.mcpServers;
+                assert.deepEqual(servers.unrelated, original.unrelated);
+                assert.ok(servers.genexus18mcp);
+            }
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    }
+});
+
+test('applyLauncherConfigOrExit creates neutral config outside a KB', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-outside-kb-'));
+    const origEnv = process.env.GX_CONFIG_PATH;
+    const origGeneXusHome = process.env.GENEXUS_HOME;
+    delete process.env.GX_CONFIG_PATH;
+    const fakeGeneXusHome = path.join(tmpDir, 'GeneXus18');
+    fs.mkdirSync(fakeGeneXusHome, { recursive: true });
+    fs.writeFileSync(path.join(fakeGeneXusHome, 'genexus.exe'), 'test fixture');
+    process.env.GENEXUS_HOME = fakeGeneXusHome;
+
+    try {
+        const stderr = { write: () => {} };
+        const result = applyLauncherConfigOrExit({ cwd: tmpDir, stderr, quiet: true });
+
+        assert.equal(result.ok, true);
+        assert.ok(process.env.GX_CONFIG_PATH);
+        assert.ok(fs.existsSync(process.env.GX_CONFIG_PATH));
+        const content = JSON.parse(fs.readFileSync(process.env.GX_CONFIG_PATH, 'utf8'));
+        assert.equal(content.Environment?.KBs, undefined);
+        assert.equal(content.Environment?.DefaultKb, undefined);
+        assert.equal(content.Environment?.ActiveKb, undefined);
+        assert.equal(content.Environment?.KBPath, undefined);
+    } finally {
+        if (origEnv !== undefined) {
+            process.env.GX_CONFIG_PATH = origEnv;
+        } else {
+            delete process.env.GX_CONFIG_PATH;
+        }
+        if (origGeneXusHome !== undefined) {
+            process.env.GENEXUS_HOME = origGeneXusHome;
+        } else {
+            delete process.env.GENEXUS_HOME;
+        }
+        try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { }
+    }
+});