genexus-mcp 2.0.4 → 2.1.0

package/cli/lib/config.js

@@ -21,6 +21,42 @@ function getToolDefinitionsPath() {
     return path.join(__dirname, '..', '..', 'src', 'GxMcp.Gateway', 'tool_definitions.json');
 }
 
+function discoverGeneXusFromRegistry() {
+    if (process.platform !== 'win32') return null;
+    try {
+        const { execFileSync } = require('child_process');
+        const versions = ['GeneXus 18', 'GeneXus 17', 'GeneXus 16'];
+        const hives = [
+            'HKLM\\SOFTWARE\\WOW6432Node\\Artech',
+            'HKLM\\SOFTWARE\\Artech',
+            'HKCU\\SOFTWARE\\Artech'
+        ];
+        for (const hive of hives) {
+            for (const ver of versions) {
+                const key = `${hive}\\${ver}`;
+                try {
+                    const out = execFileSync('reg.exe', ['query', key, '/v', 'InstallationDirectory'], {
+                        encoding: 'utf8',
+                        stdio: ['ignore', 'pipe', 'ignore'],
+                        windowsHide: true,
+                        timeout: 3000
+                    });
+                    const match = out.match(/InstallationDirectory\s+REG_SZ\s+(.+?)\r?\n/i);
+                    if (match) {
+                        const candidate = match[1].trim().replace(/[\\/]+$/, '');
+                        if (candidate && fs.existsSync(path.join(candidate, 'genexus.exe'))) {
+                            return candidate;
+                        }
+                    }
+                } catch {
+                }
+            }
+        }
+    } catch {
+    }
+    return null;
+}
+
 function discoverGeneXusInstallation() {
     const possible = [
         'C:\\Program Files (x86)\\GeneXus\\GeneXus18',
@@ -36,6 +72,15 @@ function discoverGeneXusInstallation() {
         }
     }
 
+    const fromRegistry = discoverGeneXusFromRegistry();
+    if (fromRegistry) return fromRegistry;
+
+    return null;
+}
+
+function discoverKnowledgeBase(cwd) {
+    if (!cwd) return null;
+    if (directoryLooksLikeKnowledgeBase(cwd)) return cwd;
     return null;
 }
 
@@ -71,20 +116,24 @@ function resolveConfigPathNoMutate(cwd) {
 
 function createConfigFile(kbPath, gxPath) {
     const targetConfigPath = path.join(kbPath, 'config.json');
-    const nextConfig = generateConfig(gxPath, kbPath);
+    const baseConfig = generateConfig(gxPath, kbPath);
 
     if (!fs.existsSync(kbPath)) {
         fs.mkdirSync(kbPath, { recursive: true });
     }
 
-    let changed = true;
-    if (fs.existsSync(targetConfigPath)) {
-        const current = readJsonFileSafe(targetConfigPath);
-        if (current && JSON.stringify(current) === JSON.stringify(nextConfig)) {
-            changed = false;
-        }
+    const existing = fs.existsSync(targetConfigPath) ? readJsonFileSafe(targetConfigPath) : null;
+    const preservedEnv = {};
+    if (existing && existing.Environment) {
+        if (existing.Environment.KBs) preservedEnv.KBs = existing.Environment.KBs;
+        if (existing.Environment.ActiveKb) preservedEnv.ActiveKb = existing.Environment.ActiveKb;
     }
+    const nextConfig = {
+        ...baseConfig,
+        Environment: { ...baseConfig.Environment, ...preservedEnv }
+    };
 
+    const changed = !existing || JSON.stringify(existing) !== JSON.stringify(nextConfig);
     if (changed) {
         fs.writeFileSync(targetConfigPath, JSON.stringify(nextConfig, null, 2));
     }
@@ -97,17 +146,7 @@ function createConfigFile(kbPath, gxPath) {
 }
 
 function patchClientConfig(targetConfigPath) {
-    const claudeWin = path.join(os.homedir(), 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
-    const claudeMac = path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
-    const antigravityCfg = path.join(os.homedir(), '.gemini', 'antigravity', 'mcp_config.json');
-    const claudeCodeCfg = path.join(os.homedir(), '.claude.json');
-
-    const clients = [
-        { path: claudeWin, name: 'Claude Desktop (Windows)' },
-        { path: claudeMac, name: 'Claude Desktop (macOS)' },
-        { path: antigravityCfg, name: 'Antigravity' },
-        { path: claudeCodeCfg, name: 'Claude Code' }
-    ];
+    const clients = getClientConfigTargets();
 
     const patched = [];
     const failed = [];
@@ -140,6 +179,158 @@ function patchClientConfig(targetConfigPath) {
     return { patched, failed };
 }
 
+function getClientConfigTargets() {
+    return [
+        { path: path.join(os.homedir(), 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json'), name: 'Claude Desktop (Windows)' },
+        { path: path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'), name: 'Claude Desktop (macOS)' },
+        { path: path.join(os.homedir(), '.gemini', 'antigravity', 'mcp_config.json'), name: 'Antigravity' },
+        { path: path.join(os.homedir(), '.claude.json'), name: 'Claude Code' }
+    ];
+}
+
+function unpatchClientConfig() {
+    const clients = getClientConfigTargets();
+    const removed = [];
+    const skipped = [];
+    const failed = [];
+
+    for (const client of clients) {
+        if (!fs.existsSync(client.path)) continue;
+
+        try {
+            const parsed = readJsonFileSafe(client.path);
+            if (parsed === null) {
+                failed.push({ client: client.name, reason: 'Invalid JSON' });
+                continue;
+            }
+
+            const cfgObj = parsed || {};
+            if (!cfgObj.mcpServers || !cfgObj.mcpServers.genexus) {
+                skipped.push({ client: client.name, reason: 'no genexus entry' });
+                continue;
+            }
+
+            delete cfgObj.mcpServers.genexus;
+            fs.writeFileSync(client.path, JSON.stringify(cfgObj, null, 2));
+            removed.push(client.name);
+        } catch (err) {
+            failed.push({ client: client.name, reason: err && err.message ? err.message : 'Unknown error' });
+        }
+    }
+
+    return { removed, skipped, failed };
+}
+
+function getLocalAppDataCacheDir() {
+    if (process.platform !== 'win32') return null;
+    const base = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(base, 'GenexusMCP');
+}
+
+function readGeneXusVersionFromInstall(gxPath) {
+    if (!gxPath) return null;
+    const candidates = [
+        path.join(gxPath, 'version.txt'),
+        path.join(gxPath, 'Version.txt'),
+        path.join(gxPath, 'GeneXus.version')
+    ];
+    for (const candidate of candidates) {
+        try {
+            const raw = fs.readFileSync(candidate, 'utf8').trim();
+            if (raw) return raw.split(/\r?\n/)[0].trim();
+        } catch {
+        }
+    }
+    return null;
+}
+
+function readKbCatalog(configPath) {
+    if (!configPath) return { kbs: {}, activeKb: null, kbPath: null };
+    const cfg = readJsonFileSafe(configPath);
+    if (!cfg) return { kbs: {}, activeKb: null, kbPath: null };
+    const env = cfg.Environment || {};
+    return {
+        kbs: (env.KBs && typeof env.KBs === 'object') ? env.KBs : {},
+        activeKb: typeof env.ActiveKb === 'string' ? env.ActiveKb : null,
+        kbPath: typeof env.KBPath === 'string' ? env.KBPath : null
+    };
+}
+
+function writeKbCatalog(configPath, { kbs, activeKb, kbPath }) {
+    const cfg = readJsonFileSafe(configPath) || {};
+    cfg.Environment = cfg.Environment || {};
+    cfg.Environment.KBs = kbs;
+    if (activeKb) cfg.Environment.ActiveKb = activeKb;
+    else delete cfg.Environment.ActiveKb;
+    if (kbPath) cfg.Environment.KBPath = kbPath;
+    else delete cfg.Environment.KBPath;
+    fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2));
+}
+
+function addKbToConfig(configPath, name, kbPath) {
+    const catalog = readKbCatalog(configPath);
+    const alreadyRegistered = catalog.kbs[name] === kbPath;
+    const willBecomeActive = !catalog.activeKb;
+    if (alreadyRegistered && !willBecomeActive) {
+        return catalog;
+    }
+    catalog.kbs[name] = kbPath;
+    if (willBecomeActive) {
+        catalog.activeKb = name;
+        catalog.kbPath = kbPath;
+    }
+    writeKbCatalog(configPath, catalog);
+    return catalog;
+}
+
+function removeKbFromConfig(configPath, name) {
+    const catalog = readKbCatalog(configPath);
+    if (!(name in catalog.kbs)) return { catalog, removed: false };
+    delete catalog.kbs[name];
+    if (catalog.activeKb === name) {
+        const remainingNames = Object.keys(catalog.kbs);
+        catalog.activeKb = remainingNames[0] || null;
+        catalog.kbPath = catalog.activeKb ? catalog.kbs[catalog.activeKb] : null;
+    }
+    writeKbCatalog(configPath, catalog);
+    return { catalog, removed: true };
+}
+
+function switchActiveKb(configPath, { name, path: explicitPath }) {
+    const catalog = readKbCatalog(configPath);
+
+    let targetName = name;
+    let targetPath = explicitPath;
+
+    if (explicitPath && !name) {
+        const existing = Object.entries(catalog.kbs).find(([, p]) => p === explicitPath);
+        if (existing) {
+            targetName = existing[0];
+        } else {
+            targetName = path.basename(explicitPath);
+            if (catalog.kbs[targetName] && catalog.kbs[targetName] !== explicitPath) {
+                return {
+                    ok: false,
+                    reason: `Name '${targetName}' is already registered to a different path (${catalog.kbs[targetName]}). Pass --name explicitly to disambiguate.`
+                };
+            }
+            catalog.kbs[targetName] = explicitPath;
+        }
+    } else if (name) {
+        if (!(name in catalog.kbs)) {
+            return { ok: false, reason: `KB '${name}' is not registered. Use \`genexus-mcp kb add\` first or pass --path.` };
+        }
+        targetPath = catalog.kbs[name];
+    } else {
+        return { ok: false, reason: 'Either --name or --path is required.' };
+    }
+
+    catalog.activeKb = targetName;
+    catalog.kbPath = targetPath;
+    writeKbCatalog(configPath, catalog);
+    return { ok: true, catalog, switchedTo: { name: targetName, path: targetPath } };
+}
+
 function applyLauncherConfigOrExit({ cwd, stderr, quiet }) {
     const log = (msg) => {
         if (!quiet) stderr.write(`${msg}\n`);
@@ -185,10 +376,20 @@ module.exports = {
     getGatewayExePath,
     getToolDefinitionsPath,
     discoverGeneXusInstallation,
+    discoverGeneXusFromRegistry,
+    discoverKnowledgeBase,
     directoryLooksLikeKnowledgeBase,
     readJsonFileSafe,
     resolveConfigPathNoMutate,
     createConfigFile,
     patchClientConfig,
+    unpatchClientConfig,
+    getClientConfigTargets,
+    getLocalAppDataCacheDir,
+    readGeneXusVersionFromInstall,
+    readKbCatalog,
+    addKbToConfig,
+    removeKbFromConfig,
+    switchActiveKb,
     applyLauncherConfigOrExit
 };

package/cli/run.test.js

@@ -135,6 +135,7 @@ test('non-interactive init supports idempotent no-op', () => {
         kbDir,
         '--gx',
         'C:\\Program Files (x86)\\GeneXus\\GeneXus18',
+        '--no-smoke',
         '--format',
         'json'
     ];
@@ -143,6 +144,10 @@ test('non-interactive init supports idempotent no-op', () => {
     assert.equal(first.status, 0);
     const firstParsed = JSON.parse(first.stdout);
     assert.equal(firstParsed.ok.noOp, false);
+    assert.ok(firstParsed.ok.verification, 'init should include verification block');
+    assert.ok(firstParsed.ok.verification.summary, 'verification should have summary');
+    assert.ok(Array.isArray(firstParsed.ok.verification.checks), 'verification should have checks array');
+    assert.equal(firstParsed.meta.smokeSkipped, true, '--no-smoke should be reflected in meta');
 
     const second = runCli(args);
     assert.equal(second.status, 0);
@@ -155,6 +160,257 @@ test('non-interactive init supports idempotent no-op', () => {
     fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
+test('whoami without config returns disconnected state', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const res = runCli(['whoami', '--format', 'json'], { cwd: tempRoot });
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.ok.connected, false);
+    assert.ok(parsed.ok.reason, 'should explain why not connected');
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('whoami with config returns kb and geneXus details', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbDir = path.join(tempRoot, 'kb-w');
+    fs.mkdirSync(kbDir, { recursive: true });
+
+    runCli(['init', '--kb', kbDir, '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json']);
+
+    const res = runCli(['whoami', '--format', 'json'], { cwd: kbDir });
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.ok.connected, true);
+    assert.equal(parsed.ok.kb.path, kbDir);
+    assert.equal(parsed.ok.kb.name, path.basename(kbDir));
+    assert.equal(parsed.ok.geneXus.installationPath, 'C:\\Program Files (x86)\\GeneXus\\GeneXus18');
+    assert.equal(parsed.meta.command, 'whoami');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('uninstall --yes removes local config and reports plan', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbDir = path.join(tempRoot, 'kb-u');
+    fs.mkdirSync(kbDir, { recursive: true });
+
+    runCli(['init', '--kb', kbDir, '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json']);
+
+    const cfgPath = path.join(kbDir, 'config.json');
+    assert.equal(fs.existsSync(cfgPath), true, 'precondition: config.json exists');
+
+    const res = runCli(['uninstall', '--yes', '--format', 'json'], { cwd: kbDir });
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.ok.action, 'uninstall');
+    assert.equal(parsed.ok.cancelled, false);
+    assert.equal(parsed.ok.configRemoved, true);
+    assert.equal(fs.existsSync(cfgPath), false, 'config.json should be deleted');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('uninstall --help returns usage entry', () => {
+    const res = runCli(['uninstall', '--help', '--format', 'json']);
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.ok.command, 'uninstall');
+    assert.ok(parsed.ok.usage.includes('--yes'), 'usage should mention --yes flag');
+});
+
+test('whoami --help returns usage entry', () => {
+    const res = runCli(['whoami', '--help', '--format', 'json']);
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.ok.command, 'whoami');
+});
+
+test('init auto-discovers KB from cwd when --kb is omitted', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbDir = path.join(tempRoot, 'kb-disco');
+    fs.mkdirSync(kbDir, { recursive: true });
+    fs.writeFileSync(path.join(kbDir, 'KnowledgeBase.Connection'), '');
+
+    const res = runCli(
+        ['init', '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json'],
+        { cwd: kbDir }
+    );
+
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.ok.resolved.kb.path, kbDir);
+    assert.equal(parsed.ok.resolved.kb.source, 'cwd');
+    assert.equal(parsed.ok.resolved.gx.source, 'flag');
+
+    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-'));
+
+    const res = runCli(
+        ['init', '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json'],
+        { cwd: tempRoot }
+    );
+
+    assert.equal(res.status, 2);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.error.code, 'usage_error');
+    assert.ok(parsed.error.message.includes('--kb'), 'error should mention --kb');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('kb list shows the KB auto-registered by init', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbDir = path.join(tempRoot, 'kb-list');
+    fs.mkdirSync(kbDir, { recursive: true });
+
+    runCli(['init', '--kb', kbDir, '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json']);
+
+    const res = runCli(['kb', 'list', '--format', 'json'], { cwd: kbDir });
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.meta.command, 'kb.list');
+    assert.equal(parsed.ok.activeKb, path.basename(kbDir));
+    assert.equal(parsed.ok.kbs.length, 1);
+    assert.equal(parsed.ok.kbs[0].active, true);
+    assert.equal(parsed.ok.kbs[0].path, kbDir);
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('kb add and switch update active KB', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbA = path.join(tempRoot, 'kb-a');
+    const kbB = path.join(tempRoot, 'kb-b');
+    fs.mkdirSync(kbA, { recursive: true });
+    fs.mkdirSync(kbB, { recursive: true });
+
+    runCli(['init', '--kb', kbA, '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json']);
+
+    const addRes = runCli(['kb', 'add', '--name', 'bravo', '--kb', kbB, '--format', 'json'], { cwd: kbA });
+    assert.equal(addRes.status, 0);
+    const addParsed = JSON.parse(addRes.stdout);
+    assert.equal(addParsed.ok.registeredCount, 2);
+    assert.equal(addParsed.ok.activeKb, path.basename(kbA), 'active KB should remain the first one');
+
+    const switchRes = runCli(['kb', 'switch', '--name', 'bravo', '--format', 'json'], { cwd: kbA });
+    assert.equal(switchRes.status, 0);
+    const switchParsed = JSON.parse(switchRes.stdout);
+    assert.equal(switchParsed.ok.activeKb, 'bravo');
+    assert.equal(switchParsed.ok.kbPath, kbB);
+
+    const cfg = JSON.parse(fs.readFileSync(path.join(kbA, 'config.json'), 'utf8'));
+    assert.equal(cfg.Environment.KBPath, kbB, 'legacy KBPath should be updated');
+    assert.equal(cfg.Environment.ActiveKb, 'bravo');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('kb switch rejects unknown name', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbDir = path.join(tempRoot, 'kb-x');
+    fs.mkdirSync(kbDir, { recursive: true });
+
+    runCli(['init', '--kb', kbDir, '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json']);
+
+    const res = runCli(['kb', 'switch', '--name', 'nonexistent', '--format', 'json'], { cwd: kbDir });
+    assert.equal(res.status, 2);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.error.code, 'usage_error');
+    assert.ok(parsed.error.message.includes('nonexistent'));
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('kb remove deletes entry and reassigns active when applicable', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbA = path.join(tempRoot, 'kb-r-a');
+    const kbB = path.join(tempRoot, 'kb-r-b');
+    fs.mkdirSync(kbA, { recursive: true });
+    fs.mkdirSync(kbB, { recursive: true });
+
+    runCli(['init', '--kb', kbA, '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json']);
+    runCli(['kb', 'add', '--name', 'second', '--kb', kbB, '--format', 'json'], { cwd: kbA });
+
+    const removeRes = runCli(['kb', 'remove', '--name', path.basename(kbA), '--format', 'json'], { cwd: kbA });
+    assert.equal(removeRes.status, 0);
+    const parsed = JSON.parse(removeRes.stdout);
+    assert.equal(parsed.ok.removed, true);
+    assert.equal(parsed.ok.activeKb, 'second', 'active should fall back to remaining KB');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('kb switch --kb refuses to overwrite existing entry with different path', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbA = path.join(tempRoot, 'a', 'Sales');
+    const kbB = path.join(tempRoot, 'b', 'Sales');
+    fs.mkdirSync(kbA, { recursive: true });
+    fs.mkdirSync(kbB, { recursive: true });
+
+    runCli(['init', '--kb', kbA, '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json']);
+
+    const res = runCli(['kb', 'switch', '--kb', kbB, '--format', 'json'], { cwd: kbA });
+    assert.equal(res.status, 2);
+    const parsed = JSON.parse(res.stdout);
+    assert.ok(/already registered/i.test(parsed.error.message), 'should warn about basename collision');
+
+    const cfg = JSON.parse(fs.readFileSync(path.join(kbA, 'config.json'), 'utf8'));
+    assert.equal(cfg.Environment.KBs.Sales, kbA, 'original entry must be preserved');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('kb remove of last KB clears legacy KBPath', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbDir = path.join(tempRoot, 'kb-last');
+    fs.mkdirSync(kbDir, { recursive: true });
+
+    runCli(['init', '--kb', kbDir, '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json']);
+
+    runCli(['kb', 'remove', '--name', path.basename(kbDir), '--format', 'json'], { cwd: kbDir });
+
+    const cfg = JSON.parse(fs.readFileSync(path.join(kbDir, 'config.json'), 'utf8'));
+    assert.equal(cfg.Environment.KBPath, undefined, 'KBPath should be cleared after removing last KB');
+    assert.equal(cfg.Environment.ActiveKb, undefined, 'ActiveKb should be cleared');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('kb subcommand validation: missing subcommand returns usage error', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbDir = path.join(tempRoot, 'kb-v');
+    fs.mkdirSync(kbDir, { recursive: true });
+
+    runCli(['init', '--kb', kbDir, '--gx', 'C:\\Program Files (x86)\\GeneXus\\GeneXus18', '--no-smoke', '--format', 'json']);
+
+    const res = runCli(['kb', '--format', 'json'], { cwd: kbDir });
+    assert.equal(res.status, 2);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.error.code, 'usage_error');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('tool_definitions.json is valid and disambiguation tools have use-when guidance', () => {
+    const defsPath = path.join(__dirname, '..', 'src', 'GxMcp.Gateway', 'tool_definitions.json');
+    const defs = JSON.parse(fs.readFileSync(defsPath, 'utf8'));
+    assert.ok(Array.isArray(defs) && defs.length > 0, 'tool defs should be a non-empty array');
+
+    const byName = Object.fromEntries(defs.map((t) => [t.name, t]));
+    const disambiguationTools = ['genexus_inspect', 'genexus_analyze', 'genexus_summarize', 'genexus_doc'];
+    for (const name of disambiguationTools) {
+        assert.ok(byName[name], `${name} should exist`);
+        const desc = byName[name].description || '';
+        assert.ok(
+            /use when|don't use|use this|use to/i.test(desc),
+            `${name} description should include use-when/don't-use guidance`
+        );
+    }
+});
+
 test('tools list supports query and category aggregate', () => {
     const result = runCli([
         'tools',

package/package.json

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