genexus-mcp 2.41.9 → 2.41.11

package/README.md

@@ -20,7 +20,7 @@ In practice: you point the MCP at your KB, then ask your AI assistant things lik
 
 ## What you can do with it
 
-A quick map of what the agent can do against your real KB through the **47 tools** (details in [Tool Surface](#tool-surface)):
+A quick map of what the agent can do against your real KB through the **48 tools** (details in [Tool Surface](#tool-surface)):
 
 | Area | What the agent can do |
 |---|---|
@@ -86,7 +86,7 @@ What you'll see (takes ~30 seconds first time, faster on re-runs):
 
 ### Step 2 — Register the MCP in your AI client
 
-Step 1 auto-registers with Claude Desktop, Claude Code, Cursor, and Antigravity when it detects them. If yours wasn't detected, copy the JSON snippet from Step 1 into your client's MCP config manually. See the [client setup guide](TROUBLESHOOTING.md#client-setup) if unsure where that file lives.
+Step 1 auto-registers every supported client it detects, including Claude Desktop, Claude Code, Cursor, Antigravity, Gemini CLI, OpenCode, Codex CLI, and VS Code. If yours wasn't detected, copy the JSON snippet from Step 1 into your client's MCP config manually. See the [client setup guide](TROUBLESHOOTING.md#client-setup) if unsure where that file lives.
 
 ### Step 3 — Restart your AI client, then test
 
@@ -95,6 +95,8 @@ This part trips most people: **fully close** your AI client and reopen it. Not j
 - **Claude Desktop**: right-click the system-tray icon → **Quit**. Then launch it again. (Closing the window is not enough.)
 - **Claude Code**: end the session and start a fresh one.
 - **Cursor / Antigravity**: close all windows and reopen.
+- **OpenCode**: fully quit and reopen it so it reloads `opencode.json` / `opencode.jsonc`.
+- **Gemini CLI / Codex CLI**: start a new process or session.
 
 Then paste this prompt:
 
@@ -205,7 +207,7 @@ Auto-detected and auto-configured by the installer:
 | Cursor | ✅ | Restart required |
 | Antigravity | ✅ | Restart required; detected even before its MCP config exists |
 | Gemini CLI | ✅ | — |
-| OpenCode (CLI) | ✅ | Reads `opencode.json` / `opencode.jsonc` |
+| OpenCode (CLI) | ✅ | Reads both direct and nested MCP layouts; restart required |
 | 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 |
@@ -234,7 +236,7 @@ Still stuck? [Open an issue](https://github.com/lennix1337/Genexus18MCP/issues)
 
 ## Tool Surface
 
-The worker exposes **47 tools** to the MCP router, grouped by capability below. Most are umbrellas with an `action` (e.g. `genexus_db action=sql_ddl`); the detailed schemas live in [`src/GxMcp.Gateway/tool_definitions.json`](src/GxMcp.Gateway/tool_definitions.json).
+The worker exposes **48 tools** to the MCP router, grouped by capability below. Most are umbrellas with an `action` (e.g. `genexus_db action=sql_ddl`); the detailed schemas live in [`src/GxMcp.Gateway/tool_definitions.json`](src/GxMcp.Gateway/tool_definitions.json).
 
 **Orientation & health**
 - `genexus_whoami` — KB context, version, worker/index/database health, self-update check, next-step hints
@@ -268,7 +270,8 @@ produced by `DataSelectorStructurePart.ToString()` on U16.
 - `genexus_edit_form` — semantic WebForm edits
 - `genexus_variable` — Variables-part CRUD
 - `genexus_create` — creation umbrella (Transaction, Procedure, Domain, SDT, API, Folder, Module, `curl_procedure` = scaffold a Procedure from a curl command, …); `object_atomic` authors definition + variables + Rules + properties + Source with preflight/read-back/rollback
-- `genexus_delete_object` — delete an object
+- `genexus_data_view` — atomically create/inspect/update/delete a root-only Business Component Transaction mapped through a native Data View to an existing physical table; validates attributes/keys first, supports optimistic versions and true no-mutation dry-runs, requires `confirm=true` for destructive delete, and reports commit/verification state separately
+- `genexus_delete_object` — delete an object by native SDK identity; use `dryRun=true` to inspect incoming references before `confirm=true`
 - `genexus_format` — format a code snippet with the worker's rules
 
 **Data model & structure authoring**
@@ -427,21 +430,37 @@ Once you declare more than one KB in `Environment.KBs[]`, every tool accepts an
 ```
 
 Resolution rules when `kb` is omitted:
-- exactly 1 KB open → uses that KB
-- 0 KBs open + `DefaultKb` set → opens `DefaultKb` lazily
-- 2+ KBs open → server returns `KB_AMBIGUOUS` and you must pass `kb` explicitly
+- an explicit `kb` always wins; use it for parallel work or when a prompt touches more than one KB
+- each MCP session snapshots the configured `DefaultKb` at `initialize`; `set_default` changes the current session and persists the startup fallback for future sessions
+- `open` only starts/registers a Worker; it does not silently change another session's target. Select it with `set_default`, or pass `kb` explicitly
+- exactly 1 KB open → uses that KB when the session has no selection
+- 2+ KBs open with no session selection → server returns `KB_AMBIGUOUS`; choose one with `set_default` or pass `kb` explicitly
 
 Manage the pool at runtime:
 
 ```jsonc
 { "tool": "genexus_kb", "arguments": { "action": "list" } }
-// → { openKbs: [{alias, path, pid, workingSetMB, idleSeconds}], maxOpenKbs, defaultKb, declaredKbs }
+// → { selectedKb, activeKb, openKbs: [{alias, path, pid, workingSetMB, idleSeconds}], knownKbs, maxOpenKbs, defaultKb, declaredKbs }
 
 { "tool": "genexus_kb", "arguments": { "action": "open", "alias": "adhoc", "path": "C:/KBs/ScratchKB" } }
 { "tool": "genexus_kb", "arguments": { "action": "close", "alias": "legacy" } }
 { "tool": "genexus_kb", "arguments": { "action": "set_default", "alias": "main" } }   // persists to config.json
 ```
 
+For OpenCode, call `genexus_whoami` once at the start of a session. Use
+`kb.selected`, `kb.default`, `kb.openKbs`, `kb.knownKbs`, and `kb.declaredKbs`
+to understand the target, then select the normal working KB with
+`genexus_kb action=set_default`. Every KB-bound response also includes `kbAlias`
+in its JSON payload, which lets OpenCode correlate text-only responses. Keep
+`kb=<alias>` on calls that intentionally compare or update another KB.
+
+The installer registers both OpenCode configuration layouts: the legacy direct
+`mcp.genexus` entry used by OpenCode 1.x and the current `mcp.servers.genexus`
+layout. `clients add --clients opencode` is only needed to repair or explicitly
+re-register a client after installation; normal `init` handles detected clients
+automatically. Restart OpenCode after a registration so it reloads the MCP
+configuration.
+
 When the pool is full and no Worker is idle, the server returns `KB_POOL_FULL` — close one explicitly or raise `Server.MaxOpenKbs`. Each Worker carries the SDK in its own process (~200–400 MB idle, up to 1–2 GB on heavy KBs), so size the pool against available RAM.
 
 ### Architecture

package/cli/lib/config.js

@@ -413,6 +413,7 @@ function createConfigFile(kbPath, gxPath) {
     if (existing && existing.Environment) {
         if (existing.Environment.KBs) preservedEnv.KBs = existing.Environment.KBs;
         if (existing.Environment.ActiveKb) preservedEnv.ActiveKb = existing.Environment.ActiveKb;
+        if (existing.Environment.DefaultKb) preservedEnv.DefaultKb = existing.Environment.DefaultKb;
     }
     const nextConfig = {
         ...baseConfig,
@@ -868,7 +869,23 @@ function removeVsCodeServersJson(filePath) {
     return true;
 }
 
-// OpenCode (sst/opencode) uses `mcp.<name>` with `type: 'local'` and `command: string[]`.
+// OpenCode 1.x uses `mcp.<name>`, while the current v2 config nests servers under
+// `mcp.servers.<name>`. Keep the shape already present in the user's config so an
+// upgrade does not silently move or disable their other MCP servers.
+function getOpenCodeMcpContainer(cfgObj) {
+    if (!cfgObj.mcp || typeof cfgObj.mcp !== 'object' || Array.isArray(cfgObj.mcp)) {
+        cfgObj.mcp = {};
+    }
+    const nested = cfgObj.mcp.servers
+        && typeof cfgObj.mcp.servers === 'object'
+        && !Array.isArray(cfgObj.mcp.servers);
+    return {
+        mcp: cfgObj.mcp,
+        servers: nested ? cfgObj.mcp.servers : cfgObj.mcp,
+        nested: Boolean(nested)
+    };
+}
+
 function applyOpenCodeJson(filePath, launcher, targetConfigPath) {
     const parsed = fs.existsSync(filePath) ? readJsonFileSafe(filePath) : {};
     if (parsed === null) throw new Error('Invalid JSON');
@@ -876,14 +893,20 @@ function applyOpenCodeJson(filePath, launcher, targetConfigPath) {
     // 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 = {
+    const { mcp, servers, nested } = getOpenCodeMcpContainer(cfgObj);
+    servers.genexus = {
         type: 'local',
         command: [launcher.command, ...(launcher.args || [])],
         environment: { GX_CONFIG_PATH: targetConfigPath },
-        enabled: true
+        ...(nested ? { disabled: false } : { enabled: true })
     };
-    if (cfgObj.mcp.genexus18) delete cfgObj.mcp.genexus18;
+    if (servers.genexus18) delete servers.genexus18;
+    // If a config was migrated manually and contains both shapes, leave unrelated
+    // servers alone but remove our duplicate legacy entry.
+    if (nested) {
+        if (mcp.genexus) delete mcp.genexus;
+        if (mcp.genexus18) delete mcp.genexus18;
+    }
     writeClientJson(filePath, cfgObj);
 }
 
@@ -891,8 +914,23 @@ function removeOpenCodeJson(filePath) {
     const parsed = readJsonFileSafe(filePath);
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
-    if (!cfgObj.mcp || !cfgObj.mcp.genexus) return false;
-    delete cfgObj.mcp.genexus;
+    if (!cfgObj.mcp || typeof cfgObj.mcp !== 'object') return false;
+    let removedAny = false;
+    for (const key of ['genexus', 'genexus18']) {
+        if (cfgObj.mcp[key]) {
+            delete cfgObj.mcp[key];
+            removedAny = true;
+        }
+    }
+    if (cfgObj.mcp.servers && typeof cfgObj.mcp.servers === 'object' && !Array.isArray(cfgObj.mcp.servers)) {
+        for (const key of ['genexus', 'genexus18']) {
+            if (cfgObj.mcp.servers[key]) {
+                delete cfgObj.mcp.servers[key];
+                removedAny = true;
+            }
+        }
+    }
+    if (!removedAny) return false;
     writeClientJson(filePath, cfgObj);
     return true;
 }
@@ -993,7 +1031,7 @@ function readClientCommandEntry(client) {
         if (client.format === 'opencode') {
             const parsed = readJsonFileSafe(client.path);
             if (!parsed || typeof parsed !== 'object') return null;
-            const entry = parsed.mcp && parsed.mcp.genexus;
+            const entry = parsed.mcp?.servers?.genexus || parsed.mcp?.genexus;
             if (!entry || !Array.isArray(entry.command) || entry.command.length === 0) return null;
             return { command: entry.command[0], args: entry.command.slice(1) };
         }
@@ -1044,14 +1082,34 @@ function readGeneXusVersionFromInstall(gxPath) {
     return null;
 }
 
+function normalizeKbCatalog(raw) {
+    if (Array.isArray(raw)) {
+        const normalized = {};
+        for (const entry of raw) {
+            if (!entry || typeof entry !== 'object') continue;
+            const name = typeof entry.alias === 'string' ? entry.alias : entry.Alias;
+            const kbPath = typeof entry.path === 'string' ? entry.path : entry.Path;
+            if (typeof name === 'string' && name && typeof kbPath === 'string' && kbPath) {
+                normalized[name] = kbPath;
+            }
+        }
+        return normalized;
+    }
+
+    return raw && typeof raw === 'object' ? raw : {};
+}
+
 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 || {};
+    const activeKb = typeof env.ActiveKb === 'string' && env.ActiveKb
+        ? env.ActiveKb
+        : (typeof env.DefaultKb === 'string' && env.DefaultKb ? env.DefaultKb : null);
     return {
-        kbs: (env.KBs && typeof env.KBs === 'object') ? env.KBs : {},
-        activeKb: typeof env.ActiveKb === 'string' ? env.ActiveKb : null,
+        kbs: normalizeKbCatalog(env.KBs),
+        activeKb,
         kbPath: typeof env.KBPath === 'string' ? env.KBPath : null
     };
 }
@@ -1060,8 +1118,13 @@ 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 (activeKb) {
+        cfg.Environment.ActiveKb = activeKb;
+        cfg.Environment.DefaultKb = activeKb;
+    } else {
+        delete cfg.Environment.ActiveKb;
+        delete cfg.Environment.DefaultKb;
+    }
     if (kbPath) cfg.Environment.KBPath = kbPath;
     else delete cfg.Environment.KBPath;
     writeFileAtomic(configPath, JSON.stringify(cfg, null, 2));

package/cli/run.test.js

@@ -285,6 +285,61 @@ test('kb list shows the KB auto-registered by init', () => {
     fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
+test('kb list reads gateway-style KB arrays and DefaultKb', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbA = path.join(tempRoot, 'kb-array-a');
+    const kbB = path.join(tempRoot, 'kb-array-b');
+    fs.mkdirSync(kbA, { recursive: true });
+    fs.mkdirSync(kbB, { recursive: true });
+    fs.writeFileSync(path.join(tempRoot, 'config.json'), JSON.stringify({
+        Environment: {
+            DefaultKb: 'legacy',
+            KBs: [
+                { Alias: 'main', Path: kbA },
+                { alias: 'legacy', path: kbB }
+            ]
+        }
+    }));
+
+    const res = runCli(['kb', 'list', '--format', 'json'], { cwd: tempRoot });
+    assert.equal(res.status, 0);
+    const parsed = JSON.parse(res.stdout);
+    assert.equal(parsed.ok.activeKb, 'legacy');
+    assert.deepEqual(parsed.ok.kbs.map((entry) => entry.name), ['main', 'legacy']);
+    assert.equal(parsed.ok.kbs[1].active, true);
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('kb switch preserves gateway-style array entries', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
+    const kbA = path.join(tempRoot, 'kb-switch-a');
+    const kbB = path.join(tempRoot, 'kb-switch-b');
+    fs.mkdirSync(kbA, { recursive: true });
+    fs.mkdirSync(kbB, { recursive: true });
+    const configPath = path.join(tempRoot, 'config.json');
+    fs.writeFileSync(configPath, JSON.stringify({
+        Environment: {
+            DefaultKb: 'main',
+            KBs: [
+                { Alias: 'main', Path: kbA },
+                { Alias: 'legacy', Path: kbB }
+            ]
+        }
+    }));
+
+    const res = runCli(['kb', 'switch', '--name', 'legacy', '--format', 'json'], { cwd: tempRoot });
+    assert.equal(res.status, 0);
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    assert.deepEqual(Object.keys(cfg.Environment.KBs).sort(), ['legacy', 'main']);
+    assert.equal(cfg.Environment.KBs.main, kbA);
+    assert.equal(cfg.Environment.KBs.legacy, kbB);
+    assert.equal(cfg.Environment.ActiveKb, 'legacy');
+    assert.equal(cfg.Environment.DefaultKb, 'legacy');
+
+    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');
@@ -380,6 +435,7 @@ test('kb remove of last KB clears legacy KBPath', () => {
     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');
+    assert.equal(cfg.Environment.DefaultKb, undefined, 'DefaultKb should be cleared');
 
     fs.rmSync(tempRoot, { recursive: true, force: true });
 });
@@ -734,6 +790,103 @@ test('clients add tolerates a JSONC (commented) VS Code mcp.json', () => {
     fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
+test('clients add preserves OpenCode 1.x direct mcp shape', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-opencode-v1-'));
+    const env = sandboxHomeEnv(tempRoot);
+    const cfgPath = path.join(tempRoot, 'config.json');
+    const openCodeCfg = path.join(env.XDG_CONFIG_HOME, 'opencode', 'opencode.json');
+    fs.mkdirSync(path.dirname(openCodeCfg), { recursive: true });
+    fs.writeFileSync(cfgPath, JSON.stringify({ Environment: { KBPath: tempRoot } }));
+    fs.writeFileSync(openCodeCfg, JSON.stringify({
+        mcp: { other: { type: 'local', command: ['other-tool'] } }
+    }, null, 2));
+
+    const res = runCli(['clients', 'add', '--clients', 'opencode', '--format', 'json'], {
+        env: { ...env, GX_CONFIG_PATH: cfgPath }
+    });
+    assert.equal(res.status, 0);
+    const written = JSON.parse(fs.readFileSync(openCodeCfg, 'utf8'));
+    assert.ok(written.mcp.genexus, 'direct OpenCode entry should be written');
+    assert.equal(written.mcp.genexus.enabled, true);
+    assert.equal(written.mcp.genexus.disabled, undefined);
+    assert.ok(written.mcp.other, 'unrelated direct MCP server should be preserved');
+    assert.equal(written.mcp.servers, undefined);
+    assert.deepEqual(written.mcp.genexus.environment, { GX_CONFIG_PATH: cfgPath });
+
+    const listed = runCli(['clients', '--format', 'json'], { env });
+    assert.equal(listed.status, 0);
+    const row = JSON.parse(listed.stdout).ok.clients.find((client) => client.id === 'opencode');
+    assert.ok(row && row.registered, 'clients list should read the direct OpenCode entry');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('clients add preserves OpenCode v2 nested mcp.servers shape', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-opencode-v2-'));
+    const env = sandboxHomeEnv(tempRoot);
+    const cfgPath = path.join(tempRoot, 'config.json');
+    const openCodeCfg = path.join(env.XDG_CONFIG_HOME, 'opencode', 'opencode.json');
+    fs.mkdirSync(path.dirname(openCodeCfg), { recursive: true });
+    fs.writeFileSync(cfgPath, JSON.stringify({ Environment: { KBPath: tempRoot } }));
+    fs.writeFileSync(openCodeCfg, JSON.stringify({
+        mcp: { servers: { other: { type: 'local', command: ['other-tool'] } } }
+    }, null, 2));
+
+    const res = runCli(['clients', 'add', '--clients', 'opencode', '--format', 'json'], {
+        env: { ...env, GX_CONFIG_PATH: cfgPath }
+    });
+    assert.equal(res.status, 0);
+    const written = JSON.parse(fs.readFileSync(openCodeCfg, 'utf8'));
+    assert.ok(written.mcp.servers.genexus, 'nested OpenCode entry should be written');
+    assert.equal(written.mcp.servers.genexus.disabled, false);
+    assert.equal(written.mcp.servers.genexus.enabled, undefined);
+    assert.ok(written.mcp.servers.other, 'unrelated nested MCP server should be preserved');
+    assert.equal(written.mcp.genexus, undefined);
+    assert.deepEqual(written.mcp.servers.genexus.environment, { GX_CONFIG_PATH: cfgPath });
+
+    const listed = runCli(['clients', '--format', 'json'], { env });
+    assert.equal(listed.status, 0);
+    const row = JSON.parse(listed.stdout).ok.clients.find((client) => client.id === 'opencode');
+    assert.ok(row && row.registered, 'clients list should read the nested OpenCode entry');
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('init auto-registers detected OpenCode in either config layout', () => {
+    for (const [label, mcp] of [
+        ['direct', { other: { type: 'local', command: ['other-tool'] } }],
+        ['nested', { servers: { other: { type: 'local', command: ['other-tool'] } } }]
+    ]) {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), `genexus-mcp-opencode-init-${label}-`));
+        try {
+            const env = sandboxHomeEnv(tempRoot);
+            const kbDir = path.join(tempRoot, 'kb');
+            const openCodeCfg = path.join(env.XDG_CONFIG_HOME, 'opencode', 'opencode.json');
+            fs.mkdirSync(kbDir, { recursive: true });
+            fs.mkdirSync(path.dirname(openCodeCfg), { recursive: true });
+            fs.writeFileSync(openCodeCfg, JSON.stringify({ mcp }, null, 2));
+
+            const result = runCli(
+                ['init', '--kb', kbDir, '--gx', testGxPath, '--no-smoke', '--format', 'json'],
+                { cwd: kbDir, env: { ...env, ...testGatewayEnv } }
+            );
+            assert.equal(result.status, 0, `${label} OpenCode init should succeed: ${result.stderr}`);
+
+            const parsed = JSON.parse(result.stdout);
+            assert.ok(parsed.ok.clientsPatchedCount >= 1, `${label} OpenCode should be auto-registered`);
+            assert.ok(parsed.meta.patchedClients.includes('OpenCode (CLI)'));
+
+            const written = JSON.parse(fs.readFileSync(openCodeCfg, 'utf8'));
+            const entry = label === 'nested' ? written.mcp.servers.genexus : written.mcp.genexus;
+            assert.ok(entry, `${label} OpenCode entry should be present after init`);
+            assert.deepEqual(entry.environment, { GX_CONFIG_PATH: path.join(kbDir, 'config.json') });
+            assert.ok(label === 'nested' ? written.mcp.servers.other : written.mcp.other);
+        } finally {
+            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);
@@ -825,6 +978,35 @@ test('clients remove drops the genexus entry (sandbox home)', () => {
     fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
+test('clients remove drops both OpenCode config shapes and legacy key', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-opencode-rm-'));
+    const env = sandboxHomeEnv(tempRoot);
+    const openCodeCfg = path.join(env.XDG_CONFIG_HOME, 'opencode', 'opencode.json');
+    fs.mkdirSync(path.dirname(openCodeCfg), { recursive: true });
+    fs.writeFileSync(openCodeCfg, JSON.stringify({
+        mcp: {
+            genexus: { type: 'local', command: ['old'] },
+            genexus18: { type: 'local', command: ['older'] },
+            servers: {
+                genexus: { type: 'local', command: ['nested'] },
+                genexus18: { type: 'local', command: ['nested-old'] },
+                other: { type: 'local', command: ['other'] }
+            }
+        }
+    }, null, 2));
+
+    const res = runCli(['clients', 'remove', '--clients', 'opencode', '--format', 'json'], { env });
+    assert.equal(res.status, 0);
+    const written = JSON.parse(fs.readFileSync(openCodeCfg, 'utf8'));
+    assert.equal(written.mcp.genexus, undefined);
+    assert.equal(written.mcp.genexus18, undefined);
+    assert.equal(written.mcp.servers.genexus, undefined);
+    assert.equal(written.mcp.servers.genexus18, undefined);
+    assert.ok(written.mcp.servers.other, 'unrelated nested MCP server should be preserved');
+
+    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/package.json

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

package/publish/config.json

@@ -3,15 +3,15 @@
     "HttpPort": 5000,
     "McpStdio": true
   },
-  "Logging": {
-    "Level": "Debug",
-    "Path": "logs"
-  },
   "GeneXus": {
-    "WorkerExecutable": "C:\\Projetos\\Genexus18MCP\\publish\\\\worker\\\\GxMcp.Worker.exe",
-    "InstallationPath": "C:\\\\Program Files (x86)\\\\GeneXus\\\\GeneXus18"
+    "InstallationPath": "C:\\\\Program Files (x86)\\\\GeneXus\\\\GeneXus18",
+    "WorkerExecutable": "C:\\Projetos\\Genexus18MCP\\publish\\\\worker\\\\GxMcp.Worker.exe"
   },
   "Environment": {
     "KBPath": "C:\\\\KBs\\\\YourKB"
+  },
+  "Logging": {
+    "Level": "Debug",
+    "Path": "logs"
   }
 }

package/publish/tool_definitions.json

@@ -1,4 +1,5 @@
 [
+  {"name":"genexus_data_view","description":"Native, typed, atomic Transaction + Data View authoring over an existing physical table. action=inspect|dry_run|create|update|delete. dry_run performs validation without constructing or saving SDK objects. create/update persist the root-only Transaction and Data View, then reread and verify the committed pair; commit and verification status are reported separately. action=delete is destructive and requires confirm=true when dryRun=false. No action implicitly runs Specify, Generate, Build, Rebuild, Reorg, compilation, publish, execution, or tests; the response includes a no-DDL reorg preview.","inputSchema":{"type":"object","required":["action","transaction","dataViewName"],"additionalProperties":false,"properties":{"action":{"type":"string","enum":["inspect","dry_run","create","update","delete"]},"transaction":{"type":"string","description":"Root-only Transaction name."},"dataViewName":{"type":"string","description":"Data View name associated with the Transaction logical table."},"dataStore":{"type":"string","description":"Existing GeneXus data store category (default Default)."},"schema":{"type":"string","description":"Existing physical schema."},"table":{"type":"string","description":"Existing physical table and GeneXus table-metadata name."},"attributeMappings":{"type":"array","items":{"type":"object","required":["attribute","column"],"additionalProperties":false,"properties":{"attribute":{"type":"string"},"column":{"type":"string"},"key":{"type":"boolean","default":false}}}},"updatable":{"type":"boolean","default":true},"expectedVersion":{"type":"string","description":"Optimistic concurrency token returned by inspect/dry_run/create/update/delete preview."},"dryRun":{"type":"boolean","default":false,"description":"Forces every action to remain read-only; create/update validate their complete definition and delete returns a deletion preview."},"confirm":{"type":"boolean","description":"Required for action=delete when dryRun=false; explicitly authorizes removing the Transaction and Data View."},"rollbackOnFailure":{"type":"boolean","default":true,"description":"Atomic SDK rollback is always enforced; this flag records the caller's rollback intent."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"dry_run","transaction":"LedgerEntryView","dataViewName":"LedgerEntryDV","dataStore":"Default","schema":"APP","table":"LEDGERENTRY","updatable":true,"attributeMappings":[{"attribute":"LedgerEntryId","column":"LedgerEntryId","key":true},{"attribute":"LedgerEntryAmount","column":"LedgerEntryAmount"}],"rollbackOnFailure":true},{"action":"delete","transaction":"LedgerEntryView","dataViewName":"LedgerEntryDV","confirm":true}]} ,"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_whoami","description":"KB context + version + health (worker/index/database) + next-step hints. Call FIRST every session. Lean by default; pass verbose=true ONCE for the inline playbooks + skills catalog of verified GeneXus reference resources (navigation, GAM, SD panel, WebPanel events). For a minimal connection+index health check use genexus_doctor.","inputSchema":{"type":"object","properties":{"verbose":{"type":"boolean","description":"Include the static playbooks + skills catalog + per-tool stats/heatmap. Default false (lean health payload)."}},"additionalProperties":false,"examples":[{},{"verbose":true}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_recipe","description":"Named playbooks + self-extending macros. action=list|describe|run|suggest_macro|crystallize.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Recipe key (latest version), 'name@v1' (pinned), or 'list'."},"action":{"type":"string","enum":["list","describe","run","suggest_macro","crystallize"],"description":"suggest_macro: detect repeated sequences; crystallize: save one as a recipe."},"windowMinutes":{"type":"integer","description":"suggest_macro: history window (default 30)."},"minRepetitions":{"type":"integer","description":"suggest_macro: threshold (default 3)."},"macroName":{"type":"string","description":"crystallize: proposed name from suggest_macro."},"description":{"type":"string","description":"crystallize: human-readable description."}},"examples":[{"name":"list"},{"name":"wwp_on_transaction"},{"action":"suggest_macro"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_query","description":"Search objects in active KB. Prefixes: name:, type:, usedby:, parent:, parentPath:, description:. name:\"X\" (or bare quoted \"X\") demands exact-name match — use it when you know the object's name. Compact by default. See genexus://kb/tool-help/genexus_query. Requires the KB index to be Ready — check genexus_lifecycle action=status if results look empty.","inputSchema":{"type":"object","properties":{"query":{"type":"string"},"typeFilter":{"type":"string"},"domainFilter":{"type":"string"},"limit":{"type":"integer"},"inline_read_top":{"type":"integer","description":"0-3. Inline reads of top N."},"sort":{"type":"string","enum":["relevance","lastUpdate"],"description":"relevance (default) or lastUpdate (newest first; bypasses score ranking)."},"since":{"type":"string","description":"ISO-8601 UTC. Only items with lastUpdate >= since."},"modifiedBefore":{"type":"string","description":"ISO-8601 UTC. Only items with lastUpdate < modifiedBefore."},"cursor":{"type":"string","description":"Opaque token from prior nextCursor. Use with sort=lastUpdate for stable paging."},"kb":{"type":"string","description":"KB alias."},"axiCompact":{"type":"boolean","description":"Compact projection (default true).","default":true}},"required":["query"],"examples":[{"query":"type:Transaction parent:Customers"},{"query":"\"Customer\"","limit":5}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
@@ -11,18 +12,18 @@
   {"name":"genexus_test","description":"Execute native GeneXus tests (GXtest).","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"kb":{"type":"string","description":"KB alias."}},"required":["name"],"examples":[{"name":"MyTestProc"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},
   {"name":"genexus_sdk_probe","description":"Dump SDK surface (types/methods/props) to docs/sdk-probe/. Use when hunting for entry points.","inputSchema":{"type":"object","properties":{"outputDir":{"type":"string","description":"Absolute path. Default <repo>/docs/sdk-probe/."}},"examples":[{}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_worker_reload","description":"Reload worker. modes: soft (drain+respawn), hard (copy sourceDir+respawn). force=true: gateway kills directly. See tool-help.","inputSchema":{"type":"object","properties":{"mode":{"type":"string","enum":["soft","hard"]},"force":{"type":"boolean","description":"Bypass drain; gateway kills + respawns. Use when worker is wedged."},"sourceDir":{"type":"string","description":"Required for mode=hard."},"drainTimeoutMs":{"type":"integer","description":"Soft only; default 30000."}},"examples":[{"mode":"soft"},{"mode":"hard","sourceDir":"C:\\Projetos\\Genexus18MCP\\src\\GxMcp.Worker\\bin\\Debug"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},
-  {"name":"genexus_delete_object","description":"Delete an object from the KB. Irreversible — confirm=true required. dryRun=true returns what would be deleted without persisting.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"confirm":{"type":"boolean"},"dryRun":{"type":"boolean","default":false,"description":"When true, returns the object that would be deleted without deleting it."},"kb":{"type":"string","description":"KB alias."}},"required":["name","confirm"],"examples":[{"name":"ObsoletePanel","type":"WebPanel","confirm":true},{"name":"ObsoletePanel","type":"WebPanel","confirm":true,"dryRun":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}},
+  {"name":"genexus_delete_object","description":"Delete an object from the KB through its native SDK identity. Irreversible — confirm=true required. Inspects native incoming references first; dryRun=true previews without persisting.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"confirm":{"type":"boolean"},"dryRun":{"type":"boolean","default":false,"description":"When true, returns the resolved object and native references without deleting it."},"expectedVersion":{"type":"string","description":"Optional optimistic-concurrency token returned by a prior dry run."},"kb":{"type":"string","description":"KB alias."}},"required":["name","confirm"],"examples":[{"name":"ObsoletePanel","type":"WebPanel","confirm":true},{"name":"TemporaryDomain","type":"Domain","confirm":true,"dryRun":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_refactor","description":"Run GeneXus refactor: rename, extract procedure, extract local subroutine, or WWP condition set. For KB-wide rename with call-site patching (RenameObject/RenameAttribute), the response includes a patched-site count from RefactorService. dryRun=true previews what would change without persisting.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["RenameAttribute","RenameVariable","RenameObject","ExtractProcedure","ExtractSubroutine","WWPSetCondition"]},"target":{"type":"string","description":"Primary object or symbol to refactor."},"newName":{"type":"string"},"objectName":{"type":"string"},"code":{"type":"string"},"procedureName":{"type":"string"},"subroutineName":{"type":"string"},"controlAttribute":{"type":"string"},"value":{"type":"string"},"type":{"type":"string","description":"RenameObject: object type (e.g. WebPanel, Transaction, Procedure) to disambiguate when several objects share the name — e.g. a WebPanel vs the same-named Table behind a Transaction. Ignored by RenameAttribute/RenameVariable."},"dryRun":{"type":"boolean","default":false,"description":"When true, returns what would be changed without persisting."},"kb":{"type":"string","description":"KB alias."}},"required":["action"],"examples":[{"action":"RenameObject","target":"Customer","newName":"Client"},{"action":"RenameAttribute","target":"CustomerId","newName":"ClientId"},{"action":"ExtractSubroutine","target":"Customer","code":"&Total = 0","subroutineName":"ResetTotal"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_run_object","description":"Resolve runtime URL for an object (webRoot + aspx + encoded args). gamSession='auto'|{user,pass,...} captures GAM cookies. Does NOT open a browser. dryRun=true returns the resolved URL without performing GAM login.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"args":{"type":"array","items":{"type":"string"},"description":"Positional parameter values."},"gamSession":{"description":"'auto' (use GXMCP_GAM_USER/PASS env) or {user, pass, repository?, loginUrl?}."},"dryRun":{"type":"boolean","default":false,"description":"When true, returns the resolved URL without performing the GAM login step."},"kb":{"type":"string","description":"KB alias."}},"required":["name"],"examples":[{"name":"WPMain"},{"name":"WPCustomer","args":["42"]}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},
   {"name":"genexus_format","description":"Format a GeneXus code snippet using worker rules.","inputSchema":{"type":"object","properties":{"code":{"type":"string"},"kb":{"type":"string","description":"KB alias."}},"required":["code"],"examples":[{"code":"for each Customer where CustomerId = &Id\n  &Name = CustomerName\nendfor"}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_gam","description":"GAM / integrated-security provisioning via the SDK's IIntegratedSecurityService — distinct from genexus_security (env-scan/regex audit). action=status (default) is read-only: IsEnabledIntegratedSecurity + GAM-DB-reorganize flag. action=define_api / action=deploy are DESTRUCTIVE — they create/alter GAM security tables in the KB's datastore; no default reaches them, action must be set explicitly.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["status","define_api","deploy"],"description":"status (default, read-only) | define_api | deploy."},"force":{"type":"boolean","description":"define_api only: force flag passed to DefineAPI."},"forceTableCreation":{"type":"boolean","description":"deploy only: force GAM table creation."},"rebuild":{"type":"boolean","description":"deploy only: rebuild flag."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"status"},{"action":"deploy","forceTableCreation":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_properties","description":"Read/update object properties. action=get|set|move. move snapshots every persisted part, checks baseVersion, verifies inside the SDK transaction and after commit, and rolls back divergence. Use destination for a Folder/Module or targetModule for a Module; destKind disambiguates equal names. dryRun does not save or change the token. Move never runs lifecycle, compilation, execution, or tests. Description is the WebPanel/Popup title-bar text. Use genexus_layout set_property for layout controls.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get","set","move"]},"name":{"type":"string"},"type":{"type":"string","description":"Optional object type disambiguator."},"control":{"type":"string","description":"Optional. Layout control name (e.g. BtnConfirmar), variable name with & prefix (e.g. &Alu2RegProf), or attribute name."},"propertyName":{"type":"string"},"value":{"type":"string"},"destination":{"type":"string","description":"move: target Folder/Module name (auto-detects kind)."},"targetModule":{"type":"string","description":"move: typed alias for a Module destination."},"destKind":{"type":"string","enum":["Folder","Module"],"description":"move: disambiguate when a Folder and Module share a name."},"dryRun":{"type":"boolean","description":"move: preview from/to and preserved parts without persisting."},"baseVersion":{"type":"string","description":"move: opaque optimistic concurrency token returned by a prior read."},"validationMode":{"type":"string","enum":["specify"],"description":"Issue #60: with action=set, run the inline Specify pass (Spec+Gen, no Compile) after the property write, returning structured spc*/gen* diagnostics in the same call. Combines with rollbackOnFailure."},"rollbackOnFailure":{"type":"boolean","description":"move: attempt compensating snapshot restoration if the SDK transaction rollback is insufficient (default true). set+validationMode=specify: request rollback after validation failure."},"kb":{"type":"string","description":"KB alias."}},"required":["action","name"],"examples":[{"action":"get","name":"MyPanel"},{"action":"move","name":"InvoiceHelper","type":"Procedure","targetModule":"operacional","baseVersion":"<versionToken from genexus_read>","dryRun":true,"rollbackOnFailure":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
-  {"name":"genexus_structure","description":"Read or write the structure/data-model of GeneXus objects. Read: get_visual, get_logic, get_indexes (source=User indexes are droppable; response includes versionToken). Write: move_attribute reorders the existing native TransactionAttribute; update_visual authors a Transaction/SDT structure; update_group edits SubType Group membership; create_index plans or creates an index with optimistic concurrency, exact post-save verification and rollback; drop_index removes an index; remove_attribute detaches a TransactionAttribute from a level via the native TransactionLevel.Items storage (preserving the KB-global Attribute and every SubtypeGroup membership) so agents can drop + re-add a misclassified subtype attribute to force re-derivation; check_subtypes runs the issue #97 guard-rail — flags subtype attributes (IS_SUBTYPE=True) classified as stored (SECONDARY) while their same-supertype siblings on the same level are derived (INFERRED), which silently creates a physical column and breaks supertype propagation; set_attribute, set_level, and set_domain edit SDK properties. move_attribute and create_index never run Specify, Generate, Build, Rebuild, compilation, reorganization, execution, tests, or Pattern application. Run genexus_lifecycle action=reorg separately after persisted index/type changes. For layout control trees use genexus_layout.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get_visual","update_visual","get_indexes","create_index","drop_index","set_attribute","set_level","set_domain","get_logic","update_group","move_attribute","remove_attribute","check_subtypes"]},"name":{"type":"string","description":"Object name. move_attribute: Transaction name; create_index/get_indexes: Transaction or Table name; set_attribute: attribute name; set_domain: domain name."},"module":{"type":"string","description":"move_attribute optional: Transaction module."},"attribute":{"type":"string","description":"move_attribute: existing attribute to reorder by native SDK identity."},"before":{"type":"string","description":"move_attribute: place attribute before this attribute in the same level. Mutually exclusive with after/position."},"after":{"type":"string","description":"move_attribute: place attribute after this attribute in the same level. Mutually exclusive with before/position."},"position":{"type":"integer","minimum":0,"description":"move_attribute: zero-based final attribute position in the level. Mutually exclusive with before/after."},"level":{"type":"string","description":"move_attribute: root (default) or an unambiguous subordinate level name."},"levelPath":{"type":"array","items":{"type":"string"},"description":"move_attribute: nested level path, e.g. [\"Item\",\"Operation\"]."},"dryRun":{"type":"boolean","default":false,"description":"move_attribute/create_index: validate and return the projected diff without saving. create_index re-reads the SDK state and reports DryRunMutationDetected if persistence changed."},"baseVersion":{"type":"string","description":"move_attribute/create_index optimistic-concurrency token. For create_index, use versionToken returned by get_indexes; stale state returns VersionConflict before mutation."},"payload":{"type":"object","description":"update_visual (Transaction):{children:[...]}; update_visual (SDT):{isCollection?,collectionItemName?,children:[{name,type?,length?,decimals?,basedOnDomain?,isCollection?,isLevel?,children?}]}. update_group:{members:[{name,subtypeOf}],remove?:[name]}. create_index:{attributes:[\"Attr\"],unique?:true,name?,order?:\"Ascending\"|\"Descending\"}; requested attribute order is preserved. drop_index:{indexName}. set_attribute:{formula?,subtypeOf?,title?,columnTitle?,contextualTitle?,isCollection?,basedOnDomain?}. set_level:{level?,descriptionAttribute?,imageAttribute?}. set_domain:{enumValues:[{name,value,description?}],dataType?,length?,decimals?,signed?}."},"validationMode":{"type":"string","enum":["specify"],"description":"Issue #60: run the inline Specify pass (Spec+Gen, no Compile) after update_visual/set_domain/set_attribute/set_level/update_group. Not accepted by move_attribute/create_index."},"rollbackOnFailure":{"type":"boolean","default":true,"description":"create_index: restore the captured index snapshot if save or exact post-save verification fails. move_attribute always snapshots and rolls back automatically on failed integrity checks."},"kb":{"type":"string","description":"KB alias."}},"required":["action","name"],"examples":[{"action":"move_attribute","name":"SampleTransaction","attribute":"SampleSubtypeId","after":"SampleReferenceId","level":"root","dryRun":true},{"action":"move_attribute","name":"SampleTransaction","attribute":"NestedDescription","after":"NestedId","levelPath":["Item","Operation"]},{"action":"get_indexes","name":"Customer"},{"action":"create_index","name":"Country","dryRun":true,"baseVersion":"<get_indexes versionToken>","payload":{"name":"UCountryName","attributes":["CountryName"],"unique":true},"rollbackOnFailure":true},{"action":"set_attribute","name":"CustomerBalance","payload":{"formula":"sum(SampleTransactionAmount)"}},{"action":"set_level","name":"Customer","payload":{"descriptionAttribute":"CustomerName"}},{"action":"update_visual","name":"MySdt","payload":{"isCollection":true,"collectionItemName":"MySdtItem","children":[{"name":"Title","type":"VarChar","length":100},{"name":"Kind","basedOnDomain":"MyDomain"}]}},{"action":"update_group","name":"gst_orgao_exercicio","payload":{"members":[{"name":"orgao_exercicio_id","subtypeOf":"exercicio_id"},{"name":"orgao_exercicio","subtypeOf":"exercicio"}]}}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
+  {"name":"genexus_structure","description":"Read or write the structure/data-model of GeneXus objects. update_visual now snapshots every part, checks optimistic concurrency, saves and re-reads the Transaction, and restores the complete snapshot when persistence or authored-part verification fails. Default form projections are allowed to follow Structure; user-authored forms are invariant. No structure action implicitly runs Specify, Generate, Build, Rebuild, compilation, reorganization, execution, or tests. Other actions cover indexes, attributes, levels, Domains, SubType Groups and subtype consistency. For layout control trees use genexus_layout.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get_visual","update_visual","get_indexes","create_index","drop_index","set_attribute","set_level","set_domain","get_logic","update_group","move_attribute","remove_attribute","check_subtypes"]},"name":{"type":"string","description":"Object name. update_visual/move_attribute: Transaction name; create_index/get_indexes: Transaction or Table name."},"module":{"type":"string","description":"update_visual/move_attribute optional: Transaction module."},"attribute":{"type":"string","description":"move_attribute: existing attribute to reorder by native SDK identity."},"before":{"type":"string","description":"move_attribute: place attribute before this attribute in the same level. Mutually exclusive with after/position."},"after":{"type":"string","description":"move_attribute: place attribute after this attribute in the same level. Mutually exclusive with before/position."},"position":{"type":"integer","minimum":0,"description":"move_attribute: zero-based final attribute position in the level. Mutually exclusive with before/after."},"level":{"type":"string","description":"move_attribute: root (default) or an unambiguous subordinate level name."},"levelPath":{"type":"array","items":{"type":"string"},"description":"move_attribute: nested level path, e.g. [\"Item\",\"Operation\"]."},"dryRun":{"type":"boolean","default":false,"description":"update_visual/move_attribute/create_index: validate and return the projected diff without changing any object, Attribute, hash, or version."},"baseVersion":{"type":"string","description":"Optimistic-concurrency token for update_visual/move_attribute/create_index. Stale state returns VersionConflict before mutation."},"expectedVersion":{"type":"string","description":"Alias of baseVersion for update_visual."},"payload":{"type":"object","description":"update_visual (Transaction):{children:[...]}; update_visual (SDT):{isCollection?,collectionItemName?,children:[{name,type?,length?,decimals?,basedOnDomain?,isCollection?,isLevel?,children?}]}. update_group:{members:[{name,subtypeOf}],remove?:[name]}. create_index:{attributes:[\"Attr\"],unique?:true,name?,order?:\"Ascending\"|\"Descending\"}. Other actions keep their existing typed payloads."},"validationMode":{"type":"string","enum":["specify"],"description":"Explicitly run the inline Specify pass after selected writes. Never runs unless requested."},"rollbackOnFailure":{"type":"boolean","default":true,"description":"update_visual, move_attribute and create_index capture snapshots and verify rollback after any save or re-read divergence."},"kb":{"type":"string","description":"KB alias."}},"required":["action","name"],"examples":[{"action":"update_visual","name":"OrderRecord","module":"Operations","dryRun":true,"expectedVersion":"<versionToken>","payload":{"children":[{"name":"OrderId"},{"name":"OrderAverageTime"}]}},{"action":"move_attribute","name":"SampleTransaction","attribute":"SampleSubtypeId","after":"SampleReferenceId","level":"root","dryRun":true},{"action":"get_indexes","name":"Customer"},{"action":"create_index","name":"Country","dryRun":true,"baseVersion":"<get_indexes versionToken>","payload":{"name":"UCountryName","attributes":["CountryName"],"unique":true},"rollbackOnFailure":true},{"action":"set_attribute","name":"CustomerBalance","payload":{"formula":"sum(SampleTransactionAmount)"}},{"action":"set_level","name":"Customer","payload":{"descriptionAttribute":"CustomerName"}},{"action":"update_group","name":"SampleSubtypeGroup","payload":{"members":[{"name":"SampleId","subtypeOf":"BaseId"}]}}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_authoring","description":"Author members of object types the structure DSL doesn't cover. add_external_method / add_external_property add a method (with parameters) or property to an External Object; add_menu_option adds an option to a Menu (target = a KB object to call); add_condition adds a filter expression to a Data Selector. name = the target object.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["add_external_method","add_external_property","add_menu_option","add_condition"]},"name":{"type":"string","description":"ExternalObject / Menu / DataSelector name."},"payload":{"type":"object","description":"add_external_method:{name,returnType?,parameters?:[{name,type?,inout?}]}. add_external_property:{name,type?}. add_menu_option:{description,target?,optionCode?}. add_condition:{source}."},"kb":{"type":"string","description":"KB alias."}},"required":["action","name"],"examples":[{"action":"add_external_property","name":"MyExternalObject","payload":{"name":"apiKey","type":"Character"}},{"action":"add_menu_option","name":"MainMenu","payload":{"description":"Customers","target":"CustomerWW"}},{"action":"add_condition","name":"ActiveCustomers","payload":{"source":"CustomerActive = True"}}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_layout","description":"SDK layout/WebForm ops: get_tree, set_property, find_controls, inspect_surface, scan_mutators. For object-level properties use genexus_properties; for object-level visual structure use genexus_structure get_visual.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get_tree","set_property","find_controls","set_properties","inspect_surface","get_preview","scan_mutators","rename_printblock","add_printblock","list_controls","design_system"]},"name":{"type":"string"},"control":{"type":"string"},"propertyName":{"type":"string"},"value":{"type":"string"},"query":{"type":"string"},"changes":{"type":"array","items":{"type":"object","properties":{"control":{"type":"string"},"propertyName":{"type":"string"},"value":{"type":"string"}},"required":["control","propertyName","value"]}},"limit":{"type":"integer"},"currentName":{"type":"string"},"newName":{"type":"string"},"printBlockName":{"type":"string"},"height":{"type":"integer"},"kb":{"type":"string","description":"KB alias."}},"required":["action"],"examples":[{"action":"get_tree","name":"WPMain"},{"action":"find_controls","name":"WPMain","query":"Button"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_doc","description":"Use to generate structured docs (wiki, sequence diagrams, health reports). Don't use for programmatic analysis (see genexus_analyze) or source (see genexus_read).","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["wiki","visualize","health"]},"target":{"type":"string","description":"Object or domain name."}},"required":["action"],"examples":[{"action":"wiki","target":"Customer"},{"action":"health"}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_search_source","description":"Regex/semantic search across Procedure/DataProvider/WebPanel/Transaction source. Requires the KB index to be Ready — check genexus_lifecycle action=status if results look empty.","inputSchema":{"type":"object","properties":{"callee":{"type":"string","description":"Method/function name (qualified or unqualified)."},"argMatches":{"type":"object","description":"Positional arg index to expected literal text."},"pattern":{"type":"string"},"typeFilter":{"type":"string"},"objectName":{"type":"string","description":"Restrict the scan to these exact object name(s), comma-separated. Makes a search inside one known object O(object) not O(KB), and bypasses the type whitelist."},"startIndex":{"type":"integer","description":"Legacy object-boundary resume. For a page that ended inside an object, prefer the opaque cursor returned in nextCursor."},"cursor":{"type":"string","description":"Opaque continuation token from nextCursor; preferred when a result page ended inside an object. Do not edit."},"timeoutMs":{"type":"integer","description":"Wall-clock budget (default 30000). Raise it to scan more objects per call."},"scope":{"type":"array","items":{"type":"string","enum":["source","rules","conditions","events","webForm","layout"]},"description":"Parts to scan with line-numbered context. Default [source]. webForm/layout scans the WebPanel/Transaction visual XML (control names, captions, classes, bindings)."},"fields":{"type":"array","items":{"type":"string","enum":["source","caption","description","parmNames","webForm"]},"description":"Whole-field metadata match (returns matchedValue, no line context). Default [source]. Prefer scope=[webForm] for line-context WebForm hits; use fields=[webForm] only for a coarse contains-match."},"maxResults":{"type":"integer"},"caseSensitive":{"type":"boolean"},"includeComments":{"type":"boolean"},"inline_read_top":{"type":"integer","description":"0-3. Inline reads of top N distinct objects in response."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"pattern":"ControlType=\"Radio\""},{"pattern":"for each","typeFilter":"Procedure","maxResults":20}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
-  {"name":"genexus_kb","description":"Manage open KBs and startup config. list/open/close/set_default operate on WorkerPool; set_startup/get_startup mirror IDE 'Set As Startup Object'.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","open","close","set_default","set_startup","get_startup"]},"alias":{"type":"string","description":"KB alias. open: auto from path basename if omitted."},"path":{"type":"string","description":"Absolute KB path (required for open if alias not in config)."},"name":{"type":"string","description":"Object name (required for set_startup)."}},"required":["action"],"examples":[{"action":"open","path":"C:\\KBs\\MyKb"},{"action":"list"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
+  {"name":"genexus_kb","description":"Manage open KBs, startup config, and the active GeneXus environment. list/open/close/set_default operate on WorkerPool; set_default selects the implicit target for calls that omit kb (an explicit kb always wins for parallel or cross-KB work); set_startup/get_startup mirror IDE 'Set As Startup Object'; get_environment reads the SDK selection; set_environment selects an environment through the SDK task used by the IDE.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","open","close","set_default","set_startup","get_startup","get_environment","set_environment"]},"alias":{"type":"string","description":"KB alias. open: auto from path basename if omitted."},"path":{"type":"string","description":"Absolute KB path (required for open if alias not in config)."},"name":{"type":"string","description":"Object name (required for set_startup)."},"environment":{"type":"string","description":"Environment name/folder (required for set_environment), e.g. development."}},"required":["action"],"examples":[{"action":"open","path":"C:\\KBs\\MyKb"},{"action":"list"},{"action":"get_environment"},{"action":"set_environment","environment":"development"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_navigation","description":"View navigation report (IDE Right-click → View Navigation). latest=true returns cached report from .gx/navigation-cache; else runs fresh.","inputSchema":{"type":"object","required":["action","name"],"properties":{"action":{"type":"string","enum":["view"]},"name":{"type":"string"},"latest":{"type":"boolean","default":false,"description":"Return the most recent cached navigation if any; otherwise run fresh."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"view","name":"Customer"},{"action":"view","name":"Customer","latest":true}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_api","description":"Introspect REST endpoints exposed by HTTP procedures. action=list|describe|snapshot|diff_baseline. Returns endpoints + detects breaking changes vs a saved baseline.","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["list","describe","snapshot","diff_baseline"]},"target":{"type":"string","description":"Procedure name (action=describe)."},"name":{"type":"string","description":"Baseline name (action=snapshot)."},"baseline":{"type":"string","description":"Baseline name under .gx/api-baselines/ or absolute path (action=diff_baseline)."},"pathPrefix":{"type":"string","description":"Folder prefix filter (action=list), e.g. 'Root Module/API/'."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"list"},{"action":"describe","target":"ApiCustomerGet"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_apply_pattern","description":"Apply a pattern (e.g. WorkWithPlus) to a parent (IDE Right-click → Apply Pattern). Transaction=family-gen; WebPanel/WebComponent/SDPanel=direct-attach (pass settings.template). mode=diagnose (or dryRun=true) returns findings without mutating. Working on Smart Devices? → resources/read uri=genexus://kb/skills/sd-panel-mobile for Main object semantics. mode=actions manages typed grid actions and Action Groups, persists and re-reads PatternInstance, supports dryRun diff, and never adds security permissions automatically.","inputSchema":{"type":"object","required":["name","pattern"],"properties":{"name":{"type":"string","description":"Target KBObject name."},"pattern":{"type":"string","description":"Pattern key ('WorkWithPlus') or GUID."},"mode":{"type":"string","enum":["apply","diagnose","actions"],"description":"apply (default) mutates; diagnose returns reasons without applying. actions exposes typed WWP action-group editing."},"action":{"type":"string","enum":["list_actions","add_grid_action","update_action","move_action","remove_action"],"description":"mode=actions operation."},"group":{"type":"string"},"actionName":{"type":"string"},"newGroup":{"type":"string"},"position":{"type":"integer","minimum":0},"procedure":{"type":"string"},"selection":{"type":"string","enum":["current","multiple"]},"enabledWhen":{"type":"string"},"visibleWhen":{"type":"string"},"icon":{"type":"string"},"description":{"type":"string"},"confirmation":{"type":"string"},"confirmTitle":{"type":"string"},"settings":{"type":"object","description":"Pattern-instance settings tree."},"reapply":{"type":"boolean","default":false,"description":"Re-run on existing instance."},"validate":{"type":"boolean","default":false,"description":"After apply, build the generated host. Adds validation block (60-180s). Catches binding errors."},"dryRun":{"type":"boolean","default":false,"description":"Alias for mode=diagnose. When true, returns pattern findings without mutating. With mode=actions it previews the typed action diff."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"name":"Customer","pattern":"WorkWithPlus"},{"name":"Customer","pattern":"WorkWithPlus","mode":"diagnose"},{"name":"Customer","pattern":"WorkWithPlus","mode":"actions","action":"add_grid_action","group":"Actions","actionName":"Approve","procedure":"ApproveCustomer","dryRun":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
@@ -39,7 +40,7 @@
   {"name":"genexus_db","description":"Database umbrella. action: drift_check|drift_report (Transaction↔DB schema drift) | optimize_analyze|optimize_suggest|optimize_report (static index advisor) | sql_ddl|sql_navigation (SQL for Transaction/Procedure) | sample_data (fake INSERTs) | types_list|types_describe|types_validate (Domains/SDT constraints) | reorg_impact (timestamp/deep ImpactDatabase) | reorg_preview (non-mutating logical↔physical impact diff plus exact SQL only when a current artifact is available) | translations_import.","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["drift_check","drift_report","optimize_analyze","optimize_suggest","optimize_report","sql_ddl","sql_navigation","sample_data","types_list","types_describe","types_validate","translations_import","reorg_impact","reorg_preview"]},"deep":{"type":"boolean","description":"reorg_impact/reorg_preview only: run ISpecifierService.ImpactDatabase (specification, build-heavy) for the authoritative AnalysisResult. Default false (cheap timestamp heuristic)."},"name":{"type":"string","description":"Object/transaction/type name."},"trn":{"type":"string","description":"sample_data: Transaction name."},"rows":{"type":"integer","description":"sample_data: 1-1000; default 5."},"includeSubordinated":{"type":"boolean","description":"sql_ddl only."},"levelNumber":{"type":"integer","description":"sql_navigation only."},"includeExecutionPlan":{"type":"boolean","description":"sql_navigation."},"includeIndexAdvisor":{"type":"boolean","description":"sql_navigation."},"format":{"type":"string","enum":["json","markdown"],"description":"optimize_report only."},"kind":{"type":"string","enum":["domain","sdt","all"],"description":"types_list filter."},"value":{"type":"string","description":"types_validate."},"type":{"type":"string","description":"types_validate / disambiguator."},"inputPath":{"type":"string","description":"translations_import: CSV path."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"drift_check"},{"action":"sql_ddl","name":"Customer"},{"action":"reorg_preview","name":"Customer","deep":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_versioning","description":"Versioning umbrella. action: history_list|history_get|history_save|history_restore (snapshot store; restore+discard=true is IDE 'Discard changes' parity) | undo (revert last N edits) | time_travel (recover bytes from a past git commit) | blame (git blame an object part) | diff (text: mode=textVsText|currentVsText) | diff_generated (against=last-build|git-head).","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["history_list","history_get","history_save","history_restore","undo","time_travel","blame","diff","diff_generated"]},"name":{"type":"string"},"part":{"type":"string"},"versionId":{"type":"integer"},"snapshot":{"type":"string"},"discard":{"type":"boolean"},"dryRun":{"type":"boolean"},"last":{"type":"integer","description":"undo: default 1, max 20."},"at":{"type":"string","description":"time_travel: ISO-8601 or commit sha."},"line":{"type":"integer","description":"blame: 1-based line number to annotate."},"filePath":{"type":"string","description":"blame: absolute or KB-relative file path."},"context":{"type":"integer","description":"blame: surrounding lines of context."},"mode":{"type":"string","enum":["textVsText","currentVsText"],"description":"diff."},"left":{"type":"string","description":"diff: left-side text or snapshot label."},"right":{"type":"string","description":"diff: right-side text or snapshot label."},"against":{"type":"string","enum":["last-build","git-head"],"description":"diff_generated."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"history_list","name":"Customer"},{"action":"time_travel","name":"Customer","at":"2026-05-20T10:00:00Z"}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_io","description":"IO umbrella for assets, part text exchange, screenshots, OCR. action: asset_find|asset_read|asset_write (binary asset CRUD) | export_part|import_part (object part to/from a text file) | export_unified (full object envelope JSON) | screenshot_publish (copy PNG to .gx/published-screenshots) | ocr (Tesseract stub).","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["asset_find","asset_read","asset_write","export_part","import_part","export_unified","screenshot_publish","ocr"]},"path":{"type":"string","description":"asset/screenshot_publish/ocr: file path."},"name":{"type":"string","description":"export/import/export_unified: object name."},"outputPath":{"type":"string","description":"export_part: destination file path."},"inputPath":{"type":"string","description":"import_part: source file path."},"part":{"type":"string","description":"export/import_part: part name (e.g. Source)."},"type":{"type":"string","description":"export/import/export_unified disambiguator."},"overwrite":{"type":"boolean","description":"export_part: overwrite if exists."},"pattern":{"type":"string","description":"asset_find: glob pattern."},"relativeRoot":{"type":"string","description":"asset_find: root for relative paths."},"limit":{"type":"integer","description":"asset_find: max results."},"includeContent":{"type":"boolean","description":"asset_find: inline file content."},"maxBytes":{"type":"integer","description":"asset_read: max bytes to return."},"contentBase64":{"type":"string","description":"asset_write: base64-encoded file content."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"asset_read","path":"C:\\KBs\\MyKb\\custom.xml"},{"action":"export_part","name":"Customer","part":"Source","outputPath":"C:\\tmp\\Customer.gxp"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
-  {"name":"genexus_variable","description":"Variables CRUD. add accepts varName or variables[] batch; modify changes type atomically. basedOn binds a Domain by native SDK identity. length/decimals override size; collection=true declares a collection; untyped add inherits a same-named attribute. VarChar stays VARCHAR. dryRun previews; validationMode=specify can run inline validation; async returns an operationId.","inputSchema":{"type":"object","required":["action","name"],"properties":{"action":{"type":"string","enum":["add","delete","modify"]},"name":{"type":"string"},"varName":{"type":"string","description":"Single-variable form (add/delete/modify). For batch add use variables[] instead."},"variables":{"type":"array","description":"Batch add only: one object per variable — {varName, typeName?, length?, decimals?, collection?}. Added before a single save.","items":{"type":"object","required":["varName"],"properties":{"varName":{"type":"string"},"typeName":{"type":"string"},"length":{"type":"integer"},"decimals":{"type":"integer"},"collection":{"type":"boolean"},"basedOn":{"type":"string","description":"Domain name; native SDK reference."}}}},"typeName":{"type":"string","description":"Primitive (Character/Numeric/VarChar/Date/...), SDT/BC/Domain name, or WebSession. VarChar keeps VARCHAR semantics."},"length":{"type":"integer","description":"add/modify optional: overrides the length parsed from typeName (fixes the Character(20) default)."},"decimals":{"type":"integer","description":"add/modify optional: overrides decimals parsed from typeName."},"collection":{"type":"boolean","description":"add/modify optional: declare the variable as a collection."},"basedOn":{"type":"string","description":"modify optional: Domain."},"dryRun":{"type":"boolean","default":false,"description":"When true, returns what would change without persisting."},"validationMode":{"type":"string","enum":["specify"],"description":"Issue #60: run the inline Specify pass (Spec+Gen, no Compile) against the edited object right after the write, returning structured spc*/gen* diagnostics in the same call. Combines with rollbackOnFailure."},"rollbackOnFailure":{"type":"boolean","description":"Issue #60: with validationMode=specify, restore the pre-write state when the specify pass reports errors. Variable writes have no pre-write snapshot, so rollback reports rolledBack=false (the variables stay) when spec fails."},"async":{"type":"boolean","description":"Run as a background job. Result returns operationId/job_id for genexus_lifecycle polling."},"estimated_seconds":{"type":"integer","description":"When async=true, expected runtime used for progress/job metadata (default 30)."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"add","name":"MyPanel","varName":"&Choice","typeName":"Numeric"},{"action":"add","name":"MyProc","variables":[{"varName":"&ApiKey","typeName":"VarChar","length":80},{"varName":"&CmdNro","typeName":"Numeric","length":9}]},{"action":"delete","name":"MyPanel","varName":"&OldVar"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
+  {"name":"genexus_variable","description":"Variables CRUD. add accepts varName or variables[] batch; modify changes type atomically. basedOn binds a Domain by native SDK identity. objectType=BusinessComponent with objectName+module binds a modular BC by EntityKey/GUID and verifies it after save. length/decimals override size; collection=true declares a collection; untyped add inherits a same-named attribute. dryRun validates and previews without mutation; async returns an operationId.","inputSchema":{"type":"object","required":["action","name"],"properties":{"action":{"type":"string","enum":["add","delete","modify"]},"name":{"type":"string"},"varName":{"type":"string","description":"Single-variable form (add/delete/modify). For batch add use variables[] instead."},"variables":{"type":"array","description":"Batch add only: one object per variable — {varName, typeName?, length?, decimals?, collection?}. Added before a single save.","items":{"type":"object","required":["varName"],"properties":{"varName":{"type":"string"},"typeName":{"type":"string"},"length":{"type":"integer"},"decimals":{"type":"integer"},"collection":{"type":"boolean"},"basedOn":{"type":"string","description":"Domain name; native SDK reference."}}}},"typeName":{"type":"string","description":"Primitive (Character/Numeric/VarChar/Date/...), SDT/BC/Domain name, or WebSession. VarChar keeps VARCHAR semantics."},"objectType":{"type":"string","enum":["BusinessComponent"],"description":"add/modify: resolve an object-backed variable natively instead of interpreting typeName as a Domain."},"objectName":{"type":"string","description":"Business Component Transaction name, without module when module is passed separately."},"module":{"type":"string","description":"Module owning objectName. Required to disambiguate modular Business Components."},"expectedVersion":{"type":"string","description":"Optimistic-concurrency token for an object-backed add/modify. Stale state returns VersionConflict before mutation."},"length":{"type":"integer","description":"add/modify optional: overrides the length parsed from typeName."},"decimals":{"type":"integer","description":"add/modify optional: overrides decimals parsed from typeName."},"collection":{"type":"boolean","description":"add/modify optional: declare the variable as a collection."},"basedOn":{"type":"string","description":"modify optional: Domain."},"dryRun":{"type":"boolean","default":false,"description":"Validate and return the typed diff without changing any object, Attribute, hash, or version."},"validationMode":{"type":"string","enum":["specify"],"description":"Explicitly run the inline Specify pass after a legacy variable write. Never runs unless requested."},"rollbackOnFailure":{"type":"boolean","default":true,"description":"Object-backed variables always snapshot the complete owner and restore it on save/re-read divergence."},"async":{"type":"boolean","description":"Run as a background job. Result returns operationId/job_id for genexus_lifecycle polling."},"estimated_seconds":{"type":"integer","description":"When async=true, expected runtime used for progress/job metadata (default 30)."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"add","name":"MyPanel","varName":"&Choice","typeName":"Numeric"},{"action":"add","name":"MyProc","varName":"&OrderRecord","objectType":"BusinessComponent","objectName":"OrderRecord","module":"Operations","dryRun":true},{"action":"add","name":"MyProc","variables":[{"varName":"&ApiKey","typeName":"VarChar","length":80},{"varName":"&CmdNro","typeName":"Numeric","length":9}]},{"action":"delete","name":"MyPanel","varName":"&OldVar"}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_telemetry","description":"Observability umbrella. action: executions (recent invocations) | watch_event (ops mentioning an event) | friction_append|friction_tail (.gx/friction.jsonl) | learning_report (aggregate friction) | logs (worker_debug.log tail) | profile_analyze|profile_hotspots|profile_correlate (GeneXus profiler XML).","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["executions","watch_event","friction_append","friction_tail","learning_report","logs","profile_analyze","profile_hotspots","profile_correlate"]},"target":{"type":"string","description":"executions/watch_event: object name to filter."},"event":{"type":"string","description":"watch_event: event name to match in operation payload."},"last":{"type":"integer","description":"executions/watch_event: max results."},"tool":{"type":"string","description":"friction_append: tool name that produced the friction entry."},"message":{"type":"string","description":"friction_append: description of the friction encountered."},"severity":{"type":"string","enum":["info","warn","error","critical"],"description":"friction_append: severity level."},"n":{"type":"integer","description":"friction_tail: number of recent lines to return."},"since":{"type":"string","description":"learning_report/logs: ISO-8601 start time filter."},"until":{"type":"string","description":"learning_report: ISO-8601 end time filter."},"tail":{"type":"integer","description":"logs: number of tail lines from worker_debug.log."},"filterCorrelation":{"type":"string","description":"logs: filter by correlation/operation ID."},"grep":{"type":"string","description":"logs: substring filter on log lines."},"path":{"type":"string","description":"profile_*: path to the GeneXus profiler XML file."},"top":{"type":"integer","description":"profile_hotspots: top-N hottest procedures to return."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"executions"},{"action":"friction_tail","n":20}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_create","description":"Creation umbrella. action: object (Transaction/Procedure/WebPanel/SDT/API/Domain/Dashboard/Folder/Module; type='API' scaffolds a REST API object — routes use ONE HTTP-verb block per object 'Verb { route => Object; }' (mixing Get+Post blocks is unsupported); type='Folder'/'Module' create containers, and folder=<name>/module=<name> place the new object there (created in Root, then moved+verified); SDT takes optional firstItem/firstItemType; Domain takes dataType+length or enumValues; NOT WWP — use genexus_apply_pattern) | popup (popup WebPanel with Form type='layout' body) | sd_panel_create|sd_panel_inspect|sd_panel_edit | save_as (clone parts) | scaffold|translate|sample (forge) | template (kpi_header|empty_state|confirm_dialog) | object_atomic (issue #62: all-or-nothing create/update of an object with variables[], rules[], parms[], properties{} and source in ONE validated call — pre-validates every field before the first save, composes the SDK write primitives, compensates on failure, dryRun previews, validate=true runs the inline Specify pass, update mode guards concurrent writes via expectedVersion). | curl_procedure imports a REST-consumer Procedure from a curl command through the GeneXus SDK.","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["object","object_atomic","popup","sd_panel_create","sd_panel_inspect","sd_panel_edit","save_as","scaffold","translate","sample","template","curl_procedure"]},"curl":{"type":"string","description":"curl_procedure: the curl command to import as a Procedure."},"type":{"type":"string"},"name":{"type":"string"},"newName":{"type":"string","description":"save_as."},"description":{"type":"string"},"dataType":{"type":"string","description":"object Domain."},"length":{"type":"integer","description":"object Domain."},"decimals":{"type":"integer","description":"object Domain."},"signed":{"type":"boolean","description":"object Domain."},"basedOn":{"type":"string","description":"object Domain."},"enumValues":{"type":"array","items":{"type":"object"},"description":"object Domain enum."},"firstItem":{"type":"string","description":"object SDT optional: name of the first structure item to seed (SDK requires ≥1). Defaults to Item1. Use to avoid the throwaway Item1."},"firstItemType":{"type":"string","description":"object SDT optional: type of the seeded first item (Character/Numeric/VarChar/…). Defaults to VarChar."},"folder":{"type":"string","description":"object: Folder destination (created in Root, then moved+verified)."},"module":{"type":"string","description":"object: Module destination (created in Root, then moved+verified)."},"parentPath":{"type":"string","description":"object: folder/module destination (fallback when folder/module absent)."},"mode":{"type":"string","enum":["create","update","auto"],"description":"object_atomic: create (fail if exists), update (fail if missing), auto (default — create or update by existence)."},"variables":{"type":"array","items":{"type":"object","required":["varName"],"properties":{"varName":{"type":"string"},"typeName":{"type":"string"},"length":{"type":"integer"},"decimals":{"type":"integer"},"collection":{"type":"boolean"},"name":{"type":"string"},"basedOn":{"type":"string"}}},"description":"object_atomic: one object per variable — {varName, typeName?, length?, decimals?, collection?}. Validated before any save; errors are attributed to variables[N]."},"rules":{"type":"array","items":{"type":"string"},"description":"object_atomic: rule lines (e.g. \"Parm(in:&Id);\")."},"parms":{"type":"array","items":{"type":"string"},"description":"object_atomic: parameter entries rendered into a Parm rule — bare names (\"&Id\") or prefixed (\"out:&Msg\")."},"source":{"type":"string","description":"object_atomic: Source part text."},"properties":{"type":"object","description":"object_atomic: object-level properties applied via the genexus_properties path (propertyName → value)."},"expectedVersion":{"type":"string","description":"object_atomic update: optimistic concurrency token returned as `version` by a prior atomic create/update/read; a mismatch fails with ConcurrentModification instead of overwriting concurrent changes."},"validate":{"type":"boolean","description":"object_atomic: run the inline Specify pass (Spec+Gen) before confirming success. On failure with rollbackOnFailure=true, a freshly-created object is deleted so the operation stays all-or-nothing."},"validationMode":{"type":"string","enum":["specify"],"description":"Issue #60: with action=object, run the inline Specify pass (Spec+Gen, no Compile) after creation, returning structured spc*/gen* diagnostics in the same call. Combines with rollbackOnFailure."},"rollbackOnFailure":{"type":"boolean","description":"Issue #60: with action=object and validationMode=specify, roll back the created object when the specify pass reports errors. A fresh object has no pre-write snapshot, so rollback reports rolledBack=false — delete it via genexus_delete_object if spec fails."},"spec":{"type":"object","description":"popup."},"part":{"type":"string","description":"sd_panel_edit/template."},"content":{"type":"string","description":"sd_panel_edit/scaffold/translate."},"includePatternInstance":{"type":"boolean","description":"save_as."},"overwrite":{"type":"boolean","description":"save_as."},"dryRun":{"type":"boolean","description":"popup/save_as/template/object."},"template":{"type":"string","enum":["kpi_header","empty_state","confirm_dialog"],"description":"template."},"args":{"type":"object","description":"template."},"kb":{"type":"string","description":"KB alias."},"baseVersion":{"type":"string"},"updateExisting":{"type":"boolean","default":false}},"examples":[{"action":"object","name":"NewPanel","type":"WebPanel"},{"action":"object","name":"CustomerApi","type":"API"},{"action":"popup","name":"MyPopup","spec":{"host":"Customer"}}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_memory","description":"Per-KB fact store. action: save (fact required; optional target/type/tags; dedups on identical fact+object, bumping a hit count) | recall (filter by target/type/tags — ANY match; no filter returns all) | list (all, newest first) | forget (tombstone by id) | promote (lift a friction-log message into a memory, tagged 'friction') | consolidate (dreaming — merge redundant/overlapping facts within scope; dryRun=true previews, dryRun=false compacts memory.jsonl). Persisted to .gx/memory/memory.jsonl.","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["save","recall","list","forget","promote","consolidate"]},"fact":{"type":"string","description":"save: the fact to remember."},"target":{"type":"string","description":"object name this memory is about."},"type":{"type":"string","description":"object type this memory is about."},"tags":{"type":"array","items":{"type":"string"},"description":"labels for filtering."},"id":{"type":"string","description":"forget: memory id to tombstone."},"message":{"type":"string","description":"promote: friction text to promote into a memory."},"dryRun":{"type":"boolean","description":"consolidate: true previews proposed merges without writing; false (default) applies and compacts memory.jsonl."},"kb":{"type":"string","description":"KB alias."}},"additionalProperties":false,"examples":[{"action":"save","fact":"Customer.Email must be unique","target":"Customer","type":"Transaction","tags":["validation"]},{"action":"recall","target":"Customer"},{"action":"consolidate","dryRun":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},