genexus-mcp 2.6.3 → 2.6.5

package/cli/commands/axi.js

@@ -21,7 +21,10 @@ const {
     readKbCatalog,
     addKbToConfig,
     removeKbFromConfig,
-    switchActiveKb
+    switchActiveKb,
+    isPathLikelyAppLockerBlocked,
+    normalizeExePath,
+    readClientCommandEntry
 } = require('../lib/config');
 
 function resolveClientIds(options) {
@@ -176,7 +179,17 @@ async function spawnGatewayProbe({ env = process.env, spawnHoldMs, timeoutMs, la
             });
 
             child.once('error', (err) => {
-                finish({ status: 'fail', detail: `${label} failed: ${err.message}` });
+                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) {
+                    const zone = isPathLikelyAppLockerBlocked(gatewayExePath);
+                    const hint = zone
+                        ? ` Gateway exe is under %${zone}% — likely blocked by AppLocker/SRP. Reinstall via scripts/install.ps1 to a whitelisted path.`
+                        : ' Access denied. AppLocker/SRP or AV may be blocking execution. Move the exe to a whitelisted path (see scripts/install.ps1).';
+                    finish({ status: 'fail', detail: `${label} failed: ${err.message}.${hint}` });
+                } else {
+                    finish({ status: 'fail', detail: `${label} failed: ${err.message}` });
+                }
             });
 
             child.once('spawn', () => {
@@ -304,6 +317,7 @@ async function runMcpSmokeProbe(cwd) {
 
 async function handleStatus(options, ctx) {
     const data = buildStatusData(ctx.cwd);
+    const riskyZone = isPathLikelyAppLockerBlocked(data.gatewayExePath);
 
     const ok = options.full
         ? {
@@ -311,6 +325,7 @@ async function handleStatus(options, ctx) {
             configFound: data.configFound,
             gatewayExeFound: data.gatewayExeFound,
             kbLooksValid: data.kbLooksValid,
+            pathSafetyWarn: !!riskyZone,
             configSource: data.configSource,
             configPath: data.configPath,
             gatewayExePath: data.gatewayExePath,
@@ -321,20 +336,86 @@ async function handleStatus(options, ctx) {
             ready: data.ready,
             configFound: data.configFound,
             gatewayExeFound: data.gatewayExeFound,
-            kbLooksValid: data.kbLooksValid
+            kbLooksValid: data.kbLooksValid,
+            pathSafetyWarn: !!riskyZone
         };
 
+    const help = data.ready
+        ? ['Run `genexus-mcp tools list --limit 10` to inspect available MCP tools.']
+        : [
+            'Run `genexus-mcp doctor` for expanded checks.',
+            'Run `genexus-mcp init --kb "<kbPath>" --gx "<geneXusPath>"` to create config.'
+        ];
+    if (riskyZone) {
+        help.unshift(`Gateway exe is under %${riskyZone}% — likely AppLocker-blocked on corporate Windows. Reinstall to a whitelisted path via scripts/install.ps1.`);
+    }
+
     return {
         exitCode: ctx.EXIT_CODES.OK,
-        envelope: {
-            ok,
-            help: data.ready
-                ? ['Run `genexus-mcp tools list --limit 10` to inspect available MCP tools.']
-                : [
-                    'Run `genexus-mcp doctor --full` for expanded checks.',
-                    'Run `genexus-mcp init --kb "<kbPath>" --gx "<geneXusPath>"` to create config.'
-                ]
+        envelope: { ok, help }
+    };
+}
+
+function buildClientExeCrossCheck(packageExePath) {
+    const packageNorm = normalizeExePath(packageExePath);
+    const targets = filterClientTargets(getClientConfigTargets(), { platform: process.platform });
+
+    const mismatches = [];
+    const matches = [];
+    const errors = [];
+    let inspected = 0;
+
+    for (const client of targets) {
+        if (!fs.existsSync(client.path)) continue;
+        let entry;
+        try {
+            entry = readClientCommandEntry(client);
+        } catch (err) {
+            errors.push(`${client.name}: ${err.message || 'read failed'}`);
+            continue;
         }
+        if (!entry || !entry.command) continue;
+        inspected += 1;
+
+        const cmd = entry.command;
+        const lowerCmd = cmd.toLowerCase();
+
+        // Skip launchers that always resolve via npm at runtime (npx, node CLI shim).
+        if (/(^|[\\/])(npx|npx\.cmd|node|node\.exe)$/i.test(lowerCmd) || /[\\/]genexus-mcp(\.cmd)?$/i.test(lowerCmd)) {
+            continue;
+        }
+
+        // Only compare when the configured command points to an .exe.
+        if (!/\.exe$/i.test(lowerCmd)) continue;
+
+        const configuredNorm = normalizeExePath(cmd);
+        if (configuredNorm === packageNorm) {
+            matches.push(client.name);
+        } else {
+            const configuredExists = fs.existsSync(cmd);
+            mismatches.push({
+                client: client.name,
+                configured: cmd,
+                exists: configuredExists
+            });
+        }
+    }
+
+    if (inspected === 0) {
+        return { status: 'warn', detail: 'No AI client config with a direct gateway exe found (or all clients use npx). Run `genexus-mcp init --write-clients` if you want to register one.' };
+    }
+
+    if (mismatches.length === 0) {
+        return {
+            status: 'pass',
+            detail: `All inspected client configs (${matches.join(', ')}) point at the npm-package gateway exe.`
+        };
+    }
+
+    const detailParts = mismatches.map((m) => `${m.client} -> ${m.configured}${m.exists ? '' : ' (missing)'}`);
+    return {
+        status: 'warn',
+        detail: `Client(s) reference a gateway exe that is NOT this npm package's bundled exe. \`npm install -g genexus-mcp@latest\` will NOT update those instances. Bundled: ${packageExePath}. Mismatches: ${detailParts.join('; ')}. Re-run scripts/install.ps1 (or genexus-mcp init --write-clients) to resync.`
     };
 }
 
@@ -359,21 +440,32 @@ async function handleDoctor(options, ctx) {
     const kbExists = !!(kbPath && fs.existsSync(kbPath));
     const gxExeExists = !!(gxPath && fs.existsSync(path.join(gxPath, 'genexus.exe')));
 
+    const riskyZone = isPathLikelyAppLockerBlocked(gatewayExePath);
+    const clientCrossCheck = buildClientExeCrossCheck(gatewayExePath);
+
     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: 'gateway_exe_path_safety',
+            status: riskyZone ? 'warn' : 'pass',
+            detail: riskyZone
+                ? `Gateway exe is under %${riskyZone}%, which is commonly blocked by AppLocker/SRP in Windows domains. If clients show "Failed to connect" / "Access denied", reinstall to a whitelisted path via scripts/install.ps1 (defaults to C:\\Tools\\GenexusMCP or %LOCALAPPDATA%\\Programs\\GenexusMCP).`
+                : 'Gateway exe is in a path unlikely to be blocked by AppLocker/SRP.'
+        },
         { id: 'kb_path_exists', status: kbExists ? 'pass' : 'warn', detail: kbExists ? 'Configured KB path exists.' : 'Configured KB path does not exist.' },
         { id: 'kb_shape', status: data.kbLooksValid ? 'pass' : 'warn', detail: data.kbLooksValid ? 'KB folder shape looks valid.' : 'KB markers were not found in configured KB path.' },
         { id: 'gx_installation', status: gxExeExists ? 'pass' : 'warn', detail: gxExeExists ? 'GeneXus installation has genexus.exe.' : 'Configured GeneXus installation is missing genexus.exe.' },
         { id: 'tool_definitions', status: toolDefsExists ? 'pass' : 'warn', detail: toolDefsExists ? `Tool definition file found (${toolCount} tools).` : 'tool_definitions.json is missing.' },
-        { id: 'gx_env', status: process.env.GX_CONFIG_PATH ? 'pass' : 'warn', detail: process.env.GX_CONFIG_PATH ? 'GX_CONFIG_PATH env var is set.' : 'GX_CONFIG_PATH env var is not set for this process.' }
+        { id: 'gx_env', status: process.env.GX_CONFIG_PATH ? 'pass' : 'warn', detail: process.env.GX_CONFIG_PATH ? 'GX_CONFIG_PATH env var is set.' : 'GX_CONFIG_PATH env var is not set for this process.' },
+        { id: 'client_config_sync', status: clientCrossCheck.status, detail: clientCrossCheck.detail }
     ];
 
-    if (options.full) {
+    if (data.gatewayExeFound) {
         const probe = await probeGatewaySpawn();
         checks.push({ id: 'gateway_spawn_probe', status: probe.status, detail: probe.detail });
     } else {
-        checks.push({ id: 'gateway_spawn_probe', status: 'warn', detail: 'Spawn probe skipped by default. Run doctor with --full.' });
+        checks.push({ id: 'gateway_spawn_probe', status: 'warn', detail: 'Spawn probe skipped: gateway exe not found.' });
     }
 
     if (options.mcpSmoke) {
@@ -399,9 +491,6 @@ async function handleDoctor(options, ctx) {
     if (checks.length > options.limit) {
         help.push(`Run 'genexus-mcp doctor --limit ${checks.length}' for all checks.`);
     }
-    if (!options.full) {
-        help.push('Run `genexus-mcp doctor --full` to include runtime spawn probe.');
-    }
     if (!options.mcpSmoke) {
         help.push('Run `genexus-mcp doctor --mcp-smoke` to execute MCP protocol smoke checks.');
     }
@@ -774,6 +863,16 @@ async function handleLayout(subcommand, options, ctx) {
     };
 }
 
+function buildInteractiveInitHelp(patchResult) {
+    const help = [];
+    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.');
+    }
+    return help;
+}
+
 async function runInteractiveInit(ctx) {
     const defaultGx = discoverGeneXusInstallation() || 'C:\\Program Files (x86)\\GeneXus\\GeneXus18';
 
@@ -820,7 +919,7 @@ async function runInteractiveInit(ctx) {
                     noOp: !created.changed,
                     clientsPatchedCount: patchResult.patched.length
                 },
-                help: patchResult.patched.length === 0 ? ['Set `GX_CONFIG_PATH` in your MCP client env to the generated config path.'] : [],
+                help: buildInteractiveInitHelp(patchResult),
                 meta: {
                     patchedClients: patchResult.patched,
                     failedClients: patchResult.failed,
@@ -828,10 +927,26 @@ async function runInteractiveInit(ctx) {
                 }
             }
         };
-    } catch {
+    } catch (err) {
+        if (err && err.code === 'GATEWAY_EXE_MISSING') {
+            return {
+                exitCode: ctx.EXIT_CODES.ERROR,
+                envelope: operationalErrorEnvelope(
+                    'GENEXUS_MCP_GATEWAY_EXE points to a path that does not exist. Client configs were NOT modified.',
+                    ctx.EXIT_CODES.ERROR,
+                    [
+                        `Path checked: ${process.env.GENEXUS_MCP_GATEWAY_EXE}`,
+                        'Either unset GENEXUS_MCP_GATEWAY_EXE (then init writes the npx-based launcher) or re-run scripts/install.ps1 to materialize the exe at that path.'
+                    ]
+                )
+            };
+        }
         return {
             exitCode: ctx.EXIT_CODES.ERROR,
-            envelope: operationalErrorEnvelope('Interactive init failed.', ctx.EXIT_CODES.ERROR)
+            envelope: operationalErrorEnvelope(
+                sanitizeOperationalMessage(`Interactive init failed: ${err && err.message ? err.message : 'unknown error'}`),
+                ctx.EXIT_CODES.ERROR
+            )
         };
     } finally {
         rl.close();
@@ -913,8 +1028,11 @@ async function handleInit(options, ctx) {
         if (patchResult.patched.length === 0 && !options.writeClients) {
             help.push('Run `genexus-mcp init --kb "<kbPath>" --gx "<geneXusPath>" --write-clients` to patch supported clients.');
         }
+        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.');
+        }
         if (verification.summary.fail > 0 || verification.summary.warn > 0) {
-            help.push('Some verification checks did not pass. Run `genexus-mcp doctor --full --mcp-smoke` for details.');
+            help.push('Some verification checks did not pass. Run `genexus-mcp doctor --mcp-smoke` for details.');
         }
         if (options.noSmoke) {
             help.push('MCP protocol smoke was skipped (--no-smoke). Re-run `genexus-mcp doctor --mcp-smoke` to validate end-to-end.');
@@ -950,10 +1068,27 @@ async function handleInit(options, ctx) {
                 }
             }
         };
-    } catch {
+    } catch (err) {
+        if (err && err.code === 'GATEWAY_EXE_MISSING') {
+            return {
+                exitCode: ctx.EXIT_CODES.ERROR,
+                envelope: operationalErrorEnvelope(
+                    'GENEXUS_MCP_GATEWAY_EXE points to a path that does not exist. Client configs were NOT modified.',
+                    ctx.EXIT_CODES.ERROR,
+                    [
+                        `Path checked: ${process.env.GENEXUS_MCP_GATEWAY_EXE}`,
+                        'Either unset GENEXUS_MCP_GATEWAY_EXE (then init writes the npx-based launcher) or re-run scripts/install.ps1 to materialize the exe at that path.'
+                    ]
+                )
+            };
+        }
         return {
             exitCode: ctx.EXIT_CODES.ERROR,
-            envelope: operationalErrorEnvelope('Failed to write configuration.', ctx.EXIT_CODES.ERROR)
+            envelope: operationalErrorEnvelope(
+                sanitizeOperationalMessage(`Failed to write configuration: ${err && err.message ? err.message : 'unknown error'}`),
+                ctx.EXIT_CODES.ERROR,
+                ['Check write permissions on the target directory; on Windows, run from a path outside protected areas.']
+            )
         };
     }
 }

package/cli/index.js

@@ -1,7 +1,8 @@
 const { spawn } = require('child_process');
 const {
     getGatewayExePath,
-    applyLauncherConfigOrExit
+    applyLauncherConfigOrExit,
+    isPathLikelyAppLockerBlocked
 } = require('./lib/config');
 const {
     SUPPORTED_FORMATS,
@@ -294,6 +295,17 @@ function parseArgs(argv) {
     return result;
 }
 
+function writeAppLockerHint(stderr, gatewayExePath) {
+    const riskyZone = isPathLikelyAppLockerBlocked(gatewayExePath);
+    stderr.write('[genexus-mcp] Likely cause: Windows AppLocker / SRP is blocking execution from this path.\n');
+    if (riskyZone) {
+        stderr.write(`[genexus-mcp] The gateway exe lives under %${riskyZone}% (typically restricted by corporate policy):\n[genexus-mcp]   ${gatewayExePath}\n`);
+    }
+    stderr.write('[genexus-mcp] Remediation: install to a whitelisted path with:\n');
+    stderr.write('[genexus-mcp]   iex (irm https://raw.githubusercontent.com/lennix1337/Genexus18MCP/main/scripts/install.ps1)\n');
+    stderr.write('[genexus-mcp] Or copy the package `publish/` folder to a path outside %APPDATA%/%LOCALAPPDATA% and point the MCP client at that exe.\n');
+}
+
 async function launchGateway(passthroughArgs, options) {
     const setup = applyLauncherConfigOrExit({
         cwd: process.cwd(),
@@ -323,6 +335,11 @@ async function launchGateway(passthroughArgs, options) {
         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);
         });

package/cli/lib/config.js

@@ -278,6 +278,18 @@ function filterClientTargets(targets, opts = {}) {
 }
 
 function patchClientConfig(targetConfigPath, opts = {}) {
+    // Validate corporate-install env var before we write it into N client configs.
+    // Otherwise we silently propagate a broken path to every AI client and the
+    // user only finds out when each one fails with "Failed to connect".
+    if (process.env.GENEXUS_MCP_GATEWAY_EXE && !fs.existsSync(process.env.GENEXUS_MCP_GATEWAY_EXE)) {
+        const err = new Error(
+            `GENEXUS_MCP_GATEWAY_EXE points to a path that does not exist: ${process.env.GENEXUS_MCP_GATEWAY_EXE}. ` +
+            `Refusing to write this into client configs. Unset the env var (to use the npx launcher) or re-run scripts/install.ps1 to materialize the exe.`
+        );
+        err.code = 'GATEWAY_EXE_MISSING';
+        throw err;
+    }
+
     const launcher = getLauncher();
     const onlyExisting = opts.onlyExisting !== false;
     const candidates = filterClientTargets(getClientConfigTargets(), {
@@ -456,6 +468,65 @@ function tomlString(value) {
     return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
 
+function isPathLikelyAppLockerBlocked(exePath) {
+    if (process.platform !== 'win32' || !exePath) return null;
+    const norm = String(exePath).toLowerCase().replace(/\\/g, '/');
+    const candidates = [
+        { name: 'APPDATA', base: process.env.APPDATA },
+        { name: 'LOCALAPPDATA', base: process.env.LOCALAPPDATA },
+        { name: 'TEMP', base: process.env.TEMP },
+        { name: 'TMP', base: process.env.TMP }
+    ];
+    for (const { name, base } of candidates) {
+        if (!base) continue;
+        const baseNorm = base.toLowerCase().replace(/\\/g, '/').replace(/\/$/, '');
+        if (norm.startsWith(baseNorm + '/')) return name;
+    }
+    return null;
+}
+
+function normalizeExePath(p) {
+    if (!p) return '';
+    let s = String(p).trim().replace(/^"|"$/g, '');
+    s = s.replace(/\\/g, '/').replace(/\/+$/, '');
+    if (process.platform === 'win32') s = s.toLowerCase();
+    return s;
+}
+
+function readClientCommandEntry(client) {
+    if (!fs.existsSync(client.path)) return null;
+    try {
+        if (client.format === 'mcpServers') {
+            const parsed = readJsonFileSafe(client.path);
+            if (!parsed || typeof parsed !== 'object') return null;
+            const entry = parsed.mcpServers && parsed.mcpServers.genexus;
+            if (!entry) return null;
+            return { command: entry.command || null, args: Array.isArray(entry.args) ? entry.args : [] };
+        }
+        if (client.format === 'opencode') {
+            const parsed = readJsonFileSafe(client.path);
+            if (!parsed || typeof parsed !== 'object') return null;
+            const entry = parsed.mcp && parsed.mcp.genexus;
+            if (!entry || !Array.isArray(entry.command) || entry.command.length === 0) return null;
+            return { command: entry.command[0], args: entry.command.slice(1) };
+        }
+        if (client.format === 'codex-toml') {
+            const raw = fs.readFileSync(client.path, 'utf8');
+            // Minimal extraction: find [mcp_servers.genexus] block and pull command = "..."
+            const blockRe = /\[mcp_servers\.genexus\]([\s\S]*?)(?=\n\[|$)/;
+            const m = raw.match(blockRe);
+            if (!m) return null;
+            const cmdMatch = m[1].match(/^\s*command\s*=\s*"((?:[^"\\]|\\.)*)"/m);
+            if (!cmdMatch) return null;
+            const command = cmdMatch[1].replace(/\\\\/g, '\\').replace(/\\"/g, '"');
+            return { command, args: [] };
+        }
+    } catch {
+        return null;
+    }
+    return null;
+}
+
 function getLocalAppDataCacheDir() {
     if (process.platform !== 'win32') return null;
     const base = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
@@ -628,5 +699,8 @@ module.exports = {
     addKbToConfig,
     removeKbFromConfig,
     switchActiveKb,
-    applyLauncherConfigOrExit
+    applyLauncherConfigOrExit,
+    isPathLikelyAppLockerBlocked,
+    normalizeExePath,
+    readClientCommandEntry
 };

package/cli/lib/update-check.js

@@ -2,6 +2,13 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const https = require('https');
+const {
+    getGatewayExePath,
+    getClientConfigTargets,
+    filterClientTargets,
+    readClientCommandEntry,
+    normalizeExePath
+} = require('./config');
 
 const REPO = 'lennix1337/Genexus18MCP';
 const NPM_PACKAGE = 'genexus-mcp';
@@ -159,9 +166,37 @@ function startBackgroundUpdateCheck(opts) {
     scheduleBackgroundFetch();
 }
 
+function detectClientExeDrift() {
+    try {
+        const packageNorm = normalizeExePath(getGatewayExePath());
+        const targets = filterClientTargets(getClientConfigTargets(), { platform: process.platform });
+        const mismatches = [];
+        for (const client of targets) {
+            if (!fs.existsSync(client.path)) continue;
+            const entry = readClientCommandEntry(client);
+            if (!entry || !entry.command) continue;
+            const cmd = entry.command;
+            // Skip launchers that resolve via npm at runtime.
+            if (/(^|[\\/])(npx|npx\.cmd|node|node\.exe)$/i.test(cmd) || /[\\/]genexus-mcp(\.cmd)?$/i.test(cmd)) continue;
+            if (!/\.exe$/i.test(cmd)) continue;
+            if (normalizeExePath(cmd) !== packageNorm) {
+                mismatches.push({ client: client.name, configured: cmd });
+            }
+        }
+        return mismatches;
+    } catch {
+        return [];
+    }
+}
+
 async function handleUpdate(_options, ctx) {
     const current = getPackageVersion();
     const result = await fetchLatestRelease();
+    const mismatches = detectClientExeDrift();
+
+    const driftHelp = mismatches.length
+        ? [`WARNING: ${mismatches.length} AI client(s) point at a gateway exe that is NOT this npm package — \`npm install -g ${NPM_PACKAGE}@latest\` will NOT update them. Mismatches: ${mismatches.map((m) => `${m.client} -> ${m.configured}`).join('; ')}. Re-run scripts/install.ps1 (or genexus-mcp init --write-clients) to resync.`]
+        : [];
 
     if (!result) {
         return {
@@ -171,9 +206,10 @@ async function handleUpdate(_options, ctx) {
                     current,
                     latest: null,
                     updateAvailable: false,
-                    fetched: false
+                    fetched: false,
+                    clientDrift: mismatches
                 },
-                help: ['Could not reach GitHub releases API. Check connectivity or retry later.']
+                help: ['Could not reach GitHub releases API. Check connectivity or retry later.', ...driftHelp]
             }
         };
     }
@@ -185,7 +221,7 @@ async function handleUpdate(_options, ctx) {
     });
 
     const updateAvailable = compareSemver(result.latestVersion, current || '0.0.0') > 0;
-    const help = updateAvailable
+    const baseHelp = updateAvailable
         ? [`Run: npm install -g ${NPM_PACKAGE}@latest`, result.releaseUrl ? `Release: ${result.releaseUrl}` : null].filter(Boolean)
         : ['Already on latest version.'];
 
@@ -198,9 +234,10 @@ async function handleUpdate(_options, ctx) {
                 releaseUrl: result.releaseUrl,
                 updateAvailable,
                 installCommand: `npm install -g ${NPM_PACKAGE}@latest`,
-                fetched: true
+                fetched: true,
+                clientDrift: mismatches
             },
-            help
+            help: [...baseHelp, ...driftHelp]
         }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genexus-mcp",
-  "version": "2.6.3",
+  "version": "2.6.5",
   "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": [

package/publish/GxMcp.Gateway.deps.json

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

package/publish/tool_definitions.json

@@ -1,16 +1,17 @@
 [
-  {"name":"genexus_whoami","description":"Return current KB context, GeneXus install, and MCP version.","inputSchema":{"type":"object","properties":{}}},
+  {"name":"genexus_whoami","description":"Return current KB context, GeneXus install, MCP version, AND inline playbooks for common flows (WWP, popup, layout). Call this FIRST on every session — the `playbooks` block routes you to the right tool without exploration.","inputSchema":{"type":"object","properties":{}}},
+  {"name":"genexus_recipe","description":"Fetch a step-by-step playbook for a named flow (e.g. 'wwp_on_transaction', 'wwp_on_webpanel', 'create_popup', 'edit_pattern_instance', 'add_custom_button'). Returns prereq/steps/pitfalls. Call name='list' to enumerate available recipes.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Recipe key, or 'list' to enumerate."}},"required":["name"]}},
   {"name":"genexus_query","description":"Search objects in the active KB. Supports prefixes (type:, usedby:, parent:, parentPath:, description:). Compact projection by default. See genexus://kb/tool-help/genexus_query for examples.","inputSchema":{"type":"object","properties":{"query":{"type":"string"},"typeFilter":{"type":"string"},"domainFilter":{"type":"string"},"limit":{"type":"integer"},"inline_read_top":{"type":"integer","description":"0-3. Inline reads of top N in response."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."},"axiCompact":{"type":"boolean","description":"Default true. Returns compact projection (name,type,path). Pass false for full payload.","default":true}},"required":["query"]}},
   {"name":"genexus_list_objects","description":"List objects with pagination. Feed nextOffset until hasMore=false. Returns minimal shape by default (name, type, path, parent); verbose=true for full shape.","inputSchema":{"type":"object","properties":{"filter":{"type":"string","description":"Legacy: matches name OR description. Prefer nameFilter/descriptionFilter."},"nameFilter":{"type":"string","description":"Substring match on object name only."},"descriptionFilter":{"type":"string","description":"Substring match on description only."},"pathPrefix":{"type":"string","description":"Folder path prefix, e.g. 'Root Module/ClickSign/'."},"limit":{"type":"integer"},"offset":{"type":"integer"},"parent":{"type":"string"},"parentPath":{"type":"string"},"typeFilter":{"type":"string"},"verbose":{"type":"boolean","description":"When true, returns full item shape (default false)."},"inline_read_top":{"type":"integer","description":"0-3. Inline reads of top N in response."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."},"axiCompact":{"type":"boolean","description":"Default true. Returns compact projection (name,type,path,parentPath). Pass false for full payload.","default":true}}}},
   {"name":"genexus_read","description":"Read source/metadata parts of one or more objects. Pass name or targets, plus parts=[...]. Paginate large source with offset/limit. See genexus://kb/tool-help/genexus_read for examples.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"targets":{"type":"array","items":{"type":"string"}},"part":{"type":"string"},"parts":{"type":"array","items":{"type":"string"},"description":"When set, only the listed parts are returned in a combined response. Mutually exclusive with part/offset/limit."},"offset":{"type":"integer"},"limit":{"type":"integer"},"type":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
-  {"name":"genexus_edit","description":"Edit an object part. Pass name or targets (mutually exclusive). Mode: full | patch. Use dryRun before persisting. See genexus://kb/tool-help/genexus_edit for examples.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"part":{"type":"string"},"mode":{"type":"string","enum":["full","patch","ops"]},"content":{"type":"string"},"ops":{"type":"array","description":"RFC 6902 JSON-Patch ops. Supported: add, remove, replace, test.","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","remove","replace","test"]},"path":{"type":"string"},"value":{}},"required":["op","path"]}},"patch":{"description":"Legacy string replacement OR {find, replace} JSON object. Prefer separate operation/context/content params for new code.","anyOf":[{"type":"string"},{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"]}]},"context":{"type":"string"},"operation":{"type":"string","enum":["Replace","Insert_After","Append"]},"expectedCount":{"type":"integer"},"dryRun":{"type":"boolean"},"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":"Set false to omit post_state.diff from the response (default true)."},"verbose":{"type":"boolean","description":"When true, adds slices (±15 lines around each hunk) to post_state (default false)."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
+  {"name":"genexus_edit","description":"Edit an object part. Pass name or targets (mutually exclusive). Mode: full | patch. Use dryRun before persisting. For WWP screens edit the host WorkWithPlus<X>.PatternInstance — NOT the WebForm of the parent (gets overwritten on reapply). See recipe 'edit_pattern_instance' and 'add_custom_button' via genexus_recipe.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"part":{"type":"string"},"mode":{"type":"string","enum":["full","patch","ops"]},"content":{"type":"string"},"ops":{"type":"array","description":"RFC 6902 JSON-Patch ops. Supported: add, remove, replace, test.","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","remove","replace","test"]},"path":{"type":"string"},"value":{}},"required":["op","path"]}},"patch":{"description":"Legacy string replacement OR {find, replace} JSON object. Prefer separate operation/context/content params for new code.","anyOf":[{"type":"string"},{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"]}]},"context":{"type":"string"},"operation":{"type":"string","enum":["Replace","Insert_After","Append"]},"expectedCount":{"type":"integer"},"dryRun":{"type":"boolean"},"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":"Set false to omit post_state.diff from the response (default true)."},"verbose":{"type":"boolean","description":"When true, adds slices (±15 lines around each hunk) to post_state (default false)."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
   {"name":"genexus_inspect","description":"Snapshot of an object: metadata, variables, structure, signature. Raw object shape without source text. For source/code use genexus_read.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"include":{"type":"array","items":{"type":"string","enum":["metadata","variables","signature","structure","parts","controls","events_repertoire","callers"]}},"type":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name"]}},
-  {"name":"genexus_analyze","description":"Cross-object semantic analysis: impact, dependencies, complexity, naming, summary, explain. See genexus://kb/tool-help/genexus_analyze for mode selection.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"mode":{"type":"string","enum":["linter","navigation","hierarchy","impact","data_context","ui_context","pattern_metadata","summary","explain"]},"kb":{"type":"string","description":"Target KB. Required when 2+ open."},"code":{"type":"string","description":"Required when mode=explain."},"waitForIndex":{"type":"boolean","description":"For mode=impact: when true (default) block up to 30s for the index to be Ready; when false return a status envelope immediately if the index is Cold/Reindexing.","default":true}},"required":["name","mode"]}},
+  {"name":"genexus_analyze","description":"Cross-object semantic analysis: impact, dependencies, complexity, naming, summary. See genexus://kb/tool-help/genexus_analyze for mode selection.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"mode":{"type":"string","enum":["linter","navigation","hierarchy","impact","data_context","ui_context","pattern_metadata","summary"]},"kb":{"type":"string","description":"Target KB. Required when 2+ open."},"waitForIndex":{"type":"boolean","description":"For mode=impact: when true (default) block up to 30s for the index to be Ready; when false return a status envelope immediately if the index is Cold/Reindexing.","default":true}},"required":["name","mode"]}},
   {"name":"genexus_inject_context","description":"Inject SDT structures and Procedure signatures of called objects.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"recursive":{"type":"boolean"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name"]}},
   {"name":"genexus_lifecycle","description":"Build, validate, index, or poll the KB. Long ops are async with operationId. See genexus://kb/tool-help/genexus_lifecycle for actions and target formats.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["build","cancel","rebuild","reorg","validate","validate-kb","sync","index","status","result","snapshots-list","snapshots-restore"]},"target":{"type":"string","description":"Object name(s), taskId, job_id, or op:<operationId>."},"code":{"type":"string"},"limit":{"type":"integer"},"snapshotPath":{"type":"string"},"estimated_seconds":{"type":"integer","description":"Build: <20 forces sync fast-path (one turn); >=20 (default 60) goes async."},"wait_seconds":{"type":"integer","description":"Status: 0-25. >0 long-polls server-side until terminal or timeout."},"compact":{"type":"boolean","description":"Status: when true (default) returns counts + top-10 errors + warning dedup. Set false for legacy full Output/Errors[]."},"force":{"type":"boolean","description":"Index: when true, clears in-memory + on-disk snapshot and runs a full SDK rescan. Use when impact analyze reports indexEdgesMissing or after adding/renaming objects."},"includeCallees":{"type":"string","enum":["none","direct","transitive"],"description":"Build: auto-expand target via call graph so callees compile before callers (fixes CS0246 from missing DLLs). Default transitive."},"buildPlanCap":{"type":"integer","description":"Build: max expanded nodes before BuildPlanTooLarge (default 200)."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action"]}},
   {"name":"genexus_forge","description":"Generate new code or structures from templates or translations.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["scaffold","translate","sample"]},"type":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action"]}},
   {"name":"genexus_test","description":"Execute native GeneXus tests (GXtest).","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name"]}},
-  {"name":"genexus_create_object","description":"Create any IDE-creatable GeneXus object (Transaction, Procedure, WebPanel, SDPanel, SDT, DataProvider, Domain, Dashboard, WorkflowDiagram, etc.). Domain takes dataType+length or enumValues. See genexus://kb/tool-help/genexus_create_object.","inputSchema":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"dataType":{"type":"string"},"length":{"type":"integer"},"decimals":{"type":"integer"},"signed":{"type":"boolean"},"description":{"type":"string"},"basedOn":{"type":"string"},"enumValues":{"type":"array","items":{"type":"object"}},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["type","name"]}},
+  {"name":"genexus_create_object","description":"Create any IDE-creatable GeneXus object (Transaction, Procedure, WebPanel, SDPanel, SDT, DataProvider, Domain, Dashboard, WorkflowDiagram, etc.). Domain takes dataType+length or enumValues. NOT for WorkWithPlus/WWP — that is a pattern applied via genexus_apply_pattern (see recipe 'wwp_on_transaction' or 'wwp_on_webpanel'). NOT for popups with editable inputs — use genexus_create_popup. See genexus://kb/tool-help/genexus_create_object.","inputSchema":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"dataType":{"type":"string"},"length":{"type":"integer"},"decimals":{"type":"integer"},"signed":{"type":"boolean"},"description":{"type":"string"},"basedOn":{"type":"string"},"enumValues":{"type":"array","items":{"type":"object"}},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["type","name"]}},
   {"name":"genexus_logs","description":"Read worker_debug.log tail for error diagnosis or correlation.","inputSchema":{"type":"object","properties":{"lines":{"type":"integer"},"filterCorrelation":{"type":"string"},"grep":{"type":"string"}}}},
   {"name":"genexus_sdk_probe","description":"Scan loaded GeneXus SDK assemblies and dump a structured map of every public type, method, property to docs/sdk-probe/. Use when investigating new SDK surface or hunting for an entry point. Outputs raw.json + INDEX.md + generators.md.","inputSchema":{"type":"object","properties":{"outputDir":{"type":"string","description":"Optional absolute path. Defaults to <repo>/docs/sdk-probe/ or %TEMP%/gxmcp_sdk_probe/."}}}},
   {"name":"genexus_worker_reload","description":"Hot-reload worker: copy new binaries and respawn.","inputSchema":{"type":"object","properties":{"sourceDir":{"type":"string","description":"Absolute path to freshly built bin/Release."}},"required":["sourceDir"]}},
@@ -37,7 +38,7 @@
   {"name":"genexus_kb","description":"Manage open KBs: list (with PID/RSS/idle), open (acquire Worker), close (release), set_default (persist alias to config.json).","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","open","close","set_default"]},"alias":{"type":"string","description":"KB alias (for open/close). For open, auto-generated from path basename if omitted."},"path":{"type":"string","description":"Absolute path to the KB (required for action=open if alias is not declared in config)."}},"required":["action"]}},
   {"name":"genexus_sql","description":"SQL for a Transaction/Table (DDL) or a procedure For Each navigation.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["ddl","navigation"]},"name":{"type":"string"},"includeSubordinated":{"type":"boolean","description":"action=ddl only."},"levelNumber":{"type":"integer","description":"action=navigation only."},"type":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action","name"]}},
   {"name":"genexus_preview","description":"Render preview of a WebPanel via headless Chrome (chrome-devtools-axi). Opens the launcher page, fills required parms, navigates to the target, captures HTML/a11y/screenshot, optionally diffs vs baseline. Returns status + captures.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Target WebPanel name."},"parms":{"type":"object","description":"Per-call launcher parms (merged over config defaults and objectParms)."},"launcher":{"type":"string","description":"Launcher page (default 'auto' = config.launcher)."},"buildFirst":{"type":"boolean","default":false,"description":"If true, dispatch a build before opening the browser."},"waitMs":{"type":"integer","default":3000,"description":"Milliseconds to wait after navigation before capture."},"capture":{"type":"array","items":{"type":"string","enum":["html","a11y","screenshot","console"]},"description":"Capture set (default ['html','a11y'])."},"diffBaseline":{"type":"boolean","default":false,"description":"Compute structural diff vs stored a11y baseline."},"updateBaseline":{"type":"boolean","default":false,"description":"Persist current a11y snapshot as the new baseline."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name"]}},
-  {"name":"genexus_apply_pattern","description":"Apply a GeneXus pattern (e.g. WorkWithPlus) to a parent object. Equivalent to IDE 'Right-click → Apply Pattern'.","inputSchema":{"type":"object","required":["name","pattern"],"properties":{"name":{"type":"string","description":"Target KBObject name (Transaction, WebPanel, etc.)"},"pattern":{"type":"string","description":"Pattern key ('WorkWithPlus') or GUID"},"settings":{"type":"object","description":"Optional pattern-instance settings (deeply nested config tree from the pattern's settings dialog)"},"reapply":{"type":"boolean","default":false,"description":"Re-run on existing instance instead of first-time apply"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
+  {"name":"genexus_apply_pattern","description":"Apply a GeneXus pattern (e.g. WorkWithPlus) to a parent object. Equivalent to IDE 'Right-click → Apply Pattern'. ALWAYS run genexus_inspect first to confirm parentType — Transaction (family-gen, no template) vs WebPanel/SDPanel (direct-attach, pass settings.template). Other types are rejected. See recipe 'wwp_on_transaction' or 'wwp_on_webpanel' via genexus_recipe.","inputSchema":{"type":"object","required":["name","pattern"],"properties":{"name":{"type":"string","description":"Target KBObject name (Transaction, WebPanel, etc.)"},"pattern":{"type":"string","description":"Pattern key ('WorkWithPlus') or GUID"},"settings":{"type":"object","description":"Optional pattern-instance settings (deeply nested config tree from the pattern's settings dialog)"},"reapply":{"type":"boolean","default":false,"description":"Re-run on existing instance instead of first-time apply"},"validate":{"type":"boolean","default":false,"description":"After apply, build the generated host to verify it compiles cleanly. Response gains a `validation` block: {status: ok|failed|timeout, errorCount, warningCount, errors[], warnings[], durationMs}. Adds 60-180s wall time but catches binding/wiring errors the LLM would only see by opening the IDE."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
   {"name":"genexus_edit_and_build","description":"Edit an object then rebuild its callers in one call. Returns edit diff + impact + build operationId. See genexus://kb/tool-help/genexus_edit_and_build for examples.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Target object name."},"part":{"type":"string","description":"Part to edit (Source, Rules, ...)."},"content":{"type":"string","description":"New content or unified diff."},"mode":{"type":"string","enum":["full","patch"],"default":"patch"},"type":{"type":"string","description":"Disambiguates when name matches multiple objects."},"dryRun":{"type":"boolean","default":false},"buildIncludeCallees":{"type":"string","enum":["none","direct","transitive"],"default":"direct"},"buildPlanCap":{"type":"integer","default":200},"waitForIndex":{"type":"boolean","default":true},"waitTimeoutMs":{"type":"integer","default":30000}},"required":["name","part","content"]}},
   {"name":"genexus_create_popup","description":"W3: create a popup WebPanel with a Form type=\"layout\" body so radio/combo bindings render editable. Spec carries title, description, inputs (radio|combo|text with options), buttons, inParms, outParms.","inputSchema":{"type":"object","required":["name","spec"],"properties":{"name":{"type":"string","description":"WebPanel name. Created if missing; updated if exists."},"spec":{"type":"object","description":"Popup spec.","properties":{"title":{"type":"string"},"description":{"type":"string"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["radio","combo","text"]},"varName":{"type":"string"},"label":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"showWhen":{"type":"string","description":"e.g. \"RespRegProf == 'S'\"; emits Refresh event toggling group visibility."}},"required":["type","varName"]}},"buttons":{"type":"array","items":{"type":"object","properties":{"caption":{"type":"string"},"event":{"type":"string"}}}},"inParms":{"type":"array","items":{"type":"string"},"description":"e.g. [\"AluAnoCad:Numeric(2)\"]"},"outParms":{"type":"array","items":{"type":"string"}}}},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}}
 ]