GeneXus MCP服务器——用于Claude、Cursor和AI代理的GeneXus 18
你会说西班牙语吗？ → 西班牙语入门指南 卡住了？ → 故障排除指南
______________________________________________________________________
GeneXus MCP服务器 允许人工智能代理（Claude Desktop、Claude Code、Cursor、Antigravity和任何兼容MCP的客户端）读取、编辑、分析和重构GeneXus 18知识库中的对象。它与 原生GeneXus SDK，因此代理与 *真实的* KB，不是副本或解析的近似值。
在实践中：你把MCP指向你的知识库，然后问你的人工智能助手一些事情，比如 *“列出具有CustomerId属性的所有事务”*, *“在Order事务中添加一条规则，以验证总计”*，或 *“重构此过程以使用新的SDT”* --它确实做到了。
______________________________________________________________________
先决条件
在开始之前，请确保您已经：
- ✅ 视窗 （GeneXus仅支持Windows，此MCP在Windows上运行）
- ✅ GeneXus 18 本地安装（通常
C:\Program Files (x86)\GeneXus\GeneXus18) - ✅ GeneXus 18知识库 在IDE中至少打开一次（因此它已被构建/初始化）
- ✅ Node.js 18+ (下载)
你做 不 需要克隆此仓库或全局安装任何东西-- npx 处理它。
______________________________________________________________________
快速入门（3个步骤）
步骤1--运行安装程序
打开终端并运行，将路径替换为 你的 KB文件夹和 你的 GeneXus安装：
npx genexus-mcp@latest init --kb "C:\KBs\YourKB" --gx "C:\Program Files (x86)\GeneXus\GeneXus18"更喜欢巫师？跑 npx genexus-mcp@latest init --interactive 并回答提示。当它完成时，你应该看到 🎉 You are all set! 为您的AI客户端添加一个JSON代码段。
步骤2——在您的AI客户端中注册MCP
安装程序 自动寄存器 当检测到Claude Desktop、Claude Code、Cursor和Antigravity时，服务器会使用它们。如果未检测到您的配置，请手动将步骤1中的JSON代码段复制到客户端的MCP配置中。请参阅 客户端设置指南 如果不确定该文件的位置。
步骤3——重启AI客户端并测试
完全关闭并重新打开Claude/Cursor/等。然后尝试以下提示：
*“使用GeneXus MCP，列出我的知识库中的前5个事务并显示它们的名称。”*
如果你收到一份清单-- 你完了.跳到 我能问AI什么？ 对于想法。
如果有什么不起作用，直接去 故障排除 --其中涵盖了大多数问题。
______________________________________________________________________
🤖 让你的AI为你安装它
如果你不想自己在终端上运行任何东西，请将此粘贴到你的AI聊天中：
请配置GeneXus MCP服务器。跑 npx genexus-mcp@latest init --kb "" --gx "" 在终端。如果我还没有告诉你我的GeneXu路径和KB路径，请先问我。一旦成功，读取它打印的JSON块并将其添加到我的MCP客户端配置中。告诉我什么时候应该重新启动客户端以开始使用GeneXu的工具。替换占位符或让AI向您索取。
______________________________________________________________________
企业安装（固定路径，ASR友好）
如果你的机器有 Microsoft Defender ASR, 智能屏幕，或另一个端点策略阻止未签名的二进制文件，默认值 npx 流是痛苦的-- npx 将包缓存在 %LOCALAPPDATA%\npm-cache\_npx\\...，以及 `` 每个版本都会发生变化，因此IT无法在整个npm缓存上没有通配符的情况下将稳定路径列入白名单（这太宽泛了）。
请改用公司安装程序。它将二进制文件提取到一个稳定的目录中，并注册AI客户端以直接从那里启动网关-- npx 从不在运行时路径上。
# One-liner — installs latest release, registers AI clients
iex (irm https://raw.githubusercontent.com/lennix1337/Genexus18MCP/main/scripts/install.ps1)
# With explicit KB and GeneXus paths
$s = irm https://raw.githubusercontent.com/lennix1337/Genexus18MCP/main/scripts/install.ps1
& ([scriptblock]::Create($s)) -Kb "C:\KBs\MyKB" -Gx "C:\Program Files (x86)\GeneXus\GeneXus18"安装位置：
- 管理员shell →
C:\Tools\GenexusMCP\ - 非管理员shell →
%LOCALAPPDATA%\Programs\GenexusMCP\
ASR/Defender排除列表给IT的路径：
\GxMcp.Gateway.exe
\worker\GxMcp.Worker.exe稍后重新运行同一个liner 升级 --它检测已安装的版本(version.txt 在安装目录中），并且仅在有较新版本可用时下载。使用 -Force 为了重新安装相同的版本， -Version v2.3.0 为了固定特定标签， -NoClient 跳过AI客户端注册。客户端注册必须安装Node.js 18+；没有它，脚本仍然会提取二进制文件，但您需要编辑客户端配置(claude_desktop_config.json 等等）手动操作。
______________________________________________________________________
我能问AI什么？
安装后，以下是解锁的内容。尝试以下作为您的第一个提示：
探索
- *“列出知识库中所有Procedure类型的对象。”*
- *“显示CalculateInvoiceTotal过程的来源。”*
- *“查找引用CustomerId属性的所有事务。”*
编辑
- *“向订单事务添加规则：如果总计\ 多KB（v2.3.0+）： 每个非元工具都有一个可选
kb参数（别名或绝对路径）。网关可以承受Server.MaxOpenKbs（默认3）KB一次打开，每个KB都在自己的Worker进程中——对不同KB的调用真正并行运行。看 高级配置 为了KBs[]模式。
编辑模式 (genexus_edit): xml （完全替换，默认）， ops （键入语义操作，如 set_attribute, add_rule), patch （JSON补丁RFC 6902）。
默认安全：所有写入工具都接受 dryRun: true （返回预览而不改变KB）和 idempotencyKey （安全重试；并发调用合并，结果缓存15分钟）。
______________________________________________________________________
AXI CLI（用于代理和自动化）
这 genexus-mcp 命令本身也是一个面向代理的CLI，具有令牌优化的输出：
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全球旗帜： --format toon|json|text · --fields f1,f2,... · --limit N · --query · --quiet · --no-color.
完整合同： docs/axi_cli_contract.md.最佳做法手册： docs/llm_cli_mcp_playbook.md.
______________________________________________________________________
高级配置
安装程序写入 config.json 为你。要自定义网络、超时或影子路径，请执行以下操作：
{
"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" }
]
}
}向后兼容性： 旧配置与单一Environment.KBPath继续工作--网关会自动将它们迁移到KBs[]+DefaultKb在加载时。
使用多个KB
一旦您在中声明了多个KB Environment.KBs[]，每个工具都接受一个可选 kb 论点：
// LLM example: list procedures in two KBs in parallel
{ "tool": "genexus_list_objects", "arguments": { "kb": "main", "type": "Procedure" } }
{ "tool": "genexus_list_objects", "arguments": { "kb": "legacy", "type": "Transaction" } }决议规则 kb 省略：
- 正好打开1 KB→ 使用该KB
- 0 KB打开+
DefaultKbset → opensDefaultKb懒洋洋地 - 2+KB打开→ 服务器返回
KB_AMBIGUOUS你必须通过kb明确地
运行时管理池：
{ "tool": "genexus_kb", "arguments": { "action": "list" } }
// → { openKbs: [{alias, path, pid, workingSetMB, idleSeconds}], maxOpenKbs, defaultKb, declaredKbs }
{ "tool": "genexus_kb", "arguments": { "action": "open", "alias": "adhoc", "path": "C:/KBs/ScratchKB" } }
{ "tool": "genexus_kb", "arguments": { "action": "close", "alias": "legacy" } }
{ "tool": "genexus_kb", "arguments": { "action": "set_default", "alias": "main" } } // persists to config.json当池已满且没有Worker处于空闲状态时，服务器将返回 KB_POOL_FULL --明确关闭或提高 Server.MaxOpenKbs每个Worker都在其自己的进程中携带SDK（约200-400 MB空闲，在大KB上高达1-2 GB），因此请根据可用RAM调整池的大小。
建筑
graph LR
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]- 工作池（v2.3.0+）：一个。NET 4.8每打开KB的工作进程数，上限为
MaxOpenKbs（默认值3）。工人们懒洋洋地出生，被回收WorkerIdleTimeoutMinutes，并在游泳池满时驱逐LRU。 - 跨KB并行性：对不同KB的工具调用在不同的Worker进程上运行，从不相互阻塞。对同一KB的调用仍然按照GeneXus SDK的STA要求进行序列化。
- 网关重用：多个IDE实例通过以下位置的租约文件共享一个网关
%LOCALAPPDATA%\GenexusMCP\gateway-leases. - HTTP模式：也可在
http://127.0.0.1:5000/mcp与SSE。头球MCP-Protocol-Version: 2025-11-25.
______________________________________________________________________
从源头开发和建设
想要贡献或运行本地开发构建？
- 在Windows上克隆此仓库。
- 跑
.\setup.bat--检查先决条件，构建C#组件，并向检测到的AI客户端自动注册本地构建。 - 如果未自动检测到GeneXus或您的知识库，请按照提示进行操作。
捆绑式AI技能(.gemini/skills/)
此回购提供了一组 代理技能 在...之下 .gemini/skills/ 任何具有技能支持的MCP兼容客户端（Gemini CLI、通过插件的Claude Code等）都可以加载其GeneXu的推理：
| 技能 | 它给代理人带来了什么 |
|---|---|
genexus-mastery | 此存储库的首选MCP工作流+多KB使用 |
genexus18-guidelines | 基于Nexa的本地工程规则 |
nexa | 完整的GeneXus 18参考集：每个对象类型、命令、类型、属性——从官方导入 genexuslabs/genexus-skills |
frontend/chameleon-controls-library | 58变色龙UI组件规格 |
frontend/mercury-design-system | 水星代币、捆绑、主题化 |
frontend/design-system-builder | 编写自定义设计系统 |
frontend/ui-creator | 面板/屏幕生成模板 |
第三方技能是Apache 2.0（参见 .gemini/skills/NOTICE.md).要刷新上游，请按照中的步骤操作 NOTICE.md.
Nexus IDE（VS代码扩展）
src/nexus-ide 是仓库附带的轻量级VS Code扩展：
- 使用虚拟文件系统
genexus://方案 - 具有多部分编辑功能的动态知识库浏览器（源、规则、事件、变量）
- 内置MCP发现命令（工具、资源、提示）
自动发布
- 工作流程：
.github/workflows/release.yml - 触发器：按下
main带着一个package.json版本碰撞 - 行为：如果版本是新的，则发布到npm+创建一个标记为GitHub Release的GitHub
v - 所需机密：
NPM_TOKEN
______________________________________________________________________
许可证
麻省理工学院——见 许可证.
搜索关键字： GeneXus MCP·GeneXus 18 MCP·GeneXus AI·GeneXus-Claude·模型上下文协议GeneXus·GeneXu低代码AI代理·GeneXu's游标·GeneXus-反重力