genexus-mcp 2.49.1 → 2.49.2

package/README.md

@@ -84,6 +84,13 @@ What you'll see (takes ~30 seconds first time, faster on re-runs):
 4. Prints a JSON snippet at the end — keep it in case you need to configure a client manually.
 5. Finishes with `🎉 You are all set!`.
 
+On Windows, Antigravity is registered with the gateway executable bundled in the
+current npm package when that artifact is available, so it skips the npx bootstrap
+chain on every MCP handshake. That path follows the package in the npx cache; after
+an upgrade, run `npx genexus-mcp@latest clients add --clients antigravity` again if
+`genexus-mcp clients` reports a stale launcher. Other clients keep the `npx genexus-mcp@latest`
+launcher unless you use the fixed-path installer below.
+
 ### Step 2 — Register the MCP in your AI client
 
 Step 1 auto-registers every supported client it detects, including Claude Desktop, Claude Code, Cursor, Antigravity, Gemini CLI, OpenCode, Codex CLI, and VS Code. If yours wasn't detected, copy the JSON snippet from Step 1 into your client's MCP config manually. See the [client setup guide](TROUBLESHOOTING.md#client-setup) if unsure where that file lives.
@@ -205,7 +212,7 @@ Auto-detected and auto-configured by the installer:
 | Claude Desktop | ✅ | Restart required after install |
 | Claude Code (CLI) | ✅ | Reload session |
 | Cursor | ✅ | Restart required |
-| Antigravity | ✅ | Restart required; detected even before its MCP config exists |
+| Antigravity | ✅ | Direct packaged gateway; restart required; detected even before its MCP config exists |
 | Gemini CLI | ✅ | — |
 | OpenCode (CLI) | ✅ | Reads both direct and nested MCP layouts; restart required |
 | Codex CLI | ✅ | Writes `~/.codex/config.toml` |
@@ -229,6 +236,14 @@ Most install issues fall into a handful of buckets — see **[TROUBLESHOOTING.md
 - KB build errors / locked artifacts
 - Port 5000 already in use
 - Permissions on `%LOCALAPPDATA%\GenexusMCP\`
+- Antigravity only shows `exit status 1` / `0xffffffff` with no useful stderr
+
+When a stdio launcher fails before the client can retain stderr, the wrapper writes
+the last failure to `%LOCALAPPDATA%\GenexusMCP\logs\last-stdio-error.txt`. It contains
+the UTC timestamp, exit code, and bounded stderr tail. `genexus-mcp doctor` reports the
+same path when a previous failure is present. Read it before changing the install or
+using a global npm install; if the Antigravity launcher is stale, re-register it with
+`npx genexus-mcp@latest clients add --clients antigravity`.
 
 Still stuck? [Open an issue](https://github.com/lennix1337/Genexus18MCP/issues) with the output of `npx genexus-mcp doctor --mcp-smoke`.
 

package/cli/commands/axi.js

@@ -30,6 +30,7 @@ const {
     readClientCommandEntry,
     DEFAULT_MCP_SERVER_NAME
 } = require('../lib/config');
+const { getStdioErrorLogPath } = require('../lib/stdio-diagnostics');
 
 function resolveClientIds(options) {
     if (!options || !options.clients) return null;
@@ -656,6 +657,8 @@ async function handleDoctor(options, ctx) {
     const toolDefPath = getToolDefinitionsPath();
     const toolDefsExists = fs.existsSync(toolDefPath);
     const gatewayExePath = getGatewayExePath();
+    const stdioErrorLogPath = getStdioErrorLogPath();
+    const stdioErrorLogExists = !!(stdioErrorLogPath && fs.existsSync(stdioErrorLogPath));
 
     let toolCount = 0;
     if (toolDefsExists) {
@@ -678,6 +681,13 @@ async function handleDoctor(options, ctx) {
     const checks = [
         { id: 'config_file', status: data.configFound ? 'pass' : 'fail', detail: data.configFound ? 'GX config file was found.' : 'GX config file is missing.' },
         { id: 'gateway_exe', status: data.gatewayExeFound ? 'pass' : 'fail', detail: data.gatewayExeFound ? 'Gateway executable is available.' : 'Gateway executable is missing.' },
+        {
+            id: 'stdio_error_log',
+            status: stdioErrorLogExists ? 'warn' : 'pass',
+            detail: stdioErrorLogExists
+                ? `Previous stdio launcher failure recorded at ${stdioErrorLogPath}. Read this file for the last exit code and stderr tail.`
+                : `Stdio launcher error log: ${stdioErrorLogPath || 'not available on this platform'}.`
+        },
         {
             id: 'gateway_exe_path_safety',
             status: riskyZone ? 'warn' : 'pass',
@@ -1153,6 +1163,18 @@ async function handleLayout(subcommand, options, ctx) {
     };
 }
 
+function buildClientLauncherHelp(patchResult) {
+    const help = [];
+    const patched = patchResult && Array.isArray(patchResult.patched) ? patchResult.patched : [];
+    if (patched.includes('Antigravity') && process.platform === 'win32' && !process.env.GENEXUS_MCP_GATEWAY_EXE) {
+        help.push('Antigravity uses the gateway executable bundled with this npm package when available; re-run `npx genexus-mcp@latest clients add --clients antigravity` after an upgrade if its package path is stale.');
+    }
+    if (patched.length > 0 && process.platform === 'win32' && !process.env.GENEXUS_MCP_GATEWAY_EXE) {
+        help.push('Windows launcher paths may resolve under the npm cache and be blocked by AppLocker/SRP. Use scripts/install.ps1 for a stable whitelisted path.');
+    }
+    return help;
+}
+
 function buildInteractiveInitHelp(patchResult) {
     const help = [];
     if (patchResult.failed && patchResult.failed.some((f) => f.reason && f.reason.includes('third-party or HTTP MCP server'))) {
@@ -1160,9 +1182,8 @@ function buildInteractiveInitHelp(patchResult) {
     }
     if (patchResult.patched.length === 0) {
         help.push('Set `GX_CONFIG_PATH` in your MCP client env to the generated config path.');
-    } else if (process.platform === 'win32' && !process.env.GENEXUS_MCP_GATEWAY_EXE) {
-        help.push('Windows + corporate AppLocker: the npx launcher resolves the gateway from %LOCALAPPDATA%\\npm-cache, which is commonly blocked. If clients fail with "Failed to connect" / Access denied, reinstall to a whitelisted path via scripts/install.ps1.');
     }
+    help.push(...buildClientLauncherHelp(patchResult));
     return help;
 }
 
@@ -1440,9 +1461,7 @@ async function handleInit(options, ctx) {
         } else if (patchResult.patched.length === 0 && !shouldWriteClients) {
             help.push('Client patching was skipped (--no-write-clients). Register manually, or set GX_CONFIG_PATH to this config for global use.');
         }
-        if (patchResult.patched.length > 0 && process.platform === 'win32' && !process.env.GENEXUS_MCP_GATEWAY_EXE) {
-            help.push('Windows + corporate AppLocker: the npx launcher resolves the gateway from %LOCALAPPDATA%\\npm-cache, which is commonly blocked. If clients fail with "Failed to connect" / Access denied, reinstall to a whitelisted path via scripts/install.ps1.');
-        }
+        help.push(...buildClientLauncherHelp(patchResult));
         if (verification.summary.fail > 0) {
             const failedIds = verification.checks
                 .filter((c) => c.status === 'fail')

package/cli/index.js

@@ -28,6 +28,7 @@ const {
     commandHelpMap
 } = require('./commands/axi');
 const { startBackgroundUpdateCheck, handleUpdate } = require('./lib/update-check');
+const { createStderrTail, writeLastStdioError } = require('./lib/stdio-diagnostics');
 
 const EXIT_CODES = {
     OK: 0,
@@ -350,49 +351,91 @@ function writeAppLockerHint(stderr, gatewayExePath) {
 }
 
 async function launchGateway(passthroughArgs, options) {
+    const stderrTail = createStderrTail();
+    const launcherStderr = {
+        write(chunk) {
+            stderrTail.append(chunk);
+            if (!options.quiet) process.stderr.write(chunk);
+            return true;
+        }
+    };
+    const recordStdioFailure = ({ gatewayExePath, exitCode = null, signal = null, error = null } = {}) => {
+        const logPath = writeLastStdioError({
+            gatewayExePath,
+            exitCode,
+            signal,
+            error,
+            stderrTail: stderrTail.toString()
+        });
+        if (logPath && !options.quiet) {
+            process.stderr.write(`[genexus-mcp] Last stdio error saved to ${logPath}\n`);
+        }
+    };
+
     const setup = applyLauncherConfigOrExit({
         cwd: process.cwd(),
-        stderr: process.stderr,
+        stderr: launcherStderr,
         quiet: options.quiet
     });
 
     if (!setup.ok) {
+        recordStdioFailure({ gatewayExePath: getGatewayExePath(), exitCode: EXIT_CODES.ERROR, error: 'Launcher setup failed.' });
         return EXIT_CODES.ERROR;
     }
 
     const gatewayExePath = getGatewayExePath();
     if (!require('fs').existsSync(gatewayExePath)) {
-        if (!options.quiet) {
-            process.stderr.write(`[genexus-mcp] ERROR: Gateway executable not found at ${gatewayExePath}\n`);
-        }
+        const message = `[genexus-mcp] ERROR: Gateway executable not found at ${gatewayExePath}`;
+        launcherStderr.write(`${message}\n`);
+        recordStdioFailure({ gatewayExePath, exitCode: EXIT_CODES.ERROR, error: 'Gateway executable not found.' });
         return EXIT_CODES.ERROR;
     }
 
     return await new Promise((resolve) => {
-        const child = spawn(gatewayExePath, passthroughArgs, {
-            stdio: 'inherit',
-            env: process.env,
-            windowsHide: true
-        });
+        let settled = false;
+        const finish = (code) => {
+            if (settled) return;
+            settled = true;
+            resolve(code);
+        };
+        const handleSpawnError = (err) => {
+            const message = `[genexus-mcp] ERROR: Failed to start gateway process: ${err.message}`;
+            launcherStderr.write(`${message}\n`);
+            const code = err && (err.code || err.errno);
+            const accessDenied = code === 'EACCES' || code === 'EPERM' || /access is denied|access denied|acesso negado/i.test(err.message || '');
+            if (accessDenied) writeAppLockerHint(launcherStderr, gatewayExePath);
+            recordStdioFailure({ gatewayExePath, error: err.message || 'Failed to start gateway process.' });
+            finish(EXIT_CODES.ERROR);
+        };
 
-        child.on('error', (err) => {
-            if (!options.quiet) {
-                process.stderr.write(`[genexus-mcp] ERROR: Failed to start gateway process: ${err.message}\n`);
-                const code = err && (err.code || err.errno);
-                const accessDenied = code === 'EACCES' || code === 'EPERM' || /access is denied|access denied|acesso negado/i.test(err.message || '');
-                if (accessDenied) {
-                    writeAppLockerHint(process.stderr, gatewayExePath);
-                }
-            }
-            resolve(EXIT_CODES.ERROR);
-        });
+        let child;
+        try {
+            child = spawn(gatewayExePath, passthroughArgs, {
+                // Keep stdout attached to the MCP protocol and tee stderr so a
+                // failed bootstrap remains available after a client drops it.
+                stdio: ['inherit', 'inherit', 'pipe'],
+                env: process.env,
+                windowsHide: true
+            });
+        } catch (err) {
+            handleSpawnError(err);
+            return;
+        }
+
+        if (child.stderr) {
+            child.stderr.on('data', (chunk) => {
+                stderrTail.append(chunk);
+                process.stderr.write(chunk);
+            });
+        }
+
+        child.once('error', handleSpawnError);
 
-        child.on('exit', (code, signal) => {
-            if (signal) {
-                resolve(EXIT_CODES.ERROR);
-                return;
+        child.once('close', (code, signal) => {
+            if (signal || code !== 0) {
+                recordStdioFailure({ gatewayExePath, exitCode: code, signal });
             }
-            resolve(code || EXIT_CODES.OK);
+            finish(signal ? EXIT_CODES.ERROR : (code === null || code === undefined ? EXIT_CODES.ERROR : code));
         });
     });
 }

package/cli/lib/config.js

@@ -444,13 +444,21 @@ function createConfigFile(kbPath, gxPath) {
     };
 }
 
-function getLauncher() {
+function getLauncher(client = null, gatewayExePath = getGatewayExePath()) {
     // Set by scripts/install.ps1 for fixed-path corporate installs — clients
     // launch the gateway exe directly instead of resolving via the npx cache.
     const directExe = process.env.GENEXUS_MCP_GATEWAY_EXE;
-    return directExe
-        ? { command: directExe, args: [] }
-        : { command: process.platform === 'win32' ? 'npx.cmd' : 'npx', args: ['-y', 'genexus-mcp@latest'] };
+    if (directExe) return { command: directExe, args: [] };
+
+    // Antigravity does not retain child stderr in its Language Server logs. When
+    // the packaged gateway is available, point it directly at that executable so
+    // each MCP handshake skips the npx bootstrap chain. The fallback keeps
+    // source-tree development and incomplete packages on the existing npx path.
+    if (client && client.preferDirectGateway && fs.existsSync(gatewayExePath)) {
+        return { command: gatewayExePath, args: [] };
+    }
+
+    return { command: process.platform === 'win32' ? 'npx.cmd' : 'npx', args: ['-y', 'genexus-mcp@latest'] };
 }
 
 const DEFAULT_MCP_SERVER_NAME = 'genexus18mcp';
@@ -576,6 +584,9 @@ function getClientConfigTargets() {
             name: 'Antigravity',
             format: 'mcpServers',
             path: resolveAntigravityConfigPath(home),
+            // The npm package includes the gateway exe. Prefer it for this client
+            // because Antigravity hides the stderr of an npx child when startup fails.
+            preferDirectGateway: true,
             // Unambiguous Antigravity markers only. ~/.gemini/config is NOT a
             // marker — gemini-cli can create ~/.gemini, and we'd false-positive;
             // it's still used as the write path (resolveAntigravityConfigPath)
@@ -699,7 +710,7 @@ function listSupportedClientIds() {
 // by an explicit path (a separator in the command) that no longer exists on disk
 // is the classic "Failed to connect / still on old version" cause after an
 // install dir moved or was cleaned — covers .exe, .bat, .cmd, .sh, extensionless.
-function clientCommandHealth(entry) {
+function clientCommandHealth(entry, client = null) {
     if (!entry || !entry.command) return { stale: false, reason: null };
     const cmd = String(entry.command);
     if (/(^|[\\/])(npx|npx\.cmd|node|node\.exe|genexus-mcp|genexus-mcp\.cmd)$/i.test(cmd)) {
@@ -708,6 +719,12 @@ function clientCommandHealth(entry) {
     if (/[\\/]/.test(cmd) && !fs.existsSync(cmd)) {
         return { stale: true, reason: 'configured launcher does not exist on disk' };
     }
+    if (client && client.preferDirectGateway && /GxMcp\.Gateway\.exe$/i.test(cmd)) {
+        const currentPackageGateway = getGatewayExePath();
+        if (fs.existsSync(currentPackageGateway) && normalizeExePath(cmd) !== normalizeExePath(currentPackageGateway)) {
+            return { stale: true, reason: 'configured launcher points at a different package gateway; re-register the client' };
+        }
+    }
     return { stale: false, reason: null };
 }
 
@@ -723,7 +740,7 @@ function clientsStatus(opts = {}) {
     return targets.map((client) => {
         const det = detectClientInstalled(client);
         const entry = readClientCommandEntry(client, serverName);
-        const health = clientCommandHealth(entry);
+        const health = clientCommandHealth(entry, client);
         const isThirdParty = entry && !isOurMcpEntry(entry.raw || entry, serverName);
         return {
             id: client.id,
@@ -771,7 +788,6 @@ function patchClientConfig(targetConfigPath, opts = {}) {
 
     const serverName = opts.serverName || DEFAULT_MCP_SERVER_NAME;
     const force = Boolean(opts.force);
-    const launcher = getLauncher();
     const onlyExisting = opts.onlyExisting !== false;
     const candidates = filterClientTargets(getClientConfigTargets(), {
         ids: opts.ids,
@@ -800,7 +816,7 @@ function patchClientConfig(targetConfigPath, opts = {}) {
         }
         try {
             fs.mkdirSync(path.dirname(client.path), { recursive: true });
-            applyClientEntry(client, launcher, targetConfigPath, { serverName, force });
+            applyClientEntry(client, getLauncher(client), targetConfigPath, { serverName, force });
             // 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)) {
@@ -1187,10 +1203,6 @@ function removeCodexToml(filePath, { serverName = DEFAULT_MCP_SERVER_NAME } = {}
     return true;
 }
 
-function stripCodexGenexusBlocks(content) {
-    return stripCodexServerBlocks(content, 'genexus');
-}
-
 function tomlString(value) {
     const s = String(value);
     return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
@@ -1519,6 +1531,7 @@ module.exports = {
     applyLauncherConfigOrExit,
     isPathLikelyAppLockerBlocked,
     normalizeExePath,
+    getLauncher,
     readClientCommandEntry,
     isOurMcpEntry,
     DEFAULT_MCP_SERVER_NAME

package/cli/lib/stdio-diagnostics.js

@@ -0,0 +1,67 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const MAX_STDERR_BYTES = 64 * 1024;
+
+function getStdioErrorLogPath() {
+    if (process.platform !== 'win32') return null;
+    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(localAppData, 'GenexusMCP', 'logs', 'last-stdio-error.txt');
+}
+
+function trimToMaxBytes(value, maxBytes = MAX_STDERR_BYTES) {
+    const raw = String(value || '');
+    const bytes = Buffer.from(raw, 'utf8');
+    if (bytes.length <= maxBytes) return raw;
+    return bytes.subarray(bytes.length - maxBytes).toString('utf8');
+}
+
+function createStderrTail(maxBytes = MAX_STDERR_BYTES) {
+    let value = '';
+    return {
+        append(chunk) {
+            if (chunk === undefined || chunk === null) return;
+            value = trimToMaxBytes(value + (Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk)), maxBytes);
+        },
+        toString() {
+            return value;
+        }
+    };
+}
+
+function oneLine(value, fallback = '') {
+    const text = value === undefined || value === null ? '' : String(value);
+    return text.replace(/\r?\n/g, ' ').trim() || fallback;
+}
+
+function writeLastStdioError({ gatewayExePath, exitCode = null, signal = null, error = null, stderrTail = '' } = {}) {
+    const logPath = getStdioErrorLogPath();
+    if (!logPath) return null;
+
+    const tail = trimToMaxBytes(stderrTail).trimEnd();
+    const lines = [
+        `timestampUtc: ${new Date().toISOString()}`,
+        `gateway: ${oneLine(gatewayExePath, '(unknown)')}`,
+        `exitCode: ${exitCode === null || exitCode === undefined ? 'n/a' : exitCode}`,
+        `signal: ${oneLine(signal, 'none')}`
+    ];
+    if (error) lines.push(`error: ${oneLine(error)}`);
+    lines.push('stderr:');
+    lines.push(tail || '(none captured)');
+    lines.push('');
+
+    try {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        fs.writeFileSync(logPath, lines.join('\n'), 'utf8');
+        return logPath;
+    } catch {
+        return null;
+    }
+}
+
+module.exports = {
+    createStderrTail,
+    getStdioErrorLogPath,
+    writeLastStdioError
+};

package/cli/lib/update-check.js

@@ -224,7 +224,7 @@ function detectInstallMethod() {
     if (process.env.GENEXUS_MCP_GATEWAY_EXE) {
         return { method: 'fixed-path', detail: process.env.GENEXUS_MCP_GATEWAY_EXE, evidence: [] };
     }
-    const counts = { 'npx-latest': 0, 'npm-global': 0, 'fixed-path': 0 };
+    const counts = { 'npx-latest': 0, 'npm-global': 0, 'fixed-path': 0, 'package-direct': 0 };
     const evidence = [];
     try {
         for (const c of clientsStatus()) {
@@ -233,6 +233,7 @@ function detectInstallMethod() {
             let m;
             if (/(^|[\\/])npx(\.cmd)?$/i.test(cmd)) m = 'npx-latest';
             else if (/(^|[\\/])genexus-mcp(\.cmd)?$/i.test(cmd)) m = 'npm-global';
+            else if (c.id === 'antigravity' && /GxMcp\.Gateway\.exe$/i.test(cmd)) m = 'package-direct';
             else if (/[\\/]/.test(cmd)) m = 'fixed-path';
             else m = 'npm-global';
             counts[m] = (counts[m] || 0) + 1;
@@ -279,6 +280,20 @@ function upgradePlanFor(method, channel) {
             restartRequired: true
         };
     }
+    if (method === 'package-direct') {
+        const tag = channel && channel !== 'latest' ? `@${channel}` : '@latest';
+        return {
+            method,
+            auto: false,
+            steps: [
+                'Antigravity launches the gateway executable bundled with the npm package, so each MCP handshake skips npx.',
+                `Refresh its pinned package path with: npx -y ${NPM_PACKAGE}${tag} clients add --clients antigravity`,
+                'Then fully restart Antigravity.'
+            ],
+            applyCommand: null,
+            restartRequired: true
+        };
+    }
     // npm-global
     return {
         method: 'npm-global',
@@ -383,7 +398,11 @@ async function handleUpdate(options, ctx) {
                 source: result.source || null,
                 installMethod: install.method,
                 autoUpdates: plan.auto,
-                installCommand: plan.applyCommand ? `${plan.applyCommand.exe} ${plan.applyCommand.args.join(' ')}` : INSTALL_ONE_LINER,
+                installCommand: plan.applyCommand
+                    ? `${plan.applyCommand.exe} ${plan.applyCommand.args.join(' ')}`
+                    : (install.method === 'package-direct'
+                        ? `npx -y ${NPM_PACKAGE}${channel && channel !== 'latest' ? `@${channel}` : '@latest'} clients add --clients antigravity`
+                        : INSTALL_ONE_LINER),
                 applied,
                 fetched: true,
                 clientDrift: mismatches

package/cli/run.js

@@ -2,6 +2,7 @@
 const { main, EXIT_CODES } = require('./index');
 const { writeStructured } = require('./lib/output');
 const { operationalErrorEnvelope } = require('./commands/axi');
+const { writeLastStdioError } = require('./lib/stdio-diagnostics');
 
 // Detect gateway-passthrough mode: no subcommand means we're forwarding stdio
 // as the MCP JSON-RPC channel. Writing a JSON envelope to stdout there would
@@ -13,7 +14,15 @@ const errorOut = isInteractiveCommand ? process.stdout : process.stderr;
 
 main(argv)
     .then((code) => process.exit(code))
-    .catch(() => {
+    .catch((err) => {
+        if (!isInteractiveCommand) {
+            writeLastStdioError({
+                gatewayExePath: process.env.GENEXUS_MCP_GATEWAY_EXE || process.argv[1],
+                exitCode: EXIT_CODES.ERROR,
+                error: err && err.message ? err.message : 'Unhandled CLI failure.',
+                stderrTail: err && err.stack ? err.stack : ''
+            });
+        }
         const envelope = operationalErrorEnvelope('Unhandled CLI failure.', EXIT_CODES.ERROR);
         envelope.meta = { ...(envelope.meta || {}), command: 'runtime' };
         writeStructured(errorOut, envelope, 'toon');

package/cli/run.test.js

@@ -6,7 +6,7 @@ const os = require('node:os');
 const fs = require('node:fs');
 const { renderOutput } = require('./lib/output');
 const { compareSemver, detectInstallMethod, upgradePlanFor } = require('./lib/update-check');
-const { detectClientInstalled, readJsonFileSafe } = require('./lib/config');
+const { detectClientInstalled, readJsonFileSafe, getLauncher } = require('./lib/config');
 
 const cliPath = path.join(__dirname, 'run.js');
 const testGxPath = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-gx-'));
@@ -639,15 +639,69 @@ test('toon output key ordering is stable', () => {
 });
 
 test('quiet flag suppresses launcher stderr noise', () => {
-    const result = runCli(['--quiet'], {
-        env: {
-            GX_CONFIG_PATH: '',
-            GENEXUS_MCP_GATEWAY_EXE: 'C:\\missing\\nope.exe'
-        }
-    });
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-quiet-'));
+    try {
+        const result = runCli(['--quiet'], {
+            env: {
+                GX_CONFIG_PATH: '',
+                GENEXUS_MCP_GATEWAY_EXE: 'C:\\missing\\nope.exe',
+                LOCALAPPDATA: tempRoot
+            }
+        });
 
-    assert.equal(result.status, 1);
-    assert.equal(result.stderr.trim(), '');
+        assert.equal(result.status, 1);
+        assert.equal(result.stderr.trim(), '');
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('stdio launcher writes a breadcrumb when the gateway is missing before spawn', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-stdio-missing-'));
+    try {
+        const configPath = path.join(tempRoot, 'config.json');
+        fs.writeFileSync(configPath, JSON.stringify({ Environment: { KBPath: tempRoot } }));
+        const missingGateway = path.join(tempRoot, 'missing', 'GxMcp.Gateway.exe');
+        const result = runCli([], {
+            env: {
+                GX_CONFIG_PATH: configPath,
+                GENEXUS_MCP_GATEWAY_EXE: missingGateway,
+                LOCALAPPDATA: tempRoot
+            }
+        });
+
+        assert.equal(result.status, 1);
+        const logPath = path.join(tempRoot, 'GenexusMCP', 'logs', 'last-stdio-error.txt');
+        assert.equal(fs.existsSync(logPath), true, 'pre-spawn failure should leave a diagnostic file');
+        const log = fs.readFileSync(logPath, 'utf8');
+        assert.match(log, /timestampUtc:/);
+        assert.match(log, /exitCode: 1/);
+        assert.match(log, /Gateway executable not found/);
+        assert.match(log, /missing[\\/]GxMcp\.Gateway\.exe/);
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('doctor surfaces the stdio error breadcrumb when one exists', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-doctor-stdio-'));
+    try {
+        const logPath = path.join(tempRoot, 'GenexusMCP', 'logs', 'last-stdio-error.txt');
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        fs.writeFileSync(logPath, 'timestampUtc: 2026-08-31T00:00:00.000Z\nexitCode: 1\n');
+
+        const result = runCli(['doctor', '--format', 'json'], {
+            env: { ...sandboxHomeEnv(tempRoot), LOCALAPPDATA: tempRoot }
+        });
+        assert.equal(result.status, 0);
+        const parsed = JSON.parse(result.stdout);
+        const check = parsed.ok.checks.find((row) => row.id === 'stdio_error_log');
+        assert.ok(check);
+        assert.equal(check.status, 'warn');
+        assert.ok(check.detail.includes(logPath));
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
 });
 
 test('update --help returns usage entry', () => {
@@ -737,6 +791,92 @@ test('clients list returns structured status with summary', () => {
     assert.equal(typeof row.registered, 'boolean');
 });
 
+test('getLauncher prefers the packaged gateway for Antigravity only', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-launcher-'));
+    const gatewayPath = path.join(tempRoot, 'publish', 'GxMcp.Gateway.exe');
+    const previous = process.env.GENEXUS_MCP_GATEWAY_EXE;
+    delete process.env.GENEXUS_MCP_GATEWAY_EXE;
+    try {
+        fs.mkdirSync(path.dirname(gatewayPath), { recursive: true });
+        fs.writeFileSync(gatewayPath, 'gateway');
+
+        assert.deepEqual(getLauncher({ preferDirectGateway: true }, gatewayPath), {
+            command: gatewayPath,
+            args: []
+        });
+        assert.deepEqual(getLauncher({ preferDirectGateway: false }, gatewayPath), {
+            command: process.platform === 'win32' ? 'npx.cmd' : 'npx',
+            args: ['-y', 'genexus-mcp@latest']
+        });
+    } finally {
+        if (previous === undefined) delete process.env.GENEXUS_MCP_GATEWAY_EXE;
+        else process.env.GENEXUS_MCP_GATEWAY_EXE = previous;
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('clients add selects a direct gateway for Antigravity and npx for other clients', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-client-launchers-'));
+    try {
+        const env = sandboxHomeEnv(tempRoot);
+        const cfgPath = path.join(tempRoot, 'config.json');
+        fs.writeFileSync(cfgPath, JSON.stringify({ Environment: { KBPath: tempRoot } }));
+        const result = runCli(['clients', 'add', '--clients', 'antigravity,cursor', '--format', 'json'], {
+            env: { ...env, GX_CONFIG_PATH: cfgPath, GENEXUS_MCP_GATEWAY_EXE: '' }
+        });
+        assert.equal(result.status, 0);
+
+        const antigravityPath = path.join(tempRoot, '.gemini', 'antigravity', 'mcp_config.json');
+        const cursorPath = path.join(tempRoot, '.cursor', 'mcp.json');
+        const antigravity = JSON.parse(fs.readFileSync(antigravityPath, 'utf8')).mcpServers.genexus18mcp;
+        const cursor = JSON.parse(fs.readFileSync(cursorPath, 'utf8')).mcpServers.genexus18mcp;
+        const packagedGateway = path.join(__dirname, '..', 'publish', 'GxMcp.Gateway.exe');
+
+        assert.equal(cursor.command, 'npx.cmd');
+        assert.deepEqual(cursor.args, ['-y', 'genexus-mcp@latest']);
+        if (fs.existsSync(packagedGateway)) {
+            assert.equal(antigravity.command, packagedGateway);
+            assert.deepEqual(antigravity.args, []);
+        } else {
+            assert.equal(antigravity.command, 'npx.cmd', 'source checkouts without publish artifacts retain the fallback');
+        }
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('clients add uses the unified Antigravity config when it already exists', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-antigravity-unified-'));
+    try {
+        const env = sandboxHomeEnv(tempRoot);
+        const configPath = path.join(tempRoot, 'config.json');
+        const unifiedPath = path.join(tempRoot, '.gemini', 'config', 'mcp_config.json');
+        fs.writeFileSync(configPath, JSON.stringify({ Environment: { KBPath: tempRoot } }));
+        fs.mkdirSync(path.dirname(unifiedPath), { recursive: true });
+        fs.writeFileSync(unifiedPath, JSON.stringify({ mcpServers: { unrelated: { command: 'keep-me' } } }));
+
+        const result = runCli(['clients', 'add', '--clients', 'antigravity', '--format', 'json'], {
+            env: { ...env, GX_CONFIG_PATH: configPath, GENEXUS_MCP_GATEWAY_EXE: '' }
+        });
+        assert.equal(result.status, 0);
+
+        const written = JSON.parse(fs.readFileSync(unifiedPath, 'utf8'));
+        const entry = written.mcpServers.genexus18mcp;
+        const packagedGateway = path.join(__dirname, '..', 'publish', 'GxMcp.Gateway.exe');
+        assert.ok(written.mcpServers.unrelated);
+        if (fs.existsSync(packagedGateway)) {
+            assert.equal(entry.command, packagedGateway);
+            assert.deepEqual(entry.args, []);
+        } else {
+            assert.equal(entry.command, 'npx.cmd');
+            assert.deepEqual(entry.args, ['-y', 'genexus-mcp@latest']);
+        }
+        assert.equal(fs.existsSync(path.join(tempRoot, '.gemini', 'antigravity', 'mcp_config.json')), false);
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
 test('clients add registers a client into a sandbox home with backup + atomic write', () => {
     const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-clients-'));
     const env = sandboxHomeEnv(tempRoot);
@@ -929,6 +1069,36 @@ test('clients list flags a registered command pointing at a missing launcher as
     fs.rmSync(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-'));
+    try {
+        const env = sandboxHomeEnv(tempRoot);
+        const currentGateway = path.join(tempRoot, 'current', 'GxMcp.Gateway.exe');
+        const oldGateway = path.join(tempRoot, 'old-cache', 'GxMcp.Gateway.exe');
+        fs.mkdirSync(path.dirname(currentGateway), { recursive: true });
+        fs.mkdirSync(path.dirname(oldGateway), { recursive: true });
+        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: [] } }
+        }, null, 2));
+
+        const result = runCli(['clients', '--format', 'json'], {
+            env: { ...env, GENEXUS_MCP_GATEWAY_EXE: currentGateway }
+        });
+        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/);
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
 test('readJsonFileSafe parses JSONC without corrupting string values containing commas', () => {
     const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-jsonc2-'));
     const f = path.join(tempRoot, 'mcp.json');
@@ -1047,6 +1217,11 @@ test('upgradePlanFor encodes the per-method upgrade strategy', () => {
     const fixed = upgradePlanFor('fixed-path', 'latest');
     assert.equal(fixed.auto, false);
     assert.equal(fixed.applyCommand, null, 'fixed-path has no npm apply; uses the installer');
+
+    const direct = upgradePlanFor('package-direct', 'latest');
+    assert.equal(direct.auto, false);
+    assert.equal(direct.applyCommand, null);
+    assert.ok(direct.steps.join(' ').includes('clients add --clients antigravity'));
 });
 
 test('gateway passthrough remains intact when no AXI subcommand is used', () => {
@@ -1070,6 +1245,36 @@ test('gateway passthrough remains intact when no AXI subcommand is used', () =>
     fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
+test('stdio launcher persists the last child stderr when the gateway exits non-zero', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-stdio-crash-'));
+    try {
+        const configPath = path.join(tempRoot, 'config.json');
+        const fakeGateway = path.join(tempRoot, 'fake-gateway.js');
+        fs.writeFileSync(configPath, JSON.stringify({ Environment: { KBPath: tempRoot } }));
+        fs.writeFileSync(fakeGateway, 'process.stderr.write("gateway bootstrap failed\\nsecond line\\n"); process.exit(7);');
+
+        const result = runCli([fakeGateway], {
+            env: {
+                GX_CONFIG_PATH: configPath,
+                GENEXUS_MCP_GATEWAY_EXE: process.execPath,
+                LOCALAPPDATA: tempRoot
+            }
+        });
+
+        assert.equal(result.status, 7);
+        assert.match(result.stderr, /gateway bootstrap failed/);
+        const logPath = path.join(tempRoot, 'GenexusMCP', 'logs', 'last-stdio-error.txt');
+        assert.equal(fs.existsSync(logPath), true, 'child crash should leave a diagnostic file');
+        const log = fs.readFileSync(logPath, 'utf8');
+        assert.match(log, /timestampUtc:/);
+        assert.match(log, /exitCode: 7/);
+        assert.match(log, /gateway bootstrap failed/);
+        assert.match(log, /second line/);
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
 test('npm package contains all bin, postinstall and required runtime files', () => {
     const pkgPath = path.join(__dirname, '..', 'package.json');
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
@@ -1099,6 +1304,17 @@ test('npm package contains all bin, postinstall and required runtime files', ()
             );
         }
     }
+
+    const requiredFiles = ['cli/lib/stdio-diagnostics.js', 'scripts/test-one.js'];
+    for (const relative of requiredFiles) {
+        assert.ok(fs.existsSync(path.join(__dirname, '..', relative)), `runtime file ${relative} must exist on disk`);
+        const normalized = relative.replace(/\\/g, '/');
+        const covered = (pkg.files || []).some((pattern) => {
+            const normalizedPattern = pattern.replace(/\\/g, '/');
+            return normalized === normalizedPattern || normalized.startsWith(normalizedPattern.endsWith('/') ? normalizedPattern : `${normalizedPattern}/`);
+        });
+        assert.ok(covered, `runtime file '${relative}' must be included by package.json files`);
+    }
 });
 
 test('isOurMcpEntry identifies third-party / HTTP servers vs our own entry', () => {

package/docs/llm_cli_mcp_playbook.md

@@ -44,6 +44,22 @@ Recommended flags:
 - `--full` only when needed.
 - `--quiet` in automation contexts.
 
+## Stdio startup failures
+
+If an MCP client reports only `exit status 1` or `0xffffffff`, inspect the wrapper's
+last-failure breadcrumb on Windows:
+
+```powershell
+Get-Content "$env:LOCALAPPDATA\GenexusMCP\logs\last-stdio-error.txt"
+```
+
+It contains the UTC timestamp, exit code, and a bounded stderr tail from the gateway
+bootstrap. For Antigravity, `init` and `clients add --clients antigravity` use the
+current package's gateway executable directly when available; if `genexus-mcp clients`
+marks that path stale, re-register it with `npx genexus-mcp@latest clients add --clients antigravity`.
+Do not infer an npx incompatibility or switch to a global npm install before reading
+this file.
+
 ## MCP Contract (LLM-facing)
 
 For `tools/call`, parse `result.content[0].text` as JSON.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genexus-mcp",
-  "version": "2.49.1",
+  "version": "2.49.2",
   "mcpName": "io.github.lennix1337/genexus",
   "description": "GeneXus 18 MCP server — read, edit, and analyze GeneXus knowledge base objects (transactions, web panels, procedures, SDTs) directly from Claude, Cursor, and other AI agents over the Model Context Protocol.",
   "keywords": [
@@ -31,7 +31,8 @@
   ],
   "scripts": {
     "test": "node --test cli/run.test.js",
-    "lint": "eslint cli scripts eslint.config.js",
+    "lint": "eslint cli scripts eslint.config.js --max-warnings=0",
+    "test:one": "node scripts/test-one.js",
     "prepack": "node scripts/clean-package.js",
     "postinstall": "node scripts/verify-install.js"
   },
@@ -42,7 +43,8 @@
     "cli",
     "publish",
     "docs/llm_cli_mcp_playbook.md",
-    "scripts/verify-install.js"
+    "scripts/verify-install.js",
+    "scripts/test-one.js"
   ],
   "os": [
     "win32"

package/publish/GxMcp.Gateway.deps.json

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

package/publish/config.json

@@ -3,13 +3,13 @@
     "InstallationPath": "C:\\\\Program Files (x86)\\\\GeneXus\\\\GeneXus18",
     "WorkerExecutable": "C:\\Projetos\\Genexus18MCP\\publish\\\\worker\\\\GxMcp.Worker.exe"
   },
+  "Logging": {
+    "Level": "Debug",
+    "Path": "logs"
+  },
   "Environment": {
     "KBPath": "C:\\\\KBs\\\\YourKB"
   },
-  "Logging": {
-    "Path": "logs",
-    "Level": "Debug"
-  },
   "Server": {
     "HttpPort": 5000,
     "McpStdio": true

package/scripts/test-one.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const pattern = process.argv.slice(2).join(' ').trim();
+if (!pattern) {
+    process.stderr.write('Usage: npm run test:one -- "test name pattern"\n');
+    process.exit(2);
+}
+
+const result = spawnSync(process.execPath, [
+    '--test',
+    '--test-name-pattern',
+    pattern,
+    path.join(__dirname, '..', 'cli', 'run.test.js')
+], { stdio: 'inherit' });
+
+process.exit(result.status === null ? 1 : result.status);