S.A.M.U.R.A.I.：用MCP协议连接AI助手与SAP ABAP开发

1. 项目概述：当AI助手遇见SAP ABAP开发

如果你是一名SAP ABAP开发者，那么对SE80、SE38这些事务码的界面一定再熟悉不过了。几十年来，我们习惯了在这些“经典”的界面中穿梭，通过复制粘贴、手动激活、反复检查来完成开发工作。这种工作流虽然稳定，但在追求效率的今天，总让人觉得与现代开发工具之间隔着一道鸿沟。想象一下，你正在用VS Code或者Cursor编写其他语言的代码，享受着智能补全、代码导航和AI辅助编程的便利，但一转头，面对SAP GUI里的ABAP编辑器，又得切换回那个“古老”的思维模式。这种割裂感，正是S.A.M.U.R.A.I.项目想要解决的问题。

S.A.M.U.R.A.I.，全称SAP ADT MCP Unified Remote ABAP Interface，是一个开源项目。它的核心使命，是为你钟爱的AI编程助手（比如Antigravity、Cursor、Kiro、Claude Desktop等）装上一把锋利的“武士刀”，让它们能够通过标准的ADT REST API，直接、安全地与你的SAP系统对话。这意味着，你可以在自己熟悉的现代IDE里，用自然语言告诉AI：“帮我搜索所有以ZCL_SD开头的类”、“读取ZCL_MM_PO_VALIDATOR的源代码并检查语法”、“在ZFI_PAYMENTS包下创建一个新的支付处理类，并分配到传输请求DEVK900456上”。AI助手会理解你的意图，并通过S.A.M.U.R.A.I.这个“桥梁”，在后台替你执行这些操作，然后将结果清晰地呈现在你面前。

这个项目不是某个SAP厂商的闭源工具，而是一个完全开源、基于Node.js的MCP服务器。MCP，即模型上下文协议，正逐渐成为AI助手与外部工具和资源交互的事实标准。S.A.M.U.R.A.I.实现了这个协议，将SAP ADT丰富的API封装成了30个清晰的工具和2个实用的提示模板。无论你连接的是S/4HANA、ECC、BW还是其他任何启用了ADT的SAP系统（本地或云端），它都能工作。更重要的是，它没有供应商锁定，配置完全由你掌控。对于任何希望将现代AI驱动的开发体验引入传统SAP ABAP领域的开发者、顾问或团队负责人来说，这都是一件值得深入研究的利器。

1.1 核心价值：不止于效率的提升

初看之下，你可能会认为这只是一个提升编码效率的工具——确实，它能极大提升效率。但它的价值远不止于此。我认为其核心价值体现在三个层面：

第一层是开发流程的现代化与无缝集成。它打破了SAP开发必须依赖特定GUI或Eclipse ADT插件的束缚。你现在可以将ABAP开发工作流嵌入到你已有的、高度定制化的现代开发环境中。你的代码库、版本控制、终端、以及各种生产力工具，现在都能与SAP开发任务同处一个上下文。这减少了频繁切换工具带来的认知负担和上下文丢失。

第二层是知识获取与探索方式的变革。传统的ABAP开发中，了解一个系统里有什么、对象之间如何关联，往往需要运行SE80、SE11、SE16N等多个事务码，并依赖个人经验。现在，你可以直接问你的AI助手：“这个包（ZMM_PURCHASING）里都有什么对象？”、“接口ZIF_SD_PRICING_ENGINE都在哪里被使用了？”、“给我看看表EKPO的结构”。AI能通过S.A.M.U.R.A.I.瞬间获取这些信息，并以结构化的方式呈现给你。这对于新接手一个复杂系统，或者进行大规模代码审计时，尤其有用。

第三层，也是最具潜力的一层，是赋能AI进行复杂的、上下文感知的ABAP开发任务。单纯的代码补全AI和能够操作真实SAP系统的AI，能力是天壤之别。S.A.M.U.R.A.I.提供的工具覆盖了完整的开发生命周期：搜索、读取、写入、创建、激活、测试、传输。这意味着AI助手可以基于对系统现有代码的实时分析，为你生成更准确、更符合项目规范的代码。更进一步，你可以通过“创建RAP业务对象”这样的提示模板，让AI基于简单的参数，为你搭建一整套符合SAP最佳实践的RAP架构代码骨架。这相当于将资深ABAP架构师的经验和模式，固化成了可重复执行的自动化流程。

注意：尽管这个工具能力强大，但它本质上是一个“执行器”，其行为完全取决于驱动它的AI助手以及你给出的指令。因此，建立清晰的安全边界和操作规范至关重要，我们会在后续的“安全与实操规范”章节详细讨论。

2. 环境准备与快速上手

在开始体验“武士刀”的锋利之前，我们需要先把它锻造并握在手中。整个部署和配置过程清晰直接，但其中有一些细节和选择，将直接影响后续使用的稳定性和便捷性。

2.1 前置条件检查：你的“道场”是否就绪

首先，确保你的本地环境和SAP系统满足基本要求。这就像武士出征前检查兵甲和马匹。

本地环境：

• Node.js 18或更高版本：这是运行S.A.M.U.R.A.I.服务器的基石。你可以通过终端命令node --version来确认。如果未安装，建议从Node.js官网下载LTS版本。我个人偏好使用nvm（Node Version Manager）来管理多个Node版本，这在同时处理多个不同年代的项目时非常方便。
• 一个你常用的、支持MCP的AI编程助手：这是你的“大脑”。项目支持几乎所有主流选择：Antigravity、Cursor、Kiro、Claude Desktop、Windsurf、Cline等。你需要确保其中至少一个已安装并正常运行。

SAP系统环境（关键！）：

• ADT服务必须激活：这是整个工具链能工作的前提。ADT（ABAP Development Tools）的REST API是S.A.M.U.R.A.I.与SAP通信的唯一渠道。你需要联系BASIS管理员或自行检查事务码SICF。
  1. 在SAP GUI中运行事务码SICF。
  2. 在树形结构中导航到default_host/sap/bc/adt。
  3. 确保该节点及其下所有相关服务（如discovery,repository,oo,ddic等）的“状态”为“已激活”（通常显示一个绿色的勾）。如果未激活，选中节点后点击工具栏的“激活”按钮（或按F5）。
  4. 一个快速的验证方法是，在浏览器中尝试访问http(s)://<你的SAP服务器>:<端口>/sap/bc/adt/discovery。如果看到要求输入SAP用户名密码的认证框，之后返回一个XML文档，则说明服务基本正常。
• 具备开发权限的SAP用户：你使用的SAP账号必须拥有S_DEVELOP权限对象。通常，开发账号都会分配这个权限。如果遇到403错误，多半是权限问题，需要检查SU01中的角色分配。

2.2 获取与构建：打造你的专属服务器

项目的源代码托管在GitHub上。获取和构建过程非常标准。

# 1. 克隆仓库到本地 git clone https://github.com/AlleyBo55/SAMURAI.git cd SAMURAI # 2. 安装依赖 npm install # 3. 构建项目（将TypeScript编译为JavaScript） npm run build

构建完成后，核心的可执行文件位于dist/index.js。这个文件就是你将要配置到各个AI客户端中的“服务器入口”。这里有一个实操心得：我建议在完成构建后，先不要急着配置客户端，而是用Node直接测试一下这个服务器是否能正常启动，这可以排除一些基础的路径或环境问题。

# 在项目根目录下尝试运行服务器，它会输出帮助信息然后退出 node dist/index.js

如果看到类似“Usage: ... ”或MCP服务器初始化相关的日志（没有报错），说明构建产物是正常的。如果遇到关于@modelcontextprotocol/sdk未找到的错误，请回到项目根目录重新执行npm install。

2.3 客户端配置详解：连接你的“大脑”与“武士刀”

这是最关键的一步，不同的AI客户端配置方式略有不同，但核心逻辑一致：告诉你的AI客户端，有一个外部的MCP服务器可以调用，以及如何启动这个服务器（命令、参数、环境变量）。

核心配置项解析：无论你用哪个客户端，配置都围绕以下几个核心部分展开：

• command: 启动服务器的命令，这里是node。
• args: 传递给命令的参数，即编译后的dist/index.js文件的绝对路径。使用绝对路径可以避免因工作目录变化导致的“找不到文件”错误。
• env: 环境变量对象，用于传递SAP连接参数。这是安全关键点，切勿将密码等敏感信息提交到版本控制系统。

环境变量有两种模式：

• 模式一（直接URL，推荐）：最简单直观，直接指定完整的SAP系统地址。

  "env": { "SAP_HOST": "http://your-sap-server.example.com:8000", "SAP_CLIENT": "100", "SAP_USERNAME": "YOUR_USER", "SAP_PASSWORD": "YOUR_PASSWORD", "SAP_LANGUAGE": "EN" }

• 模式二（Eclipse风格）：模拟Eclipse ADT的连接方式，分别指定应用服务器和实例号。

  "env": { "SAP_ASHOST": "your-sap-server.example.com", "SAP_SYSNR": "00", "SAP_SSL": "false", // 如果是HTTP "SAP_SID": "DEV", "SAP_CLIENT": "100", "SAP_USERNAME": "YOUR_USER", "SAP_PASSWORD": "YOUR_PASSWORD" }

  在这种模式下，工具会自动根据SAP_SSL和SAP_SYSNR构建URL（例如，HTTP + 实例00 -> 端口8000；HTTPS + 实例01 -> 端口44301）。

重要安全提示：包含密码的配置文件（如mcp.json）必须被加入.gitignore文件，防止意外提交。项目通常提供了一个示例文件（如mcp.example.json），你应复制该文件并填写自己的敏感信息。

下面，我们针对几个主流客户端，看看具体的配置位置和细微差别。

Antigravity (Google):Antigravity对MCP的支持非常原生和友好。推荐通过UI进行配置：

1. 在IDE中打开Agent/Chat面板。
2. 点击右上角的三个点菜单 (...)。
3. 选择MCP Servers->Manage MCP Servers。
4. 点击View raw config按钮，这会打开mcp_config.json文件。
5. 在mcpServers对象中添加sap-adt的配置块。
6. 保存文件，回到管理界面点击“刷新”或重启Antigravity，服务器状态应显示为“Enabled”。

Kiro:Kiro的配置是项目级的，放在.kiro/settings/mcp.json。它的一个特色是支持autoApprove列表。你可以将只读工具（如搜索、读取）加入此列表，这样AI调用这些工具时无需每次征得你同意，可以流畅地进行信息探索。而所有写入类操作（创建、修改、激活、传输）则被排除在外，每次都需要你明确批准，这是一个非常好的安全实践。

Cursor:Cursor的配置同样在项目根目录的.cursor/mcp.json。特别注意：Cursor要求args中的路径必须是绝对路径。在Mac/Linux上，你可以使用pwd命令获取当前绝对路径；在Windows上，可以使用%cd%。相对路径会导致服务器无法启动。

Claude Desktop:配置位于用户应用数据目录下的JSON文件中。配置完成后，需要完全重启Claude Desktop应用才能使更改生效。这一点经常被忽略，导致配置后工具不出现。

Windsurf & Cline:两者配置方式类似，都是找到对应的配置文件（Windsurf在Cascade面板配置，Cline有专门的MCP Servers图标），将服务器配置添加进去。Windsurf还需要在设置中确保“Cascade”功能下的MCP是启用状态。

配置后的验证：配置并重启你的AI客户端后，最简单的验证方法是直接向AI助手提问：“测试一下SAP连接”或“Test the SAP connection”。如果一切正常，AI会调用test_connection工具，并返回类似“连接成功，主机：xxx，客户端：100”的信息。如果失败，请根据错误信息检查网络连通性、SAP服务状态、用户名密码及权限。

3. 核心工具解析与实战应用

S.A.M.U.R.A.I.提供了30个工具，覆盖了ABAP开发的方方面面。理解这些工具的能力边界和最佳使用场景，能让你和AI的协作事半功倍。我们可以将这些工具分为几个功能模块来理解。

3.1 探索与发现：让AI成为你的系统导航员

在大型SAP系统中，快速定位和理解代码是首要挑战。这组工具赋予了AI强大的探索能力。

• search_objects: 这是你的“全局搜索”。你可以使用通配符（*）进行模式匹配，例如query: “ZCL_SD*”来查找所有自定义的SD相关类。你还可以通过objectType参数过滤类型（如CLAS/OC表示类）。这个工具返回的是对象的ADT URI，这是后续所有操作（读取、写入）的钥匙。
• list_package_contents: 包是SAP中组织开发对象的基本单元。这个工具可以列出一个包（如ZMM_PURCHASING）下的所有对象，让你快速了解一个功能模块的代码结构。
• where_used: 影响分析神器。给定一个对象的URI，它能找出系统中所有引用该对象的地方。这在修改一个公共接口或核心类时，评估影响范围至关重要。
• get_code_completion: 虽然AI本身能进行代码补全，但这个工具直接调用SAP系统的ABAP关键字和对象建议，提供了最准确、最上下文相关的本地补全信息。

实战场景：你刚加入一个项目，需要快速熟悉“财务过账”（ZFI_POSTING）相关的代码。你可以让AI执行：“列出包ZFI_POSTING中的所有内容”。然后，你可以针对感兴趣的类，比如ZCL_FI_DOCUMENT_CREATE，继续让AI：“查找ZCL_FI_DOCUMENT_CREATE的所有使用位置”。几分钟内，你就能理清核心类的关系网，而这在过去可能需要半天的时间在SE80里点点点。

3.2 读取与审查：将代码库置于AI的显微镜下

读取是写入的基础，也是代码审查、知识传递的核心。

• read_object_source: 读取ABAP对象的源代码，支持类、接口、程序、函数组/模块等。这是最常用的工具之一。
• read_object_structure: 对于类，这个工具比读源码更有价值。它返回类的元数据：公有/私有/受保护的方法和属性、继承关系、实现的接口等。AI可以借此快速理解一个类的架构。
• read_cds_source/read_behavior_definition/read_service_binding: 这是针对SAP现代架构——RAP（Restful ABAP Programming）的专门工具。可以分别读取CDS视图的DDL、行为定义和服务绑定。对于基于RAP的项目，这些是核心资产。
• read_table_definition/read_data_element: 直接读取DDIC（数据字典）信息。想知道一个表（如MARA）有哪些字段、数据类型、数据元素（如MATNR）的域和描述？AI现在可以直接告诉你，无需打开SE11。

实操心得：read_object_source返回的是包含ABAP代码的XML格式（ADT标准格式）。AI助手通常能很好地解析并高亮显示代码。但对于我们人类阅读，有时直接看原始ABAP更舒服。一些高级的AI客户端（如配置了特定技能的Kiro）可以在展示代码时，自动将其转换为更易读的纯文本格式。如果你发现返回的是XML标签，可以尝试要求AI：“请将源代码以纯ABAP格式展示出来。”

3.3 写入、创建与激活：赋予AI“动手”能力

这是工具集中最强大，也最需要谨慎使用的部分。所有写入工具都内置了锁管理和乐观并发控制机制。

• 锁管理：当AI执行write_object_source时，工具会首先尝试锁定目标对象（通过ADT的lock服务），防止其他用户同时修改。写入完成后（无论成功与否），会自动释放锁。这模拟了我们在SE80中编辑时系统自动上锁的行为。
• 乐观并发控制：这是防止覆盖他人修改的关键。通过expectedSource参数实现。工作流程如下：
  1. AI先通过read_object_source获取对象的当前源代码（版本A）。
  2. 你或AI基于版本A进行修改，得到版本B。
  3. 调用write_object_source写入版本B，同时将版本A作为expectedSource参数传入。
  4. 服务器在写入前，会再次读取对象的当前源代码（版本C）。如果版本C与传入的版本A不同（说明在此期间有其他人修改并保存了），则写入操作会被中止，并返回冲突差异。如果相同，则执行写入。

create_class/create_interface: 这两个工具用于从零创建新的全局类或接口。你需要提供名称、描述、包名和传输请求号。这是符合企业开发规范的——任何创建都必须关联到一个传输请求，以便后续的流转和部署。AI可以帮你生成符合命名规范（如ZCL_开头）的类骨架，包括初始的类定义和方法。

activate_objects: 相当于在SE80中按Ctrl+F3。激活是一个组合操作，包括语法检查、生成运行时对象等。你可以传入一个对象的URI数组，批量激活多个对象。

run_unit_tests/run_atc_check: 质量守护者。run_unit_tests执行ABAP单元测试并返回详细结果（哪些测试通过，哪些失败及失败原因）。run_atc_check运行ABAP Test Cockpit检查，可以指定检查变式，对代码进行静态检查，发现潜在的性能、安全、语法问题。

实战场景：代码审查与自动修复。你可以让AI执行一个组合操作：“读取类ZCL_EXAMPLE的源代码，用review-abap-code提示模板进行代码审查，然后根据审查建议生成修改后的代码，并使用expectedSource机制写回。” 在这个过程中，AI不仅提出了建议，还能直接生成符合建议的代码补丁，并通过冲突检测安全地应用它。

3.4 传输管理：连接开发与部署

• list_transports: 列出指定用户或目标系统的开放传输请求。你可以快速查看有哪些传输等待释放。
• release_transport: 释放一个传输请求或任务。这是一个高风险操作，因为它会将代码变更正式释放到下一个系统（如测试系统）。因此，在几乎所有客户端的默认安全配置中，此工具永远不会被自动批准，必须手动确认。

重要警告：对于release_transport以及任何在生产系统（PRD）上的写入操作，必须保持最高级别的警惕。最佳实践是：仅在开发（DEV）系统配置写入权限，在测试（QAS）和生产（PRD）系统只配置只读权限。S.A.M.U.R.A.I.的权限完全依赖于你配置的SAP用户，务必遵循最小权限原则。

4. 安全、规范与最佳实践

将AI直接连接到企业核心的SAP系统，安全是头等大事。S.A.M.U.R.A.I.在设计上提供了多层安全机制，但最终的安全取决于使用者的配置和习惯。

4.1 安全配置的黄金法则

1. 环境变量与秘密管理：绝对不要将包含密码的mcp.json文件提交到Git。使用环境变量文件（如.env）并通过dotenv在本地加载，或者利用操作系统或IDE的密钥环功能。在团队协作或CI/CD环境中，使用HashiCorp Vault、AWS Secrets Manager或Azure Key Vault等秘密管理服务注入凭证。
2. 分级的用户权限：
   • 开发系统（DEV）：可以使用具备S_DEVELOP权限的账号，允许读写操作。
   • 测试系统（QAS）：建议使用只读权限的账号，仅用于查看和测试。
   • 生产系统（PRD）：强烈建议不使用，或仅使用具有严格限制的只读账号。任何对生产系统的直接修改都应通过正式的传输流程，而非AI工具。
3. 利用客户端的审批机制：如前所述，充分利用Kiro的autoApprove列表或类似机制。将search_objects,read_*等只读工具设为自动批准，实现无缝探索。将write_*,create_*,activate_objects,release_transport等写入工具排除在外，确保每一次修改都经过你的明确确认。在Antigravity、Cursor等客户端中，这通常意味着每次调用这些工具时，都会弹出一个确认对话框。
4. 自签名证书处理：许多开发系统使用自签名SSL证书。在开发环境中，可以通过设置环境变量NODE_TLS_REJECT_UNAUTHORIZED=0来绕过证书验证。切记，此设置仅用于开发环境，绝不可用于生产环境。

4.2 注入ABAP专家经验：技能与规则文件

S.A.M.U.R.A.I.项目最精妙的部分之一，是它提供了一套完整的“ABAP专家知识”文件。这不仅仅是工具集，更是将资深ABAP开发者的经验、规范和最佳实践“灌输”给AI的方法。

这套知识库涵盖了现代ABAP开发的方方面面：

• 命名规范：强制要求自定义对象以Z或Y开头，类、接口、CDS视图的命名模式（ZCL_, ZIF_, ZI_, ZC_）。
• 现代ABAP语法：推广使用内联声明（DATA(...)）、字符串模板（|...|）、表表达式（VALUE #,FILTER,REDUCE）等7.40+特性。
• 性能守则：禁止在循环内SELECT，必须使用FOR ALL ENTRIES前检查内表是否为空，根据访问模式选择正确的表类型（SORTED, HASHED）。
• 架构模式：指导如何正确构建RAP应用（基本视图->组合视图->消费视图的VDM分层），如何选择管理、非管理或草稿场景。
• 代码审查清单：包含20多个检查点，从Clean ABAP原则到安全性（权限检查、SQL注入风险）、错误处理、可测试性等。

如何应用这些知识？项目为不同AI客户端提供了适配的格式：

• 对于Kiro：将skill-abap-senior.md文件复制到项目的.kiro/steering/目录下。Kiro会自动加载它，使其成为AI对话的“背景知识”，在所有ABAP相关任务中生效。
• 对于Cursor：创建.cursor/rules/abap-senior.mdc文件，并将知识库内容粘贴进去。Cursor的“AI规则”功能会确保在编辑.abap文件时应用这些规则。
• 对于Antigravity：将提供的技能文件夹复制到.agents/skills/目录下，Antigravity会将其识别为一项持久技能。

效果是什么？当你让AI“创建一个新的销售订单处理类”时，它不再只是生成一段能编译的代码，而是会生成一个符合ZCL_SD_ORDER_PROCESSOR命名规范、使用类异常进行错误处理、包含必要的权限检查对象AUTHORITY-CHECK、甚至预先写好单元测试框架的“专业级”代码骨架。这极大地提升了AI生成代码的可用性和质量，减少了后续的返工和审查时间。

4.3 事件钩子（Hooks）与自动化提醒

对于Kiro用户，项目还提供了事件钩子（Hooks），这是一种更强大的自动化与安全控制机制。钩子是在特定事件（如工具调用前/后）触发的小脚本。

• sap-mcp-safety.kiro.hook（写入操作守卫）：这个钩子会在任何写入、创建、激活、释放工具被调用前触发。它会强制中断流程，并要求AI助手向你确认一系列安全事项，例如：“目标对象名称是否正确？”、“用户是否确认此次修改？”、“目标系统是开发系统吗？”、“是否使用了expectedSource进行冲突检测？”。只有在你（通过AI）确认后，操作才会继续。这为所有高风险操作增加了一道强制性的手动确认关卡。
• sap-mcp-refresh.kiro.hook（自动刷新提醒）：这个钩子在写入或激活操作成功后触发。它会提醒AI助手告诉你：“操作已完成，请在SAP ADT for VS Code扩展中刷新相应文件以查看最新内容。” 这是一个非常贴心的用户体验细节，解决了远程修改后本地视图不同步的问题。

你可以基于这些模板创建自己的钩子，例如：在每次保存ABAP文件后自动触发语法检查；或者在释放传输前，强制要求先运行ATC检查。

5. 常见问题排查与实战技巧

即使准备充分，在实际使用中仍可能遇到问题。以下是一些常见问题的排查思路和我积累的实战技巧。

5.1 连接与权限类问题

5.2 工具执行类问题

5.3 实战技巧与心得

1. 从“只读”开始，建立信任：初次使用时，先在配置中仅启用只读工具（autoApprove列表），用几天时间让AI帮你搜索、阅读代码。这既能让你熟悉工作流，也能验证工具返回数据的准确性，建立对这套系统的信任。
2. 善用“预期源码”进行安全协作：在团队环境中，务必养成使用expectedSource参数的习惯。这能有效避免你和同事同时修改同一对象时，后提交者覆盖前提交者更改的“最后一分钟”问题。让AI在每次修改前都执行“读取->修改->带预期写入”的流程。
3. 将复杂操作分解为多轮对话：不要试图在一个指令中完成所有事情。例如，构建一个RAP对象，可以分解为：“搜索一下我们有没有类似的销售订单CDS视图？” -> “读取ZR_SALESORDER的行为定义作为参考” -> “使用create-rap-bo模板，以SalesOrder为根实体，创建一套带草稿的管理模式RAP对象”。这样每一步都有确认和调整的机会。
4. 结合本地开发环境：S.A.M.U.R.A.I.并不替代本地的ABAP开发环境（如ADT in VS Code）。最佳实践是：用AI进行探索、生成代码骨架、执行重复性任务；然后在本地VS Code中打开对应的ABAP项目，进行精细化的编码、调试和版本控制（git）。两者可以完美互补。
5. 为常用操作创建快捷指令：大多数AI助手支持自定义指令或快捷方式。你可以将“用S.A.M.U.R.A.I.测试连接”、“审查当前类的代码”等常用操作设置为快捷指令，进一步提升效率。

这个项目代表了一种趋势：将企业级传统系统的能力，通过标准化协议（MCP）暴露给现代AI智能体。它解决的不仅仅是ABAP开发的效率问题，更是开启了人机协同处理复杂企业任务的新范式。你可以从今天开始，从一个简单的只读查询做起，逐步将它融入你的日常开发流程，感受这位“现代SAP武士”带来的精准与高效。