genexus-mcp 2.8.2 → 2.8.3

package/README.md

@@ -175,13 +175,22 @@ Auto-detected and auto-configured by the installer:
 | Claude Desktop | ✅ | Restart required after install |
 | Claude Code (CLI) | ✅ | Reload session |
 | Cursor | ✅ | Restart required |
-| Antigravity | ✅ | Restart required |
+| Antigravity | ✅ | Restart required; detected even before its MCP config exists |
+| Gemini CLI | ✅ | — |
+| OpenCode (CLI) | ✅ | Reads `opencode.json` / `opencode.jsonc` |
+| Codex CLI | ✅ | Writes `~/.codex/config.toml` |
+| VS Code / VS Code Insiders | ✅ | Native MCP (`User/mcp.json`); restart required |
+| OpenCode Desktop | Detect-only | Reported as installed; add the server from the app's settings |
 | Any MCP client | Manual | Use the JSON snippet printed by `init` |
 
+Run **`npx genexus-mcp clients`** at any time to see which agents are installed, which have `genexus` registered, and whether any point at a stale gateway exe. To (re)register specific ones: `npx genexus-mcp clients add --clients antigravity,vscode`.
+
 ---
 
 ## Troubleshooting
 
+First stop for any "the agent doesn't see GeneXus" problem: **`npx genexus-mcp clients`** (is it registered? does it point at a gateway exe that still exists?) and **`npx genexus-mcp doctor --mcp-smoke`**.
+
 Most install issues fall into a handful of buckets — see **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** for fixes:
 
 - Installer can't find GeneXus or the KB
@@ -375,12 +384,17 @@ This repo ships a set of **agent skills** under `.gemini/skills/` that any MCP-c
 
 Third-party skills are Apache 2.0 (see [`.gemini/skills/NOTICE.md`](.gemini/skills/NOTICE.md)). To refresh against upstream, follow the steps in `NOTICE.md`.
 
-### Nexus-IDE (VS Code extension)
+### Nexus-IDE (VS Code extension — optional, not auto-installed)
+
+`src/nexus-ide` is a lightweight, experimental VS Code extension in the repo. The installer **no longer packages or installs it** — VS Code is wired up as a native MCP client instead (see [Supported AI clients](#supported-ai-clients)). If you want the extension, build and install it manually:
+
+```powershell
+cd src/nexus-ide; npm ci; npm run compile
+npx --yes @vscode/vsce package --out nexus-ide.vsix
+code --install-extension nexus-ide.vsix --force
+```
 
-`src/nexus-ide` is a lightweight VS Code extension that ships with the repo:
-- Virtual filesystem using the `genexus://` scheme
-- Dynamic KB explorer with multi-part editing (Source, Rules, Events, Variables)
-- Built-in MCP discovery commands (tools, resources, prompts)
+It provides a virtual filesystem (`genexus://` scheme), a KB explorer with multi-part editing, and MCP discovery commands.
 
 ### Automated release
 

package/cli/commands/axi.js

@@ -12,6 +12,8 @@ const {
     patchClientConfig,
     unpatchClientConfig,
     getClientConfigTargets,
+    detectClientInstalled,
+    clientsStatus,
     filterClientTargets,
     listSupportedClientIds,
     getLocalAppDataCacheDir,
@@ -701,6 +703,25 @@ async function handleDoctor(options, ctx) {
     const inProcessLoad = buildInProcessBuildAssemblyLoadCheck(gxPath);
     checks.push({ id: 'in_process_build_assembly_load', status: inProcessLoad.status, detail: inProcessLoad.detail });
 
+    // Client registration summary — one line answering "are my AI agents wired up?".
+    const clientRows = clientsStatus();
+    const installedRows = clientRows.filter((r) => r.installed);
+    const staleRows = clientRows.filter((r) => r.commandStale);
+    const installedUnregistered = installedRows.filter((r) => !r.registered && r.writeSupported);
+    let clientsStatusLevel = 'pass';
+    let clientsDetail;
+    if (staleRows.length > 0) {
+        clientsStatusLevel = 'warn';
+        clientsDetail = `${staleRows.map((r) => r.name).join(', ')} point at a missing gateway exe. Re-register: genexus-mcp clients add --clients ${staleRows.map((r) => r.id).join(',')}.`;
+    } else if (installedUnregistered.length > 0) {
+        clientsStatusLevel = 'warn';
+        clientsDetail = `${installedUnregistered.length} installed agent(s) not registered (${installedUnregistered.map((r) => r.name).join(', ')}). Run: genexus-mcp clients add --clients ${installedUnregistered.map((r) => r.id).join(',')}.`;
+    } else {
+        const reg = clientRows.filter((r) => r.registered).length;
+        clientsDetail = `${reg} agent(s) registered; ${installedRows.length} installed. Run \`genexus-mcp clients\` for the full table.`;
+    }
+    checks.push({ id: 'clients_registered', status: clientsStatusLevel, detail: clientsDetail });
+
     if (data.gatewayExeFound) {
         const probe = await probeGatewaySpawn();
         checks.push({ id: 'gateway_spawn_probe', status: probe.status, detail: probe.detail });
@@ -1191,10 +1212,16 @@ async function runInteractiveInit(ctx) {
         ctx.stderr.write('\n3) Select AI agents to register (y/N per agent; Enter accepts default):\n');
         const selectedIds = [];
         for (const target of platformTargets) {
-            const installed = fs.existsSync(target.path);
-            const defaultYes = installed;
-            const tag = installed ? 'detected' : 'not detected';
-            const prompt = `   - ${target.name} [${tag}] (${defaultYes ? 'Y/n' : 'y/N'}): `;
+            const detection = detectClientInstalled(target);
+            const defaultYes = detection.installed;
+            const tag = detection.installed ? 'detected' : 'not detected';
+            // When not detected, show where we looked so the user understands why
+            // (and can still type `y` to register a freshly-installed agent).
+            let hint = '';
+            if (!detection.installed && detection.markersChecked.length) {
+                hint = ` — looked in ${detection.markersChecked[0]}`;
+            }
+            const prompt = `   - ${target.name} [${tag}${hint}] (${defaultYes ? 'Y/n' : 'y/N'}): `;
             const ans = (await question(prompt)).trim().toLowerCase();
             const yes = ans === '' ? defaultYes : (ans === 'y' || ans === 'yes');
             if (yes) selectedIds.push(target.id);
@@ -1715,6 +1742,107 @@ async function handleUninstall(options, ctx) {
     };
 }
 
+async function handleClients(subcommand, options, ctx) {
+    const sub = subcommand || 'list';
+
+    if (sub === 'list') {
+        const rows = clientsStatus();
+        const installedCount = rows.filter((r) => r.installed).length;
+        const registeredCount = rows.filter((r) => r.registered).length;
+        const help = [];
+        const installedUnregistered = rows.filter((r) => r.installed && !r.registered && r.writeSupported);
+        if (installedUnregistered.length > 0) {
+            help.push(`Register installed-but-unregistered agents: genexus-mcp clients add --clients ${installedUnregistered.map((r) => r.id).join(',')}`);
+        }
+        const stale = rows.filter((r) => r.commandStale);
+        if (stale.length > 0) {
+            help.push(`These clients point at a missing gateway exe (will fail to connect) — re-register: genexus-mcp clients add --clients ${stale.map((r) => r.id).join(',')}`);
+        }
+        for (const r of rows) {
+            if (r.installed && !r.writeSupported && r.note) help.push(`${r.name}: ${r.note}`);
+        }
+        return {
+            exitCode: ctx.EXIT_CODES.OK,
+            envelope: {
+                ok: {
+                    clients: rows,
+                    summary: { total: rows.length, installed: installedCount, registered: registeredCount }
+                },
+                help
+            }
+        };
+    }
+
+    if (sub === 'add' || sub === 'remove') {
+        const ids = resolveClientIds(options);
+        if (sub === 'add' && (!ids || ids.length === 0)) {
+            return {
+                exitCode: ctx.EXIT_CODES.USAGE,
+                envelope: usageEnvelope('`clients add` requires --clients <csv> (e.g. --clients antigravity,vscode).', ctx.EXIT_CODES.USAGE)
+            };
+        }
+        const validation = validateClientIds(ids);
+        if (!validation.ok) {
+            return { exitCode: ctx.EXIT_CODES.USAGE, envelope: usageEnvelope(validation.message, ctx.EXIT_CODES.USAGE) };
+        }
+
+        if (sub === 'add') {
+            const configPath = resolveConfigPathNoMutate(ctx.cwd);
+            if (!configPath) {
+                return {
+                    exitCode: ctx.EXIT_CODES.ERROR,
+                    envelope: operationalErrorEnvelope(
+                        'No config.json found to point the clients at. Run `genexus-mcp init` first (or run from a KB folder).',
+                        ctx.EXIT_CODES.ERROR
+                    )
+                };
+            }
+            let patch;
+            try {
+                // Explicit add: write even if install markers are absent (the user asked for it).
+                patch = patchClientConfig(configPath, { ids, onlyExisting: false });
+            } catch (err) {
+                return {
+                    exitCode: ctx.EXIT_CODES.ERROR,
+                    envelope: operationalErrorEnvelope(
+                        sanitizeOperationalMessage(`Client registration failed: ${err && err.message ? err.message : 'unknown error'}`),
+                        ctx.EXIT_CODES.ERROR
+                    )
+                };
+            }
+            const help = [];
+            if (patch.patched.length > 0) help.push('Restart the affected AI client(s) to load the new MCP config.');
+            if (patch.failed.length > 0) help.push('Some clients failed (see meta.failedClients).');
+            return {
+                exitCode: ctx.EXIT_CODES.OK,
+                envelope: {
+                    ok: { action: 'clients.add', configPath, patchedClients: patch.patched, patchedCount: patch.patched.length },
+                    help,
+                    meta: { failedClients: patch.failed, skippedClients: patch.skipped }
+                }
+            };
+        }
+
+        // remove
+        const unpatch = unpatchClientConfig(ids ? { ids } : {});
+        const help = [];
+        if (unpatch.removed.length > 0) help.push('Restart the affected AI client(s) to drop the stale MCP connection.');
+        return {
+            exitCode: ctx.EXIT_CODES.OK,
+            envelope: {
+                ok: { action: 'clients.remove', removedClients: unpatch.removed, removedCount: unpatch.removed.length },
+                help,
+                meta: { skippedClients: unpatch.skipped, failedClients: unpatch.failed }
+            }
+        };
+    }
+
+    return {
+        exitCode: ctx.EXIT_CODES.USAGE,
+        envelope: usageEnvelope('clients supports subcommands `list`, `add`, `remove`.', ctx.EXIT_CODES.USAGE)
+    };
+}
+
 async function handleKb(subcommand, options, ctx) {
     const data = buildStatusData(ctx.cwd);
     if (!data.configPath) {
@@ -1900,6 +2028,15 @@ function commandHelpMap() {
                 'genexus-mcp kb remove --name sales'
             ]
         },
+        clients: {
+            usage: 'genexus-mcp clients [list] [--format ...] OR genexus-mcp clients add --clients <csv> OR genexus-mcp clients remove [--clients <csv>]',
+            examples: [
+                'genexus-mcp clients              # show every AI agent: installed? registered? where?',
+                'genexus-mcp clients --format json',
+                'genexus-mcp clients add --clients antigravity,vscode',
+                'genexus-mcp clients remove --clients cursor'
+            ]
+        },
         llm: {
             usage: 'genexus-mcp llm help [--full] [--fields f1,f2] [--format toon|json|text]',
             examples: ['genexus-mcp llm help --format json', 'genexus-mcp llm help --full --format json']
@@ -1935,8 +2072,8 @@ async function handleHome(_options, ctx) {
                 description: 'GeneXus MCP launcher and AXI-oriented utility CLI',
                 ready: data.ready,
                 next: data.ready
-                    ? ['genexus-mcp status', 'genexus-mcp doctor --mcp-smoke', 'genexus-mcp tools list --limit 10', 'genexus-mcp layout status', 'genexus-mcp layout inspect --tab Layout']
-                    : ['genexus-mcp status', 'genexus-mcp doctor --full', 'genexus-mcp init --kb "<kbPath>" --gx "<geneXusPath>"']
+                    ? ['genexus-mcp status', 'genexus-mcp clients', 'genexus-mcp doctor --mcp-smoke', 'genexus-mcp tools list --limit 10', 'genexus-mcp layout status']
+                    : ['genexus-mcp status', 'genexus-mcp clients', 'genexus-mcp doctor --full', 'genexus-mcp init --kb "<kbPath>" --gx "<geneXusPath>"']
             },
             help: []
         }
@@ -2078,6 +2215,7 @@ module.exports = {
     handleWhoami,
     handleUninstall,
     handleKb,
+    handleClients,
     handleHome,
     handleLlmHelp,
     handleLayout,

package/cli/index.js

@@ -19,6 +19,7 @@ const {
     handleWhoami,
     handleUninstall,
     handleKb,
+    handleClients,
     handleHome,
     handleLlmHelp,
     handleLayout,
@@ -55,7 +56,7 @@ const GLOBAL_DEFAULTS = {
     help: false
 };
 
-const KNOWN_COMMANDS = new Set(['status', 'doctor', 'tools', 'config', 'init', 'setup', 'whoami', 'uninstall', 'kb', 'help', 'home', 'axi', 'llm', 'layout', 'update']);
+const KNOWN_COMMANDS = new Set(['status', 'doctor', 'tools', 'config', 'init', 'setup', 'whoami', 'uninstall', 'kb', 'clients', 'help', 'home', 'axi', 'llm', 'layout', 'update']);
 
 function parseArgs(argv) {
     const result = {
@@ -115,6 +116,11 @@ function parseArgs(argv) {
         tokens.shift();
     }
 
+    if (result.command === 'clients' && ['list', 'add', 'remove'].includes(tokens[0])) {
+        result.subcommand = tokens[0];
+        tokens.shift();
+    }
+
     if (result.command === 'layout' && (tokens[0] === 'status' || tokens[0] === 'run' || tokens[0] === 'inspect')) {
         result.subcommand = tokens[0];
         tokens.shift();
@@ -395,6 +401,9 @@ function resolveMetaCommand(parsed, targetHelp) {
     if (parsed.command === 'kb') {
         return parsed.subcommand ? `kb.${parsed.subcommand}` : 'kb';
     }
+    if (parsed.command === 'clients') {
+        return parsed.subcommand ? `clients.${parsed.subcommand}` : 'clients.list';
+    }
     if (parsed.command === 'update') return 'update';
     return parsed.command || 'unknown';
 }
@@ -523,6 +532,9 @@ async function main(argv) {
             }
             result = await handleKb(parsed.subcommand, parsed.options, ctx);
             break;
+        case 'clients':
+            result = await handleClients(parsed.subcommand, parsed.options, ctx);
+            break;
         case 'update':
             result = await handleUpdate(parsed.options, ctx);
             break;

package/cli/lib/config.js

@@ -237,16 +237,132 @@ function directoryLooksLikeKnowledgeBase(dir) {
     }
 }
 
+// Strip // and /* */ comments and trailing commas while respecting string
+// literals, so we can parse JSONC configs (VS Code's mcp.json/settings.json and
+// OpenCode's opencode.jsonc are JSONC). Comments are NOT preserved on rewrite.
+//
+// Trailing-comma removal is done INSIDE the scanner (a comma is deferred and only
+// emitted once we know the next significant char isn't a closing brace/bracket),
+// not by a post-hoc regex — a regex over the whole text would also strip commas
+// that live inside string values (e.g. "see foo, ]" -> "see foo ]"). Only `"`
+// opens a string: JSON/JSONC has no single-quoted strings.
+function stripJsonComments(text) {
+    let out = '';
+    let inString = false;
+    let inLine = false;
+    let inBlock = false;
+    let pendingComma = false;
+    // Resolve a deferred comma: keep it unless the next significant char closes a
+    // container (then it was a trailing comma and gets dropped).
+    const flushComma = (nextSignificant) => {
+        if (pendingComma) {
+            if (nextSignificant !== '}' && nextSignificant !== ']') out += ',';
+            pendingComma = false;
+        }
+    };
+    for (let i = 0; i < text.length; i += 1) {
+        const ch = text[i];
+        const next = text[i + 1];
+        if (inLine) {
+            if (ch === '\n') inLine = false;
+            continue;
+        }
+        if (inBlock) {
+            if (ch === '*' && next === '/') { inBlock = false; i += 1; }
+            continue;
+        }
+        if (inString) {
+            out += ch;
+            if (ch === '\\') { out += next; i += 1; continue; }
+            if (ch === '"') inString = false;
+            continue;
+        }
+        // Outside any string/comment.
+        if (ch === '/' && next === '/') { inLine = true; i += 1; continue; }
+        if (ch === '/' && next === '*') { inBlock = true; i += 1; continue; }
+        if (ch === ' ' || ch === '\t' || ch === '\r' || ch === '\n') {
+            // Whitespace between a deferred comma and the next token is collapsed
+            // (JSON.parse ignores it); otherwise emit it verbatim.
+            if (!pendingComma) out += ch;
+            continue;
+        }
+        if (ch === ',') {
+            flushComma(',');       // a prior comma followed by another comma is kept as-is
+            pendingComma = true;   // defer this one until we see what follows
+            continue;
+        }
+        flushComma(ch);
+        out += ch;
+        if (ch === '"') inString = true;
+    }
+    flushComma('');
+    return out;
+}
+
 function readJsonFileSafe(filePath) {
     try {
         const raw = fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '');
         if (!raw.trim()) return {};
-        return JSON.parse(raw);
+        try {
+            return JSON.parse(raw);
+        } catch {
+            // Fall back to a JSONC-tolerant parse before giving up, so a commented
+            // VS Code / OpenCode config isn't treated as corrupt.
+            return JSON.parse(stripJsonComments(raw));
+        }
     } catch {
         return null;
     }
 }
 
+// Atomic write: stage to a temp file then rename over the target, so a crash
+// mid-write can never leave a client's config truncated.
+function writeFileAtomic(filePath, content) {
+    const tmp = `${filePath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, content);
+    try {
+        fs.renameSync(tmp, filePath);
+    } catch (err) {
+        try { fs.rmSync(tmp, { force: true }); } catch { /* ignore */ }
+        throw err;
+    }
+}
+
+// Back up a client config once per process run before the first mutation, so the
+// user has a restore point (the old build-from-source install.ps1 did this; the
+// CLI now owns it). Best-effort \u2014 a failed backup never blocks the write.
+const _backedUpThisRun = new Set();
+function backupClientConfigOnce(filePath) {
+    if (!fs.existsSync(filePath)) return null;
+    // Case-fold the dedupe key only on Windows; lowercasing on a case-sensitive
+    // filesystem could merge two genuinely distinct paths.
+    const resolved = path.resolve(filePath);
+    const key = process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+    if (_backedUpThisRun.has(key)) return null;
+    try {
+        const d = new Date();
+        const stamp = d.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+        const bak = `${filePath}.${stamp}.bak`;
+        fs.copyFileSync(filePath, bak);
+        _backedUpThisRun.add(key);
+        return bak;
+    } catch {
+        return null;
+    }
+}
+
+// Write JSON to a client config: back up, serialize, write atomically.
+function writeClientJson(filePath, obj) {
+    backupClientConfigOnce(filePath);
+    writeFileAtomic(filePath, JSON.stringify(obj, null, 2));
+}
+
+// Write raw text to a client config (e.g. Codex TOML): back up + write atomically.
+function writeClientText(filePath, content) {
+    backupClientConfigOnce(filePath);
+    writeFileAtomic(filePath, content);
+}
+
 function resolveConfigPathNoMutate(cwd) {
     const cwdConfigPath = path.join(cwd, 'config.json');
     if (process.env.GX_CONFIG_PATH && fs.existsSync(process.env.GX_CONFIG_PATH)) {
@@ -298,67 +414,241 @@ function getLauncher() {
         : { command: process.platform === 'win32' ? 'npx.cmd' : 'npx', args: ['-y', 'genexus-mcp@latest'] };
 }
 
+// Antigravity (Google's agentic IDE) ships its MCP config under ~/.gemini.
+// The newer unified location (shared across Antigravity CLI / IDE / SDK) is
+// ~/.gemini/config/mcp_config.json; the older IDE-specific one is
+// ~/.gemini/antigravity/mcp_config.json. We write to the unified path when its
+// parent dir already exists, else fall back to the IDE-specific path.
+function resolveAntigravityConfigPath(home) {
+    // Only target the unified location when its file already exists (the user has
+    // adopted it); otherwise write the IDE-specific path, which is the location
+    // Antigravity reliably reads and was confirmed working in the field.
+    const unified = path.join(home, '.gemini', 'config', 'mcp_config.json');
+    if (fs.existsSync(unified)) return unified;
+    return path.join(home, '.gemini', 'antigravity', 'mcp_config.json');
+}
+
+// OpenCode CLI accepts either opencode.jsonc or opencode.json. Prefer an
+// existing .jsonc so we don't strand the user's commented config, else .json.
+function resolveOpenCodeConfigPath(xdgConfig) {
+    const jsonc = path.join(xdgConfig, 'opencode', 'opencode.jsonc');
+    if (fs.existsSync(jsonc)) return jsonc;
+    return path.join(xdgConfig, 'opencode', 'opencode.json');
+}
+
+// VS Code stores its user profile (and native MCP mcp.json) in a per-platform
+// location. `variant` is 'Code' (stable) or 'Code - Insiders'.
+function vscodeUserDir(variant, { appData, macAppSupport, xdgConfig }) {
+    if (process.platform === 'win32') return path.join(appData, variant, 'User');
+    if (process.platform === 'darwin') return path.join(macAppSupport, variant, 'User');
+    return path.join(xdgConfig, variant, 'User');
+}
+
 function getClientConfigTargets() {
     const home = os.homedir();
     const xdgConfig = process.env.XDG_CONFIG_HOME || path.join(home, '.config');
+    const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    const localAppData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+    const macAppSupport = path.join(home, 'Library', 'Application Support');
+    const vscodeStableUser = vscodeUserDir('Code', { appData, macAppSupport, xdgConfig });
+    const vscodeInsidersUser = vscodeUserDir('Code - Insiders', { appData, macAppSupport, xdgConfig });
+
+    // `installMarkers` prove the AGENT is installed, independent of whether our
+    // MCP config file exists yet. This is the fix for the field report where the
+    // wizard showed Antigravity as "not detected": Antigravity does not create
+    // ~/.gemini/antigravity/mcp_config.json until the user adds an MCP server, so
+    // detecting by config-file presence alone was chicken-and-egg.
     return [
         {
             id: 'claude-desktop-win',
             name: 'Claude Desktop (Windows)',
             format: 'mcpServers',
             path: path.join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json'),
-            platforms: ['win32']
+            platforms: ['win32'],
+            installMarkers: [
+                path.join(localAppData, 'AnthropicClaude'),
+                path.join(appData, 'Claude')
+            ]
         },
         {
             id: 'claude-desktop-mac',
             name: 'Claude Desktop (macOS)',
             format: 'mcpServers',
             path: path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
-            platforms: ['darwin']
+            platforms: ['darwin'],
+            installMarkers: [
+                path.join(macAppSupport, 'Claude'),
+                '/Applications/Claude.app'
+            ]
         },
         {
             id: 'antigravity',
             name: 'Antigravity',
             format: 'mcpServers',
-            path: path.join(home, '.gemini', 'antigravity', 'mcp_config.json')
+            path: resolveAntigravityConfigPath(home),
+            // Unambiguous Antigravity markers only. ~/.gemini/config is NOT a
+            // marker — gemini-cli can create ~/.gemini, and we'd false-positive;
+            // it's still used as the write path (resolveAntigravityConfigPath)
+            // once a real Antigravity install is confirmed by these markers.
+            installMarkers: [
+                path.join(localAppData, 'Programs', 'Antigravity'),
+                path.join(appData, 'Antigravity'),
+                path.join(home, '.antigravity'),
+                path.join(home, '.gemini', 'antigravity')
+            ]
         },
         {
             id: 'claude-code',
             name: 'Claude Code',
             format: 'mcpServers',
-            path: path.join(home, '.claude.json')
+            path: path.join(home, '.claude.json'),
+            installMarkers: [
+                path.join(home, '.claude.json'),
+                path.join(home, '.claude')
+            ]
         },
         {
             id: 'gemini-cli',
             name: 'Gemini CLI',
             format: 'mcpServers',
-            path: path.join(home, '.gemini', 'settings.json')
+            path: path.join(home, '.gemini', 'settings.json'),
+            installMarkers: [
+                path.join(home, '.gemini', 'settings.json')
+            ]
         },
         {
             id: 'cursor',
             name: 'Cursor',
             format: 'mcpServers',
-            path: path.join(home, '.cursor', 'mcp.json')
+            path: path.join(home, '.cursor', 'mcp.json'),
+            installMarkers: [
+                path.join(home, '.cursor'),
+                path.join(localAppData, 'Programs', 'cursor'),
+                '/Applications/Cursor.app'
+            ]
         },
         {
             id: 'opencode',
-            name: 'OpenCode',
+            name: 'OpenCode (CLI)',
             format: 'opencode',
-            path: path.join(xdgConfig, 'opencode', 'opencode.json')
+            path: resolveOpenCodeConfigPath(xdgConfig),
+            installMarkers: [
+                path.join(xdgConfig, 'opencode'),
+                path.join(home, '.local', 'share', 'opencode')
+            ]
         },
         {
             id: 'codex-cli',
             name: 'Codex CLI',
             format: 'codex-toml',
-            path: path.join(home, '.codex', 'config.toml')
+            path: path.join(home, '.codex', 'config.toml'),
+            installMarkers: [
+                path.join(home, '.codex')
+            ]
+        },
+        {
+            id: 'opencode-desktop',
+            name: 'OpenCode Desktop',
+            // Detect-only: the Desktop app's MCP config schema differs from the CLI
+            // and isn't auto-written yet. We report it so the user knows it's there
+            // and how to wire it up, but never mutate its config blindly.
+            format: 'manual',
+            writeSupported: false,
+            manualNote: 'OpenCode Desktop: add the genexus MCP server from the app\'s settings (automatic registration not supported yet).',
+            path: path.join(appData, 'ai.opencode.desktop', 'mcp.json'),
+            installMarkers: [
+                path.join(localAppData, 'Programs', '@opencode-aidesktop'),
+                path.join(appData, 'ai.opencode.desktop'),
+                '/Applications/OpenCode.app'
+            ]
+        },
+        {
+            id: 'vscode',
+            name: 'VS Code',
+            format: 'vscode-servers',
+            path: path.join(vscodeStableUser, 'mcp.json'),
+            installMarkers: [vscodeStableUser]
+        },
+        {
+            id: 'vscode-insiders',
+            name: 'VS Code Insiders',
+            format: 'vscode-servers',
+            path: path.join(vscodeInsidersUser, 'mcp.json'),
+            installMarkers: [vscodeInsidersUser]
         }
     ];
 }
 
+// Decide whether an agent is installed (independent of whether OUR config file
+// exists). Returns the installed flag plus diagnostics so the wizard can show
+// the user exactly where it looked when an agent is reported "not detected".
+function detectClientInstalled(client) {
+    const markers = Array.isArray(client.installMarkers) ? client.installMarkers : [];
+    const hasConfig = fs.existsSync(client.path);
+    let markerHit = null;
+    for (const m of markers) {
+        if (fs.existsSync(m)) {
+            markerHit = m;
+            break;
+        }
+    }
+    return {
+        installed: hasConfig || markerHit !== null,
+        hasConfig,
+        markerHit,
+        markersChecked: markers
+    };
+}
+
 function listSupportedClientIds() {
     return getClientConfigTargets().map((c) => c.id);
 }
 
+// Judge whether a registered launcher command is healthy. npx/node/genexus-mcp
+// shims resolve at runtime so we can't fault them; any other launcher referenced
+// by an explicit path (a separator in the command) that no longer exists on disk
+// is the classic "Failed to connect / still on old version" cause after an
+// install dir moved or was cleaned — covers .exe, .bat, .cmd, .sh, extensionless.
+function clientCommandHealth(entry) {
+    if (!entry || !entry.command) return { stale: false, reason: null };
+    const cmd = String(entry.command);
+    if (/(^|[\\/])(npx|npx\.cmd|node|node\.exe|genexus-mcp|genexus-mcp\.cmd)$/i.test(cmd)) {
+        return { stale: false, reason: null };
+    }
+    if (/[\\/]/.test(cmd) && !fs.existsSync(cmd)) {
+        return { stale: true, reason: 'configured launcher does not exist on disk' };
+    }
+    return { stale: false, reason: null };
+}
+
+// Read-only report of every supported agent on this platform: is it installed,
+// is genexus registered, where, what launcher command it points at, and whether
+// that command is stale. Backs the `genexus-mcp clients` command.
+function clientsStatus(opts = {}) {
+    const targets = filterClientTargets(getClientConfigTargets(), {
+        ids: opts.ids,
+        platform: process.platform
+    });
+    return targets.map((client) => {
+        const det = detectClientInstalled(client);
+        const entry = readClientCommandEntry(client);
+        const health = clientCommandHealth(entry);
+        return {
+            id: client.id,
+            name: client.name,
+            installed: det.installed,
+            registered: entry !== null,
+            writeSupported: client.writeSupported !== false,
+            configPath: client.path,
+            command: entry && entry.command ? entry.command : null,
+            commandStale: health.stale,
+            commandStaleReason: health.reason,
+            detectedAt: det.markerHit || (det.hasConfig ? client.path : null),
+            note: client.writeSupported === false ? (client.manualNote || null) : null
+        };
+    });
+}
+
 function filterClientTargets(targets, opts = {}) {
     const { ids, onlyExisting, platform } = opts;
     let out = targets;
@@ -396,13 +686,29 @@ function patchClientConfig(targetConfigPath, opts = {}) {
     const skipped = [];
 
     for (const client of candidates) {
-        if (onlyExisting && !fs.existsSync(client.path)) {
+        // Detect-only agents (e.g. OpenCode Desktop) can't be auto-written; surface
+        // the manual step instead of pretending we registered them.
+        if (client.writeSupported === false) {
+            if (detectClientInstalled(client).installed) {
+                skipped.push({ client: client.name, reason: client.manualNote || 'manual setup required' });
+            }
+            continue;
+        }
+        // "Installed" keys off install markers (the agent itself is present), not
+        // just our config file — otherwise agents that don't pre-create their MCP
+        // config (e.g. Antigravity) are wrongly skipped as "not installed".
+        if (onlyExisting && !detectClientInstalled(client).installed) {
             skipped.push({ client: client.name, reason: 'not installed' });
             continue;
         }
         try {
             fs.mkdirSync(path.dirname(client.path), { recursive: true });
             applyClientEntry(client, launcher, targetConfigPath);
+            // Read-back: confirm the entry is actually present and the file still
+            // parses, so a silently-corrupted write is reported as a failure.
+            if (!readClientCommandEntry(client)) {
+                throw new Error('post-write verification failed (genexus entry not found after write)');
+            }
             patched.push(client.name);
         } catch (err) {
             failed.push({ client: client.name, reason: err && err.message ? err.message : 'Unknown error' });
@@ -423,6 +729,11 @@ function unpatchClientConfig(opts = {}) {
     const failed = [];
 
     for (const client of targets) {
+        // Detect-only agents were never written by us — nothing to remove.
+        if (client.writeSupported === false) {
+            skipped.push({ client: client.name, reason: 'manual setup (not managed by genexus-mcp)' });
+            continue;
+        }
         try {
             const wasRemoved = removeClientEntry(client);
             if (wasRemoved) removed.push(client.name);
@@ -443,6 +754,8 @@ function applyClientEntry(client, launcher, targetConfigPath) {
             return applyOpenCodeJson(client.path, launcher, targetConfigPath);
         case 'codex-toml':
             return applyCodexToml(client.path, launcher, targetConfigPath);
+        case 'vscode-servers':
+            return applyVsCodeServersJson(client.path, launcher, targetConfigPath);
         default:
             throw new Error(`Unknown client format: ${client.format}`);
     }
@@ -456,6 +769,8 @@ function removeClientEntry(client) {
             return removeOpenCodeJson(client.path);
         case 'codex-toml':
             return removeCodexToml(client.path);
+        case 'vscode-servers':
+            return removeVsCodeServersJson(client.path);
         default:
             throw new Error(`Unknown client format: ${client.format}`);
     }
@@ -467,16 +782,63 @@ function applyMcpServersJson(filePath, launcher, targetConfigPath) {
     const cfgObj = parsed || {};
     cfgObj.mcpServers = cfgObj.mcpServers || {};
     cfgObj.mcpServers.genexus = { ...launcher, env: { GX_CONFIG_PATH: targetConfigPath } };
-    fs.writeFileSync(filePath, JSON.stringify(cfgObj, null, 2));
+    // Drop the legacy `genexus18` key from older build-from-source installs so the
+    // user isn't left with two duplicate servers (and colliding tool names).
+    if (cfgObj.mcpServers.genexus18) delete cfgObj.mcpServers.genexus18;
+    writeClientJson(filePath, cfgObj);
 }
 
 function removeMcpServersJson(filePath) {
     const parsed = readJsonFileSafe(filePath);
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
-    if (!cfgObj.mcpServers || !cfgObj.mcpServers.genexus) return false;
-    delete cfgObj.mcpServers.genexus;
-    fs.writeFileSync(filePath, JSON.stringify(cfgObj, null, 2));
+    if (!cfgObj.mcpServers) return false;
+    // Remove the current key plus the legacy `genexus18` key written by older
+    // versions of the build-from-source install.ps1, so uninstall fully cleans up
+    // regardless of which installer wrote the entry.
+    let removedAny = false;
+    for (const key of ['genexus', 'genexus18']) {
+        if (cfgObj.mcpServers[key]) {
+            delete cfgObj.mcpServers[key];
+            removedAny = true;
+        }
+    }
+    if (!removedAny) return false;
+    writeClientJson(filePath, cfgObj);
+    return true;
+}
+
+// VS Code native MCP lives in User\mcp.json and uses a top-level `servers` map
+// with `type: "stdio"` (distinct from the `mcpServers` shape Claude/Cursor use).
+function applyVsCodeServersJson(filePath, launcher, targetConfigPath) {
+    const parsed = fs.existsSync(filePath) ? readJsonFileSafe(filePath) : {};
+    if (parsed === null) throw new Error('Invalid JSON');
+    const cfgObj = parsed || {};
+    cfgObj.servers = cfgObj.servers || {};
+    cfgObj.servers.genexus = {
+        type: 'stdio',
+        ...launcher,
+        env: { GX_CONFIG_PATH: targetConfigPath }
+    };
+    // Drop the legacy `genexus18` key written by older build-from-source installs.
+    if (cfgObj.servers.genexus18) delete cfgObj.servers.genexus18;
+    writeClientJson(filePath, cfgObj);
+}
+
+function removeVsCodeServersJson(filePath) {
+    const parsed = readJsonFileSafe(filePath);
+    if (parsed === null) throw new Error('Invalid JSON');
+    const cfgObj = parsed || {};
+    if (!cfgObj.servers) return false;
+    let removedAny = false;
+    for (const key of ['genexus', 'genexus18']) {
+        if (cfgObj.servers[key]) {
+            delete cfgObj.servers[key];
+            removedAny = true;
+        }
+    }
+    if (!removedAny) return false;
+    writeClientJson(filePath, cfgObj);
     return true;
 }
 
@@ -485,6 +847,9 @@ function applyOpenCodeJson(filePath, launcher, targetConfigPath) {
     const parsed = fs.existsSync(filePath) ? readJsonFileSafe(filePath) : {};
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
+    // OpenCode configs carry a top-level $schema for editor validation; set it when
+    // absent (new file or a config that never had one) without clobbering a custom one.
+    if (!cfgObj.$schema) cfgObj.$schema = 'https://opencode.ai/config.json';
     cfgObj.mcp = cfgObj.mcp || {};
     cfgObj.mcp.genexus = {
         type: 'local',
@@ -492,7 +857,8 @@ function applyOpenCodeJson(filePath, launcher, targetConfigPath) {
         environment: { GX_CONFIG_PATH: targetConfigPath },
         enabled: true
     };
-    fs.writeFileSync(filePath, JSON.stringify(cfgObj, null, 2));
+    if (cfgObj.mcp.genexus18) delete cfgObj.mcp.genexus18;
+    writeClientJson(filePath, cfgObj);
 }
 
 function removeOpenCodeJson(filePath) {
@@ -501,7 +867,7 @@ function removeOpenCodeJson(filePath) {
     const cfgObj = parsed || {};
     if (!cfgObj.mcp || !cfgObj.mcp.genexus) return false;
     delete cfgObj.mcp.genexus;
-    fs.writeFileSync(filePath, JSON.stringify(cfgObj, null, 2));
+    writeClientJson(filePath, cfgObj);
     return true;
 }
 
@@ -524,7 +890,7 @@ function applyCodexToml(filePath, launcher, targetConfigPath) {
     lines.push('[mcp_servers.genexus.env]');
     lines.push(`GX_CONFIG_PATH = ${tomlString(targetConfigPath)}`);
     lines.push('');
-    fs.writeFileSync(filePath, stripped + lines.join('\n'));
+    writeClientText(filePath, stripped + lines.join('\n'));
 }
 
 function removeCodexToml(filePath) {
@@ -532,7 +898,7 @@ function removeCodexToml(filePath) {
     const existing = fs.readFileSync(filePath, 'utf8');
     const stripped = stripCodexGenexusBlocks(existing);
     if (stripped === existing) return false;
-    fs.writeFileSync(filePath, stripped);
+    writeClientText(filePath, stripped);
     return true;
 }
 
@@ -588,6 +954,7 @@ function normalizeExePath(p) {
 }
 
 function readClientCommandEntry(client) {
+    if (client.writeSupported === false) return null;
     if (!fs.existsSync(client.path)) return null;
     try {
         if (client.format === 'mcpServers') {
@@ -604,6 +971,13 @@ function readClientCommandEntry(client) {
             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 === 'vscode-servers') {
+            const parsed = readJsonFileSafe(client.path);
+            if (!parsed || typeof parsed !== 'object') return null;
+            const entry = parsed.servers && parsed.servers.genexus;
+            if (!entry) return null;
+            return { command: entry.command || null, args: Array.isArray(entry.args) ? entry.args : [] };
+        }
         if (client.format === 'codex-toml') {
             const raw = fs.readFileSync(client.path, 'utf8');
             // Minimal extraction: find [mcp_servers.genexus] block and pull command = "..."
@@ -786,6 +1160,8 @@ module.exports = {
     patchClientConfig,
     unpatchClientConfig,
     getClientConfigTargets,
+    detectClientInstalled,
+    clientsStatus,
     listSupportedClientIds,
     filterClientTargets,
     getLocalAppDataCacheDir,

package/cli/run.test.js

@@ -6,6 +6,7 @@ const os = require('node:os');
 const fs = require('node:fs');
 const { renderOutput } = require('./lib/output');
 const { compareSemver } = require('./lib/update-check');
+const { detectClientInstalled, readJsonFileSafe } = require('./lib/config');
 
 const cliPath = path.join(__dirname, 'run.js');
 
@@ -599,6 +600,227 @@ test('update --help returns usage entry', () => {
     assert.ok(parsed.ok.usage.includes('genexus-mcp update'));
 });
 
+test('detectClientInstalled flags an agent installed via marker even with no MCP config', () => {
+    // Regression for the field report where Antigravity showed "not detected":
+    // an agent whose install dir exists but which hasn't created our MCP config
+    // file yet must still be detected as installed.
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-detect-'));
+    const installDir = path.join(tempRoot, 'Programs', 'Antigravity');
+    fs.mkdirSync(installDir, { recursive: true });
+
+    const client = {
+        name: 'Antigravity',
+        path: path.join(tempRoot, 'never-created', 'mcp_config.json'),
+        installMarkers: [installDir]
+    };
+
+    const det = detectClientInstalled(client);
+    assert.equal(det.installed, true, 'marker dir present => installed');
+    assert.equal(det.hasConfig, false, 'config file does not exist yet');
+    assert.equal(det.markerHit, installDir);
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('detectClientInstalled reports not-installed and lists checked paths', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-detect-'));
+    const client = {
+        name: 'Antigravity',
+        path: path.join(tempRoot, 'nope.json'),
+        installMarkers: [path.join(tempRoot, 'absent-a'), path.join(tempRoot, 'absent-b')]
+    };
+
+    const det = detectClientInstalled(client);
+    assert.equal(det.installed, false);
+    assert.equal(det.markerHit, null);
+    assert.deepEqual(det.markersChecked, client.installMarkers);
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('detectClientInstalled treats an existing config file as installed', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-detect-'));
+    const cfg = path.join(tempRoot, 'settings.json');
+    fs.writeFileSync(cfg, '{}');
+    const client = { name: 'Gemini CLI', path: cfg, installMarkers: [] };
+
+    const det = detectClientInstalled(client);
+    assert.equal(det.installed, true);
+    assert.equal(det.hasConfig, true);
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+// Build a throwaway HOME so client-config writes never touch the real machine.
+function sandboxHomeEnv(root) {
+    return {
+        HOME: root,
+        USERPROFILE: root,
+        APPDATA: path.join(root, 'AppData', 'Roaming'),
+        LOCALAPPDATA: path.join(root, 'AppData', 'Local'),
+        XDG_CONFIG_HOME: path.join(root, '.config')
+    };
+}
+
+test('clients list returns structured status with summary', () => {
+    const result = runCli(['clients', '--format', 'json']);
+    assert.equal(result.status, 0);
+    const parsed = JSON.parse(result.stdout);
+    assert.equal(parsed.meta.command, 'clients.list');
+    assert.ok(Array.isArray(parsed.ok.clients));
+    assert.ok(parsed.ok.clients.length >= 8);
+    assert.equal(typeof parsed.ok.summary.installed, 'number');
+    assert.equal(typeof parsed.ok.summary.registered, 'number');
+    const row = parsed.ok.clients.find((c) => c.id === 'antigravity');
+    assert.ok(row, 'antigravity should be listed');
+    assert.equal(typeof row.installed, 'boolean');
+    assert.equal(typeof row.registered, 'boolean');
+});
+
+test('clients add registers a client into a sandbox home with backup + atomic write', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-clients-'));
+    const env = sandboxHomeEnv(tempRoot);
+    const cfgPath = path.join(tempRoot, 'config.json');
+    fs.writeFileSync(cfgPath, JSON.stringify({ Environment: { KBPath: tempRoot } }));
+
+    // Pre-existing cursor config so we can assert a backup is taken.
+    const cursorCfg = path.join(tempRoot, '.cursor', 'mcp.json');
+    fs.mkdirSync(path.dirname(cursorCfg), { recursive: true });
+    fs.writeFileSync(cursorCfg, JSON.stringify({ mcpServers: { other: { command: 'x' } } }, null, 2));
+
+    const res = runCli(['clients', 'add', '--clients', 'cursor', '--format', 'json'], {
+        env: { ...env, GX_CONFIG_PATH: cfgPath }
+    });
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.meta.command, 'clients.add');
+    assert.ok(parsed.ok.patchedClients.includes('Cursor'));
+
+    const written = JSON.parse(fs.readFileSync(cursorCfg, 'utf8'));
+    assert.ok(written.mcpServers.genexus, 'genexus entry should be written');
+    assert.ok(written.mcpServers.other, 'pre-existing entries preserved');
+
+    const baks = fs.readdirSync(path.dirname(cursorCfg)).filter((f) => f.includes('.bak'));
+    assert.ok(baks.length >= 1, 'a .bak backup should be created before mutating');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('clients add tolerates a JSONC (commented) VS Code mcp.json', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-jsonc-'));
+    const env = sandboxHomeEnv(tempRoot);
+    const cfgPath = path.join(tempRoot, 'config.json');
+    fs.writeFileSync(cfgPath, JSON.stringify({ Environment: { KBPath: tempRoot } }));
+
+    const vscodeCfg = path.join(env.APPDATA, 'Code', 'User', 'mcp.json');
+    fs.mkdirSync(path.dirname(vscodeCfg), { recursive: true });
+    fs.writeFileSync(vscodeCfg, '{\n  // user comment\n  "servers": {\n    "foo": { "command": "bar" },\n  }\n}\n');
+
+    const res = runCli(['clients', 'add', '--clients', 'vscode', '--format', 'json'], {
+        env: { ...env, GX_CONFIG_PATH: cfgPath }
+    });
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.ok(parsed.ok.patchedClients.includes('VS Code'), 'VS Code should be patched despite comments');
+
+    const written = JSON.parse(fs.readFileSync(vscodeCfg, 'utf8'));
+    assert.ok(written.servers.genexus, 'genexus server entry written');
+    assert.ok(written.servers.foo, 'pre-existing server preserved');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('clients add replaces a legacy genexus18 entry instead of duplicating it', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-legacy-'));
+    const env = sandboxHomeEnv(tempRoot);
+    const cfgPath = path.join(tempRoot, 'config.json');
+    fs.writeFileSync(cfgPath, JSON.stringify({ Environment: { KBPath: tempRoot } }));
+
+    const cursorCfg = path.join(tempRoot, '.cursor', 'mcp.json');
+    fs.mkdirSync(path.dirname(cursorCfg), { recursive: true });
+    fs.writeFileSync(cursorCfg, JSON.stringify({ mcpServers: { genexus18: { command: 'C:\\old\\start_mcp.bat' } } }, null, 2));
+
+    const res = runCli(['clients', 'add', '--clients', 'cursor', '--format', 'json'], {
+        env: { ...env, GX_CONFIG_PATH: cfgPath }
+    });
+    assert.equal(res.status, 0);
+
+    const written = JSON.parse(fs.readFileSync(cursorCfg, 'utf8'));
+    assert.ok(written.mcpServers.genexus, 'new genexus entry present');
+    assert.equal(written.mcpServers.genexus18, undefined, 'legacy genexus18 removed (no duplicate)');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('clients list flags a registered command pointing at a missing launcher as stale (.bat too)', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-stale-'));
+    const env = sandboxHomeEnv(tempRoot);
+    const cursorCfg = path.join(tempRoot, '.cursor', 'mcp.json');
+    fs.mkdirSync(path.dirname(cursorCfg), { recursive: true });
+    // A non-.exe launcher (.bat) that no longer exists must also be flagged stale.
+    const missing = path.join(tempRoot, 'gone', 'start_mcp.bat');
+    fs.writeFileSync(cursorCfg, JSON.stringify({ mcpServers: { genexus: { command: missing, args: [] } } }, null, 2));
+
+    const res = runCli(['clients', '--format', 'json'], { env });
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    const cursor = parsed.ok.clients.find((c) => c.id === 'cursor');
+    assert.ok(cursor.registered, 'cursor should read as registered');
+    assert.equal(cursor.commandStale, true, 'missing launcher => stale');
+    assert.ok(parsed.help.some((h) => h.includes('missing gateway exe')), 'help should call out the stale client');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('readJsonFileSafe parses JSONC without corrupting string values containing commas', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-jsonc2-'));
+    const f = path.join(tempRoot, 'mcp.json');
+    // Leading comment forces the JSONC fallback; the string value contains ", ]"
+    // and the object has a legitimate trailing comma that SHOULD be stripped.
+    fs.writeFileSync(f, '{\n  // comment\n  "servers": { "x": { "command": "a, ]b", "args": ["c,]"] } },\n}\n');
+    const parsed = readJsonFileSafe(f);
+    assert.ok(parsed, 'should parse');
+    assert.equal(parsed.servers.x.command, 'a, ]b', 'comma inside string value preserved');
+    assert.deepEqual(parsed.servers.x.args, ['c,]'], 'comma inside array string preserved');
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('readJsonFileSafe strips a genuine trailing comma', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-jsonc3-'));
+    const f = path.join(tempRoot, 'mcp.json');
+    fs.writeFileSync(f, '{\n  // c\n  "a": [1, 2, 3,],\n  "b": { "x": 1, },\n}\n');
+    const parsed = readJsonFileSafe(f);
+    assert.deepEqual(parsed.a, [1, 2, 3]);
+    assert.deepEqual(parsed.b, { x: 1 });
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('clients add without --clients is a usage error', () => {
+    const res = runCli(['clients', 'add', '--format', 'json']);
+    assert.equal(res.status, 2);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.error.code, 'usage_error');
+});
+
+test('clients remove drops the genexus entry (sandbox home)', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-rm-'));
+    const env = sandboxHomeEnv(tempRoot);
+    const cursorCfg = path.join(tempRoot, '.cursor', 'mcp.json');
+    fs.mkdirSync(path.dirname(cursorCfg), { recursive: true });
+    fs.writeFileSync(cursorCfg, JSON.stringify({ mcpServers: { genexus: { command: 'npx' }, genexus18: { command: 'old' } } }, null, 2));
+
+    const res = runCli(['clients', 'remove', '--clients', 'cursor', '--format', 'json'], { env });
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.ok(parsed.ok.removedClients.includes('Cursor'));
+
+    const written = JSON.parse(fs.readFileSync(cursorCfg, 'utf8'));
+    assert.equal(written.mcpServers.genexus, undefined, 'genexus removed');
+    assert.equal(written.mcpServers.genexus18, undefined, 'legacy genexus18 also removed');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
 test('compareSemver detects newer, older, equal versions', () => {
     assert.equal(compareSemver('1.3.1', '1.3.0'), 1);
     assert.equal(compareSemver('v1.4.0', '1.3.9'), 1);

package/docs/llm_cli_mcp_playbook.md

@@ -27,6 +27,7 @@ Entry points:
 - `genexus-mcp llm help`
 - `genexus-mcp status`
 - `genexus-mcp doctor --mcp-smoke`
+- `genexus-mcp clients` (which AI agents are installed/registered; `clients add|remove --clients <csv>`)
 - `genexus-mcp tools list`
 - `genexus-mcp config show`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genexus-mcp",
-  "version": "2.8.2",
+  "version": "2.8.3",
   "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.8.2": {
+      "GxMcp.Gateway/2.8.3": {
         "dependencies": {
           "Newtonsoft.Json": "13.0.3",
           "System.Management": "10.0.5",
@@ -66,7 +66,7 @@
     }
   },
   "libraries": {
-    "GxMcp.Gateway/2.8.2": {
+    "GxMcp.Gateway/2.8.3": {
       "type": "project",
       "serviceable": false,
       "sha512": ""