MCP 接入与 AI 二次开发

MCP 用于让 AI 客户端通过工具查询和配置 TGateway，并获取配套二次开发技能。连接地址为 TGateway 管理地址加 /mcp，协议类型选择 Streamable HTTP。

添加到 Codex

以下以 TGateway 管理地址 http://127.0.0.1:16100 为例，地址和端口请替换为实际部署值。连接其他电脑上的服务时，填写该服务可访问的 IP 或域名。

1. 确认 TGateway 已启动，当前电脑能够打开其管理页面。
2. 打开 Codex 设置，进入 MCP servers，点击 Add server。
3. 按下表填写服务器信息并保存，按客户端提示重启连接。

用户不需要查找或复制 Bearer 令牌，也无需手动填写 Authorization 请求头。保存地址与点击认证是两个步骤，添加服务器后不一定立即弹出浏览器。

命令行也可添加并认证：

codex mcp add tgateway --url http://127.0.0.1:16100/mcp
codex mcp login tgateway

浏览器授权

1. 点击服务器旁的 Authenticate／认证。浏览器打开授权页后，核对应用为当前使用的客户端、服务地址为目标网关。授权页按浏览器语言自动显示中文或英文。

2. 输入账号密码，点击 登录并授权／Sign in and authorize。客户端获得的操作权限与该账号一致。
3. 浏览器显示 Authentication complete. You may close this window. 时，授权已完成，可以关闭此页并返回 Codex。该结果页由 Codex 提供，客户端负责凭据交换及后续续期。

4. 返回 Codex，确认服务器工具已加载。在会话中先执行一次查询，核对连接对象，例如：

   使用 tgateway MCP 列出当前通道，只查询，不修改配置。

权限与工具

工具由 TGateway 已注册的 WebAPI 自动提供，包括查询、分页、新增、更新、删除、导入导出及其他业务操作。实际范围取决于当前网关注册的接口与账号权限。

MCP 入口先验证身份；每次工具调用继续执行原接口权限及参数校验。工具出现在列表中不表示账号拥有执行权限。停用账号、撤销业务会话等安全策略仍然生效。

客户端取得的是独立 MCP 凭据。授权码单次使用，并绑定客户端、精确回调地址、目标服务及 PKCE 证明；刷新凭据使用后轮换。重放上次刷新凭据会撤销该授权。服务重启后需要重新认证。客户端退出或撤销授权后应清除保存的凭据。

已有自动化程序仍可携带现有业务 Bearer 令牌调用 /mcp。普通用户使用浏览器授权即可。

通过 MCP 获取二次开发技能

TGateway 提供随应用程序集嵌入、与当前网关版本配套的 tgateway-development 技能。AI 可以从已连接的网关读取公开契约、操作方法和示例，在没有产品源码的情况下开发表达式、脚本、自定义节点、规则流程、采集插件和数据转发插件。

读取入口与按需取用

1. 完成上面的 MCP 认证，先让 AI 查询当前网关版本和已有资源，确认连接对象。
2. 在实例返回的工具目录中查找 GetDevelopmentSkillFile 对应工具。实际工具名称以客户端加载的目录为准，不要自行拼接前缀。调用时省略 path，默认读取 SKILL.md。
3. 再以 path: "manifest.json" 读取清单，核对 gatewayVersion、targetFramework、pluginGenerator 及示例入口。
4. 按下表选择资料，再通过同一工具的 path 参数读取。先读 references/runtime-contracts.md，涉及保存、编译或接口验证时再读 references/validation.md；无需每次把全部示例塞进会话。

以下是传给技能文件工具的参数示例，不是规则或插件配置：

{"path":"references/collect-plugins.md"}

支持普通 HTTP API 的客户端可使用同一管理地址下的接口。以下技能文本与 ZIP 是公开开发资料，HTTP 接口允许匿名获取；MCP 连接仍按前文认证，实际配置、编译、调试等业务操作继续执行各自权限校验：

GET /api/gatewayscriptcontroller/getdevelopmentskillfile
GET /api/gatewayscriptcontroller/getdevelopmentskillfile?path=manifest.json
GET /api/gatewayscriptcontroller/downloaddevelopmentskill

前两个接口读取文本，最后一个下载完整技能 ZIP。插件生成器 tools/TGateway.PluginsGenerator.dll 通过 ZIP 交付，不能当作文本通过 GetDevelopmentSkillFile 读取。MCP 下载工具可按返回的 bodyBase64、contentType、contentDisposition 恢复文件；客户端不支持二进制下载时，使用已授权的普通 HTTP 下载。

读取技能后，AI 可在当前会话按其说明工作，不要求先安装客户端技能。需要长期在本地复用时，解压完整技能包，并按所用 AI 客户端的技能发现机制安装；更换目标网关或版本后，重新核对清单并取用配套资料。技能包不包含产品完整运行包，也不会通过 MCP 自动获得服务器文件系统权限。

技能覆盖范围

代码必须匹配使用入口：表达式是方法体，动态 SQL 等入口是类成员，FullSource 是完整文件，网页自定义节点是节点成员代码，插件则是独立 DLL 工程。不能把这些形式互相粘贴代替。具体操作参见 脚本开发说明、自定义节点开发说明、采集插件二开说明 和 业务插件二开说明。

插件从开发到部署

1. 读取插件资料和 examples/plugins/index.json，下载完整 ZIP。随包提供 Modbus 采集、批量 HTTP 转发及工程示例；按索引保存文件并去掉 .txt 后缀。
2. 取得目标网关同版本、同交付构建的发布 DLL 与 XML 文档。用支持 net10.0 的 SDK 构建，GatewayRuntimeDir 指向发布目录，GatewaySkillDir 指向解压后的技能目录。生成器作为 Analyzer 参与编译，并核对生成目录及诊断。
3. 交付插件 DLL、必要的第三方依赖、配置示例和版本/验证说明。宿主引用使用 Private=false，不要把整套宿主 DLL、密钥或数据库放入插件包。
4. 停止自有测试实例，将 DLL 放入该实例项目数据根目录下的 PluginDlls 顶层，再启动宿主。该目录取决于 ProjectDirectory，不保证在可执行文件旁；子目录不会递归扫描。不要在运行中替换程序集。
5. 打开 开发配置 → 插件管理，按插件名称筛选，核对采集/数据转发类型、版本与启用状态，再创建对应设备或转发目标。

外挂 DLL 需要网关支持动态加载；网页脚本热编译不是插件安装入口。仅有 MCP 连接而没有配套发布 DLL 时，可以完成资源查询和资料获取，但不能据此宣称已构建、安装插件。

随包工程的构建命令如下，路径按实际目录替换。两次命令使用相同的目标框架与 MSBuild 属性：

$env:DOTNET_ADD_GLOBAL_TOOLS_TO_PATH = 'false'
dotnet restore ./PlantGatewayPlugins.csproj -p:GatewayRuntimeDir=C:/GatewayRuntime -p:GatewaySkillDir=C:/Skills/tgateway-development
dotnet build ./PlantGatewayPlugins.csproj -c Release --no-restore -p:GatewayRuntimeDir=C:/GatewayRuntime -p:GatewaySkillDir=C:/Skills/tgateway-development -p:EmitCompilerGeneratedFiles=true

环境设置仅作用于当前进程及子进程。生成器仅供编译，不复制到 PluginDlls；新增第三方依赖需在隔离部署中验证宿主解析，不通过覆盖宿主核心库解决冲突。

通讯与业务链验收

1. 在 采集配置 选中设备，查看实时变量的值、质量和采集时间。再打开 协议调试 → 特殊方法，从目录选择方法并填写 JSON 参数。例如，用 ReadScaledInt16 读取地址 40001 并按 0.1 缩放，核对实际返回值；地址和方法以所选插件为准。

2. 通过 MCP 调试时，先查询 GetSubject 对应工具，使用 subjectType（CollectDevice 或 DataForwardTarget）加真实 subjectId 标识对象，再按返回模块选择读写或方法调用。CancellationToken 由宿主注入，不填进业务参数数组。检查业务 isSuccess、错误和实际返回值，HTTP 200 不能代替成功判定。

3. 普通地址读写验证的是协议层；读写表达式、写前写后步骤还需用变量写入与读回验证。BatchRead 当前逐地址执行，不能用它的次数证明周期采集已经合包。

4. 在 数据转发 中核对组范围、触发间隔、最大批量、目标健康状态和待转发数。可用每秒转发组内 20 个变量的配置进行验收；为组外变量填写目标属性不会将其纳入范围。接收端还需核对实际请求、条数和内容。

5. 使用可控接收端验证拒绝、超时、断连、恢复和重启补发。CacheEnable 控制失败后是否保留重试数据，不表示正常路径完全不经过 CacheDB；重试可能重复，接收端按业务键做幂等。强杀前尚未持久化的内存批次可能丢失。

6. 记录变量数、周期、合包/分片、请求数、耗时、失败率及 CPU/分配情况。复用客户端与组生产数据，避免逐变量通讯、全局扫描、重复序列化、无界并发和长期开启报文日志。

若客户端因 JsonElement 的 object 类型描述拒绝实际需要的参数数组或标量，不要把参数改成业务不接受的对象。保留错误信息，并通过已授权的普通 HTTP API 或页面调试验证；该结果不能记作该客户端的 MCP 调用已通过。

可直接使用的任务描述

连接当前 TGateway MCP，先读取 GetDevelopmentSkillFile 的 SKILL.md 和 manifest.json。
仅通过实例工具目录、技能资料和配套发布 DLL 开发，不读取产品源码。
按任务读取所需 references 和 examples，先查询现有设备、变量、脚本及节点目录。
实现车间 Modbus 采集和 HTTP 批量转发：连续寄存器按协议限制合包，
只发送指定转发组变量，保留失败重试并验证恢复补发。
先在独立测试实例与模拟器完成构建、插件发现、配置、通讯和重启验收。
交付工程、插件包、配置步骤及实测结果，列明未测范围；不写入生产设备。

也可以把业务部分换成“温度读写换算”“报警状态节点及规则连线”或“自定义入库脚本”，并提供真实变量名、单位、触发条件和预期结果。技能提供契约和示例，生成内容仍需编译与业务验收；脚本和插件以网关进程权限执行。

核对操作与日志

1. 查询系统状态或当前用户，核对连接的网关实例。
2. 新建一条可删除的测试配置，查询、修改后删除。
3. 打开“系统日志 → 操作日志”，查看“请求来源”：MCP 表示工具调用；WebApi 表示普通 HTTP API 调用，包括管理前端。
4. 变量写入及插件方法的 RPC 日志通过“操作源”区分 MCP 与 WebApi。

日志按原策略异步落库，不是所有查询接口都会记录操作日志。Gateway 普通成功 RPC 是否保存，仍受“RPC成功日志”设置控制。

文件上传工具的 _http.bodyBase64 传入文件 Base64；下载结果的 bodyBase64、contentType、contentDisposition 用于恢复文件。文件大小受原接口及 MCP 正文上限限制。

域名与反向代理

直连时自动使用当前请求的 IP 或域名及协议。反向代理保留外部 Host，并通过 X-Forwarded-Host、X-Forwarded-Proto 传递外部主机和协议，无需另外配置服务地址；代理需覆盖客户端传入的同名头，并传递单一值。

需要固定对外地址时，可选填 Mcp:PublicOrigin，显式配置优先于请求地址和转发头：

{
  "Mcp": {
    "PublicOrigin": "https://gateway.example.com"
  }
}

该值只含协议、主机及可选端口，不带路径、查询或片段。代理需保留 /.well-known/oauth-protected-resource/mcp、/.well-known/oauth-authorization-server、/mcp 和 /mcp/oauth/ 路径，保证浏览器与客户端访问同一公开来源。

常见问题