genexus-mcp 1.3.1 → 2.0.3

package/README.md

@@ -1,8 +1,13 @@
-# GeneXus 18 MCP Server (Genexus18MCP)
+# GeneXus MCP Server — GeneXus 18 for Claude, Cursor, and AI Agents
 
+[![npm version](https://img.shields.io/npm/v/genexus-mcp.svg)](https://www.npmjs.com/package/genexus-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/genexus-mcp.svg)](https://www.npmjs.com/package/genexus-mcp)
 [![MCP Badge](https://lobehub.com/badge/mcp/lennix1337-genexus18mcp?style=for-the-badge)](https://lobehub.com/mcp/lennix1337-genexus18mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A high-performance Model Context Protocol (MCP) server for GeneXus 18. It integrates native GeneXus SDK access via a .NET 8 gateway and a .NET Framework 4.8 worker, exposing direct read/write/analysis operations directly to AI Agents and IDEs.
+**GeneXus MCP Server** is a Model Context Protocol (MCP) server that exposes a GeneXus 18 knowledge base to AI agents — Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. It lets the agent read, edit, analyze, and refactor GeneXus objects (transactions, web panels, procedures, SDTs, data providers) directly through the native GeneXus SDK, with a .NET 8 gateway over MCP/stdio and a .NET Framework 4.8 worker hosting the SDK.
+
+> **Search keywords:** GeneXus MCP · GeneXus 18 MCP · GeneXus AI · GeneXus Claude · Model Context Protocol GeneXus · GeneXus low-code AI agent
 
 ***
 
@@ -103,13 +108,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 +128,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

@@ -988,7 +988,7 @@ async function handleLlmHelp(options, ctx) {
         },
         mcp: {
             parsePath: 'result.content[0].text',
-            expectedMeta: ['schemaVersion=mcp-axi/1', 'tool=<tool-name>'],
+            expectedMeta: ['_meta.schemaVersion=mcp-axi/2', '_meta.tool=<tool-name>'],
             listHelpers: ['returned', 'total', 'empty', 'hasMore', 'nextOffset'],
             shaping: ['fields=<csv|array>', 'axiCompact=true (query/list_objects)']
         },

package/docs/llm_cli_mcp_playbook.md

@@ -47,12 +47,17 @@ Recommended flags:
 
 For `tools/call`, parse `result.content[0].text` as JSON.
 
-Gateway AXI-like enrichments are additive:
-- `meta.schemaVersion = mcp-axi/1`
-- `meta.tool = <tool-name>`
+Gateway AXI-like enrichments are additive (under `_meta` — underscore-prefixed per MCP convention):
+- `_meta.schemaVersion = mcp-axi/2` (v2.0.0+)
+- `_meta.tool = <tool-name>`
 - Collection helpers when inferable: `returned`, `total`, `empty`, `hasMore`, `nextOffset`
-- Truncation signal: `meta.truncated=true` + contextual `help`
+- Truncation signal: `_meta.truncated=true` + contextual `help`
 - Idempotent writes may include `noChange=true`
+- v2.0.0 fields:
+  - `_meta.idempotent=true` on idempotency-cache hits.
+  - `_meta.batched=true` when the request used the `targets[]` plural form.
+  - `_meta.dryRun=true` on `dryRun` preview responses; full preview shape: `{plan:{touchedObjects, xmlDiff, brokenRefs, warnings}}`.
+  - `_meta.removedTools` advertised on `initialize` so agents can self-correct before a runtime `-32601`.
 
 Optional shaping for `genexus_query` and `genexus_list_objects`:
 - `fields`: array or CSV projection.
@@ -69,11 +74,22 @@ Disambiguation:
 
 Efficient reads:
 - `genexus_read(name='Obj', part='Source', offset=1, limit=200)`
-- For many files, prefer `genexus_batch_read`.
-
-Safe edits:
-- Use `genexus_edit(mode='patch', operation='Replace', context=..., content=..., expectedCount=1, dryRun=true)` before applying.
-- Use `genexus_batch_edit` for multi-object coordinated changes.
+- For many files, prefer `genexus_read(targets=['A','B','C'], part='Source')` (plural form).
+
+Safe edits (v2.0.0):
+- Preview before applying: any `genexus_edit` call accepts `dryRun: true` and returns `{plan: {touchedObjects, xmlDiff, brokenRefs, warnings}}` without mutation.
+- Three edit modes:
+  - `mode='xml'` (default) — full XML replacement.
+  - `mode='ops'` — typed semantic ops, e.g. `ops=[{op:'set_attribute', name:'Phone', type:'Character(20)'}]`. Catalog: `set_attribute`, `add_attribute`, `remove_attribute`, `add_rule`, `remove_rule`, `set_property`.
+  - `mode='patch'` — JSON-Patch RFC 6902 array, e.g. `patch=[{op:'replace', path:'/description', value:'new'}]`. Legacy string-form text patch (`mode='patch'` with string `patch`) still works for backward compatibility.
+- Multi-object coordinated changes: `genexus_edit(targets=[{name:'A', mode:'ops', ops:[...]}, {name:'B', mode:'xml', content:'...'}])`. Mutually exclusive with singular `name`.
+- Safe retries: pass `idempotencyKey: '<token>'` (charset `[A-Za-z0-9_-]`, 1–128 chars). Same key + same payload = cached result; same key + different payload = `idempotency_conflict` error. `dryRun` bypasses the cache.
+
+Removed in v2.0.0:
+- `genexus_batch_read` → use `genexus_read` with `targets[]`.
+- `genexus_batch_edit` → use `genexus_edit` with `targets[]`.
+- `genexus_edit` `changes` arg → use `targets[]`.
+- Calling a removed tool returns `-32601` with `error.data.replacedBy` and `error.data.argHint` for self-correction. `initialize` advertises `_meta.removedTools` upfront.
 
 ## Timeout and Long-Running Operations
 

package/package.json

@@ -1,7 +1,33 @@
 {
   "name": "genexus-mcp",
-  "version": "1.3.1",
-  "description": "A high-performance Model Context Protocol (MCP) server for GeneXus 18",
+  "version": "2.0.3",
+  "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": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "genexus",
+    "genexus-18",
+    "genexus18",
+    "claude",
+    "claude-desktop",
+    "claude-code",
+    "cursor",
+    "anthropic",
+    "ai",
+    "ai-agent",
+    "ai-agents",
+    "ai-tools",
+    "llm",
+    "llm-tools",
+    "low-code",
+    "code-generation",
+    "knowledge-base",
+    "developer-tools",
+    "axi",
+    "sdk",
+    "automation"
+  ],
   "scripts": {
     "test": "node --test cli/run.test.js",
     "prepack": "node scripts/clean-package.js"