genexus-mcp 3.5.3 → 3.6.1

package/cli/run.test.js

@@ -20,6 +20,7 @@ const {
     getLauncher,
     getGeneXusMajor,
     getGeneXusCatalogEntries,
+    discoverGeneXusInstallation,
     readGeneXusInstallationIdentity,
     readGeneXusKbIdentity,
     compareGeneXusKbAndInstallation,
@@ -39,6 +40,7 @@ if (process.platform === 'win32') {
     fs.chmodSync(testGatewayPath, 0o755);
 }
 const testGatewayEnv = { GENEXUS_MCP_GATEWAY_EXE: testGatewayPath };
+const testGatewayDir = path.dirname(testGatewayPath);
 
 const RETRYABLE_REMOVE_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
 function waitForRemoveRetry(delayMs) {
@@ -49,7 +51,7 @@ function removeTempPath(targetPath, options = {}, deps = {}) {
     const fsImpl = deps.fsImpl || fs;
     const platform = deps.platform || process.platform;
     const sleep = deps.sleep || waitForRemoveRetry;
-    const maxAttempts = platform === 'win32' ? 5 : 1;
+    const maxAttempts = platform === 'win32' ? 8 : 1;
 
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
         try {
@@ -58,14 +60,38 @@ function removeTempPath(targetPath, options = {}, deps = {}) {
         } catch (error) {
             const retryable = RETRYABLE_REMOVE_CODES.has(error?.code);
             if (!retryable || attempt === maxAttempts) throw error;
-            sleep(10 * (2 ** (attempt - 1)));
+            sleep(Math.min(10 * (2 ** (attempt - 1)), 1000));
         }
     }
 }
 
+// Issue #211 teardown safety net: a probe child that outlives its terminate
+// signal keeps the stubbed GxMcp.Gateway.exe image mapped, which turns the
+// cleanup rmSync into EPERM. Terminate only processes started from this test's
+// own temp dir — never a machine-wide GxMcp.Gateway.exe sweep, which would hit
+// other checkouts and the operator's own gateways.
+function stopLingeringGatewayStubs(dirPath, deps = {}) {
+    const platform = deps.platform || process.platform;
+    const run = deps.run || ((command, args) => spawnSync(command, args, { encoding: 'utf8', windowsHide: true }));
+    if (platform !== 'win32') return false;
+
+    const escapedDir = String(dirPath).replace(/'/g, "''");
+    const script = [
+        "$ErrorActionPreference = 'SilentlyContinue'",
+        `Get-CimInstance Win32_Process -Filter "Name = 'GxMcp.Gateway.exe'"`,
+        `Where-Object { $_.ExecutablePath -and ([System.IO.Path]::GetDirectoryName($_.ExecutablePath) -eq '${escapedDir}') }`,
+        'ForEach-Object { Stop-Process -Id $_.ProcessId -Force }'
+    ].join(' | ');
+    try {
+        run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script]);
+    } catch { }
+    return true;
+}
+
 test.after(() => {
     removeTempPath(testGxPath, { recursive: true, force: true });
-    removeTempPath(testGatewayPath, { force: true });
+    stopLingeringGatewayStubs(testGatewayDir);
+    removeTempPath(testGatewayDir, { recursive: true, force: true });
 });
 
 function runCli(args, opts = {}) {
@@ -108,6 +134,58 @@ test('temporary cleanup retries transient Windows removal errors', () => {
     }), permanentError);
 });
 
+test('windows cleanup retries keep growing the backoff up to the attempt budget', () => {
+    const sleeps = [];
+    let attempts = 0;
+    const lockedFs = {
+        rmSync() {
+            attempts += 1;
+            throw Object.assign(new Error('file is still in use'), { code: 'EBUSY' });
+        }
+    };
+
+    assert.throws(() => removeTempPath('fixture', { force: true }, {
+        fsImpl: lockedFs,
+        platform: 'win32',
+        sleep: (delayMs) => sleeps.push(delayMs)
+    }));
+
+    assert.equal(attempts, 8);
+    assert.deepEqual(sleeps, [10, 20, 40, 80, 160, 320, 640]);
+});
+
+test('lingering gateway stub cleanup stays scoped to the test temp dir', () => {
+    const posixCalls = [];
+    const ranOnPosix = stopLingeringGatewayStubs('C:\\Temp\\genexus-mcp-test-1', {
+        platform: 'linux',
+        run: (command, args) => posixCalls.push([command, args])
+    });
+    assert.equal(ranOnPosix, false);
+    assert.deepEqual(posixCalls, [], 'non-Windows teardown must not spawn a shell');
+
+    const windowsCalls = [];
+    const ranOnWindows = stopLingeringGatewayStubs('C:\\Temp\\genexus-mcp-test-1', {
+        platform: 'win32',
+        run: (command, args) => windowsCalls.push([command, args])
+    });
+    assert.equal(ranOnWindows, true);
+    assert.equal(windowsCalls.length, 1);
+    assert.equal(windowsCalls[0][0], 'powershell.exe');
+
+    const script = windowsCalls[0][1].join(' ');
+    assert.ok(script.includes("GxMcp.Gateway.exe"), 'must target the stubbed gateway image');
+    assert.ok(script.includes('C:\\Temp\\genexus-mcp-test-1'), 'must be scoped to the test temp dir');
+    assert.ok(!script.includes('Stop-Process -Name'), 'must never terminate by process name machine-wide');
+});
+
+test('a failed stub cleanup does not mask the test result', () => {
+    const ran = stopLingeringGatewayStubs('C:\\Temp\\genexus-mcp-test-1', {
+        platform: 'win32',
+        run: () => { throw new Error('powershell unavailable'); }
+    });
+    assert.equal(ran, true);
+});
+
 test('status returns structured json envelope with schema version', () => {
     const result = runCli(['status', '--format', 'json']);
     assert.equal(result.status, 0);
@@ -476,6 +554,37 @@ test('GeneXus installation identity falls back to executable metadata', () => {
     }
 });
 
+test('classic GeneXus installation identity reads gx.exe metadata', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-classic-version-'));
+    try {
+        fs.writeFileSync(path.join(tempRoot, 'gx.exe'), 'not-a-real-executable');
+        const identity = readGeneXusInstallationIdentity(tempRoot, {
+            readExecutableVersion: (exePath) => exePath.endsWith('gx.exe') ? '9.0.123' : null
+        });
+        assert.deepEqual(identity, {
+            version: '9.0.123',
+            major: '9',
+            source: 'executable-metadata'
+        });
+    } finally {
+        removeTempPath(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('classic GeneXus installation discovery accepts GENEXUS_HOME with gx.exe', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-classic-home-'));
+    const previousHome = process.env.GENEXUS_HOME;
+    try {
+        fs.writeFileSync(path.join(tempRoot, 'gx.exe'), 'not-a-real-executable');
+        process.env.GENEXUS_HOME = tempRoot;
+        assert.equal(discoverGeneXusInstallation(), tempRoot);
+    } finally {
+        if (previousHome === undefined) delete process.env.GENEXUS_HOME;
+        else process.env.GENEXUS_HOME = previousHome;
+        removeTempPath(tempRoot, { recursive: true, force: true });
+    }
+});
+
 test('GeneXus installation identity ignores an invalid version file when executable metadata is valid', () => {
     const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-invalid-version-'));
     try {
@@ -542,8 +651,45 @@ test('KB identity fails closed for malformed gxw metadata', () => {
 
 test('catalog discovery ordering can prefer the KB major', () => {
     assert.equal(getGeneXusMajor('17.0.11.163677'), '17');
+    assert.equal(getGeneXusMajor('10.3.0.86550'), '10.3');
+    assert.equal(getGeneXusMajor('10.2.0'), '10.2');
+    assert.equal(getGeneXusMajor('10.1.0'), '10.1');
+    assert.equal(getGeneXusMajor('9.0.123'), '9');
+    assert.equal(getGeneXusMajor('8.0.456'), '8');
     assert.equal(getGeneXusCatalogEntries('17')[0].major, '17');
     assert.equal(getGeneXusCatalogEntries('18')[0].major, '18');
+    assert.equal(getGeneXusCatalogEntries('10.3')[0].major, '10.3');
+    assert.equal(getGeneXusCatalogEntries('9')[0].major, '9');
+    assert.equal(getGeneXusCatalogEntries('8')[0].major, '8');
+});
+
+test('KB identity reads Evolution 3 decimal major from gxw metadata', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-kb-ev3-'));
+    try {
+        fs.writeFileSync(
+            path.join(tempRoot, 'KnowledgeBase.gxw'),
+            '<KnowledgeBase><FriendlyVersion>GeneXus Evolution 3</FriendlyVersion><VersionNumber>10.3.0.86550</VersionNumber></KnowledgeBase>'
+        );
+        const identity = readGeneXusKbIdentity(tempRoot);
+        assert.equal(identity.version, '10.3.0.86550');
+        assert.equal(identity.major, '10.3');
+        assert.equal(identity.source, 'gxw-version');
+    } finally {
+        removeTempPath(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('KB identity reads GeneXus 9.0 classic major from gxi when gxw is absent', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-kb-gx9-'));
+    try {
+        fs.writeFileSync(path.join(tempRoot, 'MyLegacyKb.gxi'), 'binary-or-header-data');
+        const identity = readGeneXusKbIdentity(tempRoot);
+        assert.equal(identity.major, '9');
+        assert.equal(identity.version, '9.0');
+        assert.equal(identity.source, 'gxi-classic');
+    } finally {
+        removeTempPath(tempRoot, { recursive: true, force: true });
+    }
 });
 
 test('init rejects a known KB and SDK major mismatch before writing config', () => {
@@ -1062,7 +1208,43 @@ test('doctor rejects a KB and SDK major that is outside the compatibility catalo
         assert.ok(check);
         assert.equal(check.status, 'fail');
         assert.match(check.detail, /KB major 19 is not supported/);
-        assert.match(check.detail, /Supported majors: 17, 18/);
+        assert.match(check.detail, /Supported majors: 16, 17, 18/);
+    } finally {
+        removeTempPath(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('doctor evaluates gxpublic_com_registration and legacy_ide_lock checks for classic GeneXus', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-doctor-classic-'));
+    const kbDir = path.join(tempRoot, 'kb9');
+    const gxDir = path.join(tempRoot, 'GeneXus9');
+    fs.mkdirSync(kbDir, { recursive: true });
+    fs.mkdirSync(gxDir, { recursive: true });
+    fs.writeFileSync(path.join(kbDir, 'test.gxi'), 'legacy classic kb index');
+    fs.writeFileSync(path.join(gxDir, 'gx.exe'), 'classic-genexus-exe');
+    const configPath = path.join(tempRoot, 'config.json');
+    fs.writeFileSync(configPath, JSON.stringify({
+        GeneXus: { InstallationPath: gxDir },
+        Environment: { KBPath: kbDir }
+    }));
+
+    try {
+        const result = runCli(['doctor', '--format', 'json', '--limit', '50'], {
+            env: {
+                GX_CONFIG_PATH: configPath,
+                GENEXUS_MCP_GATEWAY_EXE: process.execPath,
+                LOCALAPPDATA: tempRoot
+            }
+        });
+        assert.equal(result.status, 0);
+        const parsed = JSON.parse(result.stdout);
+        const comCheck = parsed.ok.checks.find((row) => row.id === 'gxpublic_com_registration');
+        assert.ok(comCheck, 'gxpublic_com_registration check should be present');
+        assert.ok(['pass', 'warn'].includes(comCheck.status), `expected pass or warn, got ${comCheck.status}`);
+
+        const ideCheck = parsed.ok.checks.find((row) => row.id === 'legacy_ide_lock');
+        assert.ok(ideCheck, 'legacy_ide_lock check should be present');
+        assert.ok(['pass', 'warn'].includes(ideCheck.status), `expected pass or warn, got ${ideCheck.status}`);
     } finally {
         removeTempPath(tempRoot, { recursive: true, force: true });
     }
@@ -1310,6 +1492,41 @@ test('clients add patches OpenCode Desktop into shared opencode config', () => {
     }
 });
 
+test('OpenCode status and remove inspect both json and jsonc when they coexist', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-opencode-dual-config-'));
+    try {
+        const env = sandboxHomeEnv(tempRoot);
+        const configPath = path.join(tempRoot, 'config.json');
+        const openCodeDir = path.join(env.XDG_CONFIG_HOME, 'opencode');
+        const jsonPath = path.join(openCodeDir, 'opencode.json');
+        const jsoncPath = path.join(openCodeDir, 'opencode.jsonc');
+        fs.mkdirSync(openCodeDir, { recursive: true });
+        fs.writeFileSync(configPath, JSON.stringify({ Environment: { KBPath: tempRoot } }));
+        fs.writeFileSync(jsoncPath, JSON.stringify({ mcp: { servers: {} } }));
+        fs.writeFileSync(jsonPath, JSON.stringify({ mcp: { genexus18mcp: {
+            type: 'local',
+            command: ['npx.cmd', '-y', 'genexus-mcp@latest']
+        } } }));
+
+        const status = runCli(['clients', '--format', 'json'], {
+            env: { ...env, GX_CONFIG_PATH: configPath }
+        });
+        assert.equal(status.status, 0);
+        const row = JSON.parse(status.stdout).ok.clients.find((client) => client.id === 'opencode');
+        assert.ok(row && row.registered);
+        assert.equal(row.configPath, jsonPath);
+
+        const removed = runCli(['clients', 'remove', '--clients', 'opencode', '--format', 'json'], {
+            env: { ...env, GX_CONFIG_PATH: configPath }
+        });
+        assert.equal(removed.status, 0);
+        assert.equal(JSON.parse(fs.readFileSync(jsonPath, 'utf8')).mcp.genexus18mcp, undefined);
+        assert.equal(JSON.parse(fs.readFileSync(jsoncPath, 'utf8')).mcp.servers.genexus18mcp, undefined);
+    } finally {
+        removeTempPath(tempRoot, { recursive: true, force: true });
+    }
+});
+
 test('OpenCode Desktop is not falsely reported as installed when only CLI config exists', () => {
     const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-opencode-desktop-undetected-'));
     try {
@@ -1821,26 +2038,30 @@ test('clients list keeps an existing unrecognized launcher indeterminate', () =>
         assert.equal(cursor.launcherStructuralState, 'indeterminate');
         assert.equal(cursor.launcherSemanticState, 'unknown');
         assert.equal(cursor.commandStale, false, 'unknown commands are not treated as invalid');
+        assert.equal(cursor.launcherPathDrift, false, 'drift fields are always present in the payload');
+        assert.equal(cursor.launcherPathDriftReason, null);
     } finally {
         removeTempPath(tempRoot, { recursive: true, force: true });
     }
 });
 
-test('clients list marks an Antigravity launcher from an old package cache as stale', () => {
-    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-antigravity-stale-'));
+test('clients list reports a checkout gateway as path drift, not as stale', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-checkout-drift-'));
     try {
         const env = sandboxHomeEnv(tempRoot);
+        // A checkout install registers the client against the checkout's own
+        // publish/ gateway while this CLI compares against its own gateway.
+        const checkoutGateway = path.join(tempRoot, 'checkout', 'publish', 'GxMcp.Gateway.exe');
         const currentGateway = path.join(tempRoot, 'current', 'GxMcp.Gateway.exe');
-        const oldGateway = path.join(tempRoot, 'old-cache', 'GxMcp.Gateway.exe');
+        fs.mkdirSync(path.dirname(checkoutGateway), { recursive: true });
         fs.mkdirSync(path.dirname(currentGateway), { recursive: true });
-        fs.mkdirSync(path.dirname(oldGateway), { recursive: true });
+        fs.writeFileSync(checkoutGateway, 'checkout');
         fs.writeFileSync(currentGateway, 'current');
-        fs.writeFileSync(oldGateway, 'old');
 
         const antigravityCfg = path.join(tempRoot, '.gemini', 'antigravity', 'mcp_config.json');
         fs.mkdirSync(path.dirname(antigravityCfg), { recursive: true });
         fs.writeFileSync(antigravityCfg, JSON.stringify({
-            mcpServers: { genexus18mcp: { command: oldGateway, args: [] } }
+            mcpServers: { genexus18mcp: { command: checkoutGateway, args: [] } }
         }, null, 2));
 
         const result = runCli(['clients', '--format', 'json'], {
@@ -1849,8 +2070,39 @@ test('clients list marks an Antigravity launcher from an old package cache as st
         assert.equal(result.status, 0);
         const parsed = JSON.parse(result.stdout);
         const antigravity = parsed.ok.clients.find((client) => client.id === 'antigravity');
-        assert.equal(antigravity.commandStale, true);
-        assert.match(antigravity.commandStaleReason, /different package gateway/);
+        assert.equal(antigravity.commandStale, false, 'an existing gateway from another install is not broken');
+        assert.equal(antigravity.launcherStructuralState, 'present');
+        assert.equal(antigravity.launcherSemanticState, 'valid');
+        assert.equal(antigravity.launcherPathDrift, true, 'the drift is still reported');
+        assert.match(antigravity.launcherPathDriftReason, /differs from this CLI's gateway/);
+        assert.ok(parsed.help.some((h) => h.startsWith('Note:')), 'drift is informational, not a repair instruction');
+        assert.ok(!parsed.help.some((h) => h.includes('missing gateway exe')), 'a valid launcher must not be listed as missing');
+    } finally {
+        removeTempPath(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('clients list marks the same gateway as this CLI without drift', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-same-gateway-'));
+    try {
+        const env = sandboxHomeEnv(tempRoot);
+        const gatewayPath = path.join(tempRoot, 'publish', 'GxMcp.Gateway.exe');
+        fs.mkdirSync(path.dirname(gatewayPath), { recursive: true });
+        fs.writeFileSync(gatewayPath, 'gateway');
+        const cursorCfg = path.join(tempRoot, '.cursor', 'mcp.json');
+        fs.mkdirSync(path.dirname(cursorCfg), { recursive: true });
+        fs.writeFileSync(cursorCfg, JSON.stringify({
+            mcpServers: { genexus18mcp: { command: gatewayPath, args: [] } }
+        }, null, 2));
+
+        const result = runCli(['clients', '--format', 'json'], {
+            env: { ...env, GENEXUS_MCP_GATEWAY_EXE: gatewayPath }
+        });
+        assert.equal(result.status, 0);
+        const cursor = JSON.parse(result.stdout).ok.clients.find((client) => client.id === 'cursor');
+        assert.equal(cursor.commandStale, false);
+        assert.equal(cursor.launcherPathDrift, false);
+        assert.equal(cursor.launcherPathDriftReason, null);
     } finally {
         removeTempPath(tempRoot, { recursive: true, force: true });
     }

package/config/gx-versions.json

@@ -2,6 +2,13 @@
   "$schema": "genexus-mcp/version-catalog/1",
   "primaryMajor": "18",
   "supportedMajors": [
+    {
+      "major": "16",
+      "displayName": "GeneXus 16",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus16",
+      "registryNames": ["GeneXus 16"],
+      "legacyRegistryVersions": ["16.0"]
+    },
     {
       "major": "17",
       "displayName": "GeneXus 17",
@@ -16,5 +23,55 @@
       "registryNames": ["GeneXus 18"],
       "legacyRegistryVersions": ["18.0"]
     }
+  ],
+  "legacyMajors": [
+    {
+      "major": "10.3",
+      "displayName": "GeneXus Evolution 3",
+      "driver": "dotnet-reflection",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXusXEv3",
+      "registryNames": ["GeneXus X Evolution 3", "GeneXus 10.3"],
+      "legacyRegistryVersions": ["10.3"]
+    },
+    {
+      "major": "10.2",
+      "displayName": "GeneXus Evolution 2",
+      "driver": "dotnet-reflection",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXusXEv2",
+      "registryNames": ["GeneXus X Evolution 2", "GeneXus 10.2"],
+      "legacyRegistryVersions": ["10.2"]
+    },
+    {
+      "major": "10.1",
+      "displayName": "GeneXus Evolution 1",
+      "driver": "dotnet-reflection",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXusXEv1",
+      "registryNames": ["GeneXus X Evolution 1", "GeneXus 10.1"],
+      "legacyRegistryVersions": ["10.1"]
+    },
+    {
+      "major": "15",
+      "displayName": "GeneXus 15",
+      "driver": "dotnet-reflection",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus15",
+      "registryNames": ["GeneXus 15"],
+      "legacyRegistryVersions": ["15.0"]
+    },
+    {
+      "major": "9",
+      "displayName": "GeneXus 9.0",
+      "driver": "com-gxpublic",
+      "defaultInstallPath": "C:\\Program Files (x86)\\ARTech\\GeneXus\\GeneXus 9.0",
+      "registryNames": ["GeneXus 9.0"],
+      "legacyRegistryVersions": ["9.0"]
+    },
+    {
+      "major": "8",
+      "displayName": "GeneXus 8.0",
+      "driver": "com-gxpublic",
+      "defaultInstallPath": "C:\\Program Files (x86)\\ARTech\\GeneXus\\GeneXus 8.0",
+      "registryNames": ["GeneXus 8.0"],
+      "legacyRegistryVersions": ["8.0"]
+    }
   ]
 }

package/docs/llm_cli_mcp_playbook.md

@@ -41,6 +41,7 @@ Entry points:
 Neutral installer/runtime setup:
 - `genexus-mcp config create --config-scope neutral --output <path> --gx <path> --worker <path> --gateway-mode stdio-isolated --resolution-policy strict`
 - `genexus-mcp clients add --all-clients` (or `--clients opencode,codex-cli,vscode,antigravity,gemini-cli`)
+- From a **local checkout**, register/repair harnesses with the checkout CLI and gateway instead of `npx`: from the repo root `$env:GENEXUS_MCP_GATEWAY_EXE='<repoRoot>\publish\GxMcp.Gateway.exe'; node cli\run.js clients add --all-clients` (or `./install.ps1`), then validate with `node cli\run.js clients` / `node cli\run.js doctor`. Reserve the `npx genexus-mcp@latest …` forms for installs that have no local `publish\`; see the startup-failure section for the stale-path case.
 - `genexus-mcp config migrate --from <legacy.json> --output <neutral.json>` is the only configuration migration path. It copies runtime fields into the neutral schema (`ConfigSchemaVersion: 2`, `GatewayMode`, `GeneXus`, `Server`, and `Environment.ResolutionPolicy`), writes an atomic source backup, verifies the destination by read-back, and rolls back an existing destination if verification fails. The JSON receipt reports `backupPath`, `readBack`, `rolledBack`, `migrated`, and `notMigrated`.
 - Legacy KB fields (`Environment.KBPath`, `KBs`, `DefaultKb`, `ActiveKb`) are deliberately not migrated because neutral configs are KB-free. Use `--reject-non-migratable` to fail before writing when any are present.
 - `init` and `clients add` never migrate or rewrite an existing config automatically. `kb add`, `kb remove`, and `kb switch` remain the legacy catalog flow: they mutate the `Environment` catalog in the config selected by `GX_CONFIG_PATH` or the current directory. Neutral runtimes use explicit per-session MCP KB selection instead.
@@ -76,6 +77,28 @@ marks that path stale, re-register it with `npx genexus-mcp@latest clients add -
 Do not infer an npx incompatibility or switch to a global npm install before reading
 this file.
 
+**Local checkout.** If you run clients from a repo checkout that has a local `publish\`,
+re-register and validate with that same checkout CLI so the harness keeps pointing at
+its gateway:
+
+```powershell
+# from the repo root
+$env:GENEXUS_MCP_GATEWAY_EXE = "<repoRoot>\publish\GxMcp.Gateway.exe"
+node cli\run.js clients add --clients <id>   # or re-run .\install.ps1
+node cli\run.js clients --format json        # validate
+node cli\run.js doctor --mcp-smoke --format json
+```
+
+`clients` and `doctor` only validate — neither rewrites a launcher. Running
+`npx genexus-mcp@latest clients add` from the checkout (or its help line) rewrites the
+client to the npm-cache launcher, which is what actually moves a harness off the
+checkout; that is the reason to keep install, validation, and repair on one CLI/env.
+Reading back a checkout registration with a different CLI is safe and informative: a
+client that points at another *existing* gateway is reported as `launcherPathDrift`
+with `commandStale: false`, not as stale, because the launcher is valid. `doctor`'s
+`client_config_sync` check still warns when the configured exe is not the packaged one
+(the broader, explicit drift check across every client).
+
 ## MCP Contract (LLM-facing)
 
 For `tools/call`, parse `result.content[0].text` as JSON.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "genexus-mcp",
-  "version": "3.5.3",
+  "version": "3.6.1",
   "mcpName": "io.github.lennix1337/genexus",
-  "description": "GeneXus 17, GeneXus 18 MCP server — read, edit, and analyze Knowledge Base objects directly from Claude, Cursor, and other AI agents over the Model Context Protocol.",
+  "description": "GeneXus 16, GeneXus 17, GeneXus 18 MCP server with native SDK support; basic legacy compatibility for GeneXus Evolution 3, GeneXus Evolution 2, GeneXus Evolution 1, GeneXus 15, GeneXus 9.0, GeneXus 8.0 via com-gxpublic and dotnet-reflection drivers — read, edit, and analyze Knowledge Base objects directly from Claude, Cursor, and other AI agents over the Model Context Protocol.",
   "keywords": [
     "mcp",
     "mcp-server",
@@ -32,7 +32,7 @@
     "automation"
   ],
   "scripts": {
-    "test": "node --test cli/run.test.js cli/lib/client-adapters.test.js cli/docs.test.js scripts/lint.test.js && npm run test:live-contract",
+    "test": "node --test cli/run.test.js cli/lib/client-adapters.test.js cli/docs.test.js scripts/lint.test.js scripts/verify-install.test.js && npm run test:live-contract",
     "lint": "node scripts/lint.js",
     "test:live-contract": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/tests/test-live.test.ps1",
     "test:integration": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/integration-preflight.ps1",

package/publish/GxMcp.Gateway.deps.json

@@ -7,7 +7,7 @@
   "targets": {
     ".NETCoreApp,Version=v10.0": {},
     ".NETCoreApp,Version=v10.0/win-x64": {
-      "GxMcp.Gateway/3.5.3": {
+      "GxMcp.Gateway/3.6.1": {
         "dependencies": {
           "Newtonsoft.Json": "13.0.3",
           "System.Management": "10.0.5",
@@ -66,7 +66,7 @@
     }
   },
   "libraries": {
-    "GxMcp.Gateway/3.5.3": {
+    "GxMcp.Gateway/3.6.1": {
       "type": "project",
       "serviceable": false,
       "sha512": ""

package/publish/config/gx-versions.json

@@ -2,6 +2,13 @@
   "$schema": "genexus-mcp/version-catalog/1",
   "primaryMajor": "18",
   "supportedMajors": [
+    {
+      "major": "16",
+      "displayName": "GeneXus 16",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus16",
+      "registryNames": ["GeneXus 16"],
+      "legacyRegistryVersions": ["16.0"]
+    },
     {
       "major": "17",
       "displayName": "GeneXus 17",
@@ -16,5 +23,55 @@
       "registryNames": ["GeneXus 18"],
       "legacyRegistryVersions": ["18.0"]
     }
+  ],
+  "legacyMajors": [
+    {
+      "major": "10.3",
+      "displayName": "GeneXus Evolution 3",
+      "driver": "dotnet-reflection",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXusXEv3",
+      "registryNames": ["GeneXus X Evolution 3", "GeneXus 10.3"],
+      "legacyRegistryVersions": ["10.3"]
+    },
+    {
+      "major": "10.2",
+      "displayName": "GeneXus Evolution 2",
+      "driver": "dotnet-reflection",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXusXEv2",
+      "registryNames": ["GeneXus X Evolution 2", "GeneXus 10.2"],
+      "legacyRegistryVersions": ["10.2"]
+    },
+    {
+      "major": "10.1",
+      "displayName": "GeneXus Evolution 1",
+      "driver": "dotnet-reflection",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXusXEv1",
+      "registryNames": ["GeneXus X Evolution 1", "GeneXus 10.1"],
+      "legacyRegistryVersions": ["10.1"]
+    },
+    {
+      "major": "15",
+      "displayName": "GeneXus 15",
+      "driver": "dotnet-reflection",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus15",
+      "registryNames": ["GeneXus 15"],
+      "legacyRegistryVersions": ["15.0"]
+    },
+    {
+      "major": "9",
+      "displayName": "GeneXus 9.0",
+      "driver": "com-gxpublic",
+      "defaultInstallPath": "C:\\Program Files (x86)\\ARTech\\GeneXus\\GeneXus 9.0",
+      "registryNames": ["GeneXus 9.0"],
+      "legacyRegistryVersions": ["9.0"]
+    },
+    {
+      "major": "8",
+      "displayName": "GeneXus 8.0",
+      "driver": "com-gxpublic",
+      "defaultInstallPath": "C:\\Program Files (x86)\\ARTech\\GeneXus\\GeneXus 8.0",
+      "registryNames": ["GeneXus 8.0"],
+      "legacyRegistryVersions": ["8.0"]
+    }
   ]
 }

package/publish/config.json

@@ -1,19 +1,19 @@
 {
-  "GeneXus": {
-    "WorkerExecutable": "worker\\\\GxMcp.Worker.exe",
-    "InstallationPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18"
-  },
   "Environment": {
     "ResolutionPolicy": "strict"
   },
   "Server": {
-    "SessionIdleTimeoutMinutes": 10,
-    "EmitStructuredContent": false,
-    "WorkerIdleTimeoutMinutes": 5,
     "McpStdio": true,
+    "TerseResponses": true,
     "HttpPort": 0,
-    "TerseResponses": true
+    "WorkerIdleTimeoutMinutes": 5,
+    "SessionIdleTimeoutMinutes": 10,
+    "EmitStructuredContent": false
   },
   "ConfigSchemaVersion": 2,
+  "GeneXus": {
+    "InstallationPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18",
+    "WorkerExecutable": "worker\\\\GxMcp.Worker.exe"
+  },
   "GatewayMode": "stdio-isolated"
 }