genexus-mcp 1.1.6 → 1.2.0

package/README.md

@@ -6,35 +6,97 @@ A high-performance Model Context Protocol (MCP) server for GeneXus 18. It integr
 
 ***
 
-## 🚀 Quick Start (For AI Agents)
+## 🚀 Quick Start (Installation & Configuration)
 
-You **do not** need to clone this repository or install anything globally if you have Node.js installed. You can configure your AI Assistant (Claude Desktop, Cursor, RooCode, etc.) to fetch and run the server dynamically!
+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.
 
-### 1. Zero Configuration (For Cursor, Cline & Roo)
-If your AI Tool runs inside an IDE (where the Current Working Directory is your KB), you don't need to configure anything. `genexus-mcp` automatically discovers where GeneXus is installed and dynamically binds to your current Knowledge Base!
+### Step 1: Configure (Non-Interactive First)
 
-### 2. Guided Setup Wizard (For Claude Desktop & Antigravity)
-If you are using a Global Desktop Agent, its "Current Directory" is the global `Program Files` directory, not your project. Therefore, you must generate a `config.json` file.
-Open a terminal in any folder and run our **Setup Wizard**:
+To initialize configuration in a deterministic, agent-friendly way:
 
 ```bash
-npx genexus-mcp init
+npx genexus-mcp@latest init --kb "C:\KBs\YourKB" --gx "C:\Program Files (x86)\GeneXus\GeneXus18"
 ```
-*The wizard will ask you for your KB folder and GeneXus path, create the configuration, and output the exact JSON snippet you must paste into your AI Assistant!*
 
-### 3. Add to your AI Assistant
-Add the `mcpServers` configuration block into your AI Tool settings.
+If you want the setup wizard prompts explicitly, run:
 
-```json
-"mcpServers": {
-  "genexus": {
-    "command": "npx.cmd", // Windows requires npx.cmd
-    "args": ["-y", "genexus-mcp@latest"]
-    // "env": { "GX_CONFIG_PATH": "C:\\path\\to\\your\\config.json" } // Only if generated by 'init'!
-  }
-}
+```bash
+npx genexus-mcp@latest init --interactive
 ```
-**That's it!** The AI will automatically download the compiled Windows gateway in the background and bridge the logic directly to your local GeneXus!
+
+### Step 2: Restart your AI Assistant
+
+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.
+
+---
+
+### 🤖 Auto-Installer Prompt (Copy & Paste to your AI)
+
+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:
+
+```markdown
+Please configure your Model Context Protocol (MCP) server to connect to my GeneXus Knowledge Base by following these exact steps:
+
+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!
+```
+
+---
+
+## AXI CLI Commands
+
+The package now includes agent-facing commands optimized for shell automation:
+
+```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"
+```
+
+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)
 
 ---
 
@@ -46,15 +108,47 @@ Add the `mcpServers` configuration block into your AI Tool settings.
 - **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`)
+
+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).
 
+### MCP tool response ergonomics
+
+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
+- collection helpers such as `returned`, `total`, `empty`, and (when inferable) `hasMore` and `nextOffset`
+- truncation signals via `meta.truncated` plus contextual `help`
+
+For list-heavy calls (`genexus_query`, `genexus_list_objects`), optional arguments can reduce token usage:
+
+- `fields`: explicit projection (`["name","type"]` or `"name,type"`)
+- `axiCompact: true`: compact default projection
+
+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>')`.
+
 ---
 
 ## 💻 Development & Building from Source
 
 If you want to contribute, build the project yourself, or use the local **Nexus-IDE** VS Code Extension, use the classic source-based workflow.
 
+### 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`.