内容
# SAP ADT / RFC MCP 工具
这是一个面向 SAP ABAP 场景的 MCP 工具，提供一个统一入口，通过同一套 Java 服务支持两种后端模式：
- ADT 模式：通过 HTTP 访问 SAP ADT，适合源码浏览、对象搜索、同步、学习与回滚
- RFC 模式：通过 Java + SAP JCo 直连 SAP，适合 RFC 调用、表读取和系统信息查询
当前版本是 `0.0.2`，版权归属为吴德涵、汪晓丰、汪刚。
本项目采用 `Apache License 2.0`，许可证全文见 [`LICENSE`](LICENSE)。
## 源码和产物
这个仓库最好分成两层来看：
- 源码：`src/`、`pom.xml`、`scripts/`
- 初始化产物：`sap-abap-mcp-init/`
如果你只是想拿到一套可直接分发的初始化包，就直接下载或打包 `sap-abap-mcp-init/`。
如果你要改实现、调试工具或重新编译，就看仓库根目录的源码。
`sap-abap-mcp-init/` 已经整理成面向交付的目录。它保存说明书、脚本、示例和版权信息；目标目录才是运行时产物，初始化后会生成 `.mcp.json` 和 `sap-abap-mcp-lib/`，并预创建 `SAP_EXPORT_DIR`、`SAP_STATE_DIR`。
默认模式是 `adt`。如果你在 `.mcp.json` 里切换到 `rfc`，服务就会改走 RFC 连接。
如果你主要关心“源码同步”，这版 Java 工具已经支持：
- 按对象读取源码
- 自动探测 scope 并同步源码到本地目录
- 按对象类型直接同步源码
- package 级同步 / 仓库级同步
- DDIC / where-used / 版本探测
## 一句话快速开始
先把 `sap-abap-mcp-init/` 当作初始化包下载到本机，然后选一个你真正想运行 MCP 的目标目录执行初始化脚本。脚本会在目标目录里生成可直接使用的 `.mcp.json` 和 `sap-abap-mcp-lib/`，并预创建 `SAP_EXPORT_DIR`、`SAP_STATE_DIR`。
如果你已经有一个目标目录，比如 `~/workspaces/test-abap`，它最终会读取：
- `~/workspaces/test-abap/.mcp.json`
你只需要修改其中的环境变量，然后在那个目标目录里启动 Claude Code 或其他 MCP Host 即可。
## 配置总览
这套 MCP 的配置可以分成三层理解：
1. 公共信息：系统、用户、客户端、语言
2. 模式信息：当前走 ADT 还是 RFC
3. 模式附加信息：ADT 的 base URL / SSL，或者 RFC 的 JCo 本机库
### 公共参数
- `SAP_SYSTEM_ID`：系统标识，例如 `HRD`
- `SAP_HOST`：SAP 主机地址
- `SAP_PORT`：端口；如果你已经配置了完整的 `SAP_BASE_URL`，这个参数可以不配
- `SAP_SYSNR`：系统号，RFC 常用
- `SAP_CLIENT`：客户端号
- `SAP_USER`：用户名
- `SAP_PASSWORD`：密码
- `SAP_LANG`：登录语言，例如 `ZH`
- `SAP_EXPORT_DIR`：源码同步输出目录，默认 `sap/sap-code-repository/gm`
- `SAP_STATE_DIR`：本地学习 / 快照 / 回滚状态目录，默认 `.sap-mcp-state`
### ADT 专用参数
- `SAP_MCP_MODE=adt`
- `SAP_BASE_URL`：ADT 基础地址，例如 `https://10.249.22.11:44300`
- `SAP_AUTH_MODE`：认证方式，`basic` 或 `bearer`
- `SAP_VERIFY_SSL`：是否校验证书，`true` 或 `false`
### RFC 专用参数
- `SAP_MCP_MODE=rfc`
- `SAP_JCO_LIBRARY_DIR`：`sapjco3.jar` 和本机库所在目录
如果你在 macOS 上使用 RFC 模式，通常还需要在启动参数里显式加入：
```text
-Djava.library.path=/path/to/jco/lib
```
这样 Java 才能同时找到 `sapjco3.jar` 和本机动态库。
## 两种模式怎么理解
### ADT 模式
ADT 模式通过 HTTP 访问 SAP ADT。它更像是“围绕 `/sap/bc/adt/` 这条入口做对象级操作”。
适合做这些事情：
- 搜索 ABAP 对象
- 读取类、程序、接口、表、结构的源码或元数据
- 同步 package、函数组或单个对象
- 记录学习卡片和本地快照
如果你第一次使用 ADT，推荐的理解顺序是：
1. 先用 `sap_ping` 确认 `/sap/bc/adt/` 是否可达
2. 再用 `sap_get_system_info` 确认系统信息和认证状态
3. 然后再开始对象搜索和源码同步
这个顺序的好处是很直观：先看路通不通，再看门能不能进，最后再进屋取资料。
### RFC 模式
RFC 模式现在是 Java 实现，底层通过 SAP JCo 直接连接 SAP。
适合做这些事情：
- 调用 RFC 函数
- 读取 SAP 表
- 查询系统信息
- 读取一些常用业务对象的抽象查询结果
如果你第一次使用 RFC，推荐的理解顺序是：
1. 先用 `sap_system_info` 看当前连的是不是目标系统
2. 再用 `sap_call_rfc` 调一个基础函数，确认通道可用
3. 然后再用 `sap_read_table` 或封装好的业务查询工具
RFC 模式不使用 `sap_ping`；`sap_ping` 是 ADT 模式的工具。
### RFC 需要的额外依赖
RFC 模式需要 SAP JCo：
- `sapjco3.jar`
- `libsapjco3.dylib` / `libsapjco3.so` / `sapjco3.dll`
建议做法是把这些文件放到你的本机 `lib/` 目录里。
然后在 `.mcp.json` 里配置 `SAP_JCO_LIBRARY_DIR`。
## `.mcp.json` 示例
本地配置文件位置：
- `~/workspaces/test-abap/.mcp.json`
### RFC 模式示例
```json
{
"mcpServers": {
"sap-abap-mcp": {
"type": "stdio",
"command": "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home/bin/java",
"args": [
"-Djava.library.path=/absolute/path/to/mcp-abap-tools/lib",
"-jar",
"/absolute/path/to/mcp-abap-tools/target/abap-adt-mcp-<version>.jar",
"--transport=stdio"
],
"env": {
"SAP_MCP_MODE": "rfc",
"SAP_SYSTEM_ID": "HRD",
"SAP_HOST": "10.249.22.11",
"SAP_SYSNR": "00",
"SAP_CLIENT": "200",
"SAP_USER": "YOUR_USER",
"SAP_PASSWORD": "YOUR_PASSWORD",
"SAP_LANG": "ZH",
"SAP_JCO_LIBRARY_DIR": "/absolute/path/to/mcp-abap-tools/lib"
}
}
}
}
```
### ADT 模式示例
```json
{
"mcpServers": {
"sap-abap-mcp": {
"type": "stdio",
"command": "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home/bin/java",
"args": [
"-jar",
"/absolute/path/to/mcp-abap-tools/target/abap-adt-mcp-<version>.jar",
"--transport=stdio"
],
"env": {
"SAP_MCP_MODE": "adt",
"SAP_BASE_URL": "https://10.249.22.11:44300",
"SAP_AUTH_MODE": "basic",
"SAP_CLIENT": "100",
"SAP_USER": "YOUR_USER",
"SAP_PASSWORD": "YOUR_PASSWORD",
"SAP_VERIFY_SSL": "false",
"SAP_EXPORT_DIR": "sap/sap-code-repository/gm",
"SAP_STATE_DIR": ".sap-mcp-state"
}
}
}
}
```
## 运行与构建
### 构建
```bash
mvn test
mvn -DskipTests package
```
现在不需要额外准备旧的 RFC 代理环境了，RFC 已经完全切换到 Java + SAP JCo。
### 运行
```bash
JAVA17_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home \
"$JAVA17_HOME/bin/java" -jar target/abap-adt-mcp-<version>.jar --transport=stdio
```
这个服务是给 MCP Host 使用的，适用于 Claude Code、Codex、Cursor 等客户端。
注意：它需要由 MCP Host 以 stdio 方式启动，直接在终端里手动运行，stdin 关闭时会失败。
## 工具说明
### RFC 模式工具
- `sap_system_info`：查看系统信息、连通性和登录环境
- `sap_call_rfc`：调用任意 RFC 函数
- `sap_read_table`：读取 SAP 表
- `sap_switch_system`：切换默认系统
- `sap_get_cost_center`
- `sap_get_profit_center`
- `sap_get_employee`
- `sap_get_org_units`
### RFC 上手路径
RFC 模式的核心思路是“先确认连的是哪套系统，再逐步扩大查询范围”。
先用 `sap_system_info` 看当前连的是不是目标系统；如果你配置了多个 RFC 系统，再用 `sap_switch_system` 切换目标。等连接稳定后，先跑一个基础 RFC，再去读表和业务对象，这样排查问题会更快。
### ADT 模式工具
- `sap_ping`：检查 ADT 根路径连通性
- `sap_get_system_info`：获取系统信息
- `sap_search_objects`：搜索 ABAP 对象
- `sap_get_source`：读取源代码
- `sap_get_class_source`：按 class 读取源码
- `sap_get_program_source`：按 program 读取源码
- `sap_get_metadata`：读取对象元数据
- `sap_get_package_objects`：列出 package 中的对象
- `sap_get_ddic_object`：解析 DDIC 对象
- `sap_where_used`：查询对象被引用位置
- `sap_resolve_scope`：先探测一个名字会被识别成什么对象
- `sap_get_sap_version`：读取 SAP 版本信息
- `sap_check_source`：做一个轻量级源码检查
- `sap_sync_scope`：自动探测对象类型并同步源码到本地目录（含函数组）
- `sap_sync_function_group`：显式同步函数组
- `sap_sync_object`：按指定对象类型同步源码到本地目录
- `sap_sync_package`：同步一个 package 的对象
- `sap_sync_repository`：同步 package 前缀匹配的仓库对象
- `sap_sync_status`：查看本地同步状态
- `sap_sync_recent_changes`：查看最近同步变更
- `sap_learn_from_object`：读取单个 ABAP 对象并沉淀为本地学习卡片
- `sap_learn_status`：查看本地学习统计
- `sap_learn_recent_discoveries`：查看最近的学习发现
- `sap_skill_learn_insight`：手工写入一条可复用的知识卡片，并自动创建快照
- `sap_skill_create_snapshot`：为学习 / 同步状态创建快照
- `sap_skill_list_snapshots`：列出快照
- `sap_skill_changelog`：查看本地变更记录
- `sap_skill_rollback`：按快照回滚本地学习或同步状态
- `sap_preview_update`：预览源码更新并生成确认令牌
- `sap_update_and_activate`：应用已确认的更新并激活对象
### ADT 上手路径
如果你第一次用 ADT，可以按这个顺序理解：
1. `sap_ping`
2. `sap_get_system_info`
3. `sap_search_objects` / `sap_get_source`
4. `sap_sync_scope` / `sap_sync_package`
这个顺序的目标不是“多做几步”，而是把排错和使用分开：先确认系统可达，再确认认证和对象入口，最后再做同步和学习。
## 初始化包
如果你希望把基础资源初始化到一个新的目标目录，可以直接使用：
- `sap-abap-mcp-init/`
这个目录里包含：
- 功能说明书 Markdown / HTML 版本
- ADT / RFC 的 `.mcp.json` 示例
- 版本信息和版权信息
- 初始化脚本和 skill 说明
- 仓库内的 `sap-abap-mcp-init/` 保存说明书、skill、许可证、示例配置
- 目标目录会生成 `.mcp.json` 和 `sap-abap-mcp-lib/`，并预创建 `SAP_EXPORT_DIR`、`SAP_STATE_DIR`
- `sap-abap-mcp-lib/` 只放运行库、JCo 和模式记录
- 生成到目标目录时支持 `--mode adt|rfc` 切换
### 学习与回滚说明
这版 Java MCP 已经不只是“读 SAP 源码”，还会把本地形成的知识沉淀下来：
- `sap_learn_from_object`：适合从某个类、程序、接口或函数组里提炼模式
- `sap_skill_learn_insight`：适合人工整理经验、规范、反模式、示例片段
- `sap_skill_create_snapshot`：在大改前手工留一个回滚点
- `sap_skill_rollback`：当学习内容污染了，或者想恢复同步前状态时使用
默认情况下，这些内容会写到 `SAP_STATE_DIR`，所以你可以把它当成本地“可回滚知识仓库”。
## 常见问题
### 1）ADT 可达，但返回 401
这通常说明：
- 服务器在线，`/sap/bc/adt/` 也能访问
- 但认证失败，或者当前用户没有 ADT 权限
优先检查：
- 用户名 / 密码是否正确
- `SAP_CLIENT` 是否正确
- 用户是否具备 ADT 访问权限
- 是否需要在 `SU01` 中检查用户状态、锁定状态、密码过期状态
如果响应里已经明确出现 `sap-client=100`，那就优先把 `SAP_CLIENT` 设成 `100`，不要再用别的客户端号去猜。
### 2）为什么 `sap_sync_package` 对 `ZDTDHR_SHARE` 会 404
这说明当前系统没有把 `ZDTDHR_SHARE` 暴露成可访问的 ADT package 入口。
在这种情况下，请优先使用：
- `sap_sync_scope(name="ZDTDHR_SHARE")`
它会按函数组去探测并下载 include / function module，已经可以正常工作。
### 3）RFC 模式下应该用哪个工具检查连接
请使用：
- `sap_system_info`
不要用 `sap_ping`。`sap_ping` 只属于 ADT 模式。
