genexus-mcp 2.49.1 → 2.50.0

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.50.0",
   "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.50.0": {
         "dependencies": {
           "Newtonsoft.Json": "13.0.3",
           "System.Management": "10.0.5",
@@ -66,7 +66,7 @@
     }
   },
   "libraries": {
-    "GxMcp.Gateway/2.49.1": {
+    "GxMcp.Gateway/2.50.0": {
       "type": "project",
       "serviceable": false,
       "sha512": ""

package/publish/config.json

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

package/publish/tool_definitions.json

@@ -8,7 +8,7 @@
   {"name":"genexus_edit","description":"Edit object part. name or targets (exclusive). mode: full|patch|ops. dryRun first. async=true returns an operationId for lifecycle polling. Text payloads for Source/Rules/Events/Code must contain real line breaks; literal backslash sequences \\r\\n, \\n, or \\r are rejected before persistence with LiteralLineBreaksDetected. For WWP edit host's PatternInstance NOT the parent WebForm (gets overwritten on reapply). Uncertain about a property/method/event? → resources/read uri=genexus://kb/skills/navigation (or gam-integrated-security / sd-panel-mobile / webpanel-events) first.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"part":{"type":"string"},"parts":{"type":"array","description":"Multi-part edit on a single object. Each item: {part, content, mode?}. Saves the object once atomically. Text content must use real line breaks; literal backslash sequences \\r\\n, \\n, or \\r are rejected before persistence.","items":{"type":"object","properties":{"part":{"type":"string"},"content":{"type":"string"},"mode":{"type":"string"}},"required":["part","content"]}},"mode":{"type":"string","enum":["full","patch","ops"]},"content":{"type":"string"},"ops":{"type":"array","description":"GeneXus semantic ops (NOT RFC 6902 JSON-Patch). Each item: {op, args}. Supported ops: set_attribute, add_attribute, remove_attribute (Transaction); add_rule, remove_rule (Transaction/Procedure/WebPanel); set_property (any kind). Use mode=patch for textual find/replace.","items":{"type":"object","properties":{"op":{"type":"string","enum":["set_attribute","add_attribute","remove_attribute","add_rule","remove_rule","set_property"]},"args":{"type":"object","description":"Op-specific args. set_attribute: {name, type?, description?}. add_attribute: {name, type, ...}. add_rule: {rule}. set_property: {name, value}."}},"required":["op"]}},"patch":{"description":"Shorthand for {find,replace}. Equivalent to operation=Replace + context=find + content=replace."},"context":{"type":"string","description":"Exact existing text to find (Replace) or anchor after (Insert_After). Required for both. For text parts, send real line breaks; literal backslash sequences \\r\\n, \\n, or \\r are rejected before persistence."},"operation":{"type":"string","enum":["Replace","Insert_After","Append"]},"expectedCount":{"type":"integer"},"replaceAll":{"type":"boolean","description":"patch mode only. Apply to ALL occurrences instead of requiring expectedCount to match exactly."},"dryRun":{"type":"boolean"},"async":{"type":"boolean","description":"Run as a background job. Result returns operationId/job_id for genexus_lifecycle polling."},"estimated_seconds":{"type":"integer","description":"When async=true, expected runtime used for progress/job metadata (default 30)."},"verifyRollback":{"type":"boolean"},"targets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"content":{"type":"string"}},"required":["name","content"]}},"type":{"type":"string"},"return_post_state":{"type":"boolean","description":"Omit post_state.diff (default true)."},"verbose":{"type":"boolean","description":"Add ±15-line slices to post_state."},"validate":{"type":"string","enum":["strict","best-effort","only"],"description":"strict (default) aborts on first error and post-write-verifies visual/PatternInstance writes (re-reads + diffs the persisted XML). best-effort applies what compiles and SKIPS the post-write XML re-read/diff (faster on large WebForm/PatternInstance writes; build to confirm). only runs in-memory, no persist."},"validationMode":{"type":"string","enum":["specify"],"description":"Issue #60: run the inline Specify pass (Spec+Gen, no Compile) against the edited object right after the write, returning structured spc*/gen* diagnostics in the same call. Combines with rollbackOnFailure."},"rollbackOnFailure":{"type":"boolean","description":"Explicit rollback only: restore a valid pre-write snapshot when post-save verification or validationMode=specify fails. No rollback occurs when false or omitted."},"verifyMode":{"type":"string","enum":["semantic","normalized","exact"],"default":"normalized","description":"Post-save text comparison for patch mode. Source/Rules default to normalized (EOL, encoding marker, trailing whitespace and repeated blank lines); exact preserves logical text but treats CRLF/LF as the same SDK Source rendering; semantic also tolerates SDK casing/spacing format changes. Comment-only Replace writes require baseVersion and return CommentOnlyWriteNotPersisted on a divergent forced re-read. The part is always re-read after Save."},"visualVerify":{"type":"boolean","default":false,"description":"Post-edit headless screenshot + pixel-diff vs baseline. See tool-help."},"baseVersion":{"type":"string","description":"Optimistic concurrency: pass the versionToken from the genexus_read this edit is based on. If the object changed since (e.g. edited in the IDE), the write is refused with VersionConflict instead of overwriting the newer version. Omit to skip the check."},"expectedVersion":{"type":"string","description":"Alias of baseVersion. The write is refused when the current version no longer matches."},"autoDeclareVariables":{"type":"boolean","default":false,"description":"When true, scans updated source for newly referenced &Variable tokens and auto-declares them in VariablesPart."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"name":"Customer","mode":"patch","part":"Source","patch":{"find":"old","replace":"new"}},{"name":"Customer","mode":"patch","part":"Rules","patch":{"find":"error(","replace":"msg("},"dryRun":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_inspect","description":"Use this for a compact object snapshot: metadata, variables, structure, signature and navigation context. Don't use it when you need full Source or exact part bytes; use genexus_read for that. runtimeIds needs a prior build.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"include":{"type":"array","items":{"type":"string","enum":["metadata","variables","signature","structure","parts","controls","events_repertoire","callers","runtimeIds"]}},"projection":{"type":"string","enum":["minimal","standard","verbose"],"description":"Token budget. minimal=name/type/lastUpdate; standard=default (vars≤40 name+type, source heads 1200c); verbose=full vars + 8000c heads."},"type":{"type":"string"},"kb":{"type":"string","description":"KB alias."}},"required":["name"],"examples":[{"name":"Customer"},{"name":"Customer","include":["variables","signature"]}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_analyze","description":"Use this for cross-object semantic analysis. mode=context returns 360° task context in 1 call (object + called procedures' parm signatures + referenced tables' schemas/PKs + SDTs + callers). Other modes: impact, callers, hierarchy, navigation, linter, summary. Requires Ready index for impact/callers.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"mode":{"type":"string","enum":["context","linter","navigation","hierarchy","impact","cross_platform_impact","callers","event_flow","data_context","ui_context","pattern_metadata","summary","dependency_heatmap","code_metrics","kb_stats","table_relations"]},"format":{"type":"string","enum":["json","ascii"],"description":"mode=dependency_heatmap: ascii adds rendered bar chart."},"kb":{"type":"string","description":"KB alias."},"waitForIndex":{"type":"boolean","description":"mode=impact: block up to 30s for Ready index (default true).","default":true}},"required":["mode"],"examples":[{"name":"Customer","mode":"impact"},{"name":"Customer","mode":"summary"}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
-  {"name":"genexus_lifecycle","description":"Build, validate, index, or poll the KB. action=specify runs a spec-check (Spec+Gen only, no Compile/deploy) returning spc*/gen* diagnostics for the target fast (catch spec errors without a full build). action=build with mode=compile_check spec+gen+compiles the target(s) PLUS their transitive callers and skips the KB-wide DeveloperMenu regen (the dominant build-all cost) -- a fast 'did my edit break the build?' check that requires a target. Long ops are async with operationId. dryRun=true (build/rebuild/index) returns the build plan or index plan without executing. Build results carry generateEvidence + effective_status=SucceededWithGaps when a Succeeded build emitted no fresh .cs (don't trust Status=Succeeded alone); a 2nd concurrent build is refused (BuildAlreadyRunning). See genexus://kb/tool-help/genexus_lifecycle for the build-evidence checklist, actions, and target formats.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["build","cancel","specify","rebuild","reorg","reorg_preview","validate","validate-kb","sync","index","status","result","snapshots-list","snapshots-restore"]},"mode":{"type":"string","enum":["compile_check"],"description":"With action=build: compile_check spec+gen+compiles target(s) plus their transitive callers and SKIPS the KB-wide DeveloperMenu regen (the dominant build-all cost). Fast 'did my edit break the build?' check; requires target."},"target":{"type":"string","description":"Object name(s), taskId, job_id, or op:<id>. Build accepts CSV ('Foo,Bar')."},"code":{"type":"string"},"limit":{"type":"integer"},"snapshotPath":{"type":"string"},"estimated_seconds":{"type":"integer","description":"Build: <20 sync, >=20 async (default 60)."},"wait_seconds":{"type":"integer","description":"Status/build long-poll cap, 0-600s."},"wait_until_done":{"type":"boolean","description":"Build/rebuild: block in one turn until terminal (up to wait_seconds, default 600)."},"wait":{"type":"integer","description":"Status block, 0-600s. With a build taskId (or since): event-driven, returns on change. On index status with no since: blocks until index is Ready."},"since":{"type":"string","description":"Status: prior _meta.snapshot for chained waits."},"compact":{"type":"boolean","description":"Status: counts + top-10 errors (default true)."},"force":{"type":"boolean","description":"Index: full SDK rescan (clears snapshot)."},"dryRun":{"type":"boolean","default":false,"description":"build/rebuild/index: returns the plan (object list / index entries) without executing."},"includeCallees":{"type":"string","enum":["none","direct","transitive"],"description":"Build: expand call graph so callees compile first (default transitive)."},"callers":{"type":"boolean","description":"compile_check: expand transitive callers of the target (default true). Set false for a target-only check when the target is a base transaction/BC with a huge caller closure."},"callerCap":{"type":"integer","description":"compile_check: max callers to pull into the check (default 40). Closure beyond this is truncated and flagged."},"deploy":{"type":"boolean","description":"Build: force the full deploy (Theme/Image/Style/Module copy to web/bin + WebAppConfig) so the built object is runnable, not just compiled. Default false (fast compile-only path). Slower; use when you need to run/preview the object."},"buildPlanCap":{"type":"integer","description":"Build: max nodes before BuildPlanTooLarge (default 200)."},"kb":{"type":"string","description":"KB alias."}},"required":["action"],"examples":[{"action":"build"},{"action":"status","target":"op:abc123"},{"action":"build","mode":"compile_check","target":"MyObject"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
+  {"name":"genexus_lifecycle","description":"Build, validate, index, or poll the KB. action=specify runs a spec-check (Spec+Gen only, no Compile/deploy) returning spc*/gen* diagnostics for the target fast (catch spec errors without a full build). action=build with mode=compile_check spec+gen+compiles the target(s) PLUS their transitive callers and skips the KB-wide DeveloperMenu regen (the dominant build-all cost) -- a fast 'did my edit break the build?' check that requires a target. Long ops are async with operationId. dryRun=true (build/rebuild/index) returns the build plan or index plan without executing. Build results carry generateEvidence + effective_status=SucceededWithGaps when a Succeeded build emitted no fresh .cs (don't trust Status=Succeeded alone); a 2nd concurrent build is refused (BuildAlreadyRunning). See genexus://kb/tool-help/genexus_lifecycle for the build-evidence checklist, actions, and target formats.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["build","cancel","specify","rebuild","reorg","reorg_preview","validate","validate-kb","sync","index","status","result","snapshots-list","snapshots-restore"]},"mode":{"type":"string","enum":["compile_check"],"description":"With action=build: compile_check spec+gen+compiles target(s) plus their transitive callers and SKIPS the KB-wide DeveloperMenu regen (the dominant build-all cost). Fast 'did my edit break the build?' check; requires target."},"target":{"type":"string","description":"Object name(s), taskId, job_id, or op:<id>. Build accepts CSV ('Foo,Bar')."},"code":{"type":"string"},"limit":{"type":"integer"},"snapshotPath":{"type":"string"},"estimated_seconds":{"type":"integer","description":"Build: <20 sync, >=20 async (default 60)."},"wait_seconds":{"type":"integer","description":"Status/build long-poll cap, 0-600s."},"wait_until_done":{"type":"boolean","description":"Build/rebuild: block in one turn until terminal (up to wait_seconds, default 600)."},"wait":{"type":"integer","description":"Status block, 0-600s. With a build taskId (or since): event-driven, returns on change. On index status with no since: blocks until index is Ready."},"since":{"type":"string","description":"Status: prior _meta.snapshot for chained waits."},"compact":{"type":"boolean","description":"Status: counts + top-10 errors (default true)."},"force":{"type":"boolean","description":"Index: full SDK rescan (clears snapshot)."},"dryRun":{"type":"boolean","default":false,"description":"build/rebuild/index: returns the plan (object list / index entries) without executing."},"environment":{"type":"string","description":"Build: target environment name/folder. Switches active environment before building."},"includeCallees":{"type":"string","enum":["none","direct","transitive"],"description":"Build: expand call graph so callees compile first (default transitive)."},"callers":{"type":"boolean","description":"compile_check: expand transitive callers of the target (default true). Set false for a target-only check when the target is a base transaction/BC with a huge caller closure."},"callerCap":{"type":"integer","description":"compile_check: max callers to pull into the check (default 40). Closure beyond this is truncated and flagged."},"deploy":{"type":"boolean","description":"Build: force the full deploy (Theme/Image/Style/Module copy to web/bin + WebAppConfig) so the built object is runnable, not just compiled. Default false (fast compile-only path). Slower; use when you need to run/preview the object."},"buildPlanCap":{"type":"integer","description":"Build: max nodes before BuildPlanTooLarge (default 200)."},"kb":{"type":"string","description":"KB alias."}},"required":["action"],"examples":[{"action":"build"},{"action":"status","target":"op:abc123"},{"action":"build","mode":"compile_check","target":"MyObject"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_test","description":"Execute native GeneXus tests (GXtest).","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"kb":{"type":"string","description":"KB alias."}},"required":["name"],"examples":[{"name":"MyTestProc"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},
   {"name":"genexus_sdk_probe","description":"Dump SDK surface (types/methods/props) to docs/sdk-probe/. Use when hunting for entry points.","inputSchema":{"type":"object","properties":{"outputDir":{"type":"string","description":"Absolute path. Default <repo>/docs/sdk-probe/."}},"examples":[{}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_worker_reload","description":"Reload worker. modes: soft (drain+respawn), hard (copy sourceDir+respawn). force=true: gateway kills directly. See tool-help.","inputSchema":{"type":"object","properties":{"mode":{"type":"string","enum":["soft","hard"]},"force":{"type":"boolean","description":"Bypass drain; gateway kills + respawns. Use when worker is wedged."},"sourceDir":{"type":"string","description":"Required for mode=hard."},"drainTimeoutMs":{"type":"integer","description":"Soft only; default 30000."}},"examples":[{"mode":"soft"},{"mode":"hard","sourceDir":"C:\\Projetos\\Genexus18MCP\\src\\GxMcp.Worker\\bin\\Debug"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},
@@ -24,7 +24,7 @@
   {"name":"genexus_layout","description":"Layout/WebForm: get_tree, set_property, find_controls, inspect_surface, scan_mutators. Properties: genexus_properties; structure: genexus_structure get_visual.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get_tree","set_property","find_controls","set_properties","inspect_surface","get_preview","scan_mutators","rename_printblock","add_printblock","delete_printblock","list_controls","design_system"]},"name":{"type":"string"},"control":{"type":"string"},"propertyName":{"type":"string"},"value":{"type":"string"},"query":{"type":"string"},"changes":{"type":"array","items":{"type":"object","properties":{"control":{"type":"string"},"propertyName":{"type":"string"},"value":{"type":"string"}},"required":["control","propertyName","value"]}},"limit":{"type":"integer"},"currentName":{"type":"string"},"newName":{"type":"string"},"printBlockName":{"type":"string"},"height":{"type":"integer"},"kb":{"type":"string","description":"KB alias."}},"required":["action"],"examples":[{"action":"get_tree","name":"WPMain"},{"action":"find_controls","name":"WPMain","query":"Button"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_doc","description":"Use to generate structured docs (wiki, sequence diagrams, health reports). Don't use for programmatic analysis (see genexus_analyze) or source (see genexus_read).","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["wiki","visualize","health"]},"target":{"type":"string","description":"Object or domain name."}},"required":["action"],"examples":[{"action":"wiki","target":"Customer"},{"action":"health"}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_search_source","description":"Regex/semantic search across Procedure/DataProvider/WebPanel/Transaction source. Requires the KB index to be Ready — check genexus_lifecycle action=status if results look empty.","inputSchema":{"type":"object","properties":{"callee":{"type":"string","description":"Method/function name (qualified or unqualified)."},"argMatches":{"type":"object","description":"Positional arg index to expected literal text."},"pattern":{"type":"string"},"typeFilter":{"type":"string"},"objectName":{"type":"string","description":"Restrict the scan to these exact object name(s), comma-separated. Makes a search inside one known object O(object) not O(KB), and bypasses the type whitelist."},"startIndex":{"type":"integer","description":"Legacy object-boundary resume. For a page that ended inside an object, prefer the opaque cursor returned in nextCursor."},"cursor":{"type":"string","description":"Opaque continuation token from nextCursor; preferred when a result page ended inside an object. Do not edit."},"timeoutMs":{"type":"integer","description":"Wall-clock budget (default 30000). Raise it to scan more objects per call."},"scope":{"type":"array","items":{"type":"string","enum":["source","rules","conditions","events","webForm","layout"]},"description":"Parts to scan with line-numbered context. Default [source]. webForm/layout scans the WebPanel/Transaction visual XML (control names, captions, classes, bindings)."},"fields":{"type":"array","items":{"type":"string","enum":["source","caption","description","parmNames","webForm"]},"description":"Whole-field metadata match (returns matchedValue, no line context). Default [source]. Prefer scope=[webForm] for line-context WebForm hits; use fields=[webForm] only for a coarse contains-match."},"maxResults":{"type":"integer"},"caseSensitive":{"type":"boolean"},"includeComments":{"type":"boolean"},"inline_read_top":{"type":"integer","description":"0-3. Inline reads of top N distinct objects in response."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"pattern":"ControlType=\"Radio\""},{"pattern":"for each","typeFilter":"Procedure","maxResults":20}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
-  {"name":"genexus_kb","description":"Manage open KBs, startup config, and the active GeneXus environment. list/open/close/set_default operate on WorkerPool; set_default selects the implicit target for calls that omit kb (an explicit kb always wins for parallel or cross-KB work); set_startup/get_startup mirror IDE 'Set As Startup Object'; get_environment reads the SDK selection; set_environment selects an environment through the SDK task used by the IDE.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","open","close","set_default","set_startup","get_startup","get_environment","set_environment"]},"alias":{"type":"string","description":"KB alias. open: auto from path basename if omitted."},"path":{"type":"string","description":"Absolute KB path (required for open if alias not in config)."},"name":{"type":"string","description":"Object name (required for set_startup)."},"environment":{"type":"string","description":"Environment name/folder (required for set_environment), e.g. development."}},"required":["action"],"examples":[{"action":"open","path":"C:\\KBs\\MyKb"},{"action":"list"},{"action":"get_environment"},{"action":"set_environment","environment":"development"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
+  {"name":"genexus_kb","description":"Manage open KBs, startup config, and GeneXus environments. list/open/close/set_default operate on WorkerPool; set_default selects the implicit target for calls that omit kb (an explicit kb always wins for parallel or cross-KB work); set_startup/get_startup mirror IDE 'Set As Startup Object'; list_environments lists all configured environments; get_environment reads the active environment; set_environment selects an environment.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","open","close","set_default","set_startup","get_startup","list_environments","get_environment","set_environment"]},"alias":{"type":"string","description":"KB alias. open: auto from path basename if omitted."},"path":{"type":"string","description":"Absolute KB path (required for open if alias not in config)."},"name":{"type":"string","description":"Object name (required for set_startup)."},"environment":{"type":"string","description":"Environment name/folder (required for set_environment), e.g. development."}},"required":["action"],"examples":[{"action":"open","path":"C:\\KBs\\MyKb"},{"action":"list"},{"action":"list_environments"},{"action":"get_environment"},{"action":"set_environment","environment":"development"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_navigation","description":"View navigation report (IDE Right-click → View Navigation). latest=true returns cached report from .gx/navigation-cache; else runs fresh.","inputSchema":{"type":"object","required":["action","name"],"properties":{"action":{"type":"string","enum":["view"]},"name":{"type":"string"},"latest":{"type":"boolean","default":false,"description":"Return the most recent cached navigation if any; otherwise run fresh."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"view","name":"Customer"},{"action":"view","name":"Customer","latest":true}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_api","description":"Introspect REST endpoints exposed by HTTP procedures. action=list|describe|snapshot|diff_baseline. Returns endpoints + detects breaking changes vs a saved baseline.","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["list","describe","snapshot","diff_baseline"]},"target":{"type":"string","description":"Procedure name (action=describe)."},"name":{"type":"string","description":"Baseline name (action=snapshot)."},"baseline":{"type":"string","description":"Baseline name under .gx/api-baselines/ or absolute path (action=diff_baseline)."},"pathPrefix":{"type":"string","description":"Folder prefix filter (action=list), e.g. 'Root Module/API/'."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"list"},{"action":"describe","target":"ApiCustomerGet"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_apply_pattern","description":"Apply a pattern (e.g. WorkWithPlus) to a parent (IDE Right-click → Apply Pattern). Transaction=family-gen; WebPanel/WebComponent/SDPanel=direct-attach (pass settings.template). mode=diagnose (or dryRun=true) returns findings without mutating. Working on Smart Devices? → resources/read uri=genexus://kb/skills/sd-panel-mobile for Main object semantics. mode=actions manages typed grid actions and Action Groups, persists and re-reads PatternInstance, supports dryRun diff, and never adds security permissions automatically.","inputSchema":{"type":"object","required":["name","pattern"],"properties":{"name":{"type":"string","description":"Target KBObject name."},"pattern":{"type":"string","description":"Pattern key ('WorkWithPlus') or GUID."},"mode":{"type":"string","enum":["apply","diagnose","actions"],"description":"apply (default) mutates; diagnose returns reasons without applying. actions exposes typed WWP action-group editing."},"action":{"type":"string","enum":["list_actions","add_grid_action","update_action","move_action","remove_action"],"description":"mode=actions operation."},"group":{"type":"string"},"actionName":{"type":"string"},"newGroup":{"type":"string"},"position":{"type":"integer","minimum":0},"procedure":{"type":"string"},"selection":{"type":"string","enum":["current","multiple"]},"enabledWhen":{"type":"string"},"visibleWhen":{"type":"string"},"icon":{"type":"string"},"description":{"type":"string"},"confirmation":{"type":"string"},"confirmTitle":{"type":"string"},"settings":{"type":"object","description":"Pattern-instance settings tree."},"reapply":{"type":"boolean","default":false,"description":"Re-run on existing instance."},"validate":{"type":"boolean","default":false,"description":"After apply, build the generated host. Adds validation block (60-180s). Catches binding errors."},"dryRun":{"type":"boolean","default":false,"description":"Alias for mode=diagnose. When true, returns pattern findings without mutating. With mode=actions it previews the typed action diff."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"name":"Customer","pattern":"WorkWithPlus"},{"name":"Customer","pattern":"WorkWithPlus","mode":"diagnose"},{"name":"Customer","pattern":"WorkWithPlus","mode":"actions","action":"add_grid_action","group":"Actions","actionName":"Approve","procedure":"ApproveCustomer","dryRun":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},

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);