English · Español

GxGenie — MCP Server for GeneXus 17 / 18

GxGenie is a Model Context Protocol server that lets Claude Code talk to GeneXus 17 / 18 Knowledge Bases directly — listing objects, reading source code, creating procedures, exporting/importing XPZs, building objects — without opening the GeneXus IDE.

Talk to your KB in plain language:

"List all transactions whose name starts with Customer" "Show me the source of procedure CalcularTotal" "Create a procedure called DemoMCP that logs 'hello'"

---

Requirements

| Component | Version | Notes | |-------------|--------------------|--------------------------------------------------------| | Windows | 10 / 11 | GeneXus SDK is x86 | | GeneXus | 17U1 / 17U11 / 18 | 17 validated end-to-end; 18 supported via adapter | | .NET SDK | 8.0+ | Installed automatically by setup.ps1 | | LocalDB | Bundled with SQL Server Express | KBs are persisted in LocalDB | | Claude Code | latest | Run claude --version to check |

---

Installation

The recommended mode is Per-KB: the MCP gets attached to each KB folder and loads automatically when Claude Code opens it. A global mode is also available for multi-KB scenarios with hot switching.

Per-KB mode (recommended)

git clone https://github.com/aocampol/GxGenie-MCP.git C:\Proyectos\GxGenie
cd C:\Proyectos\GxGenie
.\setup.ps1 -InstallToKb C:\KB\Gx17U1\SampleKB

A single command per KB. Re-run for every KB you want to "MCP-enable" — setup.ps1 is idempotent. It will:

1. Verify .NET 8 SDK (installs via winget if missing).
2. Build Worker + Gateway in Release mode.
3. Drop a .mcp.json file in the KB folder, pointing at the compiled Gateway, with GXGENIE_ALLOW_WRITE=true and GXGENIE_ALLOW_BUILD=true in its env block so that writes and builds are enabled out of the box. Every destructive op still snapshots the LocalDB to a .bak and logs to audit.log — the safety net is automatic, not opt-in.

Then to use it:

cd C:\KB\Gx17U1\SampleKB
claude

The first time Claude Code starts in that folder, it will ask you to approve the genexus MCP server. Say yes — the decision is remembered per folder.

Disabling writes (read-only per-KB install — useful when sharing a KB for inspection-only access):

.\setup.ps1 -InstallToKb C:\KB\Gx17U1\SampleKB -ReadOnly

This emits a .mcp.json without the env block; the Worker then auto-detects the KB by cwd and stays in read-only mode (the original safe default).

Using a shared config.json (instead of per-KB auto-detect):

.\setup.ps1 -InstallToKb C:\KB\Gx17U1\SampleKB -ConfigPath C:\Proyectos\GxGenie\config.json

Injects GXGENIE_CONFIG in the .mcp.json env, pointing at the explicit file. Useful if you maintain Security/backup settings centrally instead of per-KB.

Global mode (multi-KB)

Registers a single MCP at the user level and uses a central config.json listing all your KBs. Required if you want to use gx_switch_kb to hop between KBs without restarting Claude Code.

.\setup.ps1

This scans C:\KB, D:\KB, C:\GeneXus\KB for .gxw files, builds a multi-KB config.json, and registers the MCP globally via claude mcp add.

Uninstall

.\setup.ps1 -Uninstall

Removes the global MCP registration, deletes bin/ and obj/, and clears environment variables. Does not touch config.json, .mcp.json files already deployed to KB folders, audit.log, or backups/ — those are yours to manage.

---

Updating

If you already cloned the repo and want to pull newer versions, the fast path is the bundled script:

cd C:\Proyectos\GxGenie
.\update.ps1

update.ps1 aborts if any GxGenie.Worker.exe / GxGenie.Gateway.exe is still running (typically because Claude Code has the MCP server attached), then does git pull + dotnet build for both projects.

Manual equivalent (if you prefer to run each step):

# 1) Close every Claude Code session that has the MCP server loaded —
#    otherwise the .exe is locked and the build fails. Verify with:
tasklist /FI "IMAGENAME eq GxGenie.Gateway.exe"

# 2) Pull the new commits
git -C C:\Proyectos\GxGenie pull origin main

# 3) Rebuild Worker and Gateway
dotnet build C:\Proyectos\GxGenie\GxGenie.Worker\GxGenie.Worker.csproj  -c Release
dotnet build C:\Proyectos\GxGenie\GxGenie.Gateway\GxGenie.Gateway.csproj -c Release

# 4) Reopen Claude Code — the next tool call relaunches the Gateway with the new binary.

Check CHANGELOG.md for what every release introduces, removes, or breaks. The MCP registration (claude mcp add) and the config.json / .mcp.json files do not need to be re-created across versions unless the changelog explicitly says so.

If dotnet build complains with error MSB3027 about a file in use, some Claude Code window still has the Gateway open. Close it and retry, or as a last resort:

taskkill /F /IM GxGenie.Worker.exe /IM GxGenie.Gateway.exe

---

Usage

You don't invoke tools with slash commands — talk to Claude in plain language and it picks the right tool. See USAGE.md for the full guide. A few quick examples:

Inspect the KB

You: What objects are in the current Knowledge Base? Claude: [calls gx_kb_info] SampleKB (GX17), ~120,000 entities. Procedures: ~4,000, WebPanels: ~2,300, Transactions: ~600, SDTs: ~1,200...

Read an object's source

You: Show me the source of procedure CalcularTotal. Claude: [calls gx_read_object with name="CalcularTotal"]

for each Customer
    &total += CustomerBalance
endfor

Search code for an attribute

You: Where is the attribute ClienteId used in code? Claude: [calls gx_search with query="ClienteId", search_in="code"] Found in 47 objects: ...

Create a procedure

You: Create a procedure called DemoMCP that writes "hello" to the log. Claude: [calls gx_create_procedure] Procedure created. Backup at backups\SampleKB\20260514_104530\GX_KB_SampleKB__create_proc_DemoMCP.bak.

Work with two KBs in the same session (global mode only)

You: List my KBs. Claude: [calls gx_list_kbs] SampleKB (active), SampleKB2, SampleKB4 — all GX17.

You: Switch to SampleKB2 and tell me how many procedures it has. Claude: [calls gx_switch_kb, then gx_list_objects type=Procedure] SampleKB2 has 76 procedures.

---

Available tools (28)

Basic reads (direct SQL)

| Tool | Description | |----------------------|------------------------------------------------------------------------| | gx_kb_info | KB version, object counts per type, active KB, GeneXus version | | gx_list_objects | List objects by type with name filter | | gx_read_object | Decoded source of every Part (events, rules, body, structure, …) | | gx_search | Search by name (fast) or by code content (slow but thorough) | | gx_list_attributes | List a Transaction's attributes with type, length, PK status | | gx_list_object_parts | List the Parts known for an object type, with editable flag and kind |

Structured reads (parsed JSON)

| Tool | Description | |----------------------|------------------------------------------------------------------------| | gx_get_structure | Transaction/SDT/DataSelector structure as nested JSON levels | | gx_get_layout | Web Form as JSON tree, auto-detecting KIP (legacy) vs GXML (modern) | | gx_get_variables | Variables of any object with data_type decoded from AttCustomType | | gx_get_unused_variables | Variables not referenced in events / rules / conditions / source of the same object. Surfaces removable candidates separately from auto-included <StandardVariable> entries. |

Writes — objects and source code (MSBuild + GeneXus tasks)

| Tool | Notes | |-------------------------|----------------------------------------------------------------------| | gx_export_xpz | Export object(s) to an .xpz file | | gx_import_xpz | Import an .xpz. Auto SQL backup before | | gx_create_procedure | Create a new Procedure (minimal XPZ generated in memory + import) | | gx_create_transaction | Create a new Transaction — root level + key attribute, plus optional nested sub-levels (levels, recursive master-detail). Reuses attributes that already exist in the KB. | | gx_update_object_code | Update a Part's source/text for 15 object types (Procedure, WebPanel, Transaction, DataProvider, Domain, SDT, …). Validates editability per Part. | | gx_build_object | Specify + generate an object (requires AllowBuild=true) | | gx_delete_object | Delete an object. Auto SQL backup before |

Writes — Transaction Structure (granular)

| Tool | Notes | |----------------------------|--------------------------------------------------------------------| | gx_add_attribute | Create attribute and optionally attach it to a Transaction Level. Supports data_type (bas:Numeric, bas:VarChar, …) or based_on_domain. | | gx_remove_attribute | Remove the attribute reference from a Transaction Level. The Attribute stays in the KB. | | gx_set_attribute_property| Patch any Property of an existing Attribute (Description, Length, Decimals, ATTCUSTOMTYPE, idBasedOn, AUTONUMBER, …) | | gx_remove_variable | Remove a <Variable> from a Procedure/DataProvider/WebPanel/Transaction. Pre-checks reject standards and any variable still referenced in events/rules/conditions/source. |

Writes — Web Form layout (granular, mostly GXML)

| Tool | Notes | |---------------------------|---------------------------------------------------------------------| | gx_set_control_property | Modify an XML attribute on a control identified by controlName | | gx_add_control | Add a new control inside a parent (by controlName or id). Whitelist-validated; GXML only. | | gx_remove_control | Remove a control and its descendants. GeneXus BL may reject if the result is invalid (e.g. empty <cell>); SQL snapshot rollback is automatic. |

Multi-KB

| Tool | Description | |-----------------|--------------------------------------------------------------------------| | gx_list_kbs | List KBs from config.json and indicate which is active | | gx_switch_kb | Hot-swap the active KB without restarting Claude Code |

Writing tools require Security.AllowWrite=true (and AllowBuild=true for gx_build_object) in config.json. Off by default — you have to opt in. Every destructive operation snapshots the KB's LocalDB to a .bak under backups/ first, so any failed Import is restorable with RESTORE DATABASE.

---

Architecture

Claude Code (Anthropic)
    │ stdio — MCP Protocol (JSON-RPC 2.0)
    ▼
GxGenie.Gateway      ← .NET 8 — speaks MCP with Claude Code
    │ stdin/std