genexus

GeneXus MCP Server — 面向 Claude、Cursor 和 AI Agent 的多版本 GeneXus

¿Hablás español? → 西班牙语入门指南 Fala português? → 葡萄牙语入门指南 遇到问题？ → 故障排除指南 所有文档 → 文档索引

---

GeneXus MCP Server 可让 AI Agent（Claude Desktop、Claude Code、Cursor、Antigravity 以及任何兼容 MCP 的客户端）读取、编辑、分析和重构知识库中的对象。知识库需受所选原生 SDK 或旧版兼容驱动程序支持。原生 SDK 路径使用真正的 GeneXus SDK，旧版路径则使用明确的反射/COM 适配器；两种路径都不依赖经过解析的知识库副本。

实际使用时，只需将 MCP 指向你的知识库，然后向 AI 助手提出诸如 “列出所有包含属性 CustomerId 的事务”、“为 Order 事务添加一条用于验证总额的规则” 或 “重构此过程以使用新的 SDT” 之类的要求，它就会帮你完成。

---

多版本 GeneXus 支持

同一 MCP 分发包支持生成的兼容性文档中列出的官方原生 SDK 主版本。它还通过独立驱动，为其中列出的旧版本提供基础的尽力兼容；这条路径不等同于完整的原生 SDK 支持。进程可以为每个已声明的 KB 路由到各自的 SDK／驱动；对于仅配置一个主版本的场景，--gx 仍是便捷的全局默认选项。以下命令展示了如何切换现有配置：

npx genexus-mcp@latest init --kb "C:\KBs\KBTeste17" --gx "C:\Program Files (x86)\GeneXus\GeneXus17Trial"
# To switch this MCP configuration to GX18:
npx genexus-mcp@latest init --kb "C:\KBs\MyGX18KB" --gx "C:\Program Files (x86)\GeneXus\GeneXus18"

切换 SDK 或 KB 后，请完全重启 AI 客户端，使其重新加载 MCP 进程及其工具架构。如果必须同时运行 GX17 和 GX18，请使用独立的 MCP 配置和端口。

经典 GX8／GX9 KB 可以在不更改全局 GX18 默认值的情况下打开，方法是为每个 KB 声明其驱动和安装位置（Gateway 接受列表和对象两种目录结构）：

{
  "Environment": {
    "KBs": {
      "SECT80": {
        "Path": "D:\\GX80\\SECT",
        "Driver": "com-gxpublic",
        "InstallationPath": "C:\\Program Files (x86)\\ARTech\\GeneXus\\gxw80",
        "Major": "8"
      }
    }
  }
}

等效的一次性请求是 genexus_kb action=open，包含 path、alias、driver: "com-gxpublic"、installationPath 和 major: "8"。GX8 使用已注册的 32 位 GXPublic 提供程序；文档所述的 .4 ProgID 和已安装的 GXPubGXX.GXPublic(.5) 兼容性注册均可识别。经典 DAT KB 根目录会根据其旧版标记（DATA001、GXSPC001、kbdata、ATTRIBUT.DAT 或 ATT.XPW）进行识别。

init 也会读取 KB 的 .gxw 主版本以及所选 GeneXus.exe 的元数据。如果主版本冲突，或无法验证自动选择结果，它会在写入 config.json 前中止。当多个安装版本与 KB 主版本一致时，自动选择会优先选取更新版本与 .gxw 版本相符的安装（例如，针对 18.0.7.x KB 选择 U7），而不是最新版本。genexus-mcp doctor 会通过 kb_sdk_compatibility 检查项公开相同结果。对于临时测试夹具，实时 KB 测试工具包含一个由目录驱动的矩阵，可针对一个已发布的制品检查每个受支持的主版本。

Gateway 通过 genexus_whoami 报告检测到的 SDK：

• geneXus.supportedMajors：版本目录中明确验证过的原生 SDK 主版本
• geneXus.legacyMajors：目录中列出的、由兼容性驱动处理的旧版主版本
• geneXus.sdkCompatibility.supportLevel：针对检测到的安装，其值为 native-sdk 或 basic-legacy
• geneXus.matchedMajor：检测到的配置安装对应的主版本
• geneXus.versionMatches：检测到的安装是否在该目录中
• geneXus.supportedMajor：保留为目录中主版本的旧版单主版本别名

Worker 通过兼容性适配器隔离对版本敏感的 SDK 成员。 例如，对于不同 SDK 主版本中有所差异的 Design System 辅助方法，会在需要时通过解析原生 Tokens 和 Styles 部分，逐字段替代。现有工具名称、参数和 MCP 客户端配置格式均不变。

受支持的 SDK 主版本：GeneXus 16、GeneXus 17、GeneXus 18（原生 SDK）。 基础旧版兼容性：通过 com-gxpublic 和 dotnet-reflection 支持 GeneXus Evolution 3、GeneXus Evolution 2、GeneXus Evolution 1、GeneXus 15、GeneXus 9.0、GeneXus 8.0（非原生 SDK 构建）。 主要 SDK：GeneXus 18。 权威来源：config/gx-versions.json。

今后如需添加其他原生 SDK 主版本，只有在使用该 SDK 编译 Worker 并通过针对性测试和实时 KB 冒烟测试后，才能将其加入明确的 supportedMajors 目录。这样可以避免服务仅凭版本字符串就宣称兼容原生 SDK。

基本旧版兼容性（非原生 SDK 支持）

目前 legacyMajors 中声明的每个旧版本都使用尽力而为的驱动，而非原生 SDK 构建：

• GeneXus Evolution 1 (10.1)、Evolution 2 (10.2)、Evolution 3 (10.3) 和 GeneXus 15：通过运行时反射（dotnet-reflection）驱动，并动态适配缺失的类型或结构差异（例如没有 QualifiedName 的无模块 KB）。
• GeneXus 8.0 和 GeneXus 9.0：通过经典 GXPublic 接口（com-gxpublic）驱动；通过 gxw32.exe/gx.exe/gxdl32.dll 和经典 .gxi 知识库进行检测。GXPublic 是面向元数据的 OLE DB 接口；此路径有意仅限于基本元数据和核心操作，不声称在源代码和编辑方面与原生 SDK 完全一致。
• 优雅降级：需要较新 GeneXus 版本所引入功能的现代工具（例如 genexus_api、genexus_gam 或 genexus_module）会返回结构化的 UNSUPPORTED_IN_GENEXUS_VERSION 错误，指出所需的最低版本，而不会以不友好的方式失败。

此旧版路径旨在支持已实现的基本核心操作；它不声称与 GeneXus 16、17 和 18 的原生 SDK 契约具有相同的功能一致性。

---

实验性 gx-engine（Rust SDK 替代项目）

src/gx-engine 是一个独立的高性能 Rust 编译器和运行时，旨在完全替代专有 GeneXus SDK，消除旧版 32 位 STA 工作进程，并实现低于 20 秒的构建（Plan 130、Plan 129）。

🎮 反编译 / 一致性进度

进度依据记录的 SDK 差异输入和可观察结果衡量，而不是依据已实现模块的数量或通过的单元测试数量。在已发布的 4.0.0 基线中，一次可丢弃的 KBTeste Rebuild All 记录为 346/346，0 项跳过，0 项拒绝，并且 C# 输出逐字节一致（328/328 个文件），同时涵盖 Web 脚本、gxcfg.js、消息和运行时配置。这些历史计数不能验证后续更改，也不能证明不支持的数据库语义得到了保留。对于任意 KB，尚未验证能否完全替代 SDK：仍会按名称拒绝不支持的形式，并且只有一个 KB 可作为基准。gx-engine 是默认后端（Engine.Backend=gxengine：支持的构建和受字段限制的仅类型查询；读取/编辑及其他形式使用 SDK 回退；auto = 仅构建，sdk = 关闭引擎）；请参阅引擎路由。

目前构建情况

以下数量和耗时描述的是已发布的 4.0.0 基线，不代表对尚未提交的生成器变更进行了新一轮验证。现在，经过检查的生成过程会拒绝不受支持的数据库语句，而不是接受不完整的行为；变更后的整个知识库数量和 SDK 一致性仍需重新测量。

构建项	已验证的证据	范围限制
软件包构建	build.ps1 构建了 Gateway、Worker、gxwire 和 gx-engine；本地发布版与后端引擎的哈希值一致。	构建 MCP 发行包不等于构建知识库中的每个对象。
选定对象构建	使用本地 SDK/引擎交替运行 5 组配对构建，重新生成并编译了 DCM37961700；核心 API 和实际 CLI 输出一致。SDK 中位耗时为 14.756s，引擎为 0.230s（64.19×）。	合成的热启动测试夹具；两边均设置了 AUTO_CLOSE=OFF，测试后已恢复原始 ON 状态。未对打包的二进制文件进行基准测试；该文件通过了单独的构建/运行冒烟测试。
完整原生知识库构建（KBTeste）	rebuild-all：生成 346 个 / 编译 346 个，跳过 0 个，拒绝 0 个。与 SDK 为同一知识库生成的输出相比：328/328 个 C# 文件逐字节一致，无缺失文件；24/24 个 Web .js 文件、gxcfg.js、messages.eng.txt/.js、log.config、log.console.config（及 bin/ 副本）和 CloudServices.config 均逐字节一致。	仅验证了一个对照知识库。额外的 SDT 和程序集信息输出不计入匹配文件的分母。未写入 Developer Menu（尚未确定其对象选择方式）。

对于不在已验证引擎覆盖范围内的必需工作流，请使用 SDK。有关准确的二进制文件、命令、样例和注意事项，请参阅 计划 131；有关默认/显式后端行为，请参阅引擎路由。

子系统	证据范围 / 剩余工作
语言、运行时、控制流、SDT 和集合	有范围限制的原生差分测试集；并未涵盖所有 GeneXus 语义。
可移植目录和 XML 投影	已通过基于测试夹具的支持验证；不能据此认定与原生知识库往返操作一致。
指定器、SQL 导航和数据存储行为	可移植测试无法证明完整的实时 SDK 导航或数据库行为。
原生 UDM 存储	有实时读取证据和针对性测试；不能全面替代 SDK 持久化。
C# 生成和 Rebuild All	在有限范围内通过了实时生成对象检查；仍存在拒绝项、缺失对象和 SDK 对照缺口。
Web UI、Transactions、Reports 和 BC	实现不完整；成功编译并不代表端到端产品一致。

请参阅当前验收/证据台账，了解受测二进制文件、范围、失败情况和后续操作。

Gateway 能力注册表关卡

MCP Gateway 提供证据关卡（EngineCapabilityRegistry）。各项受限状态、使用方和证据来源，请参阅当前能力表。运行时预言机测试夹具、可移植模型测试和实时 MCP 兼容性属于不同类型的证据；它们都不能代表整体 SDK 替代百分比。

• 原生运行时预言机条目仅涵盖其记录的输入、编码和环境；仅凭合成库测试无法证明原生 parity。
• 当前原生 MCP 表面仅支持已纳入的只读类型查询，以及阻塞式构建／重建。读取和编辑仍由 SDK 支持，否则会以 fail-closed 方式失败；将调用路由到延迟防护逻辑不等于具备原生实现覆盖。
• 存储解码、导航规划、对象建模和 C# 生成仍不完整。遇到不支持的数据库语句时，必须停止生成，而不能生成一个缺少数据库行为却显示成功的 Procedure。

已发布的 4.0.0 KBTeste 结果（346 个已编译类、328 个匹配的 SDK C# 文件和 20 个额外文件）属于历史性的有限证据。它并非对后续安全更改、所有对象族或整个 SDK 行为的重新验证。完整 parity 验收计划跟踪剩余工作流和所需证据。

⚡ 性能基准（gx-engine 对比 GeneXus SDK）

速度比较必须使用相同的输入工作负载、目标、依赖闭包、可观察结果和成功标准。不同生成器不必生成字节完全相同的源代码或程序集。SDK 完整 specify／generate／compile 耗时应与仅编译的 MSBuild 耗时，以及有限范围的运行时微基准测试分开。在一次性 KBTeste 上，完整编译的整个 KB Rebuild All 耗时是 SDK 仅执行 specify + generate 耗时的 51.7 倍（配对运行的中位数）；所选对象的结果仅在其声明的预热测试夹具范围内达到 50 倍。历史微基准测试无法证明整个 KB 的速度目标。

这些数字的适用范围。 测量使用的是仅含一个 Design 模型的一次性 KB。对于包含版本的 KB，已验证的情况仅限一个一次性副本：引擎只构建主干；冻结版本或分支则由 SDK 构建（公开检查：包含版本的 KB 的主干构建）。对于使用 SQL 身份验证、位于 SQL Server 上的 KB，还需要在进程环境或连接文件中提供 SQL 凭据；此外，引擎会跳过 Web UI 对象（部分构建，退出码为 3）。仅查询类型的 genexus_query 只有在 fields 限定为 name／type 时才由引擎处理；而 SDK 搜索索引预热后，SDK 的速度更快：对于一个位于远程 SQL Server 后方、包含 86 个 Procedure 的 KB，SDK 耗时 38 毫秒，引擎耗时 300–370 毫秒（2026-10-23，直接通过 Gateway 的 sdkMs 执行 kb-query）。因此，SDK 索引尚未就绪时，引擎查询路径才主要有帮助。

基准工作负载	GeneXus SDK（.NET / MSBuild）	gx-engine（Rust）	加速比 / 提升	验证与基准
热启动的选定对象 C# 构建（DCM37961700）	14,755.9 ms （本地指定 + 生成 + Rebuild/Publish）	229.9 ms （实时读取 + 输出 + 受保护的编译器重放，包含设置时间）	64.19×	5 组交替配对；有界 API 和直接 CLI 检查，源文件稳定。合成测试夹具，AUTO_CLOSE=OFF；不代表冷启动/完整 KB 或打包二进制的性能。协议。
Str() 数值图片格式化（微基准）	274 – 286 ns / 行 （1.75 ms / 次）	121 – 130 ns / 行 （0.75 ms / 次）	快约 2.25 倍	6,152 行（str_matrix.tsv），80,235 个字符，FNV-1a UTF-16 哈希值一致（0xb9e1b48fb72067b0），与官方 GeneXus.Classes.Core 运行时相比，0 处不匹配。
实时 KB 元数据与部件 Hydration	12,000 – 18,000 ms （串行 COM STA）	320 ms （直接 TDS 查询）	快 > 35 倍	在实时 LocalDB GX_KB_KBTeste 上验证（test_udm_real_kb_live_read_procedure）。
整个 KB 生成（KBTeste，指定 + 生成，不编译；较早版本的引擎二进制）	33.4 – 39.9 s （MSBuild SpecifyAllOnly + GenerateOnly，运行 3 次）	0.61 – 0.68 s （rebuild-all --skip-compile，与 SDK 运行交替运行 3 次；其中约 0.45 s 用于读取 KB 目录）	约 58 倍（配对中位数）	配对测试，在同一台机器上进行，日期为 2026-10-21；两者均不编译；SDK 运行后引擎输出未改变。这不是 50 倍性能声明：输出一致性为 328/328 个 C# 文件相同，另有 20 个额外文件，且没有 Developer Menu，因此尚未验证与完整 SDK 的一致性。之前的引擎二进制测得 1.29 – 1.40 s（12 次交替运行）。
整个 KB 全量重建，内容未更改（KBTeste，346 个类）	中位数 42.2 s （32.3 – 46.2 s；MSBuild SpecifyAllOnly + GenerateOnly，不编译，运行 3 次）	中位数 289 ms （271 – 306 ms，运行 9 次：目录读取约 150 ms + 输出约 70 ms；因编译已是最新状态而跳过）	约 146 倍（中位数）	配对并交替运行，在同一台机器上进行，日期为 2026-10-21；由于打开的 KB 会保持数据库连接，数据库由空闲连接保持打开。SDK 端不编译，引擎端会编译（或确认其输出为最新状态）。输出一致性：328/328 个 C# 文件相同，20 个额外文件，缺失 0 个；尚未验证与完整 SDK 的一致性。脚本 bench-s42.py。
整个 KB 全量重建，强制完整编译（KBTeste，346 个类）	中位数 42.2 s （与上述 SDK 运行相同，不编译）	中位数 816 ms （739 – 989 ms，运行 9 次：直接调用 csc，使用 /shared 和 /skipanalyzers+，约 0.6 – 0.7 s）	约 51.7 倍（中位数）	同一组配对运行；每个样本运行前都会删除编译记录，因此 346 个类都会重新编译。该比值是中位数之比：与最快的 SDK 运行（32.3 s）和最慢的引擎运行相比，约为 33 倍。首次构建到新文件夹需要约 1.9 s（dotnet build）；冷启动编译器服务器曾测得一次约 22.8 s。此前的 480,000 ms / 1,250 ms（>380 倍）比较没有匹配的 IDE 测量结果，现已撤回。
历史算术测试夹具构建	10,930 ms （SDK 阶段） 16,366 ms （MSBuild 进程墙钟时间）	223 ms （Rust CLI + rustc 构建）	不代表整个 SDK 的速度比	RustTimingProbe（21 * 2 = 42），记录了 3 个样本，并检查了退出状态/输出。管线和目标不同；此前约 49 倍的阶段/构建比仅适用于该小型测试夹具。证据与注意事项。
生成的制品启动与执行	123.06 ms （CLR 引导 + 运行）	5.75 ms （原生二进制引导）	快约 21 倍	对已编译的算术过程制品进行冷启动进程和控制台输出测试。

📈 基准测试协议与改进记录方式

随着新功能达到同等水平并逐步落地更多优化，请遵循此协议更新此记录：

1. 先验证同等性： 与官方 SDK 或已记录的原生差异测试样例相比，差异必须为零，否则基准测试无效：

   python src/gx-engine/scripts/benchmark.py --iterations 100
   

2. 标准化环境： 明确记录编译器标志、硬件规格和迭代次数（参见 src/gx-engine/VALIDATION.md）。
3. 记录到台账： 更新此表和 plans/129-implementation-progress.md，记录：工作负载描述、GeneXus SDK 基线、gx-engine 耗时、观察到的加速比，以及已提交的证据测试样例。

激活标志与安全边界

重要

引擎优先： Engine.Backend 默认为 "gxengine"。在已准入范围内，阻塞式 genexus_lifecycle 构建/重建使用 gx-engine；仅选择 name/type 字段的已准入类型限定 genexus_query 调用也使用 gx-engine。指定 mode=compile_check、显式设置 callers=false 且包含传递被调用项的定向 build 也使用 gx-engine，且只构建目标闭包。编辑、异步/其他定向构建、所有读取、usedby: 搜索、排序模糊查询和不受支持的请求形式会回退到 SDK。能力与参数门控仍然适用。引擎启动后出现构建错误或结果不确定时，绝不会自动重放到 SDK。"auto" 仅将构建路由到引擎；"sdk" 则让所有操作都使用 SDK，且绝不调用引擎。

无需设置后端。若要将路由范围缩小到构建（"auto"）或关闭引擎（"sdk"），请配置 config.json：

{
  "Engine": {
    "Backend": "auto",
    "Fallback": "sdk",
    "TimeoutSeconds": 120
  }
}

• Engine.Backend："gxengine"（默认：处理已准入的构建和字段受限的类型限定查询；读取/编辑回退到 SDK）、"auto"（仅处理已准入的构建）或 "sdk"（仅使用 SDK，绝不调用引擎）。
• Engine.Fallback："sdk"（在已准入的原生覆盖范围之外回退到 GeneXus SDK）或 "error"（失败时关闭：证据门控拒绝时返回 EngineCapabilityNotParity；读取/编辑延后处理以及不受支持的查询/构建参数则返回 EngineOperationOutsideAdmittedSpace）。
• 诊断： genexus_doctor 通过 --version 握手检查引擎，并报告包含 backend、available、version 和 capabilities 的 engine 状态区块。其 routedOperations 列出由原生操作处理的项目；deferredOperations 单独列出读取/编辑的延后处理，不会将其视为同等性。

若要从检出目录运行编译器测试或独立项目：

cargo test --manifest-path src/gx-engine/Cargo.toml
cargo run --manifest-path src/gx-engine/Cargo.toml -- check src/gx-engine/fixtures/demo.json

完整架构和证据台账请参见 docs/engine_backend.md、引擎指南和能力矩阵。

---

在 MCP 客户端之间共享一个 Worker

Gateway 和 GeneXus SDK Worker 各司其职。默认情况下，Server.WorkerSharingMode 为 "isolated"：每个 Gateway 都拥有自己的 Worker 进程。当 Agent 有意需要多个相互独立的 Worker 时，请保留此模式。

当两个或更多独立的 MCP 客户端需要操作同一个物理 KB 时，请在 stdio-isolated 配置中将 WorkerSharingMode 设置为 "shared-host"：

{
  "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 仅通过有界的本地命名管道连接共享由代理管理的每个 KB 的 SDK Worker。各 Gateway 仍保持独立：MCP 会话、授权、KB 选择、缓存、请求跟踪、取消、进度、通知和生成的工件都不会跨越进程边界。仅当物理 KB、Worker 可执行文件、GeneXus 安装、驱动程序和目标主版本兼容时才会接受共享；如果不兼容，将安全拒绝连接，而不会连接到错误的 SDK 进程。

写入时会将 Gateway 本地所有者传递给 Worker。同一个对象／部件不能由两个已连接的客户端并发写入，而对不同对象的写入可以通过共享的 SDK 边界独立进行。Worker 本身仍是单个 STA 进程，因此，GeneXus 要求串行执行的调用仍会按要求串行执行。

对于正常运行的共享连接，genexus_whoami 和 genexus_doctor 会报告模式、身份密钥、管道、主机／Worker PID、代次、连接 ID、连接状态，以及最新的启动／故障诊断信息。出现故障时，请先检查 worker.diagnostics 和 workerHealth，再重启或删除本地状态；这些字段可以区分配置／身份、互斥锁或注册表、管道／握手、启动、子进程退出／重启、TTL 和帧故障。

请参阅 Worker 所有权了解生命周期约定，并参阅共享 Worker 基准测试了解双客户端冒烟测试和背压结果的实测数据。

---

你可以用它做什么

通过 60 个工具，快速了解 Agent 如何操作你的真实 KB（详情参见 工具概览）：

领域	Agent 可以做什么
🔎 探索	搜索和列出对象，读取任意部分（源代码、规则、事件、结构、文档、模式 XML），检查元数据和调用方，对源代码进行正则搜索，查看导航报告
🧭 定位与追踪	按任务涉及程度为对象排序，列出直接和传递调用方，追踪两个对象之间的最短调用路径，检查影响范围和安全删除情况，追踪单个变量的数据流。通过 genexus_wire 对导出的源代码运行（只读，受令牌预算限制）；pack_task 也可直接在已打开的原生 KB 上运行
✏️ 编辑代码	编辑任意对象部分（full/patch/ops 模式），对变量执行 CRUD 操作，格式化代码，创建和删除对象，根据 curl 命令搭建 Procedure，一次性编辑并重建调用方
🗄️ 编写数据模型	Transaction 结构（DSL）、唯一/非唯一索引（创建和删除）、属性公式与子类型、层级 Description/Image 属性、Domain 枚举值、文件夹和模块、表↔Transaction 关系及冗余属性检测
🧩 编写其他对象	External Object 方法和属性、Menu 选项、REST API 对象、WorkWithPlus / WorkWith 模式、强类型 .NET 生成器引用
🎨 UI 与 WorkWithPlus	完整读取和写入模式 XML（控件、操作、网格、排序、组），主题类与样式设置，原生 WebForm/布局编辑，控件目录与设计系统令牌/类/图像，无头浏览器验证
🔬 分析	影响/依赖分析、复杂度与代码指标、命名、解释代码功能、KB 活动/新鲜度、重组/DDL 影响预览、原生安全扫描、架构漂移检查
🛠️ 构建、测试与部署	构建（完整构建或快速 compile_check）、验证、重组、索引、运行原生 GXtest 测试、部署应用程序（目标 + 部署）
🔀 重构与比较	在整个 KB 中重命名、提取 procedure、比较和合并对象（与 IDE 功能对等）
🌿 版本控制、传输与团队协作	KB 模型版本/分支、真实 XPZ 导出/导入（考虑依赖关系）、GXserver（Team Development）同步 + CI 管道、Git 风格历史记录、多 KB 并行工作
🔐 安全	GAM / 集成安全配置、KB 安全审计 + 原生 Security Scanner

原生 SDK 支持通过 原生 GeneXus SDK 实现，即 IDE 使用的同一套代码路径，因此编辑是真正的编辑，并经过验证，而不是对 KB 文件进行文本篡改。 旧版支持使用目录中列出的反射或 COM 驱动，并会明确说明不支持的现代工具。

---

前提条件

开始之前，请确保你具备以下条件：

• ✅ Windows（GeneXus 仅支持 Windows）
• ✅ 本机已安装受支持的 GeneXus 版本：要使用原生 SDK 支持，需安装 GeneXus 16、17 或 18；要获得基本兼容性，也可使用目录中列出的旧版安装（参见 docs/generated/supported-versions.md；必要时可显式传入其他安装路径）
• ✅ 本机已安装 GeneXus 18，以使用主要的原生 SDK 路径；其他目录中列出的原生版本和旧版也受支持，具体取决于其对应的驱动
• ✅ 使用受支持的原生或旧版 GeneXus 主版本创建的知识库，并且至少在 IDE 中打开过一次（以完成初始化）
• ✅ Node.js 22+ — 在终端中运行 node --version 检查；若未安装，请从 nodejs.org 下载
• ✅ 兼容 MCP 的 AI 客户端 — Claude Desktop、Claude Code、Cursor、Antigravity 等

你无需克隆此仓库或全局安装任何内容 — npx 会处理这些工作。

从未使用过终端？ 按 Win+R，输入 powershell，然后按 Enter。那就是你的终端。

---

快速入门（3 步，约 5 分钟）

先找到两个路径

运行安装程序前，记下以下路径：

1. GeneXus 安装文件夹 — GeneXus.exe 所在的位置。通常为 C:\Program Files (x86)\GeneXus\GeneXus18。
2. 你的 KB 文件夹 — 知识库的根文件夹（包含 .gx 文件以及 Model/、WebSpa/ 等子文件夹）。

不确定 KB 位于哪里？在 GeneXus 中打开它并查看标题栏，或查看 File → Recent。

第 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 并按提示操作。

你将看到以下过程（首次运行约需 30 秒，再次运行会更快）：

1. npx 会下载软件包。
2. 安装程序会验证路径是否存在，以及是否已安装 GeneXus。
3. 它会自动检测你安装了哪些 AI 客户端，并将 MCP 配置添加到每个客户端。
4. 最后会打印一段 JSON 代码片段 — 请保留它，以便在需要手动配置客户端时使用。
5. 安装完成后会显示 🎉 You are all set!。

在 Windows 上，如果当前 npm 软件包中包含 Antigravity 所需的网关可执行文件，Antigravity 会注册为使用该可执行文件，因此每次 MCP 握手时都会跳过 npx 引导链。该路径会使用 npx 缓存中的软件包；升级后，如果 genexus-mcp clients 报告启动器已过期，请再次运行 npx genexus-mcp@latest clients add --clients antigravity。除非使用下面的固定路径安装程序，否则其他客户端仍会使用 npx genexus-mcp@latest 启动器。

第 2 步 — 在 AI 客户端中注册 MCP

第 1 步会自动注册检测到的所有受支持客户端，包括 Claude Desktop、Claude Code、Cursor、Antigravity、Gemini CLI、OpenCode、Codex CLI 和 VS Code。如果没有检测到你的客户端，请将第 1 步中的 JSON 代码片段手动复制到客户端的 MCP 配置中。如果不确定配置文件的位置，请参阅客户端设置指南。

第 3 步 — 重启 AI 客户端，然后测试

这一步最容易出问题：完全关闭 AI 客户端，然后重新打开。不能只关窗口 — 必须关闭整个进程。

• Claude Desktop：右键单击系统托盘图标 → 退出。然后重新启动它。（仅关闭窗口是不够的。）
• Claude Code：结束当前会话并开始一个新会话。
• Cursor / Antigravity：关闭所有窗口并重新打开。
• OpenCode：完全退出并重新打开，以便重新加载 opencode.json / opencode.jsonc。
• Gemini CLI / Codex CLI：启动一个新进程或会话。

然后粘贴以下提示词：

“使用 GeneXus MCP，列出我的 KB 中前 5 个对象，并显示名称 + 类型。”

预期结果：

• AI 会调用 genexus_list_objects 工具（有些界面会显示“正在调用工具…”）。
• 几秒钟后，你会收到 KB 中的对象列表。

如果收到列表 — 就完成了。请跳转到我可以向 AI 提出什么问题？，了解一些示例。

如果 AI 表示没有 GeneXus 工具，或没有任何反应，请查看故障排除 — 大多数问题都有对应的解决方法。

---

🤖 让 AI 帮你安装

如果你不想自己在终端中运行任何命令，请将以下内容粘贴到 AI 聊天中：

请配置 GeneXus MCP 服务。在终端中运行 npx genexus-mcp@latest init --kb "<MY_KB_PATH>" --gx "<MY_GENEXUS_PATH>"。如果我还没告诉你 GeneXus 路径和 KB 路径，请先询问我。成功后，读取它打印的 JSON 代码块，并将其添加到我的 MCP 客户端配置中。告诉我何时需要重启客户端，才能开始使用 GeneXus 工具。

替换占位符，或让 AI 询问你需要填写的内容。

---

企业安装（固定路径，兼容 ASR）

如果你的计算机启用了 Microsoft Defender ASR、SmartScreen 或其他会拦截未签名二进制文件的终端策略，默认的 npx 流程会很麻烦——npx 会将软件包缓存到 %LOCALAPPDATA%\npm-cache\_npx\<hash>\... 下，而 <hash> 会随版本变化，因此 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\

提供给 IT 以添加到 ASR / Defender 排除列表的路径：

<InstallDir>\GxMcp.Gateway.exe
<InstallDir>\worker\GxMcp.Worker.exe

之后再次运行同一条命令即可升级——它会检测已安装的版本（安装目录中的 version.txt），并仅在有更新版本可用时下载。使用 -Force 重新安装相同版本，使用 -Version v2.3.0 固定到指定标签，使用 -NoClient 跳过 AI 客户端注册。注册客户端需要安装 Node.js 22+；如果没有安装，脚本仍会解压二进制文件，但你需要手动编辑客户端配置（例如 claude_desktop_config.json）。

---

我可以向 AI 提问什么？

安装后，你可以使用以下功能。试试这些入门提示词：

探索

• “列出 KB 中所有类型为 Procedure 的对象。”
• “显示过程 CalculateInvoiceTotal 的源代码。”
• “查找所有引用属性 CustomerId 的事务。”

编辑

• “向 Order 事务添加一条规则：如果 Total < 0，则执行 error('Total must be positive')。”
• “向 Customer 事务添加一个类型为 DateTime 的新属性 CreatedAt。”
• “在过程 CreateOrder 中，将变量 &qty 重命名为 &quantity。”

数据模型编写（无需往返 IDE）

• “在 Customer 事务中将 CustomerEmail 设为唯一。”（创建唯一索引）
• “将 CustomerBalance 转换为公式：sum(InvoiceAmount)。”
• “向 Status 域添加枚举值 Active/Inactive/Pending。”
• “向 PaymentGateway 外部对象添加属性 apiKey 和方法 Connect(url)。”
• “向 MainMenu 添加一个打开 CustomerWW 的菜单选项‘Customers’。”

WorkWithPlus 模式编辑（全面控制结构与主题）

• “向 WorkWithPlus WebPanel 添加一个带变量、操作和嵌套响应式表格的类型化选项卡。”
• “在 WorkWithPlusOrder 中，向事务视图添加一个‘Duplicate’按钮，与 Save/Cancel/Delete 并列。”
• “将 Customer 事务的属性分组到‘Contact Info’区域，并使用主题类 GroupTelaResp。”
• “在 WorkWithPlusInvoice 列表中，添加按 InvoiceDate 降序排列的新排序方式。”
• “使用 buttonClass='btn ButtonGreen' 设置 WorkWithPlusOrder 上 Save 按钮的样式，并将 BigTitle 应用于表单标题。”
• “从 WorkWithPlusReport 的 Selection 网格中移除 Export 操作。”
• “读取 Customer 事务的 Documentation 部分，并将其改写为 markdown。”

架构、调用图与影响分析（genexus_wire）

• “在我更改 CliSaldo 之前，影响范围有多大？哪些过程会写入它？”
• “哪些过程会直接或通过其他过程调用 PValidaCreditoLive？”
• “显示从 PEmiteFaturaLive 到 PValidaCreditoLive 的调用路径。”
• “我需要更改发票利息计算。应该从哪里着手？”

分析

• “解释过程 ProcessShipment 的作用。” — genexus_analyze mode=explain 是仅用于兼容的封装，会返回 NotImplemented；如需受支持的分析和源代码，请使用 mode=summary、mode=context 或 genexus_read。
• “WebPanel CustomerList 中的查询会生成什么 SQL？”
• “概述 Sales 模块的结构。”

构建与生命周期

• “构建 KB 并报告任何错误。”
• “运行单元测试并告诉我哪些测试失败了。”

Agent 会从 MCP 提供的 60 个工具中选择合适的工具（读取、编辑、重构、分析、构建、数据模型编写、布局自动化、DB/DDL、版本控制、安全、SQL 预览等）。完整工具列表见下方的 工具概览。

---

支持的 AI 客户端

安装程序会自动检测并自动配置：

客户端	自动配置	备注
Claude Desktop	✅	安装后需要重启
Claude Code (CLI)	✅	重新加载会话
Cursor	✅	需要重启
Antigravity	✅	直接使用打包的网关；需要重启；即使尚未创建其 MCP 配置，也能检测到
Gemini CLI	✅	—
OpenCode (CLI)	✅	可读取直接和嵌套的 MCP 布局；需要重启
Codex CLI	✅	写入 ~/.codex/config.toml
VS Code / VS Code Insiders	✅	原生 MCP（User/mcp.json）；需要重启
OpenCode Desktop	✅	与 OpenCode CLI 共用 opencode.jsonc；需要重启
任意 MCP 客户端	手动	使用 init 打印的 JSON 代码段

随时运行 npx genexus-mcp clients，查看已安装的 Agent、已注册 genexus 的客户端，以及是否有客户端指向过期的网关 exe。要注册（或重新注册）指定客户端，请运行：npx genexus-mcp clients add --clients antigravity,vscode。

OpenCode Desktop

OpenCode Desktop 与 OpenCode CLI 共用 MCP 配置文件（opencode.jsonc 或 opencode.json）。 运行 genexus-mcp init --write-clients 或 genexus-mcp clients add --clients opencode-desktop 会自动在共用配置中注册 genexus18mcp。注册后， 请完全重启 OpenCode Desktop，以便重新加载其 MCP 配置。

---

故障排查

遇到“Agent 看不到 GeneXus”问题时，首先运行：npx genexus-mcp clients（是否已注册？它指向的网关 exe 是否仍然存在？）和 npx genexus-mcp doctor --mcp-smoke。

大多数安装问题都属于以下几类，解决方法请参见 TROUBLESHOOTING.md：

• 安装程序找不到 GeneXus 或 KB
• AI 客户端重启后看不到 GeneXus 工具
• “Worker failed to start”／.NET 4.8 错误
• KB 构建错误／工件被锁定
• 端口 5000 已被占用
• %LOCALAPPDATA%\GenexusMCP\ 的权限问题
• Antigravity 仅显示 exit status 1／0xffffffff，没有有用的 stderr

当 stdio 启动器在客户端保留 stderr 之前就发生故障时，包装器会将最近一次故障写入 %LOCALAPPDATA%\GenexusMCP\logs\last-stdio-error.txt。其中包含 UTC 时间戳、退出代码和有长度限制的 stderr 末尾内容。如果存在之前的故障，genexus-mcp doctor 也会报告相同路径。更改安装或使用全局 npm 安装之前，请先查看此文件；如果 Antigravity 启动器已过时，请使用 npx genexus-mcp@latest clients add --clients antigravity 重新注册。

诊断共享 Worker 故障

如果 shared-host 未能连接，或 Worker 被重启，请在受影响的客户端中运行 genexus_whoami 和 genexus_doctor，并保留结构化的 worker.diagnostics／workerHealth 区块。有用的证据包括模式、身份、主机／Worker PID、代次、连接状态、连接错误和故障诊断，而不仅仅是最终的 no_worker 或 startup_failed 摘要。匹配的主机仍在运行时，请勿删除共享 Worker 注册文件；该生命周期由代理管理器负责，经过 PID／启动时间验证后会恢复过时记录。

仍无法解决？请提交问题，并附上 npx genexus-mcp doctor --mcp-smoke 的输出以及上述有长度限制的诊断字段。请对凭据、令牌、连接字符串和其他敏感值进行脱敏。

---

工具概览

Worker 向 MCP 路由器公开 60 个工具，按功能分组如下。大多数是带有 action 的集合工具（例如 genexus_db action=sql_ddl）；详细架构见 src/GxMcp.Gateway/tool_definitions.json。功能指南，例如 K2B Designer 桥接、空 WebPanel 上的 WorkWithPlus、文本化 Variables 编辑 和 External Object 方法，均列在文档索引中。

概览与健康状态

• genexus_whoami — KB 上下文、版本、Worker／索引／数据库健康状态、自更新检查、后续步骤提示
• genexus_doctor — 连接、安装和缓存健康检查
• genexus_recipe — 命名操作手册／可自扩展宏
• genexus_telemetry — 可观测性（指标、延迟、错误）

架构发现与调用图

• genexus_wire — 只读、按令牌预算限制的调用图引擎（捆绑的 gxwire.exe）。操作：pack_task（默认；针对任务的一次性概览包）、for（通过领域同义词进行意图排序，例如 fat → faturamento）、status（图规模和顶级枢纽）、callers（直接和传递调用者）、impact（影响范围、写入者、读取者）、path（从 from 到 to 的最短调用路径）、slice（一个变量的定义和使用，target = Object:Variable）、safe_delete（删除符号前的阻碍项）、index（重建缓存）、doctor（引擎和缓存诊断） genexus_wire 不经过 Worker 或 GeneXus SDK，只有一个例外：对于会话已打开的原生 KB，action=pack_task 由该 KB 的 Worker 从基于 SDK 的索引中回答，不导出文本。传入 targets（对象名称；使用 Type:Name 消除歧义），和/或在 task 中写明对象名称；结果会列出已解析对象及其直接调用者和被调用者，并列出所有无法解析、存在歧义、已跳过或因令牌预算而未纳入的对象。此操作只读，不读取任何部件正文。对于其他所有操作，Gateway 都会在目标文件夹（dir、kb 或活动 KB 路径）中运行 gxwire.exe 并返回其输出；如果目标是原生 KB 文件夹，则会返回 GXWIRE_REQUIRES_TEXT_SOURCE_TREE，因此请将 dir 指向已导出的文本树。它会通过正则表达式启发式方法读取导出的源文本（.prc、.trn、.wp、.sdp、.xml、.txt、.gx、.gxd），因此结果反映的是导出的文件，而非实时 KB；空文件夹会返回 empty="true"。可用它来判断应查看哪些内容，以及更改会影响什么。使用 genexus_query 搜索实时对象，使用 genexus_read 读取对象部件。参数：task（pack_task、for）、target（callers、impact、slice、safe_delete）、from/to（path）、format、token_budget（默认值为 1200）、full、kb/dir。format 可以是 toon（紧凑格式，推荐）、xml（默认值）、json 或 mermaid；mermaid 会渲染 status、callers、impact、path 和 pack_task，其他操作则返回 XML。它写入的唯一文件是目标文件夹中的 .gxwire_cache.bin，写入时机为执行 index 操作时，以及缓存过期时。

搜索与发现

• genexus_query — 对象搜索（前缀包括 name:、type:、usedby:、parent: 等）
• genexus_list_objects — 分页列出对象并提供聚合信息
• genexus_read — 读取对象的任意部件（源代码、结构、规则、事件、文档、模式 XML 等）
• genexus_inspect — 一次性对象快照（元数据、变量、结构、签名、调用者）
• genexus_search_source — 在 Procedure/DataProvider/WebPanel/Transaction 源代码中进行正则表达式／语义搜索
• genexus_navigation — IDE“查看导航”报告

对于 GeneXus 18 U16 Data Selector，genexus_read type=DataSelector 还接受 parameters、conditions、orders、definedBy、baseTransaction、 baseTable 和 structure。它会保留 SDK 顺序及完整表达式， 返回 versionToken，且不会执行任何生命周期操作。公共 U16 SDK 不会为此对象类型公开投影属性集合或已解析的联接，因此 projection 和 joins 会连同技术原因一起返回到 unsupportedParts 中，而不会用误导性的空数组表示。仅当无需 Specify 即可解析时，才会报告基对象和声明的索引。 structure.expression 被标识为 semanticProjection：它会组合类型化的公共 SDK 元素，且绝不会暴露 U16 上 DataSelectorStructurePart.ToString() 生成的内部集合类型名称。

若要更改 Data Selector 的条件，请使用 genexus_edit type=DataSelector part=Conditions mode=full，每行填写一个条件（genexus_read parts=["conditions"] 也会将 该文本作为 source 返回）。条件列表会整体替换，参数／顺序／Defined By 保持不变，并且会重新读取和验证已保存的条件。如果 Data Selector 的 条件位于嵌套的 AND/OR 组中，操作会返回 DataSelectorConditionsNestedGroupsUnsupported 并且不会保存任何内容：每行一个条件的形式 无法保留分组，因此替换列表会悄无声息地将其扁平化。请先在 GeneXus 中扁平化这些层级。 编辑

• genexus_edit — 编辑任意对象部分；模式为 full / patch / ops
• genexus_edit_and_build — 在一次调用中完成编辑 + 可选规格化 + 重建调用方，验证失败时执行补偿回滚
• genexus_edit_form — 语义化 WebForm 编辑
• genexus_variable — Variables 部分的 CRUD
• genexus_create — 创建总入口（Transaction、Procedure、Domain、SDT、API、Folder、curl_procedure = 根据 curl 命令搭建 Procedure 脚手架，…）；object_atomic 编写定义 + 变量 + Rules + 属性 + Source，并执行预检/回读/回滚
• genexus_data_view — 原子化地创建/检查/更新/删除仅含根级别的 Business Component Transaction，通过原生 Data View 映射到现有物理表；先验证属性/键，支持乐观版本控制和真正不产生变更的试运行，破坏性删除要求 confirm=true，并分别报告提交/验证状态
• genexus_delete_object — 通过原生 SDK 标识删除对象；使用 dryRun=true 在 confirm=true 前检查传入引用
• genexus_format — 使用 worker 的规则格式化代码片段

数据模型与结构编写

• genexus_structure — 读取/写入数据模型：get_visual/get_logic、update_visual（结构 DSL）、create_index/drop_index（唯一/非唯一索引——GeneXus 实现唯一性约束的方式）、set_attribute（Formula、子类型、Title/ColumnTitle、IsCollection、basedOnDomain）、set_level（级别 Description/Image 属性）、set_domain（编辑现有 Domain 的枚举值/基类型）。对于 create_index，dryRun:true 会验证并返回预计差异，但不保存；将 get_indexes 返回的 versionToken 用作 baseVersion 以进行并发保护。实际写入后会重新读取并精确验证，失败时使用快照回滚。它绝不会触发 Specify、Generate、Build、Rebuild、编译、重组、执行或测试。
• genexus_authoring — 编写结构 DSL 未涵盖的对象类型成员：add_external_method/add_external_property（External Objects）、add_menu_option（Menus）
• genexus_properties — 读取/更新对象级属性
• genexus_generator_reference — 列出/预览/添加/移除原生 .NET 生成器引用，并进行托管程序集验证、乐观并发控制、保存后重新读取验证，以及精确的完整快照回滚；绝不会隐式运行生命周期操作

重构、模式与比较

• genexus_refactor — 重命名、提取过程、WWP 条件集
• genexus_apply_pattern — 应用 GeneXus 模式（WorkWith、WorkWithPlus，…）；mode=actions 管理类型化的 WorkWithPlus 网格操作和 Action Groups
• genexus_wwp — WorkWithPlus 类型化编辑：Action Groups、原子化原生 add_grid_attribute，以及用于 WebPanel 标签页和类型化子项的 add_tab、move_tab 和 remove_tab
• genexus_workwith — 在标签页（General 等）上以类型化方式编写标准 WorkWith（WorkWith for Web）模式操作、过程调用、条件和参数
• genexus_compare — 与 IDE“比较对象”功能一致（IComparerService）
• genexus_merge — 对象 2 路或 3 路合并（IMergeService） 分析、文档与 API
• genexus_analyze — 跨对象语义分析（影响、依赖关系、复杂度、命名、code_metrics、summary、kb_stats = 知识库活动/新鲜度、table_relations = 表↔事务关系 + 冗余属性，…）。mode=explain 仅用于兼容：保留旧版响应封装并返回 NotImplemented；请改用 mode=summary、mode=context 或 genexus_read。
• genexus_dfd - 只读的事务/表 ER 图（extends/subordinates 边 + Mermaid erDiagram），仅基于 SDK 表关系构建
• genexus_impact - 只读的对象调用图影响范围：按类型统计数量、按依赖优先顺序排列的重建 order、循环依赖及截断结果的上限（不提供风险评分）
• genexus_object_context - 只读的单个对象标识信息 + 调用方/被调用方（含覆盖率）+ 数据模型；如果多个对象共用一个名称，则会拒绝请求并返回它们的 guid 和路径
• genexus_doc — 生成 wiki / 依赖关系图 / 健康报告
• genexus_api — 检查 HTTP 程序公开的 REST 端点
• genexus_security — 审计知识库安全性：audit_gam（环境/GAM 属性）、scan_secrets（对 Source 使用正则表达式）、scan_native（SDK 自带的 Security Scanner，ISecurityScannerService）

生命周期、构建、测试与数据库

• genexus_lifecycle — 定向 build（含 compile_check）、增量全局 build_all、强制全局 rebuild、验证、索引、重组及轮询状态
• genexus_test — 运行原生 GXtest 测试
• genexus_db — 数据库综合工具：架构漂移、sql_ddl/sql_navigation、静态索引顾问、sample_data、带试运行、乐观版本控制、重新读取和已验证回滚功能的类型化 Transaction 记录查询/插入/更新、Domain/SDT 类型检查、翻译导入、reorg_impact，以及仅根据当前 Impact Analysis 工件生成精确 DDL 的非变更型 reorg_preview
• genexus_deploy — 部署应用（IDeploymentService）：list_targets（读取）/ deploy（有破坏性，confirm=true）
• genexus_run_object / genexus_browser — 解析运行时 URL 并通过无头浏览器验证

原生布局 / UI

• genexus_layout — SDK 布局/WebForm 操作（get_tree、find_controls、set_property、add_printblock、get_preview、list_controls = 控件/主题类目录、design_system = DSO 令牌/类/图像，…）

知识库池、版本控制与团队开发

• genexus_kb — 多知识库池（list/open/close/set_default）
• genexus_module — Module Manager（IModuleManagerService）
• genexus_kb_version — 模型版本/分支管理（Create/Activate/Revert）
• genexus_versioning — 版本控制综合工具（知识库上的 Git 风格历史记录）
• genexus_gxserver — GXserver / Team Development 同步，含 pipeline_*（通过 IContinuousIntegrationService 管理 CI 流水线）
• genexus_transfer — 实际的 XPZ 导出/导入（IKnowledgeManagerService，感知依赖关系）：export / inspect / import（默认情况下，import 会预览：传入 dryRun:false 和 confirm:true 才会实际导入）
• genexus_memory — 面向 Agent 的每知识库事实存储

安全配置、IO 与元数据

• genexus_gam — GAM / 集成安全配置（IIntegratedSecurityService）
• genexus_io — 资源、部件文本交换、屏幕截图、OCR
• genexus_sdk_probe — 转储实时 SDK 接口（类型/方法/属性），用于发现功能
• genexus_worker_reload — 热切换 Worker，无需重启客户端

多知识库（v2.3.0+）： 每个非元数据工具都接受可选的 kb 参数（别名或绝对路径）。网关最多可同时打开 Server.MaxOpenKbs（默认值为 3）个知识库，每个知识库都在各自的 Worker 进程中运行——对不同知识库的调用可真正并行执行。有关 KBs[] 架构，请参阅高级配置。

WorkWithPlus 与主题化（通过 genexus_read / genexus_edit）

• 完整读写 PatternInstance / PatternVirtual XML：容器（<table>、组）、控件（<textBlock>、<attribute>、<gridAttribute>、<filterAttribute>、<errorViewer>）、操作（<standardAction>、<userAction>）、网格、排序、规则、事件块。Transaction 和 Selection 视图可分别寻址。
• Documentation（Markdown）和 Help（HTML）是一级写入目标。
• 应用实际的 ThemeClass 值（themeClass、buttonClass、groupThemeClass 等）；使用 genexus_list_objects --typeFilter ThemeClass 查找它们。

编辑模式（genexus_edit）：full（替换整个部分，默认）、patch（围绕上下文锚点执行 Replace/Insert_After/Append——适用于源代码和模式 XML）、ops（针对包含源代码的部分执行 set_attribute、add_rule 等有类型的语义操作）。

模式 XML 自动协调：WorkWithPlus 使用每个父级上的 childrenOrderedList 属性来编码 IDE 渲染顺序。MCP 现在会在每次写入时根据实际 XML 子元素顺序重建每个列表（缺少时也会创建）；调用方只需说明元素在树中的位置，MCP 就会让 IDE 按该位置渲染。响应中包含 childrenOrderedListReconciliation 区块，列出每个被（重新）写入的父级，以及无法安全推断的结构元素。

默认安全：所有写入工具都接受 dryRun: true（返回预览，不修改 KB）和 idempotencyKey（支持安全重试；并发调用会合并，结果缓存 15 分钟）。

---

WorkWithPlus 模式编辑——实际可执行的操作

WorkWithPlus 模式是驱动 Transaction 和 Selection 屏幕的 XML 文档。MCP 暴露了完整功能，Agent 无需打开 IDE 即可设计或重构屏幕：

功能	工具 / 模式	状态
读取 PatternInstance / PatternVirtual XML	genexus_read --part PatternInstance	✅
替换整个模式（mode: full）	genexus_edit --mode full --part PatternInstance	✅ 已在实时环境验证
查找/替换文本样式的补丁（mode: patch）	genexus_edit --mode patch --part PatternInstance --operation Replace	✅ 已在实时环境验证
添加 / 移除 / 重新排序结构元素（textBlock、attribute、standardAction、table-as-group、order、filterAttribute、gridAttribute、eventBlock 等）	XML 编辑 + 自动协调	✅ 已在实时环境验证
主题类（themeClass、buttonClass、groupThemeClass、cellThemeClass、format="HTML"）	元素上的 XML 属性	✅ 已在实时环境验证
重组 Transaction 视图（表单布局、操作行）	在 /instance/transaction/... 下编辑	✅ 已在实时环境验证
重组 Selection 视图（列表/网格、筛选器、排序）	在 /instance/level/selection/... 下编辑	✅ 已在实时环境验证
根据 XML 顺序自动重建 childrenOrderedList	每次写入时隐式完成；在 childrenOrderedListReconciliation 下报告	✅ 已在实时环境验证
添加 / 移动 / 移除 WebPanel 标签页和有类型的控件	genexus_wwp add_tab / move_tab / remove_tab	✅ 原生 Pattern SDK 命令；快照 + 重新读取 + WebForm 投影验证
添加或协调单个网格 Attribute 标题	genexus_wwp add_grid_attribute	✅ 隔离的试运行、完整的 PatternInstance/WebForm 快照、精确回滚，且不隐式执行生命周期操作

屏幕重设计的推荐工作流：

1. genexus_list_objects --typeFilter ThemeClass --nameFilter Button — 查找此 KB 中实际可用的按钮类（ButtonGreen、ButtonBlue、ButtonRed 等；名称因 KB 而异）。
2. genexus_read --name WorkWithPlus<Object> --part PatternInstance — 获取当前 XML。
3. 在内存中编辑 XML（LLM）：将属性包裹在 <table isGroup="True" title="…" groupThemeClass="GroupTelaResp"> 中，调整按钮顺序，添加新的 <standardAction>，附加 buttonClass="btn ButtonGreen" 等。
4. genexus_edit --mode full --part PatternInstance --content "<new xml>" — MCP 会重写该部分、协调每个容器中的 childrenOrderedList，并验证往返结果。
5. 读回以确认；刷新 GeneXus IDE 查看结果。

自定义按钮使用 <userAction>，而不是 <standardAction>。 Trn_Enter / Trn_Cancel / Trn_Delete 是 WorkWithPlus 事务上仅有的已注册标准操作；任何自定义按钮（Duplicate、Audit、Export 等）都必须是 <userAction caption="…" name="…" buttonClass="btn ButtonGreen" confirm="False" />。MCP 的协调器会将 <userAction> 视为与 <standardAction> 同级（根据上下文使用相同的 typeCode 17/18），因此二者可以共存于同一 TableActions 行中，且 IDE 会将它们并排显示。

对于 WebPanel 标签页，优先使用原生的类型化操作，而不是替换整个 XML：

{
  "action": "add_tab",
  "name": "SamplePanel",
  "controlName": "IntegrationV3",
  "title": "Integration API V3",
  "position": 5,
  "children": [
    { "type": "variable", "name": "Operation", "basicType": "VarChar", "length": 40 },
    { "type": "userAction", "name": "SendIntegration", "caption": "Send" }
  ],
  "dryRun": true
}

试运行会返回类型化差异和 versionToken。在持久化调用中将其作为 baseVersion 传入。写入操作使用 Pattern SDK 元素命令，需要精确的 PatternInstance/WebForm 快照，保留 Apply-on-save 设置，重新读取 PatternInstance，对父 WebForm 进行投影并重新读取，并在任何确认失败时回滚这两个部分。它不会调用生命周期操作。

注意事项（帮助了解情况，并非陷阱）：

• WorkWithPlus 会在每次保存后规范化某些属性。 某些字段绑定到底层事务（例如，顶层组的 title 源自事务的友好名称）。在 WorkWithPlus 对象上启用 "Apply this pattern on save" 后，引擎会重新计算这些字段——无论是在 IDE 中还是通过 MCP 编辑，行为都相同。若要固定覆盖值，可通过 MCP 切换此标志：

  { "tool": "genexus_properties",
    "arguments": { "action": "set", "name": "WorkWithPlus<Object>",
                   "propertyName": "SDPlus_Editor_Apply_On_Save", "value": "False" } }
  

  接受 "True" | "False" | "Default"（Default 会继承 KB 级设置）。设回 "Default" 可重新启用引擎重新计算。本仓库已进行实时验证。
• SDK 会强制执行结构安全性。 如果提交的 XML 违反模式不变量（例如，不含 <level> 的 <transaction>，或 name 不是已注册操作的 <standardAction>），SDK 会拒绝保存，MCP 会返回确切错误，供你修正输入。KB 不会处于只写入一半的状态。
• IDE 的 Pattern 预览是结构示意图，而非样式渲染结果。 主题 CSS（buttonClass、themeClass、字体、颜色）会在运行时解析，而不是在预览画布中解析——因此即使 MCP 写入成功，预览窗格仍会呈现通用样式。若要验证样式，请在 IDE 树中打开元素并查看右侧的属性面板（其中会显示应用的类），或点击运行 / 实时编辑查看实际 CSS。这是 GeneXus IDE 的行为，与编辑模式无关。

---

AXI CLI（供 Agent 和自动化使用）

genexus-mcp 命令本身也是一个面向 Agent、输出经过令牌优化的 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 <text> · --quiet · --no-color。

genexus-mcp wire 是个例外：它会将参数原样转发给捆绑的 gxwire.exe（包括退出代码），因此它的 --format 使用 GxWire 的格式：

genexus-mcp wire --dir ./exports/KBTeste --pack-task "invoice interest" --format toon
genexus-mcp wire --dir ./exports/KBTeste --callers PValidaCreditoLive
genexus-mcp wire --dir ./exports/KBTeste --path PEmiteFaturaLive:PValidaCreditoLive
genexus-mcp wire --help

完整约定：docs/axi_cli_contract.md。最佳实践手册：docs/llm_cli_mcp_playbook.md。

---

高级配置

安装程序会为你写入 config.json。如需自定义网络、超时或影子路径：

{
  "Server": {
    "HttpPort": 5000,
    "BindAddress": "127.0.0.1",
    "SessionIdleTimeoutMinutes": 10,
    "WorkerIdleTimeoutMinutes": 30,
    "MaxOpenKbs": 3,
    "ArtifactOutputDirectory": "C:\\GenexusMCP\\Artifacts"
  },
  "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。

生成的文档制品

genexus_doc 会将生成的文件保存在 Worker 安装目录之外，避免更新时将其遗留在安装备份中。默认根目录为 %LOCALAPPDATA%\GxMcp\Artifacts；每个 KB 都有一个稳定的 kb-<identity> 目录，其中包含 docs 和 html 子目录。设置 Server.ArtifactOutputDirectory 可选择其他根目录；仍会添加每个 KB 对应的子目录。直接启动 Worker 时，可使用等效的覆盖项 GXMCP_ARTIFACT_OUTPUT_DIR。Wiki 响应会报告 result.file；可视化工具响应会报告 result.url；二者还会报告 result.outputDirectory。可视化工具和健康检查使用当前 KB 的规范 IndexCacheService 快照，而不是共享的、相对于安装目录的缓存。

使用多个 KB

在 Environment.KBs[] 中声明多个 KB 后，每个工具都接受可选的 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 时的解析规则：

• 显式指定的 kb 始终优先；并行处理任务或提示词涉及多个 KB 时请使用它
• 每个 MCP 会话都会在 initialize 时获取已配置的 DefaultKb 快照；set_default 会更改当前会话，并为未来会话保存启动默认值
• open 只会启动／注册 Worker，不会悄然更改其他会话的目标 KB。请使用 set_default 选择它，或显式传入 kb
• 恰好有 1 个 KB 处于打开状态 → 会话未选择 KB 时使用该 KB
• 有 2 个或更多 KB 处于打开状态，且会话未选择 KB → 服务会返回 KB_AMBIGUOUS；请使用 set_default 选择一个，或显式传入 kb

在运行时管理池：

{ "tool": "genexus_kb", "arguments": { "action": "list" } }
// → { selectedKb, activeKb, openKbs: [{alias, path, pid, workingSetMB, idleSeconds}], knownKbs, 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

对于 OpenCode，请在会话开始时调用一次 genexus_whoami。使用 kb.selected、kb.default、kb.openKbs、kb.knownKbs 和 kb.declaredKbs 了解目标 KB，然后通过 genexus_kb action=set_default 选择常用工作 KB。所有绑定 KB 的响应也会在其 JSON 负载中包含 kbAlias，以便 OpenCode 关联纯文本响应。在有意比较或更新其他 KB 的调用中，请保留 kb=<alias>。

安装程序会注册 OpenCode 的两种配置布局：OpenCode 1.x 使用的旧版直接 mcp.genexus 条目，以及当前的 mcp.servers.genexus 布局。安装后，只有在修复或显式重新注册客户端时才需要运行 clients add --clients opencode；常规的 init 会自动处理检测到的客户端。注册后请重启 OpenCode，以便重新加载 MCP 配置。

池已满且没有空闲 Worker 时，服务会返回 KB_POOL_FULL——请显式关闭一个 Worker，或提高 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[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 池（v2.3.0+）：在隔离模式下，每个 Gateway 会为每个打开的 KB 启动一个独立的 .NET 4.8 Worker 进程，并受 MaxOpenKbs 限制（默认值为 3）。使用 shared-host 时，兼容的 Gateway 会连接到由代理管理的、对应每个物理 KB 的单个 Worker，而不是启动重复的 SDK 进程。Worker 按需启动，由 WorkerIdleTimeoutMinutes 回收；池满时按 LRU 策略淘汰。
• 跨 KB 并行：针对不同 KB 的工具调用会在不同的 Worker 进程中运行，互不阻塞。针对同一 KB 的调用仍会受 GeneXus SDK 的 STA 要求限制，按顺序执行。
• Gateway 隔离：shared-host 不会将一个 Gateway 变成另一个 Gateway 的主控或代理；每个客户端都保留自己的 MCP 状态，只有 SDK Worker 会被共享。
• Gateway 复用：多个 IDE 实例通过 %LOCALAPPDATA%\GenexusMCP\gateway-leases 中的租约文件共享一个 Gateway。
• HTTP 模式：也可通过 http://127.0.0.1:5000/mcp 使用 SSE。请求头：MCP-Protocol-Version: 2025-11-25。

---

开发与从源代码构建

想要贡献代码或运行本地开发构建？

1. 在 Windows 上克隆此仓库。
2. 运行 .\build.ps1，还原并构建 C# 组件，并打包本地构件。该脚本会检查所需的 .NET SDK 和 GeneXus 18 安装。
3. 如果 GeneXus 安装在默认路径之外，请在运行构建前将 $env:GX_PATH 设置为其安装文件夹。只有运行时测试才需要知识库。
4. GxWire（genexus_wire 和 genexus-mcp wire 所需）是位于 src/gxwire 的 Rust 引擎。请安装 Rust 工具链（cargo）。build.ps1 会以发布模式构建它，并将 gxwire.exe 复制到 publish/。如果没有 cargo，该步骤会静默跳过，工具会返回 GxwireNotFound。Gateway 会在自身所在目录、publish/、src/gxwire/target/release/ 和 PATH 中查找 gxwire.exe。CLI 也会遵循 GENEXUS_MCP_GXWIRE_EXE。

随附的 AI 技能（.gemini/skills/）

此仓库随附一组位于 .gemini/skills/ 下的Agent 技能，任何支持技能的 MCP 兼容客户端（Gemini CLI、通过插件使用的 Claude Code 等）都可以加载这些技能，以便更准确地进行 GeneXus 推理：

技能	为 Agent 提供的内容
genexus-mastery	此仓库首选的 MCP 工作流 + 多 KB 用法
genexus18-guidelines	叠加在 Nexa 之上的本地工程规则
nexa	主要 GeneXus SDK 的完整参考集：每种对象类型、命令、类型和属性，导入自官方 genexuslabs/genexus-skills
frontend/chameleon-controls-library	58 个 Chameleon UI 组件规范
frontend/mercury-design-system	Mercury 设计令牌、资源包和主题
frontend/design-system-builder	自定义设计系统编写指南
frontend/ui-creator	面板／屏幕生成模板

第三方技能采用 Apache 2.0 许可（见 .gemini/skills/NOTICE.md）。如需与上游同步更新，请按照 NOTICE.md 中的步骤操作。

Nexus-IDE（VS Code 扩展 — 可选，不会自动安装）

src/nexus-ide 是仓库中一个轻量级的实验性 VS Code 扩展。安装程序不再打包或安装它——VS Code 已改为作为原生 MCP 客户端接入（见支持的 AI 客户端）。如果你想使用该扩展，请手动构建并安装：

cd src/nexus-ide; npm ci; npm run compile
npx --yes @vscode/vsce package --out nexus-ide.vsix
code --install-extension nexus-ide.vsix --force

它提供虚拟文件系统（genexus:// 方案）、支持多部分编辑的 KB 浏览器，以及 MCP 发现命令。

自动化发布

通过 release.ps1 发布；完整协议见 docs/release_protocol.md。

• 入口： ./release.ps1 -Version <X.Y.Z> 会构建制品、创建 v<version> 标签和 GitHub Release（附带 publish.zip、其校验和以及 Nexus VSIX）。推送到 main 不会触发发布。
• 工作流： 创建该 Release 后，会在 release: [published] 事件触发时运行 .github/workflows/release.yml；对于已存在的 Release，也可以通过带有 tag 的手动 workflow_dispatch 重新运行。该工作流会验证 Release 的资源并将包发布到 npm——不会创建标签或 Release。
• npm 身份验证： OIDC 受信任发布。无需配置 npm 令牌密钥；工作流会在发布前取消设置找到的任何令牌。

---

许可证

MIT — 详见 LICENSE。

搜索关键词： GeneXus MCP · GeneXus 18 MCP · GeneXus AI · GeneXus Claude · Model Context Protocol GeneXus · GeneXus 低代码 AI Agent · GeneXus Cursor · GeneXus Antigravity