GeneXus 18 MCP服务器

Prerequisites

Before you start, make sure you have:

• ✅ Windows (GeneXus is Windows-only)
• ✅ GeneXus 18 installed locally (default path: C:\Program Files (x86)\GeneXus\GeneXus18)
• ✅ A GeneXus 18 Knowledge Base opened at least once in the IDE (so it's initialized)
• ✅ Node.js 18+ — check with node --version in a terminal; install from nodejs.org if missing
• ✅ An MCP-compatible AI client — Claude Desktop, Claude Code, Cursor, Antigravity, etc.

You do not need to clone this repo or install anything globally — npx handles it.

Never used a terminal before? Press Win+R, type powershell, hit Enter. That's your terminal.

---

Step 1 — Run the installer

Open a terminal and run, replacing the paths with your KB folder and your GeneXus install:

npx genexus-mcp@latest init --kb "C:\KBs\YourKB" --gx "C:\Program Files (x86)\GeneXus\GeneXus18"

Prefer the wizard? Run npx genexus-mcp@latest init --interactive and answer the prompts.

What you'll see (takes ~30 seconds first time, faster on re-runs):

1. npx downloads the package.
2. The installer verifies the paths exist and GeneXus is present.
3. It auto-detects which AI clients you have installed and adds the MCP config to each one.
4. Prints a JSON snippet at the end — keep it in case you need to configure a client manually.
5. Finishes with 🎉 You are all set!.

🤖 Let your AI install it for you

If you'd rather not run anything in the terminal yourself, paste this into your AI chat:

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.

Replace the placeholders or let the AI ask you for them.

---

Corporate install (fixed path, ASR-friendly)

If your machine has Microsoft Defender ASR, SmartScreen, or another endpoint policy blocking unsigned binaries, the default npx flow is painful — npx caches the package under %LOCALAPPDATA%\npm-cache\_npx\<hash>\..., and the <hash> changes per version, so IT can't whitelist a stable path without a wildcard over the whole npm cache (which is too broad).

Use the corporate installer instead. It extracts the binaries to a stable directory and registers the AI clients to launch the gateway directly from there — npx is never on the runtime path.

```pwsh

One-liner — installs latest release, registers AI clients

iex (irm https://raw.githubusercontent.com/lennix1337/Genexus18MCP/main/scripts/install.ps1)

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.

Quickstart (3 steps, ~5 minutes)

Advanced Configuration

The installer writes a config.json for you. To customize networking, timeouts, or shadow paths:

{
  "Server": {
    "HttpPort": 5000,
    "BindAddress": "127.0.0.1",
    "SessionIdleTimeoutMinutes": 10,
    "WorkerIdleTimeoutMinutes": 5,
    "MaxOpenKbs": 3
  },
  "GeneXus": {
    "InstallationPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18",
    "WorkerExecutable": "worker\\GxMcp.Worker.exe"
  },
  "Environment": {
    "DefaultKb": "main",
    "KBs": [
      { "alias": "main",   "path": "C:\\KBs\\YourKB" },
      { "alias": "legacy", "path": "C:\\KBs\\OtherKB" }
    ]
  }
}

Backward compatibility: old configs with a single Environment.KBPath keep working — the gateway auto-migrates them to KBs[] + DefaultKb at load time.

AXI CLI (for agents and automation)

The genexus-mcp command itself is also an agent-facing CLI with token-optimized output:

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. Best-practices playbook: docs/llm_cli_mcp_playbook.md.

---

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)

Troubleshooting

Most install issues fall into a handful of buckets — see TROUBLESHOOTING.md for fixes:

• 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 with the output of npx genexus-mcp doctor --mcp-smoke.

---