SAP 开发中的两类阻塞：用 Sandbox 提前联调，用 MCP 查 API、路线图和 Notes

SAP 集成开发经常卡在两个地方。一个是接口资料已经拿到，测试系统却还没准备好：账号申请中、网络尚未打通、测试数据不足，映射和异常处理只能等。另一个是系统已经报错，却需要在 API Hub、Road Map Explorer 和 SAP Notes 之间反复搜索，才能拼出判断所需的资料。

这篇文章介绍两个分别应对这些问题的开源项目：sap-bah-sandbox 把接口规格变成可调用的本地模拟服务；sap-mcp-servers 把 SAP 资料查询能力接入 AI 助手。它们可以串成“查明接口 → 取得规格 → 模拟验证 → 真实系统验收”的开发流程。

遇到的问题	更适合的项目	可以获得什么
测试后端没准备好，想先写调用和映射	sap-bah-sandbox	依据接口规格生成的 Mock 服务
很难稳定重现慢响应、异常返回	sap-bah-sandbox	可调延迟、错误率，以及请求记录
想知道 Hub 中的接口或规格是否变化	sap-bah-sandbox	目录版本记录与变更报告
不知道该选哪个 SAP API	sap-mcp-servers / API Hub	带来源的搜索、元数据与规格
报错后需要找适用的 SAP Note	sap-mcp-servers / Notes	检索结果、正文、适用范围等资料
产品选型需要核对计划功能	sap-mcp-servers / Roadmap	路线图条目和计划信息

本文基于 Sandbox 提交 8861b7d 和 MCP Servers 提交 c509e06 。2026 年 10 月 28 日，我在 Windows、Node 24.18.0 下完成了三个 MCP 服务的构建、协议测试和真实查询；Sandbox 尚未在这台机器上运行，下面的 Sandbox 步骤是根据上游文档和代码核对的示例。

sap-bah-sandbox：后端没准备好，也能推进接口开发

问题一：集成开发被测试环境拖住

假设要做一个销售订单接口：调用方发出查询请求，CPI 接收响应，再把订单字段映射给下游应用。真实系统暂时不可用时，仍然有许多工作可以推进，例如 URL 拼接、请求体结构、响应解析、字段映射，以及空列表的处理。

Sandbox 接收 OpenAPI 3、Swagger 2 或 OData EDMX 规格，将它们挂载为 /mock/<slug>/… 下的 HTTP 接口。开发者可以生成模拟数据，也可以导入自己准备的 JSON 或 CSV 测试数据。这样，后端可用性不再是上述开发步骤的唯一前提。能力和格式说明见上游 Mock 文档。

这里的关键是测试数据要服务于问题。随机数据适合确认“调用能否跑通”；检查金额、日期、空字段和特殊字符时，应使用固定 fixture，使同一个输入始终对应可比较的输出。项目会保存生成的数据集，写操作可以继续修改该数据集。

示例：先做一个最小销售订单 Mock

从源码运行需要 Node.js 22.5 或更新版本，上游推荐 Node 24。以下使用 PowerShell，在自己选定的开发目录执行：

git clone https://github.com/bdbais/sap-bah-sandbox.git
cd sap-bah-sandbox
npm install
Copy-Item .env.example .env
npm run build

编辑当前目录的 .env ，本机试用可设置如下几项，其余保留模板配置：

HOST=127.0.0.1
PORT=8080
DATA_DIR=./data
AI_PROVIDER=none
AUTO_UPDATE=false

在同一目录执行 npm start ，再打开 http://127.0.0.1:8080 。服务的数据库和报告保存在 data/ 中。初次体验使用本机回环地址；如果要开放给其他机器，应按上游说明配置 ADMIN_KEY 和访问控制。

创建一个 sales-orders.yaml 。下面是用于演示的自定义接口，路径和模型都不是 SAP 的真实销售订单 API：

openapi: 3.0.3
info:
  title: Demo Sales Orders
  version: 1.0.0
paths:
  /orders:
    get:
      operationId: listOrders
      responses:
        '200':
          description: Order list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required: [id, amount]
                  properties:
                    id:
                      type: string
                    amount:
                      type: number

在 Mocks 页面导入这个规格，创建并挂载 slug 为 orders-demo 的 Mock，选择 faker 数据策略，然后调用：

curl.exe http://127.0.0.1:8080/mock/orders-demo/orders

验证目标是响应能被解析为数组，每项含有 id 和 amount 。接着将调用方的测试地址指向这个 URL，检查映射后的结果；需要业务边界样本时，再改用 fixture。

如果已经取得真实 SAP API 的规格，可以用同一流程导入，并按该规格的真实路径调用。OData 场景还可以导入 $metadata 对应的 EDMX，测试受支持的查询参数。

云端 CPI 不能直接访问开发电脑的 127.0.0.1 。这时需要按上游可达性指南建立可访问的路径，例如适合环境的 Cloud Connector 或受保护的代理入口；修改 Receiver URL 前，先验证网络路径和认证。

问题二：正常请求能通，但异常处理没有机会验证

真实后端通常不会按测试计划稳定地“变慢一次”或“失败一次”。Sandbox 可以设置延迟和错误率，因此适合观察调用方超时后的行为、错误分支能否进入、重试次数是否符合预期。错误率是概率配置；要做精确断言，还应核对实际状态码和响应体。

它的 Network 页面记录请求和响应，可以帮助回答：“调用方最终发出的 URL、查询参数和 payload 是什么？”例如映射后字段为空，可以对照发送前内容与 Mock 收到的内容，缩小问题范围。项目会遮蔽部分敏感请求头，但请求体仍可能包含业务数据，测试时应优先用合成样本。

同样在项目根目录，可以运行自动生成的只读测试：

node dist/cli/test.js --mock orders-demo --read-only

测试器根据规格生成请求，并校验声明的状态码与响应结构。它能帮助发现接口契约不一致，却不能证明真实系统的业务规则正确。完整测试可能包含写操作，选择 --read-only 会跳过这些操作。机制见测试器说明。

问题三：依赖的接口变了，却到联调时才发现

Sandbox 还可以记录 Hub 中包和工件的版本变化，并生成报告。在项目根目录执行：

node dist/cli/sync.js --filter SuccessFactors

目录跟踪可匿名进行；自动下载具体规格需要相应的 Hub 凭据。取得规格后，工具还能比较部分结构变化。报告保存在 data/reports/ 下，便于结合开发任务判断哪些变动值得复查。

需要注意两个影响结果的条件：按关键字过滤的同步无法可靠判断整个目录中的删除；规格下载失败也不能解释为“接口没有变”。这些区别在目录跟踪文档中有说明。

模拟结果的适用边界

当前版本的 $expand 不会真正内联关联对象；无法解析的部分 $filter 表达式可能返回全部行。涉及关联展开和过滤正确性的测试，必须仔细检查结果，必要时移到真实环境验证。

模拟服务也不覆盖真实 SAP 的权限、业务校验、事务行为和完整性能特征。它最有价值的地方，是让协议和映射问题在真实联调前暴露，而后再把网络、认证和业务行为放回真实系统验收。

sap-mcp-servers：把 SAP 资料查询放进开发对话

问题一：AI 能解释概念，却拿不到需要登录的资料

SAP 开发里的很多问题需要具体证据：某个 API 支持哪些操作，某条 Note 适用哪个组件或版本，某个产品功能是否还在计划中。仅凭模型已有知识回答，容易把不同产品、版本和时间点混在一起。

sap-mcp-servers 提供三个服务，以及共用的 SAP 登录模块。接入支持 MCP 的客户端后，AI 助手可以调用搜索和获取工具，将返回的资料用于当前问题。具体工具说明分别见API Hub、Roadmap和Notes。

服务	实际解决的问题	典型工作方式
API Hub MCP	找接口、核对规格、减少凭记忆编造字段	搜索 → 查看元数据 → 获取所需规格
Roadmap MCP	为选型和规划收集计划信息	搜索产品 → 查看条目 → 核对计划时间和来源
Notes MCP	为错误排查收集适用的修复资料	搜索错误 → 获取正文 → 对照组件和版本

接入服务不会替账号增加权限。项目使用 SAP 登录和受认证保护的接口，首次登录或会话失效时可能需要浏览器交互。Notes 访问还取决于账号对支持资料的权限。

示例一：从“给我写代码”改为“先确认 API 契约”

接入 API Hub MCP 后，可以这样提出任务：

在 SAP API Hub 搜索销售订单相关 API。
先区分 S/4HANA Cloud 和其他产品的候选项，列出来源链接与适用产品。
选定候选后，读取它的操作和关键实体；需要时获取 OpenAPI 或 EDMX 规格。
根据实际规格给出一个最小查询示例，缺少的字段不要猜测。

这个流程把接口选择、规格读取和代码生成连在一起。API Hub 服务提供 search 、 fetch 、 resources 、 spec 等工具；完整规格通过显式的 spec 调用获取。工具查询资料，不会执行该资料所描述的真实业务接口。

示例二：OData 415 报错时，让搜索结果参与诊断

可以对 Notes MCP 这样提问：

搜索与 OData Gateway HTTP 415 相关的 SAP Notes 或 KBA。
列出标题、来源、组件和适用条件，然后读取最相关条目的正文。
将“文档明确说明”和“需要结合当前请求检查的假设”分开。
给出应核对的请求头、payload 格式和系统版本信息。

这样得到的输出应是一份待核验的排查依据。搜索命中并不代表某条 Note 一定适用于当前系统；还要对照请求内容、组件版本和 Note 的前提条件。

本次验证中，Notes 搜索 OData 返回了 29,568 条匹配记录。这个数字是查询当时的总命中数，并不代表已下载或阅读全部正文；实际诊断应使用更精确的错误和组件关键词。

示例三：产品选型时区分已具备功能与计划功能

Roadmap MCP 的提问可以写成：

查询 SAP Road Map Explorer 中与 Work Zone 有关的条目。
列出功能、计划时间、状态和原始链接。
将计划信息与已交付信息区分；不要把路线图日期当作交付承诺。

它适合把计划信息整理进选型讨论。最终设计仍要核对实际产品文档、当前租户能力和相关发布说明，避免把未来条目当成现成能力。

在 Codex 中接入三个服务

以下给出源码构建方式。使用 Node.js 22.12 或更新版本；本次验证采用 Node 24.18.0。先在自己的开发目录执行：

git clone https://github.com/marianfoo/sap-mcp-servers.git
cd sap-mcp-servers
npm ci
npm run build
npm run install:browsers

构建顺序由根脚本处理：先构建共用认证模块，再构建三个服务。Windows 下浏览器下载较慢时，可以给下载进程配置本机代理：

$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"
npm run install:browsers

这个代理配置用于下载，并不表示 SAP 浏览器登录也自动使用相同代理。此次安装先跳过自动浏览器下载完成构建，再通过代理安装 Chromium，最后完成登录测试。

为运行配置单独创建一个目录，例如 C:/sap-tools/workspaces/sap-mcp-servers/ 。将账号放到其中的 .env ，只在本机填写真实值：

AUTH_METHOD=password
SAP_USERNAME=your-sap-account@example.com
SAP_PASSWORD="replace-locally"
HEADFUL=true
MFA_TIMEOUT=120000

HEADFUL=true 让登录浏览器可见，便于完成交互验证；账号和密码不要写进公共 MCP 示例。使用目录的 .gitignore 至少包含：

.env
*-token-cache.json
sso-storage-state.json
*.pfx
*.p12

下面这段 PowerShell 假设源码已放到 C:/sap-tools/repos/sap-mcp-servers/ ，而运行配置目录就是前述路径。按实际目录修改前两行；使用 Node 的绝对路径，避免客户端启动时找到旧版本：

$sourceDir = 'C:/sap-tools/repos/sap-mcp-servers'
$configDir = 'C:/sap-tools/workspaces/sap-mcp-servers'
$nodeExe = (Get-Command node.exe).Source

codex mcp add sap-api-hub-local `
  --env "ENV_FILE=$configDir/.env" `
  --env "API_HUB_TOKEN_CACHE_FILE=$configDir/api-hub-token-cache.json" `
  -- $nodeExe "$sourceDir/packages/api-hub/dist/mcp-server.js"

codex mcp add sap-roadmap-local `
  --env "ENV_FILE=$configDir/.env" `
  --env "ROADMAP_TOKEN_CACHE_FILE=$configDir/roadmap-token-cache.json" `
  -- $nodeExe "$sourceDir/packages/roadmap/dist/mcp-server.js"

codex mcp add sap-notes-local `
  --env "ENV_FILE=$configDir/.env" `
  --env "SAP_NOTES_TOKEN_CACHE_FILE=$configDir/notes-token-cache.json" `
  -- $nodeExe "$sourceDir/packages/notes/dist/mcp-server.js"

codex mcp list

Codex 将配置保存在用户的 ~/.codex/config.toml 。新增配置后，重新打开会话以加载服务，再使用前面的自然语言查询。配置方式参见Codex MCP 文档。

这次测试分了三层：配置被客户端识别；服务完成 MCP 初始化并返回工具列表；业务工具完成 SAP 登录并拿到实际数据。前两层成功不能替代第三层。

服务	发现的工具数	实际查询结果
API Hub	6	categories 返回 10 个分类
Roadmap	5	搜索 work zone 返回 5 条结果
Notes	3	搜索 OData 返回匹配结果及总数

Roadmap 首次查询曾报“找不到用户名字段”，重试后成功。现有证据只能说明首次认证流程没有完成，不能据此认定密码错误或账号无权限。另外，上游的一个冒烟测试在 Windows 因创建符号链接出现 EPERM ，随后直接对构建产物执行 MCP 握手和工具调用完成了验证；这两种测试覆盖的内容不同。

这些测试是以 MCP 客户端协议调用本地服务完成的。Codex 配置已登记，但“配置出现在列表中”与“新会话中的 AI 已使用它完成任务”仍是两个观察层次。

把两个项目用在同一个开发任务里

以销售订单查询集成为例，可以按下面的顺序推进：

用 API Hub MCP 查候选接口，确认产品和版本，并获取明确的接口规格。
将规格导入 Sandbox，先用固定样本验证查询构造、字段映射和响应解析。
在 Sandbox 中增加慢响应和异常返回场景，观察超时、重试和错误分支。
接入真实测试系统，验证认证、授权、业务规则与真实数据。
遇到错误时，用 Notes MCP 找文档证据，再结合真实请求和日志判断；涉及产品能力规划时查询 Roadmap。

两个项目之间没有在本文中配置自动传递规格的连接，上面的步骤需要显式导出、导入或另写自动化。其价值在于把工作拆成可以逐步验收的环节：资料查询帮助确定应该做什么，模拟服务帮助提前发现实现问题，真实系统最终确认实际行为。

如果当前瓶颈是“后端不可用，联调停住”，先试 Sandbox；如果瓶颈是“查资料慢，AI 回答缺少依据”，先接入 MCP Servers。只选择能解决当前问题的部分，通常比一次部署全部组件更容易看到效果。

参考与验证范围

SAP BAH Sandbox：本文核对的源码版本，包括 Mock、测试器、目录跟踪与已知限制。
SAP MCP Servers：本文验证的源码版本，包括三个服务及共用认证模块。
Codex MCP 配置文档。

两个项目均为独立开源项目。MCP 服务对 SAP 登录流程和受保护接口存在依赖，使用应符合账号权限和组织要求。此次依赖安装报告了 3 项漏洞提示，后续独立审计因网络失败未取得明细，未将其写成已修复。正式团队使用前，应结合自己的依赖审计、权限配置和实际测试决定版本。

sap-bah-sandbox：后端没准备好，也能推进接口开发#

问题一：集成开发被测试环境拖住#

示例：先做一个最小销售订单 Mock#

问题二：正常请求能通，但异常处理没有机会验证#

问题三：依赖的接口变了，却到联调时才发现#

模拟结果的适用边界#

sap-mcp-servers：把 SAP 资料查询放进开发对话#

问题一：AI 能解释概念，却拿不到需要登录的资料#

示例一：从“给我写代码”改为“先确认 API 契约”#

示例二：OData 415 报错时，让搜索结果参与诊断#

示例三：产品选型时区分已具备功能与计划功能#

在 Codex 中接入三个服务#

把两个项目用在同一个开发任务里#

参考与验证范围#