内容
# GeneXus MCP 服务器指南
本仓库汇集了有关 `GeneXus MCP 服务器` 的使用知识，重点是已经确认的内容和仍需验证的内容。
## 初始来源
- [GeneXus for Agents - 安装指南](https://docs.genexus.com/en/wiki?61635,GeneXus+for+Agents+-+Installation+guide)
## 本文档的范围
本材料基于 `Windows Native` 场景，这是官方安装指南的重点。
## 目标
- 注册服务器定义
- 注册机器上的确切位置
- 集中观察、验证和未来的发现于一处
- 了解如何使用或不使用 IDE 打开 MCP
## 已达成的组织
本仓库作为 `GeneXus MCP 服务器` 的知识库。
有一个独立的本地工作区用于测试和学习成果，位于 `C:\Dev\Test`。
本文件记录了我们目前的理解和仍需确认的内容。
实践规则：
- 这里存放 `.md` 文件中的注释、决定和解释
- 从知识库导出、准备导入的内容存放在本地测试工作区
- 学习成果不应与永久文档混淆
## 初始定义
`GeneXus MCP 服务器` 是 `GeneXus Next` 的本地后端，用于与工具和代理集成。在验证的安装中，它由可执行文件 `GeneXus.Services.Host.exe` 提供服务。
`模型上下文协议（MCP）` 是一种协议，允许代理连接到提供受控操作的服务器。
官方指南确认服务器：
- 已包含在 `GeneXus Next` 中
- 当 IDE 运行时可用
- 也可以直接从 `bl` 文件夹运行
- 自 `GeneXus Next 2026.01` 和 `GeneXus 18 Upgrade 15` 起可用
- 允许创建和打开知识库，创建或修改对象，定义规则，配置属性，导入或导出文本对象
## 驱动器上的位置
服务器位于 `GeneXus Next` 安装的 `bl` 文件夹中。
确认的可执行文件是 `GeneXus.Services.Host.exe`。
在验证的安装中，主机在机器上的绝对路径是：
`C:\Users\ANTONIOJOSE\AppData\Local\Programs\GeneXus\GeneXus Next\bl\GeneXus.Services.Host.exe`
## 支持文件
根据官方指南，本地需要关注的文件是：
- `GXMBLServices.log`，用于监视后端执行和交互
- `settings.json`，默认在 `bl` 中创建
- `settings-overrides.json`，用于覆盖配置而不修改默认文件
## 与 CLI 的连接
官方指南显示服务器公开了 `http://localhost:8001/mcp` 端点，可以连接到兼容 MCP 的 CLI。
## 如何启动服务器
这里的主要重点是使用 `GeneXus MCP 服务器` 而不需要依赖打开的 IDE，而不是排除混合使用。
根据官方指南，有两种有用的模式：
- 启动 IDE，它会自动启动服务器
- 只启动本地后端，从 `bl` 文件夹执行 `GeneXus.Services.Host.exe`
### 推荐的操作流程
1. 打开 `GeneXus Next` 安装。
2. 进入 `bl` 文件夹。
3. 执行 `GeneXus.Services.Host.exe`。
4. 确认服务器在默认端点响应。
### 验证的本地快捷方式
在该机器上，已经有启动快捷方式：
- `GENEXUS MCP`，正常打开主机
- `GENEXUS MCP MIN`，最小化打开主机
这些快捷方式出现在 Windows 搜索中，并指向 `GeneXus.Services.Host.exe`。
### 启动时预期行为
通过快捷方式或直接执行 `.exe` 打开主机时，预计会出现一个终端窗口。
正确的初始化信号是：
- `GeneXus Services Host started. port:8001`
- `Now listening on: http://localhost:8001`
- `Application started. Press Ctrl+C to shut down.`
窗口需要保持打开，直到服务器正在使用。
## 如何验证它是否活动
实用验证方法是确认 MCP 端点在：
`http://localhost:8001/mcp`
响应。
也可以观察 `GXMBLServices.log`，因为它记录了后端的执行和交互。
### 实用验证标准
- 主机进程正在运行
- `http://localhost:8001/mcp` 端点响应
- `GXMBLServices.log` 显示初始化无加载错误
- CLI 可以连接到 MCP 服务器
### 真实 MCP 验证
端点不响应简单的 `GET` 请求。它需要带有 `Accept: application/json, text/event-stream` 的 MCP 客户端。
使用脚本时，请注意：响应可能通过 SSE 以 `event:` 和 `data:` 前缀到达。提取 `data:` 行并解析其中的 JSON。
在验证中：
- `initialize` 成功响应
- 服务器返回 `Mcp-Session-Id`
- `tools/list` 返回公开的 GeneXus 工具
这确认服务器作为 MCP 功能正常，而不仅仅是监听端口。
## 如何在 Codex Windows 中注册
本地 Codex 支持 MCP 服务器在用户配置文件中，使用别名 `gxnext`。
```powershell
codex mcp add gxnext --url http://localhost:8001/mcp
```
## 日常使用
使用 `GeneXus MCP 服务器` 的最小流程：
1. 启动主机 `GeneXus.Services.Host.exe`。
2. 确认端口 `8001` 已打开。
3. 使用 `initialize` 进行 MCP 握手。
4. 在 Codex 中使用服务器作为 `gxnext`。
> 环境提示：在 Windows 上的本地脚本中使用 `python3`（如果可用）。`python` 命令可能指向 Python 2 并导致语法或编码错误。
如果 `initialize` 失败并返回 `406`，问题通常是请求的 `Accept` 而不是服务器已关闭。
在列表操作中，`export_kb_to_text` 使用 `listOnly:true` 可能成功完成但不返回对象列表到 MCP 负载中。
当需要实际对象列表时，可能需要将 KB 导出到工作文件系统并读取生成的工件。
## 当前状态
- `GeneXus MCP 服务器` 可以在 `http://localhost:8001/mcp` 上响应
- 本地主机是 `GeneXus.Services.Host.exe`
- 在此机器上验证的主机绝对路径是 `C:\Users\ANTONIOJOSE\AppData\Local\Programs\GeneXus\GeneXus Next\bl\GeneXus.Services.Host.exe`
- 服务器可以在不打开 IDE 的情况下启动
- 有用于正常和最小化启动主机的本地快捷方式
- 相关日志是 `GXMBLServices.log`
- `settings.json` 和 `settings-overrides.json` 是本地支持文件
## 工作术语
`GeneXus 对象文本文件` 指的是代表 GeneXus 对象并可作为 MCP 流中读、研究、导出或导入源的 `.gx` 文件。
## 测试工作区
用于生成和导出工件的本地工作区是 `C:\Dev\Test\NextTest1`。这是 `NextTest1` 知识库的所有 MCP 操作的官方 `currentDirectory`。
内部结构：
| 子文件夹 | 用途 |
|---|---|
| `ExportadosPeloGenexusMCP\` | 通过 MCP 导出的（`Textual`（src/src.ns）和物理结构） |
| `ProntosParaImportacao\` | 已验证的导入准备对象 |
| `RascunhosGerados\` | 未验证的草稿 |
| `Exemplos\` | 参考示例 |
| `Verify-*\` | 对象验证文件夹 |
## 验证的构建流程
对于具有新事务的知识库，验证的完整流程是：
1. 使用指向测试工作区的 `currentDirectory` 进行 `open_knowledge_base`
2. 使用准备好的 `.gx` 文件进行 `import_text_to_kb`
3. `build_all` - 需要 `prefer-offline=true` 和 `audit=false` 在 `~/.npmrc` 中
4. 在任何数据库操作之前验证应用程序数据库是否存在于 LocalDB 中
5. 如果数据库存在且有数据，则使用 `isCreate: false` 进行 `create_or_impact_database`；如果数据库不存在，则使用 `isCreate: true`
6. 在 `NetModel\web\bin` 文件夹中使用 `dotnet GxNetCoreStartup.dll` 启动应用程序
## `npm install` 卡住构建
`build_all` 调用 `npm install` 用于 GeneXusUnanimo 的 UserControls。 如果配置不正确，此过程将无限期卡住。
验证的解决方案：在 `~/.npmrc` 中添加：
```
prefer-offline=true
```
> **评估中：** `audit=false` 也解决了问题，但全局禁用安全检查。仍未确认仅 `prefer-offline=true` 是否足够 - 在下一个构建中验证。
## 未解决的问题
- MCP 的 `run` 工具在此版本中无法正常使用 - 在模式中声明但未实现。参见 `mcp-tools.md` 获取详细信息和替代方案。
- 确认 `prefer-offline=true` 是否足以避免在 `build_all` 中 `npm install` 卡住（观察下一个构建）
- 通过 MCP 的新 `Procedure` - `PrcSaudacao` 成功导入并位于知识库中，但未在 `build_all` 期间生成 `.dll`。可能是时间问题（构建在处理新对象之前运行）或真正的错误。需要新的 `build_all` 来验证是否编译。
## 已完成的验证
- 通过 MCP 的 `WebPanel` 往返：导出 → 编辑 `.layout.xml` → 导入 → 构建 → 浏览器中可见 ✅
- 布局中的 `textblock` 需要 `controlName` 而不仅仅是 `name` - 没有它导入失败 ✅
- 在构建之前关闭 Web 应用程序 - 安全 `.dll` 在 `NetModel\web\bin\` 中 ✅
- `Folder` 是 GeneXus 对象类型，可通过 `import_text_to_kb` 使用空正文文件创建 ✅
- 通过 MCP 将对象移动到文件夹中不起作用 - 既不能通过 `#Properties` 中的 `Folder`，也不能通过子目录；仅限于 IDE ✅
- MCP 没有 `delete_object` - 导入的对象无法通过 MCP 删除 ✅
- `WorkWith` 和 `WorkWithDevices` - 可通过 MCP 导出，但 **不可重新导入**：验证器拒绝 YAML 中的选项卡，即使是 GeneXus 自己生成的 ✅
- `#Properties` 中的 `BusinessComponent = true` 需要小写（TOML）- 大写 `True` 导致解析错误 ✅
- `&bc.Load(Key)` 需要主键作为参数 - 不带参数的 `Load()` 不被验证器接受 ✅
- 由 WorkWithWeb 生成的对象（`WWxxx`、`ViewXxx`、`XxxGeneral`）的往返 - 它们是通用 `WebPanel`/`WebComponent`，支持标准流程：导出 → 编辑 `.layout.xml` → 验证 → 导入 → 构建 → 浏览器中可见 ✅
- `.main.gx` 代码往返（不仅限于布局）- 编辑 WebPanel 中的事件/规则有效：`Form.Caption` 在启动事件中更改，导入，编译，浏览器中反映变化 ✅
- `execute.xml` 可能在 `build_all` 后被阻止：GeneXus 报告一般故障，但 `dotnet publish` 步骤已完成，`bin\` 中的 DLL 已更新 - 应用程序正确提供更改 ✅
- GeneXus 守护进程（`SpecifierDaemon`、`GeneratorDaemon`、`ResidentBuilderDaemon`）在关闭 IDE 后成为孤儿进程并阻塞通过 MCP 的构建；解决方案：使用 `Get-WmiObject Win32_Process` 列出并使用 `Stop-Process -Force` 终止 PID ✅
- 从零新建的 `WebPanel` 通过 MCP - 带有最小事件/变量的 `.webpanel.main.gx` 文件编译并生成功能性 DLL ✅
- `build_one` 和 `compile_object` - **不适用于** 此版本的 GeneXus；两者均返回“内部错误”而没有详细信息；使用 `build_all` 作为替代方案 ❌
