genexus-mcp 2.0.3 → 2.1.0

package/README.md

@@ -5,177 +5,167 @@
 [![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)
 
-**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.
+> **¿Hablás español?** → [Guía de inicio en español](docs/GETTING_STARTED.es.md)
+> **Stuck?** → [Troubleshooting guide](TROUBLESHOOTING.md)
 
-> **Search keywords:** GeneXus MCP · GeneXus 18 MCP · GeneXus AI · GeneXus Claude · Model Context Protocol GeneXus · GeneXus low-code AI agent
+---
+
+**GeneXus MCP Server** lets AI agents — Claude Desktop, Claude Code, Cursor, Antigravity, and any MCP-compatible client — read, edit, analyze, and refactor objects inside a GeneXus 18 Knowledge Base. It talks to the **native GeneXus SDK**, so the agent works with the *real* KB, not a copy or a parsed approximation.
+
+In practice: you point the MCP at your KB, then ask your AI assistant things like *"list all transactions with attribute CustomerId"*, *"add a rule to the Order transaction that validates the total"*, or *"refactor this procedure to use the new SDT"* — and it does it.
+
+---
+
+## Prerequisites
+
+Before you start, make sure you have:
 
-***
+- ✅ **Windows** (GeneXus is Windows-only — this MCP runs on Windows)
+- ✅ **GeneXus 18** installed locally (usually `C:\Program Files (x86)\GeneXus\GeneXus18`)
+- ✅ **A GeneXus 18 Knowledge Base** opened at least once in the IDE (so it has been built/initialized)
+- ✅ **Node.js 18+** ([download](https://nodejs.org/))
+- ✅ **An MCP-compatible AI client** — [Claude Desktop](https://claude.ai/download), [Claude Code](https://claude.com/claude-code), Cursor, Antigravity, etc.
 
-## 🚀 Quick Start (Installation & Configuration)
+You do **not** need to clone this repo or install anything globally — `npx` handles it.
 
-You **do NOT** need to clone this repository, and you **do NOT** need to install anything globally via `npm i -g`. The standard Node.js `npx` runner will dynamically fetch and launch the compiled gateway for you.
+---
+
+## Quickstart (3 steps)
 
-### Step 1: Configure (Non-Interactive First)
+### Step 1 — Run the installer
 
-To initialize configuration in a deterministic, agent-friendly way:
+Open a terminal and run, replacing the paths with **your** KB folder and **your** GeneXus install:
 
 ```bash
 npx genexus-mcp@latest init --kb "C:\KBs\YourKB" --gx "C:\Program Files (x86)\GeneXus\GeneXus18"
 ```
 
-If you want the setup wizard prompts explicitly, run:
+> Prefer the wizard? Run `npx genexus-mcp@latest init --interactive` and answer the prompts.
 
-```bash
-npx genexus-mcp@latest init --interactive
-```
+When it finishes you should see `🎉 You are all set!` plus a JSON snippet for your AI client.
+
+### Step 2 — Register the MCP in your AI client
+
+The installer **auto-registers** the server 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 3 — Restart your AI client and test
 
-### Step 2: Restart your AI Assistant
+Fully close and reopen Claude / Cursor / etc. Then try this prompt:
 
-Once the wizard outputs `🎉 You are all set!`, simply **Restart** or **Refresh** your AI Assistant (Claude Desktop, Antigravity, Cursor, etc.). The AI will automatically spin up the server in the background and connect.
+> *"Using the GeneXus MCP, list the first 5 transactions in my KB and show their names."*
+
+If you get a list back — **you're done**. Skip to [What can I ask the AI?](#what-can-i-ask-the-ai) for ideas.
+
+If something didn't work, go straight to [Troubleshooting](TROUBLESHOOTING.md) — most issues are covered there.
 
 ---
 
-### 🤖 Auto-Installer Prompt (Copy & Paste to your AI)
+## 🤖 Let your AI install it for you
 
-If you want your AI Assistant to install and configure everything itself without you touching the terminal, copy and paste this exact prompt into your chat window:
+If you'd rather not run anything in the terminal yourself, paste this into your AI chat:
 
-```markdown
-Please configure your Model Context Protocol (MCP) server to connect to my GeneXus Knowledge Base by following these exact steps:
+> Please configure the GeneXus MCP server. Run `npx genexus-mcp@latest init --kb "<MY_KB_PATH>" --gx "<MY_GENEXUS_PATH>"` in the terminal. If I haven't told you my GeneXus path and KB path yet, ask me first. Once it succeeds, read the JSON block it printed and add it to my MCP client config. Tell me when I should restart the client to start using GeneXus tools.
 
-1. Run the command `npx genexus-mcp@latest init` directly in the terminal in non-interactive mode using this configuration format (do not use interactive prompts). You must inject my raw KB path and GX path via environment variables or a direct config patch if needed, or simply let the zero-config auto-discovery handle it if we are already in the KB folder.
-2. If I haven't told you my GeneXus path or KB path, STOP and ask me for them now.
-3. Once the setup is complete, read the generated JSON block from the console output.
-4. If you use a global configuration file (like `mcp_config.json` or `claude_desktop_config.json`), insert the exact `mcpServers` block provided in the console output. Use `npx.cmd` as the command.
-5. Provide a summary of the installation and notify me when you are ready to query GeneXus!
-```
+Replace the placeholders or let the AI ask you for them.
 
 ---
 
-## AXI CLI Commands
+## What can I ask the AI?
 
-The package now includes agent-facing commands optimized for shell automation:
+Once installed, here's what unlocks. Try these as your first prompts:
 
-```bash
-genexus-mcp home
-genexus-mcp axi home
-genexus-mcp llm help
-genexus-mcp status
-genexus-mcp doctor --mcp-smoke
-genexus-mcp tools list
-genexus-mcp config show
-genexus-mcp layout status
-genexus-mcp layout run --action activate-layout
-genexus-mcp layout run --action activate-tab --tab "Layout"
-genexus-mcp layout inspect --tab "Layout"
-```
+**Exploration**
+- *"List all objects of type Procedure in the KB."*
+- *"Show me the source of the procedure CalculateInvoiceTotal."*
+- *"Find all transactions that reference the attribute CustomerId."*
+
+**Editing**
+- *"Add a rule to the Order transaction: error('Total must be positive') if Total < 0."*
+- *"Add a new attribute CreatedAt of type DateTime to the Customer transaction."*
+- *"Rename the variable &qty to &quantity in procedure CreateOrder."*
+
+**Analysis**
+- *"Explain what the procedure ProcessShipment does, step by step."*
+- *"What SQL does the query in WebPanel CustomerList generate?"*
+- *"Summarize the structure of the Sales module."*
 
-Global AXI flags:
-- `--format toon|json|text` (default for AXI commands: `toon`)
-- `--fields f1,f2,...` (minimal schema by default; request extra fields explicitly)
-- `--limit <n>` (for list commands)
-- `--query <text>` (for `tools list`)
-- `--full` (expand truncated long-form content when supported)
-- `--mcp-smoke` (for `doctor`; executes protocol smoke checks)
-- `--quiet` and `--no-color` (agent-safe output control)
-
-Layout automation flags (`layout run`):
-- `--action focus|activate-layout|activate-tab|send-keys|type-text|click`
-- `--title "<window-title-fragment>"` to target a specific GeneXus window
-- `--tab "<tab-name>"` for `activate-tab`
-- `--keys "<sendkeys-pattern>"` for `send-keys`
-- `--text "<text>"` for `type-text`
-- `--x <screenX> --y <screenY>` for `click`
-
-Layout inspection:
-- `genexus-mcp layout inspect [--tab "<tab-name>"] [--limit N] [--full] [--title "<window-title-fragment>"]`
-- Returns UI Automation controls with bounding rectangles (`bounds.x/y/width/height`) to support deterministic replay.
-
-Notes:
-- Structured data/errors are emitted on `stdout`.
-- Diagnostic/progress output stays on `stderr`.
-- `meta.command` is always present for stable command identity in AXI outputs.
-- Use `genexus-mcp <command> --help` for command-specific usage/examples.
-- Output metadata includes `meta.schemaVersion` for contract stability.
-- `--fields` is validated strictly per command; invalid fields return `usage_error` and exit code `2`.
-- Running `genexus-mcp` without an AXI subcommand keeps the original MCP gateway launcher behavior.
-- `genexus-mcp home` (`genexus-mcp axi home`) is the explicit content-first AXI entrypoint.
-- `genexus-mcp llm help` returns protocol-first usage guidance for agents.
-- Full LLM-facing AXI contract: [`docs/axi_cli_contract.md`](docs/axi_cli_contract.md)
-- LLM usage playbook (CLI + MCP best practices): [`docs/llm_cli_mcp_playbook.md`](docs/llm_cli_mcp_playbook.md)
+**Build & lifecycle**
+- *"Build the KB and report any errors."*
+- *"Run the unit tests and show me which failed."*
+
+The agent picks the right tool from the **30+ tools** the MCP exposes (read, edit, refactor, analyze, build, layout automation, history, SQL preview, etc.). The full tool list is in [Tool Surface](#tool-surface) below.
 
 ---
 
-## 🛠️ Tool Surface (Skills)
-*(See `GEMINI.md` for extended guidelines).* The worker natively exposes the following tools to the MCP Router:
+## Supported AI clients
+
+Auto-detected and auto-configured by the installer:
 
-- **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`)
+| Client | Auto-config | Notes |
+|---|---|---|
+| Claude Desktop | ✅ | Restart required after install |
+| Claude Code (CLI) | ✅ | Reload session |
+| Cursor | ✅ | Restart required |
+| Antigravity | ✅ | Restart required |
+| Any MCP client | Manual | Use the JSON snippet printed by `init` |
+
+---
 
-> **`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).
+## Troubleshooting
 
-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`
-- **Patterns**: Smart XML generation and interpretation (e.g., WorkWithPlus PatternInstance mapping).
+Most install issues fall into a handful of buckets — see **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** for fixes:
 
-### MCP tool response ergonomics
+- Installer can't find GeneXus or the KB
+- AI client doesn't see the GeneXus tools after restart
+- "Worker failed to start" / .NET 4.8 errors
+- KB build errors / locked artifacts
+- Port 5000 already in use
+- Permissions on `%LOCALAPPDATA%\GenexusMCP\`
+
+Still stuck? [Open an issue](https://github.com/lennix1337/Genexus18MCP/issues) with the output of `npx genexus-mcp doctor --mcp-smoke`.
+
+---
 
-For `tools/call`, the gateway keeps MCP compatibility and adds lightweight response metadata:
+## Tool Surface
 
-- `_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`
-- `_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
+The worker exposes these tool families to the MCP router. *(Detailed schemas in [`GEMINI.md`](GEMINI.md).)*
 
-For list-heavy calls (`genexus_query`, `genexus_list_objects`), optional arguments can reduce token usage:
+- **Search & Discovery** — `genexus_query`, `genexus_read`, `genexus_inspect`, `genexus_list_objects`, `genexus_properties`
+- **Editing & Architecture** — `genexus_edit`, `genexus_create_object`, `genexus_refactor`, `genexus_forge`, `genexus_add_variable`
+- **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`
+- **Lifecycle & Build** — `genexus_lifecycle`, `genexus_test`, `genexus_format`
+- **Native Layout SDK** — `genexus_layout` (`get_tree`, `find_controls`, `set_property`, `rename_printblock`, `add_printblock`, `get_preview`, …)
+- **Patterns** — Smart XML generation/interpretation (e.g., WorkWithPlus PatternInstance).
 
-- `fields`: explicit projection (`["name","type"]` or `"name,type"`)
-- `axiCompact: true`: compact default projection
+**Edit modes** (`genexus_edit`): `xml` (full replacement, default), `ops` (typed semantic ops like `set_attribute`, `add_rule`), `patch` (JSON-Patch RFC 6902).
 
-Timeout behavior for long-running MCP tools:
-- Gateway may return `result.isError=true` with `status=Running` plus `operationId`/`correlationId`.
-- In this case, do not fail fast. Continue with `genexus_lifecycle(action='status'|'result', target='op:<operationId>')`.
+**Safe by default**: all write tools accept `dryRun: true` (returns a preview without mutating the KB) and `idempotencyKey` (safe retries; concurrent calls coalesce, results cached 15 min).
 
 ---
 
-## 💻 Development & Building from Source
+## AXI CLI (for agents and automation)
 
-If you want to contribute, build the project yourself, or use the local **Nexus-IDE** VS Code Extension, use the classic source-based workflow.
+The `genexus-mcp` command itself is also an agent-facing CLI with token-optimized output:
 
-### Automated Release (npm + GitHub)
-- Workflow: `.github/workflows/release.yml`
-- Trigger: `push` na `main` com mudança em `package.json`
-- Behavior:
-- compara a versão atual com a versão do commit anterior
-- publica no npm apenas se a versão for nova
-- cria GitHub Release com tag `v<version>`
-- Required secret:
-- `NPM_TOKEN` (token de publicação no npm com permissão para o pacote `genexus-mcp`)
-
-### One-Click Build
-1. Clone the repository to your Windows machine.
-2. Run `.\setup.bat`.
-   * *This checks prerequisites, builds the C# components, and auto-registers the local server with Claude, Codex, Antigravity, and Cursor when detected.*
-3. If GeneXus or your KB are not auto-detected, follow the terminal prompts.
-
-### Nexus-IDE (VS Code)
-The repository includes `src/nexus-ide`, a lightweight VS Code extension containing:
-- Virtual file system using the `genexus://` scheme
-- Dynamic KB explorer with multi-part editing (Source, Rules, Events, Variables)
-- Built-in MCP discovery commands (tools, resources, prompts)
+```bash
+genexus-mcp status               # gateway/worker state
+genexus-mcp doctor --mcp-smoke   # health check + protocol probe
+genexus-mcp tools list           # list available tools
+genexus-mcp config show          # current resolved config
+genexus-mcp layout status        # native layout automation state
+```
+
+Global flags: `--format toon|json|text` · `--fields f1,f2,...` · `--limit N` · `--query <text>` · `--quiet` · `--no-color`.
+
+Full contract: [`docs/axi_cli_contract.md`](docs/axi_cli_contract.md). Best-practices playbook: [`docs/llm_cli_mcp_playbook.md`](docs/llm_cli_mcp_playbook.md).
 
-### Advanced Configuration
-You can expand your local `config.json` for advanced networking or timeouts:
+---
+
+## Advanced Configuration
+
+The installer writes a `config.json` for you. To customize networking, timeouts, or shadow paths:
 
 ```json
 {
@@ -195,14 +185,47 @@ You can expand your local `config.json` for advanced networking or timeouts:
 }
 ```
 
-### Process Lifecycle & Architecture
-- **Lazy Worker Mapping:** The .NET 8 Gateway is resident, but the heavy .NET 4.8 Worker is lazy (only spins up when the first standard command is received) and automatically terminates after `Server.WorkerIdleTimeoutMinutes` of inactivity to unlock build artifacts.
-- **Gateway Reuse**: Launching multiple local IDE instances reuses a single active gateway using a unique lease file located at `%LOCALAPPDATA%\GenexusMCP\gateway-leases`.
-- **HTTP Mode**: Run via HTTP at `http://127.0.0.1:5000/mcp` (Supports SSE notifications alongside standard POST JSON-RPC). Protocol expects `MCP-Protocol-Version: 2025-06-18`.
+### Architecture
 
 ```mermaid
 graph LR
-    A[AI Client or Nexus-IDE] -->|MCP stdio or HTTP /mcp| B[Gateway .NET 8]
+    A[AI Client / Nexus-IDE] -->|MCP stdio or HTTP /mcp| B[Gateway .NET 8]
     B -->|JSON-RPC over process boundary| C[Worker .NET Framework 4.8]
     C -->|Native SDK| D[GeneXus KB]
 ```
+
+- **Lazy worker**: the heavy .NET 4.8 worker only spins up on first command and shuts down after `WorkerIdleTimeoutMinutes` of inactivity to unlock build artifacts.
+- **Gateway reuse**: multiple IDE instances share one gateway via lease files at `%LOCALAPPDATA%\GenexusMCP\gateway-leases`.
+- **HTTP mode**: also available at `http://127.0.0.1:5000/mcp` with SSE. Header: `MCP-Protocol-Version: 2025-06-18`.
+
+---
+
+## Development & building from source
+
+Want to contribute or run a local dev build?
+
+1. Clone this repo on Windows.
+2. Run `.\setup.bat` — checks prerequisites, builds the C# components, and auto-registers the local build with detected AI clients.
+3. If GeneXus or your KB aren't auto-detected, follow the prompts.
+
+### Nexus-IDE (VS Code extension)
+
+`src/nexus-ide` is a lightweight VS Code extension that ships with the repo:
+- Virtual filesystem using the `genexus://` scheme
+- Dynamic KB explorer with multi-part editing (Source, Rules, Events, Variables)
+- Built-in MCP discovery commands (tools, resources, prompts)
+
+### Automated release
+
+- Workflow: `.github/workflows/release.yml`
+- Trigger: push to `main` with a `package.json` version bump
+- Behavior: publishes to npm if version is new + creates a GitHub Release tagged `v<version>`
+- Required secret: `NPM_TOKEN`
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+> **Search keywords:** GeneXus MCP · GeneXus 18 MCP · GeneXus AI · GeneXus Claude · Model Context Protocol GeneXus · GeneXus low-code AI agent · GeneXus Cursor · GeneXus Antigravity