genexus-mcp 3.0.4 → 3.2.0

package/cli/run.test.js

@@ -1,12 +1,23 @@
 const test = require('node:test');
 const assert = require('node:assert/strict');
 const { spawnSync } = require('node:child_process');
+const { Readable, Writable } = require('node:stream');
 const path = require('node:path');
 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, getLauncher } = require('./lib/config');
+const {
+    detectClientInstalled,
+    readJsonFileSafe,
+    getLauncher,
+    getGeneXusMajor,
+    getGeneXusCatalogEntries,
+    readGeneXusInstallationIdentity,
+    readGeneXusKbIdentity,
+    compareGeneXusKbAndInstallation
+} = require('./lib/config');
+const { handleInit } = require('./commands/axi');
 
 const cliPath = path.join(__dirname, 'run.js');
 const testGxPath = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-gx-'));
@@ -15,11 +26,12 @@ const testGatewayEnv = { GENEXUS_MCP_GATEWAY_EXE: process.execPath };
 test.after(() => fs.rmSync(testGxPath, { recursive: true, force: true }));
 
 function runCli(args, opts = {}) {
-    return spawnSync(process.execPath, [cliPath, ...args], {
+    const spawnOptions = {
         encoding: 'utf8',
         cwd: opts.cwd || process.cwd(),
         env: { ...process.env, ...(opts.env || {}) }
-    });
+    };
+    return spawnSync(process.execPath, [cliPath, ...args], spawnOptions);
 }
 
 test('status returns structured json envelope with schema version', () => {
@@ -250,6 +262,155 @@ test('init auto-discovers KB from cwd when --kb is omitted', () => {
     fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
+test('GeneXus installation identity falls back to executable metadata', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-version-'));
+    try {
+        fs.writeFileSync(path.join(tempRoot, 'GeneXus.exe'), 'not-a-real-executable');
+        const identity = readGeneXusInstallationIdentity(tempRoot, {
+            readExecutableVersion: () => '18.0.10.184260'
+        });
+        assert.deepEqual(identity, {
+            version: '18.0.10.184260',
+            major: '18',
+            source: 'executable-metadata'
+        });
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('GeneXus installation identity ignores an invalid version file when executable metadata is valid', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-invalid-version-'));
+    try {
+        fs.writeFileSync(path.join(tempRoot, 'version.txt'), 'not-a-version');
+        fs.writeFileSync(path.join(tempRoot, 'GeneXus.exe'), 'not-a-real-executable');
+        const identity = readGeneXusInstallationIdentity(tempRoot, {
+            readExecutableVersion: () => '17.0.11.163677'
+        });
+        assert.deepEqual(identity, {
+            version: '17.0.11.163677',
+            major: '17',
+            source: 'executable-metadata'
+        });
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('GeneXus installation identity does not infer a major from a missing folder', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-missing-install-'));
+    try {
+        const identity = readGeneXusInstallationIdentity(path.join(tempRoot, 'GeneXus17'));
+        assert.deepEqual(identity, {
+            version: null,
+            major: null,
+            source: 'unavailable'
+        });
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('KB identity reads the GeneXus major from its gxw metadata', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-kb-'));
+    try {
+        fs.writeFileSync(
+            path.join(tempRoot, 'KnowledgeBase.gxw'),
+            '<KnowledgeBase><FriendlyVersion>17.0.11 U11</FriendlyVersion><VersionNumber>17.0.11.163677</VersionNumber></KnowledgeBase>'
+        );
+        const identity = readGeneXusKbIdentity(tempRoot);
+        assert.equal(identity.version, '17.0.11.163677');
+        assert.equal(identity.major, '17');
+        assert.equal(identity.source, 'gxw-version');
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('KB identity fails closed for malformed gxw metadata', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-kb-malformed-'));
+    try {
+        fs.writeFileSync(
+            path.join(tempRoot, 'KnowledgeBase.gxw'),
+            '<KnowledgeBase><VersionNumber>17.0.11.163677</KnowledgeBase>'
+        );
+        const identity = readGeneXusKbIdentity(tempRoot);
+        assert.equal(identity.major, null);
+        assert.equal(identity.source, 'unavailable');
+        assert.equal(identity.reason, 'malformed-gxw');
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('catalog discovery ordering can prefer the KB major', () => {
+    assert.equal(getGeneXusMajor('17.0.11.163677'), '17');
+    assert.equal(getGeneXusCatalogEntries('17')[0].major, '17');
+    assert.equal(getGeneXusCatalogEntries('18')[0].major, '18');
+});
+
+test('init rejects a known KB and SDK major mismatch before writing config', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-mismatch-'));
+    const kbDir = path.join(tempRoot, 'kb17');
+    const gxDir = path.join(tempRoot, 'GeneXus18');
+    fs.mkdirSync(kbDir, { recursive: true });
+    fs.mkdirSync(gxDir, { recursive: true });
+    fs.writeFileSync(
+        path.join(kbDir, 'KnowledgeBase.gxw'),
+        '<KnowledgeBase><VersionNumber>17.0.11.163677</VersionNumber></KnowledgeBase>'
+    );
+    fs.writeFileSync(path.join(gxDir, 'GeneXus.exe'), 'not-a-real-executable');
+
+    try {
+        const result = runCli(
+            ['init', '--kb', kbDir, '--gx', gxDir, '--no-smoke', '--no-write-clients', '--format', 'json'],
+            { env: testGatewayEnv }
+        );
+        assert.equal(result.status, 1);
+        const parsed = JSON.parse(result.stdout);
+        assert.equal(parsed.error.code, 'sdk_kb_mismatch');
+        assert.equal(fs.existsSync(path.join(kbDir, 'config.json')), false);
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('interactive init does not silently choose the primary SDK when KB metadata is unresolved', async () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-interactive-unresolved-'));
+    const kbDir = path.join(tempRoot, 'kb');
+    const gxDir = path.join(tempRoot, 'GeneXus18');
+    fs.mkdirSync(kbDir, { recursive: true });
+    fs.mkdirSync(gxDir, { recursive: true });
+    fs.writeFileSync(path.join(kbDir, 'KnowledgeBase.gxw'), '');
+    fs.writeFileSync(path.join(kbDir, 'knowledgebase.connection'), 'connection');
+    fs.writeFileSync(path.join(gxDir, 'GeneXus.exe'), 'not-a-real-executable');
+
+    const previousGeneXusHome = process.env.GENEXUS_HOME;
+    process.env.GENEXUS_HOME = gxDir;
+    const input = new Readable({ read() { } });
+    setTimeout(() => input.push('\n'), 0);
+    setTimeout(() => input.push('\n'), 25);
+    setTimeout(() => input.push(null), 100);
+    try {
+        const result = await handleInit(
+            { interactive: true, quiet: true },
+            {
+                cwd: kbDir,
+                input,
+                stderr: new Writable({ write(_chunk, _encoding, callback) { callback(); } }),
+                EXIT_CODES: { OK: 0, ERROR: 1, USAGE: 2 }
+            }
+        );
+        assert.equal(result.exitCode, 1);
+        assert.equal(result.envelope.error.code, 'sdk_selection_required');
+        assert.equal(fs.existsSync(path.join(kbDir, 'config.json')), false);
+    } finally {
+        if (previousGeneXusHome === undefined) delete process.env.GENEXUS_HOME;
+        else process.env.GENEXUS_HOME = previousGeneXusHome;
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
 test('init fails clearly when paths cannot be auto-discovered', () => {
     const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
 
@@ -622,6 +783,75 @@ test('doctor --mcp-smoke adds explicit mcp_smoke check', () => {
     assert.ok(['pass', 'warn', 'fail'].includes(smoke.status));
 });
 
+test('doctor reports a KB and SDK major mismatch', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-doctor-major-'));
+    const kbDir = path.join(tempRoot, 'kb17');
+    const gxDir = path.join(tempRoot, 'GeneXus18');
+    fs.mkdirSync(kbDir, { recursive: true });
+    fs.mkdirSync(gxDir, { recursive: true });
+    fs.writeFileSync(path.join(kbDir, 'KnowledgeBase.gxw'), '<KnowledgeBase><VersionNumber>17.0.11.163677</VersionNumber></KnowledgeBase>');
+    fs.writeFileSync(path.join(gxDir, 'GeneXus.exe'), 'not-a-real-executable');
+    const configPath = path.join(tempRoot, 'config.json');
+    fs.writeFileSync(configPath, JSON.stringify({
+        GeneXus: { InstallationPath: gxDir },
+        Environment: { KBPath: kbDir }
+    }));
+
+    try {
+        const compatibility = compareGeneXusKbAndInstallation(kbDir, gxDir);
+        assert.equal(compatibility.status, 'mismatch');
+        const result = runCli(['doctor', '--format', 'json'], {
+            env: {
+                GX_CONFIG_PATH: configPath,
+                GENEXUS_MCP_GATEWAY_EXE: process.execPath,
+                LOCALAPPDATA: tempRoot
+            }
+        });
+        assert.equal(result.status, 0);
+        const parsed = JSON.parse(result.stdout);
+        const check = parsed.ok.checks.find((row) => row.id === 'kb_sdk_compatibility');
+        assert.ok(check);
+        assert.equal(check.status, 'fail');
+        assert.match(check.detail, /KB major 17.*SDK major 18/);
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
+test('doctor rejects a KB and SDK major that is outside the compatibility catalog', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-doctor-unsupported-major-'));
+    const kbDir = path.join(tempRoot, 'kb19');
+    const gxDir = path.join(tempRoot, 'GeneXus19');
+    fs.mkdirSync(kbDir, { recursive: true });
+    fs.mkdirSync(gxDir, { recursive: true });
+    fs.writeFileSync(path.join(kbDir, 'KnowledgeBase.gxw'), '<KnowledgeBase><VersionNumber>19.0.0.0</VersionNumber></KnowledgeBase>');
+    fs.writeFileSync(path.join(gxDir, 'GeneXus.exe'), 'not-a-real-executable');
+    const configPath = path.join(tempRoot, 'config.json');
+    fs.writeFileSync(configPath, JSON.stringify({
+        GeneXus: { InstallationPath: gxDir },
+        Environment: { KBPath: kbDir }
+    }));
+
+    try {
+        const result = runCli(['doctor', '--format', 'json'], {
+            env: {
+                GX_CONFIG_PATH: configPath,
+                GENEXUS_MCP_GATEWAY_EXE: process.execPath,
+                LOCALAPPDATA: tempRoot
+            }
+        });
+        assert.equal(result.status, 0);
+        const parsed = JSON.parse(result.stdout);
+        const check = parsed.ok.checks.find((row) => row.id === 'kb_sdk_compatibility');
+        assert.ok(check);
+        assert.equal(check.status, 'fail');
+        assert.match(check.detail, /KB major 19 is not supported/);
+        assert.match(check.detail, /Supported majors: 17, 18/);
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+});
+
 test('invalid format returns usage exit code 2', () => {
     const result = runCli(['status', '--format', 'yaml']);
     assert.equal(result.status, 2);

package/config/gx-versions.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "genexus-mcp/version-catalog/1",
+  "primaryMajor": "18",
+  "supportedMajors": [
+    {
+      "major": "17",
+      "displayName": "GeneXus 17",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus17Trial",
+      "registryNames": ["GeneXus 17", "GeneXus 17 Trial"],
+      "legacyRegistryVersions": ["17.0"]
+    },
+    {
+      "major": "18",
+      "displayName": "GeneXus 18",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18",
+      "registryNames": ["GeneXus 18"],
+      "legacyRegistryVersions": ["18.0"]
+    }
+  ]
+}

package/docs/llm_cli_mcp_playbook.md

@@ -20,6 +20,13 @@ Use MCP when:
 - You need long-running operation tracking (`genexus_lifecycle` + `op:<operationId>`).
 - You are inside an MCP-native client loop.
 
+## Official Nexa grounding
+
+Before modeling objects, changing properties, or using Object Text workflows,
+read `genexus://kb/skills/nexa` and then the narrow reference selected from
+`genexus://kb/skills/nexa/references/{name}`. Treat Nexa as design guidance and
+confirm the final object state and supported behavior with the live KB tools.
+
 ## AXI CLI Contract (LLM-facing)
 
 Entry points:

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "genexus-mcp",
-  "version": "3.0.4",
+  "version": "3.2.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.",
+  "description": "GeneXus 17, GeneXus 18 MCP server — read, edit, and analyze Knowledge Base objects directly from Claude, Cursor, and other AI agents over the Model Context Protocol.",
   "keywords": [
     "mcp",
     "mcp-server",
     "model-context-protocol",
     "genexus",
+    "genexus-17",
+    "genexus17",
     "genexus-18",
     "genexus18",
     "claude",
@@ -41,6 +43,7 @@
   },
   "files": [
     "cli",
+    "config/gx-versions.json",
     "publish",
     "docs/llm_cli_mcp_playbook.md",
     "scripts/verify-install.js",

package/publish/GxMcp.Gateway.deps.json

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

package/publish/config/gx-versions.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "genexus-mcp/version-catalog/1",
+  "primaryMajor": "18",
+  "supportedMajors": [
+    {
+      "major": "17",
+      "displayName": "GeneXus 17",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus17Trial",
+      "registryNames": ["GeneXus 17", "GeneXus 17 Trial"],
+      "legacyRegistryVersions": ["17.0"]
+    },
+    {
+      "major": "18",
+      "displayName": "GeneXus 18",
+      "defaultInstallPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18",
+      "registryNames": ["GeneXus 18"],
+      "legacyRegistryVersions": ["18.0"]
+    }
+  ]
+}

package/publish/config.json

@@ -1,11 +1,11 @@
 {
   "GeneXus": {
-    "InstallationPath": "C:\\\\Program Files (x86)\\\\GeneXus\\\\GeneXus18",
+    "InstallationPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18",
     "WorkerExecutable": "worker\\\\GxMcp.Worker.exe"
   },
   "Server": {
-    "HttpPort": 5000,
-    "McpStdio": true
+    "McpStdio": true,
+    "HttpPort": 5000
   },
   "Logging": {
     "Level": "Debug",

package/publish/gxmcp-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": "gxmcp-release-manifest/1",
-  "version": "3.0.4",
-  "sourceCommit": "158935499b117726db1688bf29217a4b3f508bad",
+  "version": "3.2.0",
+  "sourceCommit": "d0ed6ff43d48cc5d62ba7e09f36f28477d161710",
   "sourceCommitPolicy": "exact-tag",
-  "generatedAtUtc": "2026-09-08T18:47:30.9019243Z",
+  "generatedAtUtc": "2026-09-09T16:51:27.9077164Z",
   "runtime": {
     "gateway": "net10.0-windows",
     "worker": "net48-x86",
@@ -15,33 +15,33 @@
     "2026-07-28"
   ],
   "schema": "tool_definitions.json",
-  "schemaSha256": "df37664020c005ee75c7fa9b43b1546d90cc92f2ea8a42c236b4ccb999c32afd",
+  "schemaSha256": "e4a3043ade9e565599dabed109ade92db73360c02bc5ee0d28f21eec25d89d68",
   "provenance": "gxmcp-sbom.json",
   "artifacts": [
     {
       "path": "gxmcp-sbom.json",
       "size": 590,
-      "sha256": "9b0b60c9e1cab98d49e83ac9282cf10fb1caf0a6e59bcb4fdd7bc92597c6bbce"
+      "sha256": "02cdc88c7dff83608a1f157be94f45b914a6b7d319bd701d4ce54a4d621a6e71"
     },
     {
       "path": "GxMcp.Gateway.exe",
       "size": 162304,
-      "sha256": "15dd3003740a645a902af39c0f37a51c6bffb54ff4edf7f04a41473923cda952"
+      "sha256": "f15a4622bc1b0b552a480964e32b1defee7fa240d1ded2bb27852dd44a645977"
     },
     {
       "path": "nexus-ide.vsix",
       "size": 1318667,
-      "sha256": "521d63c951e129104a72138913fe3008305648d272fc66d9fb2a159b8a6c15f6"
+      "sha256": "e665685cd085a7d5af4c23e7704371167a02ba0ae6a2ed74a5d6681be016e44e"
     },
     {
       "path": "tool_definitions.json",
-      "size": 105044,
-      "sha256": "df37664020c005ee75c7fa9b43b1546d90cc92f2ea8a42c236b4ccb999c32afd"
+      "size": 106423,
+      "sha256": "e4a3043ade9e565599dabed109ade92db73360c02bc5ee0d28f21eec25d89d68"
     },
     {
       "path": "worker/GxMcp.Worker.exe",
-      "size": 2859520,
-      "sha256": "9050b618d876dcafd24996c4da3a59e59cfca21564ff00397e8811636e327a7a"
+      "size": 2926080,
+      "sha256": "903e41245f740f88a6d3e6f8ada00bd82a18b6ea07259ebb7dd9dbe90b1a550e"
     }
   ]
 }

package/publish/gxmcp-sbom.json

@@ -1,20 +1,20 @@
 {
   "schemaVersion": "gxmcp-provenance/1",
-  "version": "3.0.4",
-  "sourceCommit": "158935499b117726db1688bf29217a4b3f508bad",
+  "version": "3.2.0",
+  "sourceCommit": "d0ed6ff43d48cc5d62ba7e09f36f28477d161710",
   "sourceCommitPolicy": "exact-tag",
   "components": [
     {
       "name": "genexus-mcp",
       "lockfile": "package-lock.json",
       "size": 39914,
-      "sha256": "e95fb66231b2e8185448750b16795432a9d49c3e96d85edf457a3e58c91ad49e"
+      "sha256": "4ddd59d46b934fafe177482aa8d769b0cd041a7f0205cd6cc52d6fe3a825de88"
     },
     {
       "name": "nexus-ide",
       "lockfile": "src/nexus-ide/package-lock.json",
       "size": 274983,
-      "sha256": "577c995d86ffca4a3c809423250a870b9266fc4d59ee05ef64e4c12aa5590d81"
+      "sha256": "000a3e5e18fe604470bb99fe853acecfbf92712b98d74c7e6f379e0593ded562"
     }
   ]
 }