genexus-mcp 3.5.3 → 3.6.1

package/README.md

@@ -12,19 +12,21 @@
 
 ---
 
-**GeneXus MCP Server** lets AI agents — Claude Desktop, Claude Code, Cursor, Antigravity, and any MCP-compatible client — read, edit, analyze, and refactor objects inside a Knowledge Base supported by the selected GeneXus SDK. It talks to the **native GeneXus SDK**, so the agent works with the *real* KB, not a copy or a parsed approximation.
+**GeneXus MCP Server** lets AI agents — Claude Desktop, Claude Code, Cursor, Antigravity, and any MCP-compatible client — read, edit, analyze, and refactor objects inside a Knowledge Base supported by the selected native SDK or legacy compatibility driver. Native SDK paths work with the **real GeneXus SDK** and legacy paths use explicit reflection/COM adapters; neither path relies on a parsed copy of the KB.
 
 In practice: you point the MCP at your KB, then ask your AI assistant things like *"list all transactions with attribute CustomerId"*, *"add a rule to the Order transaction that validates the total"*, or *"refactor this procedure to use the new SDT"* — and it does it.
 
 ---
 
-## Multi-version SDK support
+## Multi-version GeneXus support
 
-The same MCP distribution supports the SDK majors listed in the generated
-compatibility document. Each configured MCP process selects one installed SDK
-with `--gx`; no separate MCP installation is required. The commands below are
-examples of switching the existing configuration, not running two majors in
-the same process:
+The same MCP distribution supports the official native SDK majors listed in the
+generated compatibility document. It also includes basic, best-effort
+compatibility for the legacy versions listed there through separate drivers;
+that path is not equivalent to full native-SDK support. Each configured MCP
+process selects one installed SDK or legacy driver with `--gx`; no separate MCP
+installation is required. The commands below are examples of switching the
+existing configuration, not running two majors in the same process:
 
 ```bash
 npx genexus-mcp@latest init --kb "C:\KBs\KBTeste17" --gx "C:\Program Files (x86)\GeneXus\GeneXus17Trial"
@@ -45,7 +47,9 @@ that checks every supported major against one published artifact.
 
 The Gateway reports the detected SDK through `genexus_whoami`:
 
-- `geneXus.supportedMajors`: explicitly validated SDK majors from the version catalog
+- `geneXus.supportedMajors`: explicitly validated native SDK majors from the version catalog
+- `geneXus.legacyMajors`: catalogued legacy majors handled by their compatibility drivers
+- `geneXus.sdkCompatibility.supportLevel`: `native-sdk` or `basic-legacy` for the detected installation
 - `geneXus.matchedMajor`: the major detected for the configured installation
 - `geneXus.versionMatches`: whether the detected installation is in that catalog
 - `geneXus.supportedMajor`: retained as the legacy single-major alias for the catalog primary
@@ -57,15 +61,28 @@ needed. Existing tool names, arguments, and MCP client configuration formats do
 not change.
 
 <!-- BEGIN GENERATED: gx-compatibility -->
-Supported SDK majors: **GeneXus 17, GeneXus 18**.
+Supported SDK majors: **GeneXus 16, GeneXus 17, GeneXus 18** (native SDK).
+Basic legacy compatibility: **GeneXus Evolution 3, GeneXus Evolution 2, GeneXus Evolution 1, GeneXus 15, GeneXus 9.0, GeneXus 8.0** via `com-gxpublic` and `dotnet-reflection` (not the native SDK build).
 Primary SDK: **GeneXus 18**.
 Source of truth: `config/gx-versions.json`.
 <!-- END GENERATED: gx-compatibility -->
 
-To add another GeneXus major in the future, add it to the explicit version
-catalog only after compiling the Worker with that SDK and passing the focused
-tests plus a live KB smoke. This prevents the server from claiming compatibility
-based only on a version string.
+To add another native-SDK major in the future, add it to the explicit
+`supportedMajors` catalog only after compiling the Worker with that SDK and
+passing the focused tests plus a live KB smoke. This prevents the server from
+claiming native-SDK compatibility based only on a version string.
+
+### Basic legacy compatibility (not native SDK support)
+
+Every legacy version currently declared in `legacyMajors` uses a best-effort
+driver rather than the native SDK build:
+- **GeneXus Evolution 1 (10.1), Evolution 2 (10.2), Evolution 3 (10.3), and GeneXus 15**: Driven via runtime reflection (`dotnet-reflection`), dynamically adapting to missing types or structural differences (such as module-less KBs without `QualifiedName`).
+- **GeneXus 8.0 and GeneXus 9.0**: Driven through the classic GXPublic surface (`com-gxpublic`), detected from `gx.exe`/`gxdl32.dll` and classic `.gxi` Knowledge Bases. GXPublic is a metadata-oriented OLE DB/COM surface; this path is intentionally limited to basic metadata/core operations and does not claim native-SDK source/edit parity.
+- **Graceful degradation**: Modern tools that require features introduced in newer GeneXus versions (such as `genexus_api`, `genexus_gam`, or `genexus_module`) return structured `UNSUPPORTED_IN_GENEXUS_VERSION` errors indicating the required minimum version rather than failing ungracefully.
+
+This legacy path is intended for basic core operations where implemented; it
+does not claim the same feature parity as the native SDK contract for GeneXus
+16, 17, and 18.
 
 ---
 
@@ -86,7 +103,10 @@ A quick map of what the agent can do against your real KB through the **50 tools
 | 🌿 **Versioning, transfer & teams** | KB model versions/branches, **real XPZ export/import** (dependency-aware), GXserver (Team Development) sync + **CI pipelines**, git-style history, multi-KB parallel work |
 | 🔐 **Security** | GAM / integrated-security provisioning, KB security audit + native Security Scanner |
 
-It works through the **native GeneXus SDK** — the same code paths the IDE uses — so edits are real and validated, not text hacks on KB files.
+Native SDK support works through the **native GeneXus SDK** — the same code paths
+the IDE uses — so edits are real and validated, not text hacks on KB files.
+Legacy support uses the reflection or COM driver listed in the catalog and
+degrades unsupported modern tools explicitly.
 
 ---
 
@@ -95,9 +115,9 @@ It works through the **native GeneXus SDK** — the same code paths the IDE uses
 Before you start, make sure you have:
 
 - ✅ **Windows** (GeneXus is Windows-only)
-- ✅ **A supported GeneXus SDK** installed locally (see [`docs/generated/supported-versions.md`](docs/generated/supported-versions.md); pass another install path explicitly when needed)
-- ✅ **GeneXus 18** installed locally (the primary supported SDK; other catalogued majors are also supported)
-- ✅ **A Knowledge Base created with a supported GeneXus major** and opened at least once in the IDE (so it's initialized)
+- ✅ **A supported GeneXus installation** installed locally: GeneXus 16, 17, or 18 for native SDK support, or a catalogued legacy installation for basic compatibility (see [`docs/generated/supported-versions.md`](docs/generated/supported-versions.md); pass another install path explicitly when needed)
+- ✅ **GeneXus 18** installed locally for the primary native-SDK path; other catalogued native and legacy versions are also supported according to their listed driver
+- ✅ **A Knowledge Base created with a supported native or legacy GeneXus major** and opened at least once in the IDE (so it's initialized)
 - ✅ **Node.js 22+** — check with `node --version` in a terminal; install from [nodejs.org](https://nodejs.org/) if missing
 - ✅ **An MCP-compatible AI client** — [Claude Desktop](https://claude.ai/download), [Claude Code](https://claude.com/claude-code), Cursor, Antigravity, etc.
 

package/cli/commands/axi.js

@@ -59,7 +59,9 @@ function validateClientIds(ids) {
 
 function isSupportedCatalogMajor(catalog, major) {
     if (!major) return true;
-    return catalog.supportedMajors.some((entry) => String(entry.major) === String(major));
+    const inSupported = catalog.supportedMajors && catalog.supportedMajors.some((entry) => String(entry.major) === String(major));
+    if (inSupported) return true;
+    return Array.isArray(catalog.legacyMajors) && catalog.legacyMajors.some((entry) => String(entry.major) === String(major));
 }
 
 function parseFieldSelection(raw) {
@@ -176,6 +178,37 @@ function buildStatusData(cwd) {
     return { ready, configFound, gatewayExeFound, kbLooksValid, configPath, gatewayExePath, kbPath, gxPath, configSource };
 }
 
+const PROBE_EXIT_GRACE_MS = 2000;
+
+// Stop a probe child and wait for it to actually exit. On Windows child.kill()
+// only signals the direct process and returns before the OS releases the
+// executable image, so reporting success right after kill() left the exe file
+// handle open (Issue #211: the shared gateway stub in cli/run.test.js made the
+// suite teardown fail with EPERM while every assertion passed). Resolves true
+// once the child exited, false when it did not within the bounded grace.
+function stopProbeChild(child, graceMs = PROBE_EXIT_GRACE_MS) {
+    return new Promise((resolve) => {
+        if (!child || child.exitCode !== null || child.signalCode !== null) {
+            resolve(true);
+            return;
+        }
+        let settled = false;
+        const finish = (exited) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(exited);
+        };
+        const timer = setTimeout(() => finish(false), graceMs);
+        child.once('exit', () => finish(true));
+        try {
+            child.kill();
+        } catch {
+            finish(true);
+        }
+    });
+}
+
 async function spawnGatewayProbe({ env = process.env, spawnHoldMs, timeoutMs, label, successDetail }) {
     const gatewayExePath = getGatewayExePath();
 
@@ -209,17 +242,25 @@ async function spawnGatewayProbe({ env = process.env, spawnHoldMs, timeoutMs, la
             });
 
             child.once('spawn', () => {
-                setTimeout(() => {
-                    try { child.kill(); } catch { }
-                    finish({ status: 'pass', detail: successDetail });
+                setTimeout(async () => {
+                    const exited = await stopProbeChild(child);
+                    if (exited) {
+                        finish({ status: 'pass', detail: successDetail });
+                    } else {
+                        finish({ status: 'warn', detail: `${label}: process did not exit after the stop signal; it may still hold the gateway exe.` });
+                    }
                 }, spawnHoldMs);
             });
 
-            setTimeout(() => {
-                if (!done) {
-                    try { child.kill(); } catch { }
-                    finish({ status: 'warn', detail: `${label} timed out; process was force-stopped.` });
-                }
+            setTimeout(async () => {
+                if (done) return;
+                const exited = await stopProbeChild(child);
+                finish({
+                    status: 'warn',
+                    detail: exited
+                        ? `${label} timed out; process was force-stopped.`
+                        : `${label} timed out and did not exit after the stop signal; it may still hold the gateway exe.`
+                });
             }, timeoutMs);
         } catch (err) {
             finish({ status: 'fail', detail: `${label} threw: ${err.message}` });
@@ -562,6 +603,50 @@ function buildInProcessBuildAssemblyLoadCheck(gxPath) {
     };
 }
 
+function buildGxPublicComCheck(gxMajor, gxPath) {
+    if (gxMajor !== '8' && gxMajor !== '9') {
+        return { id: 'gxpublic_com_registration', status: 'not_applicable', detail: 'Not a GeneXus 8.0/9.0 installation.' };
+    }
+    const child_process = require('child_process');
+    let isRegistered = false;
+    try {
+        const res = child_process.spawnSync('reg', ['query', 'HKCR\\GXPublic.GXPublic'], { encoding: 'utf8', timeout: 2000 });
+        isRegistered = res.status === 0;
+    } catch { }
+
+    if (isRegistered) {
+        return { id: 'gxpublic_com_registration', status: 'pass', detail: 'GXPublic COM automation server (GXPublic.GXPublic) is registered.' };
+    }
+    const dllHint = gxPath ? path.join(gxPath, 'GxPublic.dll') : 'GxPublic.dll';
+    return {
+        id: 'gxpublic_com_registration',
+        status: 'warn',
+        detail: `GXPublic COM component is not registered. Run 'regsvr32 "${dllHint}"' to enable GeneXus ${gxMajor}.0 COM automation.`
+    };
+}
+
+function buildLegacyIdeLockCheck(gxMajor) {
+    if (gxMajor !== '8' && gxMajor !== '9' && gxMajor !== '10.1' && gxMajor !== '10.2') {
+        return { id: 'legacy_ide_lock', status: 'not_applicable', detail: 'Lock check not applicable for modern GeneXus versions.' };
+    }
+    const child_process = require('child_process');
+    let ideRunning = false;
+    try {
+        const res = child_process.spawnSync('tasklist', ['/FI', 'IMAGENAME eq gx.exe', '/NH'], { encoding: 'utf8', timeout: 2000 });
+        if (res.stdout && res.stdout.toLowerCase().includes('gx.exe')) {
+            ideRunning = true;
+        }
+    } catch { }
+    if (ideRunning) {
+        return {
+            id: 'legacy_ide_lock',
+            status: 'warn',
+            detail: 'GeneXus IDE (gx.exe) process is currently running. Legacy engines hold exclusive file locks on the KB.'
+        };
+    }
+    return { id: 'legacy_ide_lock', status: 'pass', detail: 'No conflicting GeneXus IDE process (gx.exe) detected.' };
+}
+
 function redactConfig(cfg) {
     // Replace absolute paths with `<redacted:hash8>` so the structure is preserved
     // but filesystem layout, usernames, and KB names are not leaked. Hash is stable
@@ -710,7 +795,7 @@ async function handleDoctor(options, ctx) {
     const kbPath = data.kbPath;
     const gxPath = data.gxPath;
     const kbExists = !!(kbPath && fs.existsSync(kbPath));
-    const gxExeExists = !!(gxPath && fs.existsSync(path.join(gxPath, 'genexus.exe')));
+    const gxExeExists = !!(gxPath && (fs.existsSync(path.join(gxPath, 'genexus.exe')) || fs.existsSync(path.join(gxPath, 'gx.exe'))));
     const kbSdkCompatibility = kbExists && gxExeExists
         ? compareGeneXusKbAndInstallation(kbPath, gxPath)
         : null;
@@ -731,15 +816,18 @@ async function handleDoctor(options, ctx) {
             compatibilityDetail = `${unsupportedCompatibilityMajor} is not supported by this MCP distribution. Supported majors: ${catalog.supportedMajors.map((entry) => entry.major).join(', ')}.`;
         } else if (kbSdkCompatibility.status === 'mismatch') {
             compatibilityStatus = 'fail';
-            compatibilityDetail = `KB major ${kbSdkCompatibility.kb.major} does not match GeneXus SDK major ${kbSdkCompatibility.gx.major}. Re-run init with the matching --gx path.`;
+            compatibilityDetail = `KB major ${kbSdkCompatibility.kb.major} does not match GeneXus SDK major ${kbSdkCompatibility.gx.major}${kbSdkCompatibility.gx.version ? ` (${kbSdkCompatibility.gx.version})` : ''}. Re-run init with the matching --gx path.`;
         } else if (kbSdkCompatibility.status === 'match') {
             compatibilityStatus = 'pass';
-            compatibilityDetail = `KB major ${kbSdkCompatibility.kb.major} matches GeneXus SDK major ${kbSdkCompatibility.gx.major}.`;
+            compatibilityDetail = `KB major ${kbSdkCompatibility.kb.major} matches GeneXus SDK major ${kbSdkCompatibility.gx.major}${kbSdkCompatibility.gx.version ? ` (${kbSdkCompatibility.gx.version})` : ''}.`;
         } else {
             compatibilityDetail = `KB/SDK major compatibility could not be verified (KB: ${kbSdkCompatibility.kb.source}; SDK: ${kbSdkCompatibility.gx.source}).`;
         }
     }
 
+    const gxIdent = gxPath ? readGeneXusInstallationIdentity(gxPath) : null;
+    const gxVersionLabel = gxIdent && gxIdent.version ? ` (GeneXus ${gxIdent.major || ''} version ${gxIdent.version})` : (gxIdent && gxIdent.major ? ` (GeneXus ${gxIdent.major})` : '');
+
     const riskyZone = isPathLikelyAppLockerBlocked(gatewayExePath);
     const clientCrossCheck = buildClientExeCrossCheck(gatewayExePath);
 
@@ -767,7 +855,7 @@ async function handleDoctor(options, ctx) {
         // Same logic for the GeneXus install: missing genexus.exe at a configured path
         // guarantees a worker crash on first MCP call. Promote from warn to fail so init
         // exits non-zero and the caller (install.ps1, AI client) actually sees the problem.
-        { id: 'gx_installation', status: gxExeExists ? 'pass' : (gxPath ? 'fail' : 'warn'), detail: gxExeExists ? 'GeneXus installation has genexus.exe.' : (gxPath ? `Configured GeneXus installation is missing genexus.exe at: ${gxPath}` : 'No GeneXus installation path is configured.') },
+        { id: 'gx_installation', status: gxExeExists ? 'pass' : (gxPath ? 'fail' : 'warn'), detail: gxExeExists ? `GeneXus installation has ${gxPath && fs.existsSync(path.join(gxPath, 'gx.exe')) && !fs.existsSync(path.join(gxPath, 'genexus.exe')) ? 'gx.exe' : 'genexus.exe'}${gxVersionLabel}.` : (gxPath ? `Configured GeneXus installation is missing executable at: ${gxPath}` : 'No GeneXus installation path is configured.') },
         {
             id: 'kb_sdk_compatibility',
             status: compatibilityStatus,
@@ -784,6 +872,13 @@ async function handleDoctor(options, ctx) {
     const inProcessLoad = buildInProcessBuildAssemblyLoadCheck(gxPath);
     checks.push({ id: 'in_process_build_assembly_load', status: inProcessLoad.status, detail: inProcessLoad.detail });
 
+    // Legacy GeneXus checks (GX 8.0, 9.0, Ev1, Ev2)
+    const gxMajor = (gxIdent && gxIdent.major) || (kbSdkCompatibility && kbSdkCompatibility.gx && kbSdkCompatibility.gx.major) || null;
+    const comCheck = buildGxPublicComCheck(gxMajor, gxPath);
+    checks.push({ id: 'gxpublic_com_registration', status: comCheck.status, detail: comCheck.detail });
+    const ideLockCheck = buildLegacyIdeLockCheck(gxMajor);
+    checks.push({ id: 'legacy_ide_lock', status: ideLockCheck.status, detail: ideLockCheck.detail });
+
     // Client registration summary — one line answering "are my AI agents wired up?".
     const clientRows = clientsStatus();
     const installedRows = clientRows.filter((r) => r.installed);
@@ -1344,6 +1439,7 @@ function buildClientLauncherHelp(patchResult) {
     }
     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.');
+        help.push('Working from a local checkout? Register the clients with the checkout gateway from the repo root instead: `$env:GENEXUS_MCP_GATEWAY_EXE="<repoRoot>\\publish\\GxMcp.Gateway.exe"; node cli\\run.js clients add --clients <ids>` (or re-run `.\\install.ps1`). Avoid `npx @latest clients add` there, because it rewrites the registration to this npm package\'s launcher; validate with the same checkout CLI (`node cli\\run.js clients` / `doctor`).');
     }
     return help;
 }
@@ -1939,6 +2035,7 @@ async function probeWorkerStartup({ configPath, observeMs = 2500 }) {
         };
 
         let child;
+        let stopping = false;
         try {
             child = spawn(gatewayExePath, [], {
                 stdio: ['ignore', 'pipe', 'pipe'],
@@ -1957,6 +2054,9 @@ async function probeWorkerStartup({ configPath, observeMs = 2500 }) {
         });
 
         child.once('exit', (code) => {
+            // The observation timeout stops the gateway itself; that deliberate
+            // signal is reported by the timeout branch, not as a crash.
+            if (stopping) return;
             if (code === 0) {
                 finish({ status: 'pass', detail: 'Worker smoke: gateway exited cleanly during observation window.' });
             } else {
@@ -1970,10 +2070,15 @@ async function probeWorkerStartup({ configPath, observeMs = 2500 }) {
             }
         });
 
-        setTimeout(() => {
-            try { child.kill(); } catch { }
-            // Still alive after observeMs → worker bootstrapped without crashing.
-            finish({ status: 'pass', detail: `Worker smoke: gateway stayed alive for ${observeMs}ms with KB and GX configured.` });
+        setTimeout(async () => {
+            stopping = true;
+            const exited = await stopProbeChild(child);
+            if (exited) {
+                // Still alive after observeMs → worker bootstrapped without crashing.
+                finish({ status: 'pass', detail: `Worker smoke: gateway stayed alive for ${observeMs}ms with KB and GX configured.` });
+            } else {
+                finish({ status: 'warn', detail: 'Worker smoke: gateway did not exit after the stop signal; it may still hold the gateway exe.' });
+            }
         }, observeMs);
     });
 }
@@ -2150,11 +2255,12 @@ async function handleClients(subcommand, options, ctx) {
         if (invalidLaunchers.length > 0) {
             help.push(`These clients have a known-invalid MCP launcher (check command and args) — re-register: genexus-mcp clients add --clients ${invalidLaunchers.map((r) => r.id).join(',')}${serverName !== DEFAULT_MCP_SERVER_NAME ? ` --server-name ${serverName}` : ''}`);
         }
-        const otherStale = stale.filter((r) =>
-            r.launcherStructuralState !== 'missing' && r.launcherSemanticState !== 'invalid'
-        );
-        if (otherStale.length > 0) {
-            help.push(`These clients have a stale launcher — re-register: genexus-mcp clients add --clients ${otherStale.map((r) => r.id).join(',')}${serverName !== DEFAULT_MCP_SERVER_NAME ? ` --server-name ${serverName}` : ''}`);
+        // A launcher that exists but is not this CLI's gateway is a different working
+        // install (checkout, fixed-path, other package cache), so it is reported as
+        // informational drift instead of a stale registration that needs repair.
+        const driftedLaunchers = rows.filter((r) => r.launcherPathDrift && !r.commandStale);
+        if (driftedLaunchers.length > 0) {
+            help.push(`Note: ${driftedLaunchers.map((r) => r.name).join(', ')} point at a gateway that is not this CLI's (informational — the launcher exists and is valid). Re-register with this CLI only if you want them to track it: genexus-mcp clients add --clients ${driftedLaunchers.map((r) => r.id).join(',')}${serverName !== DEFAULT_MCP_SERVER_NAME ? ` --server-name ${serverName}` : ''}`);
         }
         const semanticValidCount = rows.filter((r) => r.launcherSemanticState === 'valid').length;
         const semanticInvalidCount = rows.filter((r) => r.launcherSemanticState === 'invalid').length;

package/cli/lib/client-adapters.js

@@ -78,10 +78,16 @@ class OpenCodeJsoncAdapter extends BaseClientAdapter {
         this.config = configModule || require('./config');
     }
     apply(client, launcher, targetConfigPath, opts = {}) {
-        return this.config.applyOpenCodeJson(client.path, launcher, targetConfigPath, opts);
+        return this.config.applyOpenCodeJson(client.path, launcher, targetConfigPath, {
+            ...opts,
+            alternatePaths: client.alternatePaths || []
+        });
     }
     remove(client, opts = {}) {
-        return this.config.removeOpenCodeJson(client.path, opts);
+        return this.config.removeOpenCodeJson(client.path, {
+            ...opts,
+            alternatePaths: client.alternatePaths || []
+        });
     }
     read(client, serverName) {
         if (!fs.existsSync(client.path)) return null;