SAP Connector —— SAP 接入统一技能

> 作者 / Author: justin
> 安装目录提示：Skill Hub 安装后的实际目录名可能不是 sap-connector，请把文档中的 <你的skill目录名> 替换为你本地安装后的目录名（例如 sap-capability-hub-justin__skillhub）。

> 把 SAP 接入能力（两条实时 MCP 通道 + ADT 通道 + 离线技能）收敛为一个入口，
> 登录信息外置到可编辑的 TXT，改 TXT 即换登录。
> 本技能随包附带两条自建 MCP 服务端（sap-odata-mcp/server.py、sap-gui-mcp/server.py，纯标准库、零依赖）。

能力全景

连接配置（核心：凭据外置）

• 配置文件：sap-connection.txt（随本 skill 一起存放）
• 格式：KEY=VALUE，# 开头为注释，等号两侧不留空格。
• 改这个文件就能换 client / 用户 / 密码 / 系统地址，无需动 mcp.json。
• 改完后，在 WorkBuddy 连接器面板「重新信任 / 重启」sap-all 即生效。

字段说明：

# 登录信息（最常改）
S4_BASE_URL   = https://<host>:<port>     # S/4HANA 地址
S4_CLIENT     = 500                        # 客户端号
S4_USER       = <用户>                     # 登录用户名
S4_PASS       = <密码>                     # 登录密码
S4_VERIFY_SSL = false                      # 内网自签证书常关

# OData / 服务配置（一般不用改）
S4_SERVICE / S4_ENTITY / S4_PARAMS         # 默认销售订单分析服务
S4_TABLE_SERVICE                            # 通用表 OData 服务（读表用）
S4_PROGRAM_SERVICE / S4_PROGRAM_ENTITY / S4_PROGRAM_KEY  # ABAP 程序执行服务

> 启动链路：sap-all → python server.py，server.py 在读取全局配置前自动从 sap-connection.txt 注入 S4_* 环境变量（env 优先，TXT 仅作默认）。
> 配置查找顺序（多候选兜底）：相对路径优先——server.py 位于 sap-odata-mcp，自动向上一级到技能根读取 sap-connection.txt；绝对路径兜底——C:/Users/<用户名>/.workbuddy/sap-connection.txt（装到技能目录时自动命中）。因此本 skill 目录整体搬迁/分享后，配置随行无需额外改路径。
> 密码只存在于 TXT，不在 mcp.json，也不在 server.py。

通道 C 连接配置（ADT 凭据，独立于 OData/GUI）

> 关键区别：ADT 通道（aibap.mcp）不读 sap-connection.txt，它走 SAP_CONFIG_FILE 环境变量指向独立的 JSON 凭据文件。

• 配置文件：建议放置于 C:/Users/<用户名>/.config/sap-mcp/systems.json
• 加载机制：mcp.json 中 aibap-mcp 的 env.SAP_CONFIG_FILE 指向该文件；二进制启动时解析 systems 与 default_system。
• 改这个文件就能换 ADT 登录的 host/client/用户/密码，改完后「重新信任 / 重启」aibap-mcp 即生效。

字段说明（一个 systems 可含多套系统，用 default_system 指定默认）：

{
  "default_system": "dev",
  "systems": {
    "dev": {
      "host": "https://<host>:<port>",   // SAP ADT 地址（同 S/4，无需 /sap/bc/adt 后缀）
      "user": "<用户>",
      "password": "<密码>",
      "client": "500",                     // 客户端号
      "tls_skip_verify": true             // 内网自签证书常关
    }
  }
}

> 与 OData 通道的 S4_VERIFY_SSL 同理：tls_skip_verify=true 仅限内网自签场景，上公网务必开启校验。
> 注意：systems.json 与 sap-connection.txt 是两份独立凭据——换 OData/GUI 登录改 TXT，换 ADT 登录改 JSON，二者不会互相覆盖。

通道 A 工具与用法（OData MCP）

可用工具：ping / list_services / list_analytics / list_entity_sets / query / get_by_key / read_table / read_program / run_program / list_sales_orders / get_sales_order

• 验证连通：ping
• 查销售订单：list_sales_orders(top=20, filter="CreationDate ge datetime'2026-01-01'")
• 按单号取订单：get_sales_order(sales_order_id='1000001')
• 读任意 DDIC 表：read_table(table='VBAK', where="VBELN='0900000187'", top=100)
• 查任意已激活 OData 实体：query(service='API_BUSINESS_PARTNER', entity='A_BusinessPartner', top=10, select='BusinessPartner,LastName')
• 读 ABAP 源码：read_program(program='Z_REPORT_X', object_type='program')
• 执行 ABAP 程序取输出：run_program(name='ZSD001')

> query 是取「SAP 全量数据」的主入口——只要 Basis 在 /IWFND/MAINT_SERVICE 激活了对应 OData 服务即可查。
> read_table / run_program 依赖 Basis 建好 Z_TABLE_SRV_SRV / Z_EXEC_SRV_SRV。

通道 B 工具与用法（GUI MCP）

前置（三者缺一不可）：服务器 RZ11 sapgui/user_scripting=TRUE、GUI「启用脚本编写」、一个已登录的 SAP GUI 会话。

可用工具：ping / sap_list_connections / sap_connect / sap_run_transaction / sap_send_command / sap_set_text / sap_press / sap_status / sap_read_grid / sap_screenshot

• 进入事务：sap_run_transaction(tcode='VA03') → sap_set_text(...) / sap_press(...) → sap_read_grid()
• 截图：sap_screenshot()

通道 C 工具与用法（ADT MCP / aibap.mcp）

> 通道 C 用 aibap.mcp（Hochfrequenz 出品，Go 二进制、零依赖）对接 SAP ADT REST API（/sap/bc/adt，NetWeaver 7.40+）。
> 定位：开发/质量系统上的 ABAP 源码级操作（搜索对象、读源码、改源码、语法检查、激活、查使用位置、单元测试、锁/传输请求），不读业务数据。
> 二进制：从 Hochfrequenz/aibap.mcp Releases 下载 windows-amd64 版，解压到本地（如 C:/Users/<用户名>/.workbuddy/skills/<你的skill目录名>/tools/aibap/）。

工具组与典型工具：

常用操作示例（参数风格以实际工具签名为准，先 ping 再动作）：

• 连通性自检：ping
• 搜索 Z 程序：search_objects(query="Z*", object_type="PROG")
• 读源码：get_source(object_name="ZSD001", object_type="PROG")
• 语法检查：syntax_check(object_name="ZSD001", object_type="PROG")
• 激活：activate_object(object_name="ZSD001", object_type="PROG")
• 查使用位置（where-used）：where_used(object_name="ZTABLE", object_type="DTEL")
• 跑单元测试：run_unit_tests(object_name="ZCL_DEMO", object_type="CLAS")

> 前置（务必确认）：
> 1. SAP 端 SICF 已激活 /sap/bc/adt（探测 https://<host>:<port>/sap/bc/adt/discovery?sap-client=500：
> - 200 = 已激活且认证通过；401 = 已激活待认证；403(德语页) = 未激活，需 Basis 激活 SICF 服务；000 = 网络不可达。
> 2. 账号有 ADT 开发权限（S_DEVELOP 等），且 Basic Auth 可达。
> 3. 生产系统常因 SAML SSO + Web Dispatcher 拦截 ADT → 生产只走 GUI 通道（B），ADT 仅用于开发/质量系统。

规划通道 D：RFC/BAPI 直连（pyrfc + NWRFC SDK）—— 可选，附替代路径

> 定位：经 SAP NetWeaver RFC 协议直接调用 BAPI_* / 自定义 RFC 函数模块，适合稳定的写操作与复杂业务逻辑的 ECC/On-Prem 场景。
> 现状：需 NWRFC SDK（SAP SMP 的 S-user 下载，非公开）+ VC++ 运行库 + 管理员权限，落地门槛较高。

解锁两条路径（二选一即可落地）
- 路径 A — 补原生 SDK（推荐用于要真正直连）
- 从 SAP SMP 下载 NWRFC SDK（windows-x64）→ 设环境变量 SAPNWRFC_HOME 指向它，安装 VC++ 运行库。
- 在真实 venv 里 pip install pyrfc，封装为 MCP 暴露 call_function(rfc_name, params) 工具，注册进 mcp.json。
- 验证：call_function("BAPI_USER_GETLIST", {...}) 返回即就绪。
- 路径 B — 走已部署 OData MCP 作等同替代（绕过 SDK 与权限）
- 让 Basis 把要调用的 FM/BAPI 封装成一个 OData 操作：扩展现有 Z_EXEC_SRV（或新建 SEGW 服务），在 DPC_EXT 里调 BAPI_* 并把结果作为实体返回。
- 即可经已通的 OData MCP（通道 A）调用该 BAPI，完全绕开原生 SDK、VC++ 依赖与内网环境限制。

> 选型建议：要稳定直连 + 高频 RFC → 走 A；只是偶尔调个 BAPI 取数/写数 → 走 B（复用通道 A，零额外依赖）。

离线技能（不联网）

• abap-coder：报表/ALV、OO、增强 BADI、HANA/AMDP/CDS、开发说明书分析
• abap-logic-analyzer：ABAP 源码 → 多 Sheet Excel 逻辑梳理文档
• sap-daily-operations：FICO/MM/SD/PP/QM 事务码、配置、月末结账、报错排查
• sap-fico-consultant：FI/CO 配置、S/4HANA 迁移、跨模块集成
• sap-integration：RFC/BAPI/OData 集成方案与设计（含脚本模板）

部署 / 验证

通道 A / B（OData / GUI）

1. 确认 sap-connection.txt 已填好（随包附模板）。
2. mcp.json 中 sap-all / sap-gui 的 args 已直接指向随包的 server.py（无需在 mcp.json 写凭据；server.py 启动时自读 TXT）。
3. 连接器面板重新信任 sap-all 与 sap-gui。
4. 调 ping 验证：返回「连接成功」即就绪。

通道 C（ADT / aibap.mcp）

1. 取得二进制：从 Hochfrequenz/aibap.mcp Releases 下载 windows-amd64 版，解压到本地 tools/aibap/。
2. 写 ADT 凭据 systems.json（见上文「通道 C 连接配置」）。
3. 在 mcp.json 注册 aibap-mcp（见 mcp-config-snippet.json）。
4. 连接器面板重新信任 aibap-mcp。
5. 端到端验证：调 search_objects(query="Z*", object_type="PROG") 真实命中 SAP 返回 Z 程序即就绪。

> 完整的 mcp.json 注册片段见随包根目录 mcp-config-snippet.json；SAP 侧自建 OData 服务的激活/实施步骤见随包 使用教程.md 与 references/ 下的实施手册。

排错速查

安全提示

• OData/GUI 密码明文存于 sap-connection.txt，ADT 密码明文存于 systems.json；注意本机文件权限，勿提交到任何仓库。
• S4_VERIFY_SSL=false 与 tls_skip_verify=true 关闭了证书校验，仅限内网自签场景；若上公网务必开启。
• 生产系统建议走 SSO + GUI 通道，OData 用只读账号；ADT 通道仅用于开发/质量系统，切勿对生产做源码写操作。
• aibap.mcp 二进制为第三方 Go 程序（Hochfrequenz），仅从官方 Releases 下载并校验。
• 自建 OData 服务（Z_TABLE_SRV/Z_EXEC_SRV）属高权限接口，必须收敛账号权限并仅限内网；详见 references/ 手册的「安全须知」。