genexus-mcp 3.6.0 → 3.7.0

package/README.md

@@ -12,19 +12,21 @@
 
 ---
 
-**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 Knowledge Base supported by the selected GeneXus SDK. It talks to the **native GeneXus SDK**, so the agent works with the *real* KB, not a copy or a parsed approximation.
+**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 Knowledge Base supported by the selected native SDK or legacy compatibility driver. Native SDK paths work with the **real GeneXus SDK** and legacy paths use explicit reflection/COM adapters; neither path relies on a parsed copy of the KB.
 
 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.
 
 ---
 
-## Multi-version SDK support
+## Multi-version GeneXus support
 
-The same MCP distribution supports the SDK majors listed in the generated
-compatibility document. Each configured MCP process selects one installed SDK
-with `--gx`; no separate MCP installation is required. The commands below are
-examples of switching the existing configuration, not running two majors in
-the same process:
+The same MCP distribution supports the official native SDK majors listed in the
+generated compatibility document. It also includes basic, best-effort
+compatibility for the legacy versions listed there through separate drivers;
+that path is not equivalent to full native-SDK support. A process can route
+each declared KB to its own SDK/driver; `--gx` remains the convenient global
+default for a single-major configuration. The commands below are examples of
+switching the existing configuration:
 
 ```bash
 npx genexus-mcp@latest init --kb "C:\KBs\KBTeste17" --gx "C:\Program Files (x86)\GeneXus\GeneXus17Trial"
@@ -36,6 +38,32 @@ After switching the SDK or KB, fully restart the AI client so it reloads the
 MCP process and its tool schemas. If GX17 and GX18 must run simultaneously,
 use separate MCP configurations and ports.
 
+Classic GX8/GX9 KBs can be opened without changing the global GX18 default by
+declaring their driver and installation per KB (the Gateway accepts both the
+list and object catalog shapes):
+
+```json
+{
+  "Environment": {
+    "KBs": {
+      "SECT80": {
+        "Path": "D:\\GX80\\SECT",
+        "Driver": "com-gxpublic",
+        "InstallationPath": "C:\\Program Files (x86)\\ARTech\\GeneXus\\gxw80",
+        "Major": "8"
+      }
+    }
+  }
+}
+```
+
+The equivalent one-shot request is `genexus_kb action=open` with `path`,
+`alias`, `driver: "com-gxpublic"`, `installationPath`, and `major: "8"`.
+GX8 uses the registered 32-bit GXPublic provider; the documented `.4` ProgID
+and the installed `GXPubGXX.GXPublic(.5)` compatibility registration are
+recognized. Classic DAT KB roots are identified from their legacy markers
+(`DATA001`, `GXSPC001`, `kbdata`, `ATTRIBUT.DAT`, or `ATT.XPW`).
+
 `init` also reads the KB `.gxw` major and the selected `GeneXus.exe` metadata.
 It aborts before writing `config.json` when the majors conflict or an automatic
 selection cannot be verified. `genexus-mcp doctor` exposes the same result as
@@ -45,7 +73,9 @@ that checks every supported major against one published artifact.
 
 The Gateway reports the detected SDK through `genexus_whoami`:
 
-- `geneXus.supportedMajors`: explicitly validated SDK majors from the version catalog
+- `geneXus.supportedMajors`: explicitly validated native SDK majors from the version catalog
+- `geneXus.legacyMajors`: catalogued legacy majors handled by their compatibility drivers
+- `geneXus.sdkCompatibility.supportLevel`: `native-sdk` or `basic-legacy` for the detected installation
 - `geneXus.matchedMajor`: the major detected for the configured installation
 - `geneXus.versionMatches`: whether the detected installation is in that catalog
 - `geneXus.supportedMajor`: retained as the legacy single-major alias for the catalog primary
@@ -57,23 +87,88 @@ needed. Existing tool names, arguments, and MCP client configuration formats do
 not change.
 
 <!-- BEGIN GENERATED: gx-compatibility -->
-Supported SDK majors: **GeneXus 16, GeneXus 17, GeneXus 18**.
+Supported SDK majors: **GeneXus 16, GeneXus 17, GeneXus 18** (native SDK).
+Basic legacy compatibility: **GeneXus Evolution 3, GeneXus Evolution 2, GeneXus Evolution 1, GeneXus 15, GeneXus 9.0, GeneXus 8.0** via `com-gxpublic` and `dotnet-reflection` (not the native SDK build).
 Primary SDK: **GeneXus 18**.
 Source of truth: `config/gx-versions.json`.
 <!-- END GENERATED: gx-compatibility -->
 
-To add another GeneXus major in the future, add it to the explicit version
-catalog only after compiling the Worker with that SDK and passing the focused
-tests plus a live KB smoke. This prevents the server from claiming compatibility
-based only on a version string.
+To add another native-SDK major in the future, add it to the explicit
+`supportedMajors` catalog only after compiling the Worker with that SDK and
+passing the focused tests plus a live KB smoke. This prevents the server from
+claiming native-SDK compatibility based only on a version string.
 
-### Legacy GeneXus compatibility (GX8 to GX15)
+### Basic legacy compatibility (not native SDK support)
 
-The server also includes best-effort dynamic compatibility for legacy installations:
+Every legacy version currently declared in `legacyMajors` uses a best-effort
+driver rather than the native SDK build:
 - **GeneXus Evolution 1 (10.1), Evolution 2 (10.2), Evolution 3 (10.3), and GeneXus 15**: Driven via runtime reflection (`dotnet-reflection`), dynamically adapting to missing types or structural differences (such as module-less KBs without `QualifiedName`).
-- **GeneXus 8.0 and GeneXus 9.0**: Driven via classic Win32 COM automation (`com-gxpublic`), late-binding to `GXPublic.GXPublic` on an STA thread to open, inspect, and read objects from classic `.gxi` Knowledge Bases.
+- **GeneXus 8.0 and GeneXus 9.0**: Driven through the classic GXPublic surface (`com-gxpublic`), detected from `gxw32.exe`/`gx.exe`/`gxdl32.dll` and classic `.gxi` Knowledge Bases. GXPublic is a metadata-oriented OLE DB surface; this path is intentionally limited to basic metadata/core operations and does not claim native-SDK source/edit parity.
 - **Graceful degradation**: Modern tools that require features introduced in newer GeneXus versions (such as `genexus_api`, `genexus_gam`, or `genexus_module`) return structured `UNSUPPORTED_IN_GENEXUS_VERSION` errors indicating the required minimum version rather than failing ungracefully.
 
+This legacy path is intended for basic core operations where implemented; it
+does not claim the same feature parity as the native SDK contract for GeneXus
+16, 17, and 18.
+
+---
+
+## Sharing one Worker between MCP clients
+
+The Gateway and the GeneXus SDK Worker have different responsibilities. By
+default, `Server.WorkerSharingMode` is `"isolated"`: each Gateway owns its own
+Worker process. Keep that mode when an agent intentionally needs multiple
+independent Workers.
+
+When two or more independent MCP clients need to work on the same physical KB,
+set `WorkerSharingMode` to `"shared-host"` in a `stdio-isolated` configuration:
+
+```json
+{
+  "ConfigSchemaVersion": 2,
+  "GatewayMode": "stdio-isolated",
+  "GeneXus": {
+    "InstallationPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18",
+    "WorkerExecutable": "C:\\path\\to\\GxMcp.Worker.exe"
+  },
+  "Server": {
+    "HttpPort": 0,
+    "McpStdio": true,
+    "WorkerSharingMode": "shared-host"
+  },
+  "Environment": {
+    "ResolutionPolicy": "strict",
+    "KBs": [
+      { "alias": "main", "path": "C:\\KBs\\YourKB" }
+    ]
+  }
+}
+```
+
+`shared-host` shares only the per-KB broker-owned SDK Worker through bounded
+local named-pipe attachments. The Gateways remain independent: MCP sessions,
+authorization, KB selection, caches, request tracking, cancellation, progress,
+notifications, and generated artifacts do not cross the process boundary.
+Sharing is accepted only when the physical KB, Worker executable, GeneXus
+installation, driver, and target major are compatible; a mismatch fails closed
+instead of attaching to the wrong SDK process.
+
+Writes carry a Gateway-local owner into the Worker. The same object/part cannot
+be written concurrently by two attached clients, while writes to distinct
+objects may proceed independently through the shared SDK boundary. The Worker
+itself remains a single STA process, so calls that reach the same SDK are still
+serialized as required by GeneXus.
+
+For a healthy shared attachment, `genexus_whoami` and `genexus_doctor` report the
+mode, identity key, pipe, host/Worker PIDs, generation, attachment ID, connection
+state, and the latest startup/failure diagnostic. When something fails, inspect
+`worker.diagnostics` and `workerHealth` before restarting or deleting local
+state; these fields distinguish configuration/identity, mutex or registry,
+pipe/handshake, startup, child exit/respawn, TTL, and frame failures.
+
+See [Worker ownership](docs/worker-ownership.md) for the lifecycle contract and
+[the shared-Worker benchmark](docs/benchmarks/2026-09-18-shared-worker.md) for
+the measured two-client smoke and backpressure results.
+
 ---
 
 ## What you can do with it
@@ -93,7 +188,10 @@ A quick map of what the agent can do against your real KB through the **50 tools
 | 🌿 **Versioning, transfer & teams** | KB model versions/branches, **real XPZ export/import** (dependency-aware), GXserver (Team Development) sync + **CI pipelines**, git-style history, multi-KB parallel work |
 | 🔐 **Security** | GAM / integrated-security provisioning, KB security audit + native Security Scanner |
 
-It works through the **native GeneXus SDK** — the same code paths the IDE uses — so edits are real and validated, not text hacks on KB files.
+Native SDK support works through the **native GeneXus SDK** — the same code paths
+the IDE uses — so edits are real and validated, not text hacks on KB files.
+Legacy support uses the reflection or COM driver listed in the catalog and
+degrades unsupported modern tools explicitly.
 
 ---
 
@@ -102,9 +200,9 @@ It works through the **native GeneXus SDK** — the same code paths the IDE uses
 Before you start, make sure you have:
 
 - ✅ **Windows** (GeneXus is Windows-only)
-- ✅ **A supported GeneXus SDK** installed locally (see [`docs/generated/supported-versions.md`](docs/generated/supported-versions.md); pass another install path explicitly when needed)
-- ✅ **GeneXus 18** installed locally (the primary supported SDK; other catalogued majors are also supported)
-- ✅ **A Knowledge Base created with a supported GeneXus major** and opened at least once in the IDE (so it's initialized)
+- ✅ **A supported GeneXus installation** installed locally: GeneXus 16, 17, or 18 for native SDK support, or a catalogued legacy installation for basic compatibility (see [`docs/generated/supported-versions.md`](docs/generated/supported-versions.md); pass another install path explicitly when needed)
+- ✅ **GeneXus 18** installed locally for the primary native-SDK path; other catalogued native and legacy versions are also supported according to their listed driver
+- ✅ **A Knowledge Base created with a supported native or legacy GeneXus major** and opened at least once in the IDE (so it's initialized)
 - ✅ **Node.js 22+** — check with `node --version` in a terminal; install from [nodejs.org](https://nodejs.org/) if missing
 - ✅ **An MCP-compatible AI client** — [Claude Desktop](https://claude.ai/download), [Claude Code](https://claude.com/claude-code), Cursor, Antigravity, etc.
 
@@ -312,7 +410,18 @@ same path when a previous failure is present. Read it before changing the instal
 using a global npm install; if the Antigravity launcher is stale, re-register it with
 `npx genexus-mcp@latest clients add --clients antigravity`.
 
-Still stuck? [Open an issue](https://github.com/lennix1337/Genexus18MCP/issues) with the output of `npx genexus-mcp doctor --mcp-smoke`.
+### Diagnosing a shared Worker failure
+
+If `shared-host` does not attach or a Worker is restarted, run
+`genexus_whoami` and `genexus_doctor` from the affected client and preserve the
+structured `worker.diagnostics`/`workerHealth` block. The useful evidence is the
+mode, identity, host/Worker PID, generation, attachment state, connection error,
+and failure diagnostic — not only the final `no_worker` or `startup_failed`
+summary. Do not remove a shared-worker registry file while a matching host is
+still running; the broker owns that lifecycle and stale records are recovered
+after PID/start-time validation.
+
+Still stuck? [Open an issue](https://github.com/lennix1337/Genexus18MCP/issues) with the output of `npx genexus-mcp doctor --mcp-smoke` and the bounded diagnostic fields above. Redact credentials, tokens, connection strings, and other sensitive values.
 
 ---
 
@@ -576,13 +685,16 @@ When the pool is full and no Worker is idle, the server returns `KB_POOL_FULL`
 
 ```mermaid
 graph LR
-    A[AI Client / Nexus-IDE] -->|MCP stdio or HTTP /mcp| B[Gateway .NET 10]
-    B -->|JSON-RPC over process boundary| C[Worker .NET Framework 4.8]
+    A[AI Client / Nexus-IDE] -->|MCP stdio or HTTP /mcp| B[Independent Gateway .NET 10]
+    B -->|isolated stdio: direct child| C[Worker .NET Framework 4.8]
+    B -->|shared-host: named-pipe attachment| H[Per-KB WorkerHost broker]
+    H -->|one compatible child| C
     C -->|Native SDK| D[GeneXus KB]
 ```
 
-- **Worker pool (v2.3.0+)**: one .NET 4.8 Worker process per open KB, capped by `MaxOpenKbs` (default 3). Workers are spawned lazily, recycled by `WorkerIdleTimeoutMinutes`, and evicted LRU when the pool is full.
+- **Worker pool (v2.3.0+)**: in isolated mode, one .NET 4.8 Worker process per open KB in each Gateway, capped by `MaxOpenKbs` (default 3). With `shared-host`, compatible Gateways attach to one broker-owned Worker per physical KB instead of starting duplicate SDK processes. Workers are spawned lazily, recycled by `WorkerIdleTimeoutMinutes`, and evicted LRU when the pool is full.
 - **Cross-KB parallelism**: tool calls to different KBs run on different Worker processes and never block each other. Calls to the same KB are still serialized by the GeneXus SDK's STA requirement.
+- **Gateway isolation**: `shared-host` does not turn one Gateway into a master or proxy for another; each client keeps its own MCP state and only the SDK Worker is shared.
 - **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-11-25`.