ABAP-ADT-API MCP-Server

ABAP ADT API MCP 服务

此服务保留了 127 个现有 SAP ABAP 工具，并新增了 readResultPage，用于处理大型结果。对象 CRUD、锁定、激活、传输、查询、调试、重构、Git 和分析共用一个 SAP 会话，该会话由可信的本地 stdio 客户端持有。SAP 授权决定该会话可以读取或更改哪些内容。

安装和协议

使用 Node22.22.2+ 或24.15.0+。运行 npm ci 和 npm run build，然后将 MCP 客户端配置为使用 dist/index.js 的绝对路径启动 node。现有 npm/registry 版本在所有者发布此 PR 之前不包含此 PR。此处不会发布任何版本。

{
  "mcpServers": {
    "abap-adt": {
      "command": "node",
      "args": ["/absolute/path/mcp-abap-abap-adt-api/dist/index.js"],
      "env": {
        "SAP_URL": "https://sap.example.invalid:44300",
        "SAP_USER": "YOUR_USER",
        "SAP_PASSWORD": "YOUR_PASSWORD",
        "SAP_CLIENT": "100",
        "SAP_LANGUAGE": "EN"
      }
    }
  }
}

公开的 TypeScript MCP2.0.0 支持现代2026-07-28 发现流程和旧版2025-11-25 初始化流程、经过验证的工具、取消操作和正确的错误处理。此软件包提供 stdio；它不是 HTTP 监听器，也不是 MCP OAuth 提供方。即使缺少凭据，仍可进行发现。healthcheck 报告本地配置和会话恢复状态，而非已验证的 SAP 连接状态。

环境变量来自 MCP 客户端。只有在 SAP_ENV_FILE 明确指定文件时，dotenv 才会加载该文件。SAP_URL 是不带路径、查询参数或内嵌凭据的源站。对于私有 CA，请在启动 Node 前设置 NODE_EXTRA_CA_CERTS。无法禁用 TLS 验证。允许在回环地址上使用 HTTP 进行测试；可信的私有 HTTP 部署要求设置 SAP_ALLOW_HTTP=1，并会将凭据暴露给该网络。

经授权的代理可以使用静态 SAP_BEARER_TOKEN 替代密码。重启进程即可轮换该令牌；这不会实现 XSUAA 授权，也不能证明租户已接受该令牌。此处不会引入密码授权流程。

会话与限制

一次只能运行一个操作；重叠操作会收到忙碌错误。调试器监听器也会占用此会话，直到完成或取消。SAP_REQUEST_TIMEOUT_MS 默认值为 60000，接受 100..120000，适用于登录和每个底层 HTTP 请求。取消操作会关闭真实套接字。客户端不会跟随重定向、继承环境代理、重试变更操作，也不会自动重新验证有状态调用。中断的写入可能已经更改 SAP：检查写入和锁，然后显式调用 login、dropSession 或 logout 进行恢复。关闭时会尝试有界登出；如果无法访问 SAP，状态可能会保留，直到 SAP 自行过期。

HTTP 请求始终位于配置的源下的 /sap/ 路径，限制为 2MiB 请求、4MiB 响应，并验证 TLS。拒绝 XML 实体声明。输入 JSON 按字节数、嵌套层级、数组和字段契约进行限制。这是面向可信操作员的工具，不是 OS 沙箱或多用户服务。Git 工具可以要求 SAP 使用提供的凭据联系远程 Git 服务；这些操作取决于 SAP 和远程服务的权限。

架构根据固定版本的 abap-adt-api 8.4.3 声明生成，包括对象、数组和重载。此前文档中用于对象参数的 JSON 字符串仍可接受，并会解析和验证。拒绝未知的顶层参数。scripts/generate-input-contracts.mjs 及其报告记录了映射；更新依赖项后应重新运行并审查。其 TypeScript 6 编译器 API 仅用于开发；应用由 TypeScript 7 构建。

getObjectSource/成功的 setObjectSource 生成的源代码快照，在省略 code 时可供 syntaxCheckCode 使用（issue#2）。每个运行时的缓存限制为 8MiB、64 个条目，保留五分钟。变更/会话操作会清除旧快照。快照是最近观测到的文本，并不保证期间没有外部编辑。由于上游拒绝空字符串，显式的空文本会作为等效的空白行进行检查；结果会报告 emptySourceNormalized。源代码选项接受结构化对象或 JSON 对象，包括活动/非活动版本。现有的行分页仍然可用。类包含项会先获取类元数据；公共请求适配器会处理有效但被上游解析器拒绝的单链接类 XML。映射会在 JSON 中保留其条目。

超过 64KiB 时，结果会返回不透明的 resultId、一个 JSON 页面、nextOffset 和过期时间。使用 readResultPage、拼接各页并进行 JSON 解析，即可还原原始工具结果。分页不会重复 SAP 请求或写入。最多缓存四个 4MiB 结果，保留五分钟；变更/会话重置会清除这些结果。结果过期后，需要有意重新执行原始读取操作。超大结果会明确报错。查询/搜索/ATC 的默认值为 100；在支持的情况下，上限为 1000；API 可能会返回额外的哨兵行。其他大型结构使用通用分页。

验证与部署验收

npm run build
npm test
npm run verify:stdio
npm run verify:package
npm audit
docker build -t mcp-abap-api .
node scripts/verify-stdio.mjs --offline docker run --rm -i --network none mcp-abap-api

测试使用真实的本地 HTTP/XML 夹具，以及已安装的现代/旧版协议交互。CI 在 Linux/Windows Node 22/24 和非 root Docker 环境中运行。不会使用 SAP 生产凭据，也不会进行写入。对于获准的只读部署金丝雀测试，请设置 SAP_LIVE_TEST=1 和可选的 SAP_LIVE_SOURCE_URL，然后运行 npm run verify:live。此测试会检查登录/发现/可选的源代码读取，不会测试所有 SAP 写入/调试/Git/传输功能。请在开发系统上验证这些功能。权限、凭据、API 可用性以及截至 2026 年底的支持情况，仍需在部署时检查。

现有 PR19/20/21/22 涉及重叠错误、结果大小、类包含项和登录；这些 PR 均保持开放，等待负责人审查。PR15 提议的状态恢复和重构 JSON 工作已存在于起始分支上。PR10 提议的 XSUAA 实现尚未合并到此处。

参考资料：abap-adt-api、MCP2026-07-28、Node 私有 CA 配置。

现有工具工作流参考

以下是原有工作流示例。上述运行时、架构和安装行为优先于旧版客户端专属示例。

自定义指令

使用此自定义指令向你的模型说明该工具：

## mcp-abap-abap-adt-api Server

This server provides tools for interacting with an SAP system via ADT (ABAP Development Tools) APIs. It allows you to retrieve information about ABAP objects, modify source code, and manage transports.

**Key Tools and Usage:**

*   **`searchObject`:** Finds ABAP objects based on a query string (e.g., class name).
    *   `query`: (string, required) The search term.
    *   Returns the object's URI.  Example: `/sap/bc/adt/oo/classes/zcl_invoice_xml_gen_model`

*   **`transportInfo`:** Retrieves transport information for a given object.
    *   `objSourceUrl`: (string, required) The object's URI (obtained from `searchObject`).
    *   Returns transport details, including the transport request number (`TRKORR` or `transportInfo.LOCKS.HEADER.TRKORR` in the JSON response).

*   **`lock`:** Locks an ABAP object for editing.
    *   `objectUrl`: (string, required) The object's URI.
    *   Returns a `lockHandle`, which is required for subsequent modifications.

*   **`unLock`:** Unlocks a previously locked ABAP object.
    *   `objectUrl`: (string, required) The object's URI.
    *   `lockHandle`: (string, required) The lock handle obtained from the `lock` operation.

*   **`setObjectSource`:** Modifies the source code of an ABAP object.
    *   `objectSourceUrl`: (string, required) The object's URI *with the suffix `/source/main`*.  Example: `/sap/bc/adt/oo/classes/zcl_invoice_xml_gen_model/source/main`
    *   `lockHandle`: (string, required) The lock handle obtained from the `lock` operation.
    *   `source`: (string, required) The complete, modified ABAP source code.
    *   `transport`: (string, optional) The transport request number.

*   **`syntaxCheckCode`:** Performs a syntax check on a given ABAP source code.
    *   `code`: (string, required) The ABAP source code to check.
    *   `url`: (string, optional) The URL of the object.
    *   `mainUrl`: (string, optional) The main URL.
    *   `mainProgram`: (string, optional) The main program.
    *   `version`: (string, optional) The version.
    *   Returns syntax check results, including any errors.

*   **`activate`:** Activates an ABAP object. (See notes below on activation/unlocking.)
    *    `object`: The object to be activated.

*   **`getObjectSource`:** Retrieves the source code of an ABAP object.
    *   `objectSourceUrl`: (string, required) The object's URI *with the suffix `/source/main`*.

**Workflow for Modifying ABAP Code:**

1.  **Find the object URI:** Use `searchObject`.
2.  **Read the original source code:** Use `getObjectSource` (with the `/source/main` suffix).
3.  **Clone and Modify the source code locally:** (e.g., `write_to_file` for creating a local copy, and using `read_file`, `replace_in_file` for modifying this local copy).
4.  **Get transport information:** Use `transportInfo`.
5.  **Lock the object:** Use `lock`.
6.  **Set the modified source code:** Use `setObjectSource` (with the `/source/main` suffix).
7.  **Perform a syntax check:** Use `syntaxCheckCode`.
8.  **Activate** the object, Use `activate`..
9.  **unLock the object:** Use `unLock`.

**Important Notes:**
*   **File Handling:** SAP is completly de-coupled from the local file system. Reading source code will only return the code as tool result - it has no effect on file. Files are not synchronized with SAP but merely a local copy for our reference. FYI: It's not strictly necessary for you to create local copies of source codes, as they have no effect on SAP, but it helps us track changes.
*   **File Handling:** The local filenames you will use will not contain any paths, but only a filename! It's preferable to use a pattern like "[ObjectName].[ObjectType].abap". (e.g., SAPMV45A.prog.abap for a ABAP Program SAPMV45A, CL_IXML.clas.abap for a Class CL_IXML)
*   **URL Suffix:**  Remember to add `/source/main` to the object URI when using `setObjectSource` and `getObjectSource`.
*   **Transport Request:** Obtain the transport request number (e.g., from `transportInfo` or from the user) and include it in relevant operations.
*   **Lock Handle:**  The `lockHandle` obtained from the `lock` operation is crucial for `setObjectSource` and `unLock`. Ensure you are using a valid `lockHandle`. If a lock fails, you may need to re-acquire the lock. Locks can expire or be released by other users.
*   **Activation/Unlocking Order:** The exact order of `activate` and `unLock` operations might need clarification. Refer to the tool descriptions or ask the user. It appears `activate` can be used without unlocking first.
* **Error Handling:** The tools return JSON responses. Check for error messages within these responses.

## Efficient Database Access

SAP systems contain vast amounts of data.  It's crucial to write ABAP code that accesses the database efficiently to minimize performance impact and network traffic.  Avoid selecting entire tables or using broad `WHERE` clauses when you only need specific data.

*   **Use `WHERE` clauses:** Always use `WHERE` clauses in your `SELECT` statements to filter the data retrieved from the database.  Select only the specific rows you need.
*   **`UP TO 1 ROWS`:** If you only need a single record, use the `SELECT SINGLE` statement, if you can guarantee that you can provide ALL the key fields for the `SELECT SINGLE` statement. Otherwise, use the `SELECT` statement with the `UP TO 1 ROWS` addition. This tells the database to stop searching after finding the first matching record, improving performance. Example:

    ```abap
    SELECT vgbel FROM vbrp WHERE vbeln = @me->lv_vbeln INTO @DATA(lv_vgbel) UP TO 1 ROWS.
      EXIT. " Exit any loop after this.
    ENDSELECT.
    ```
## Checking Table and Structure Definitions

When working with ABAP objects, you may encounter errors related to unknown field names or incorrect table usage. Use the following tools to inspect DDIC (Data Dictionary) objects:

*   **`objectStructure`:** Retrieves the structure/metadata of an ABAP object (including DDIC tables and structures) from its object URI. Use `searchObject` first to resolve the object name to a URI.
*   **`ddicElement`:** Retrieves details of a DDIC element (e.g. a data element or domain).
*   **`ddicRepositoryAccess`:** Reads DDIC repository information for a given path.
*   **`tableContents`:** Retrieves the *contents* (rows) of a table, not its definition. Use `runQuery` for ad-hoc `SELECT`s.

故障排除

• **npx 找不到软件包 / 客户端无法启动该工具：**确保已安装 Node.js，且其位于 PATH 中（node -v、npm -v）。在 Windows 上，尝试使用 "command": "npx.cmd"，或使用带有 node dist/index.js 绝对路径的源码构建。
• **SAP 连接错误：**验证你的凭据（SAP_URL、SAP_USER、SAP_PASSWORD、SAP_CLIENT），确认系统可访问、你的用户拥有 ADT 授权，并且 /sap/bc/adt 已在 SICF 中启用。
• **TLS / 自签名证书错误：**在 Node 启动前，将 NODE_EXTRA_CA_CERTS 配置为可信 CA 证书的绝对路径。证书验证始终保持启用。

贡献

欢迎贡献！请按照以下步骤进行贡献：

1. Fork 仓库

2. 创建新分支

   git checkout -b feature/your-feature-name
   

3. 提交更改

   git commit -m "Add some feature"
   

4. 推送到分支

   git push origin feature/your-feature-name
   

5. 创建 Pull Request

许可证

本项目采用 MIT 许可证 许可。