genexus-mcp 1.3.0 → 2.0.0

package/README.md

@@ -103,13 +103,17 @@ Notes:
 ## 🛠️ Tool Surface (Skills)
 *(See `GEMINI.md` for extended guidelines).* The worker natively exposes the following tools to the MCP Router:
 
-- **Search & Discovery**: `genexus_query`, `genexus_read`, `genexus_batch_read`, `genexus_inspect`, `genexus_list_objects`, `genexus_properties`
-- **Editing & Architecture**: `genexus_edit`, `genexus_batch_edit`, `genexus_create_object`, `genexus_refactor`, `genexus_forge`
+- **Search & Discovery**: `genexus_query`, `genexus_read`, `genexus_inspect`, `genexus_list_objects`, `genexus_properties`
+- **Editing & Architecture**: `genexus_edit`, `genexus_create_object`, `genexus_refactor`, `genexus_forge`
 - **Analysis:** `genexus_analyze`, `genexus_inject_context`, `genexus_doc`, `genexus_explain_code`, `genexus_summarize`
 - **File System & Assets**: `genexus_asset`, `genexus_export_object`, `genexus_import_object`
 - **History & DB**: `genexus_history`, `genexus_get_sql`, `genexus_structure`
 - **Native Layout SDK**: `genexus_layout` (`get_tree`, `find_controls`, `set_property`, `set_properties`, `rename_printblock`, `add_printblock`, `get_preview`, `scan_mutators`)
 
+> **`genexus_edit` modes:** `xml` (default — full XML replacement), `ops` (typed semantic op catalog: `set_attribute`, `add_attribute`, `remove_attribute`, `add_rule`, `remove_rule`, `set_property`), `patch` (JSON-Patch RFC 6902 array over canonical JSON object; legacy string-form patch also accepted for backward compatibility).
+>
+> **All write tools** accept `dryRun: true` (returns a preview `plan` envelope without mutating the KB) and `idempotencyKey` (safe retries — concurrent calls with same key are coalesced; results cached for 15 min by default).
+
 Layout color note:
 - For `ForeColor`, `BackColor`, `BorderColor`, send color values as palette names (`Black`, `Blue`, `Red`, `Transparent`) or RGB token (`R; G; B|`) to avoid nested SDK wrappers.
 - **Lifecycle & Build**: `genexus_lifecycle`, `genexus_test`, `genexus_format`
@@ -119,10 +123,14 @@ Layout color note:
 
 For `tools/call`, the gateway keeps MCP compatibility and adds lightweight response metadata:
 
-- `meta.schemaVersion` currently `mcp-axi/1`
-- `meta.tool` with the normalized tool name
+- `_meta.schemaVersion` currently `mcp-axi/2`
+- `_meta.tool` with the normalized tool name
 - collection helpers such as `returned`, `total`, `empty`, and (when inferable) `hasMore` and `nextOffset`
-- truncation signals via `meta.truncated` plus contextual `help`
+- truncation signals via `_meta.truncated` plus contextual `help`
+- `_meta.idempotent: true` on cache-hit responses
+- `_meta.batched: true` on `targets[]` multi-object responses
+- `_meta.dryRun: true` on dry-run preview responses
+- `_meta.removedTools` advertised on `initialize` for proactive agent detection of removed tools
 
 For list-heavy calls (`genexus_query`, `genexus_list_objects`), optional arguments can reduce token usage:
 

package/cli/commands/axi.js

@@ -871,6 +871,10 @@ function commandHelpMap() {
             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']
+        },
         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 ...]',
             examples: ['genexus-mcp layout status --format json', 'genexus-mcp layout run --action activate-tab --tab "Layout" --format json', 'genexus-mcp layout inspect --tab Layout --format json']
@@ -935,7 +939,7 @@ async function handleHelp(targetCommand, ctx) {
                 bin: binPath,
                 command: 'genexus-mcp',
                 description: 'GeneXus MCP launcher and AXI-oriented utility CLI',
-                commands: ['home', 'axi home', 'status', 'doctor', 'tools list', 'config show', 'layout status', 'layout run', 'layout inspect', 'init', 'llm help', 'help'],
+                commands: ['home', 'axi home', 'status', 'doctor', 'tools list', 'config show', 'layout status', 'layout run', 'layout inspect', 'init', 'llm help', 'update', 'help'],
                 defaults: { format: 'toon', limit: 100 }
             },
             help: [

package/cli/index.js

@@ -22,6 +22,7 @@ const {
     usageEnvelope,
     commandHelpMap
 } = require('./commands/axi');
+const { startBackgroundUpdateCheck, handleUpdate } = require('./lib/update-check');
 
 const EXIT_CODES = {
     OK: 0,
@@ -43,7 +44,7 @@ const GLOBAL_DEFAULTS = {
     help: false
 };
 
-const KNOWN_COMMANDS = new Set(['status', 'doctor', 'tools', 'config', 'init', 'setup', 'help', 'home', 'axi', 'llm', 'layout']);
+const KNOWN_COMMANDS = new Set(['status', 'doctor', 'tools', 'config', 'init', 'setup', 'help', 'home', 'axi', 'llm', 'layout', 'update']);
 
 function parseArgs(argv) {
     const result = {
@@ -332,12 +333,17 @@ function resolveMetaCommand(parsed, targetHelp) {
         if (parsed.subcommand === 'inspect') return 'layout.inspect';
         return 'layout.status';
     }
+    if (parsed.command === 'update') return 'update';
     return parsed.command || 'unknown';
 }
 
 async function main(argv) {
     const parsed = parseArgs(argv);
 
+    if (parsed.command !== 'update') {
+        startBackgroundUpdateCheck({ quiet: parsed.options.quiet });
+    }
+
     if (!parsed.command) {
         return launchGateway(argv, parsed.options);
     }
@@ -438,6 +444,9 @@ async function main(argv) {
         case 'init':
             result = await handleInit(parsed.options, ctx);
             break;
+        case 'update':
+            result = await handleUpdate(parsed.options, ctx);
+            break;
         default:
             writeStructured(
                 process.stdout,

package/cli/lib/update-check.js

@@ -0,0 +1,214 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const https = require('https');
+
+const REPO = 'lennix1337/Genexus18MCP';
+const NPM_PACKAGE = 'genexus-mcp';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 2000;
+
+function getPackageVersion() {
+    try {
+        const pkg = require('../../package.json');
+        return typeof pkg.version === 'string' ? pkg.version : null;
+    } catch {
+        return null;
+    }
+}
+
+function getCacheFile() {
+    return path.join(os.homedir(), '.genexus-mcp', 'update-check.json');
+}
+
+function readCache() {
+    try {
+        const raw = fs.readFileSync(getCacheFile(), 'utf8');
+        const data = JSON.parse(raw);
+        if (data && typeof data === 'object') return data;
+    } catch {
+    }
+    return null;
+}
+
+function writeCache(data) {
+    try {
+        const file = getCacheFile();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(data), 'utf8');
+    } catch {
+    }
+}
+
+function stripV(v) {
+    return typeof v === 'string' ? v.replace(/^v/i, '').trim() : '';
+}
+
+function parseSemver(v) {
+    const s = stripV(v);
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(s);
+    if (!m) return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function compareSemver(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (!pa || !pb) return 0;
+    for (let i = 0; i < 3; i += 1) {
+        if (pa[i] > pb[i]) return 1;
+        if (pa[i] < pb[i]) return -1;
+    }
+    return 0;
+}
+
+function fetchLatestRelease() {
+    return new Promise((resolve) => {
+        const options = {
+            hostname: 'api.github.com',
+            path: `/repos/${REPO}/releases/latest`,
+            method: 'GET',
+            headers: {
+                'User-Agent': `${NPM_PACKAGE}-cli`,
+                'Accept': 'application/vnd.github+json'
+            }
+        };
+
+        const req = https.request(options, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve(null);
+                return;
+            }
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => { body += chunk; });
+            res.on('end', () => {
+                try {
+                    const json = JSON.parse(body);
+                    const tag = stripV(json.tag_name || '');
+                    const url = typeof json.html_url === 'string' ? json.html_url : null;
+                    if (!tag) { resolve(null); return; }
+                    resolve({ latestVersion: tag, releaseUrl: url });
+                } catch {
+                    resolve(null);
+                }
+            });
+        });
+
+        req.on('error', () => resolve(null));
+        req.setTimeout(FETCH_TIMEOUT_MS, () => {
+            req.destroy();
+            resolve(null);
+        });
+
+        req.end();
+        if (typeof req.unref === 'function') req.unref();
+    });
+}
+
+function formatBanner(current, latest, releaseUrl) {
+    const lines = [
+        `[genexus-mcp] update available: v${current} -> v${latest}`,
+        `[genexus-mcp] run: npm install -g ${NPM_PACKAGE}@latest`
+    ];
+    if (releaseUrl) lines.push(`[genexus-mcp] release: ${releaseUrl}`);
+    return lines.join('\n') + '\n';
+}
+
+function isDisabled(opts) {
+    if (process.env.GENEXUS_MCP_NO_UPDATE_CHECK === '1') return true;
+    if (opts && opts.quiet) return true;
+    if (!process.stderr || !process.stderr.isTTY) return true;
+    return false;
+}
+
+function maybePrintCachedBanner(opts) {
+    const current = getPackageVersion();
+    if (!current) return;
+    const cache = readCache();
+    if (!cache || !cache.latestVersion) return;
+    if (compareSemver(cache.latestVersion, current) > 0) {
+        try {
+            process.stderr.write(formatBanner(current, cache.latestVersion, cache.releaseUrl || null));
+        } catch {
+        }
+    }
+}
+
+function scheduleBackgroundFetch() {
+    const cache = readCache();
+    const now = Date.now();
+    if (cache && typeof cache.checkedAt === 'number' && (now - cache.checkedAt) < CACHE_TTL_MS) {
+        return;
+    }
+
+    fetchLatestRelease().then((result) => {
+        if (!result) return;
+        writeCache({
+            checkedAt: Date.now(),
+            latestVersion: result.latestVersion,
+            releaseUrl: result.releaseUrl
+        });
+    }).catch(() => {});
+}
+
+function startBackgroundUpdateCheck(opts) {
+    if (isDisabled(opts)) return;
+    maybePrintCachedBanner(opts);
+    scheduleBackgroundFetch();
+}
+
+async function handleUpdate(_options, ctx) {
+    const current = getPackageVersion();
+    const result = await fetchLatestRelease();
+
+    if (!result) {
+        return {
+            exitCode: ctx.EXIT_CODES.OK,
+            envelope: {
+                ok: {
+                    current,
+                    latest: null,
+                    updateAvailable: false,
+                    fetched: false
+                },
+                help: ['Could not reach GitHub releases API. Check connectivity or retry later.']
+            }
+        };
+    }
+
+    writeCache({
+        checkedAt: Date.now(),
+        latestVersion: result.latestVersion,
+        releaseUrl: result.releaseUrl
+    });
+
+    const updateAvailable = compareSemver(result.latestVersion, current || '0.0.0') > 0;
+    const help = updateAvailable
+        ? [`Run: npm install -g ${NPM_PACKAGE}@latest`, result.releaseUrl ? `Release: ${result.releaseUrl}` : null].filter(Boolean)
+        : ['Already on latest version.'];
+
+    return {
+        exitCode: ctx.EXIT_CODES.OK,
+        envelope: {
+            ok: {
+                current,
+                latest: result.latestVersion,
+                releaseUrl: result.releaseUrl,
+                updateAvailable,
+                installCommand: `npm install -g ${NPM_PACKAGE}@latest`,
+                fetched: true
+            },
+            help
+        }
+    };
+}
+
+module.exports = {
+    startBackgroundUpdateCheck,
+    handleUpdate,
+    compareSemver,
+    parseSemver,
+    getPackageVersion
+};

package/cli/run.test.js

@@ -5,6 +5,7 @@ const path = require('node:path');
 const os = require('node:os');
 const fs = require('node:fs');
 const { renderOutput } = require('./lib/output');
+const { compareSemver } = require('./lib/update-check');
 
 const cliPath = path.join(__dirname, 'run.js');
 
@@ -304,6 +305,24 @@ test('quiet flag suppresses launcher stderr noise', () => {
     assert.equal(result.stderr.trim(), '');
 });
 
+test('update --help returns usage entry', () => {
+    const result = runCli(['update', '--help', '--format', 'json']);
+    assert.equal(result.status, 0);
+
+    const parsed = JSON.parse(result.stdout);
+    assert.equal(parsed.meta.command, 'help');
+    assert.equal(parsed.ok.command, 'update');
+    assert.ok(parsed.ok.usage.includes('genexus-mcp update'));
+});
+
+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);
+    assert.equal(compareSemver('1.3.0', '1.3.0'), 0);
+    assert.equal(compareSemver('1.2.9', '1.3.0'), -1);
+    assert.equal(compareSemver('garbage', '1.0.0'), 0);
+});
+
 test('gateway passthrough remains intact when no AXI subcommand is used', () => {
     const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'genexus-mcp-test-'));
     const fakeGateway = path.join(tempRoot, 'fake-gateway.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genexus-mcp",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "A high-performance Model Context Protocol (MCP) server for GeneXus 18",
   "scripts": {
     "test": "node --test cli/run.test.js",