genexus-mcp 2.8.2 → 2.8.4

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,13 +2028,27 @@ 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']
         },
         update: {
-            usage: 'genexus-mcp update [--format toon|json|text]',
-            examples: ['genexus-mcp update', 'genexus-mcp update --format json']
+            usage: 'genexus-mcp update [--apply] [--yes] [--channel latest|next] [--format toon|json|text]',
+            examples: [
+                'genexus-mcp update                  # check; reports your install method + the right upgrade step',
+                'genexus-mcp update --apply          # perform the upgrade for your install method (confirms first)',
+                'genexus-mcp update --apply --yes    # unattended (CI/automation)',
+                'genexus-mcp update --channel next   # check the @next dist-tag'
+            ]
         },
         layout: {
             usage: 'genexus-mcp layout status [--title "GeneXus"] [--format ...] OR genexus-mcp layout run --action <focus|activate-layout|activate-tab|send-keys|type-text|click> [--tab "Layout"] [--keys "..."] [--text "..."] [--x N --y N] [--title "..."] [--format ...] OR genexus-mcp layout inspect [--tab "Layout"] [--limit N] [--full] [--title "..."] [--format ...]',
@@ -1935,8 +2077,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 +2220,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,
@@ -47,6 +48,8 @@ const GLOBAL_DEFAULTS = {
     noSmoke: false,
     warm: false,
     yes: false,
+    apply: false,
+    channel: null,
     name: null,
     limit: 100,
     query: null,
@@ -55,7 +58,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 +118,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();
@@ -281,6 +289,15 @@ function parseArgs(argv) {
             case 'yes':
                 result.options.yes = true;
                 break;
+            case 'apply':
+                result.options.apply = true;
+                break;
+            case 'channel': {
+                const val = takeValue();
+                if (val) result.options.channel = val;
+                else result.unknownFlags.push('--channel requires a value');
+                break;
+            }
             case 'quiet':
                 result.options.quiet = true;
                 break;
@@ -395,6 +412,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 +543,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;