mcp-sap-docs

MCP SAP Docs（上游）

一个 MCP 服务，让 AI 助手（Claude、Cursor、ChatGPT 等）通过统一的搜索和获取接口访问 SAP 文档。它结合了基于 git 克隆的 SAP 文档的本地全文搜索和可选语义排序，以及对 SAP Help、SAP Community 和 Software Heroes 的可选实时查询——所有功能均以 MCP 工具形式提供。

安装

也可以将其添加到任何支持可流式 HTTP 的 MCP 客户端：

{
  "mcpServers": {
    "sap-docs": {
      "type": "http",
      "url": "https://mcp-sap-docs.marianzeis.de/mcp"
    }
  }
}

无需 API 密钥或登录——此服务公开提供且为只读。

公共托管端点

即刻使用——无需设置

变体	URL
SAP Docs	http://mcp-sap-docs.marianzeis.de/mcp
ABAP	https://mcp-abap.marianzeis.de/mcp

变体

mcp-sap-docs 是两个 MCP 服务变体的上游仓库。它们共享同一代码库，仅配置不同（MCP_VARIANT / .mcp-variant）：

变体	范围	额外工具
sap-docs	广泛的 SAP 文档：UI5、CAP、Cloud SDK、ABAP、BTP、AI、Terraform	Discovery Center 工具
abap	聚焦 ABAP：ABAP 关键字文档、RAP、速查表、风格指南	abap_lint

文档来源

离线来源（本地索引，始终可用）

来源	描述
abap-docs-standard	官方 ABAP 关键字文档——本地部署 / 完整语法
abap-docs-cloud	官方 ABAP 关键字文档——ABAP Cloud / BTP（受限语法）
abap-cheat-sheets	实用的 ABAP/RAP 代码片段和示例
abap-fiori-showcase	基于注解的 RAP + OData V4 + Fiori Elements 功能展示
abap-platform-rap-opensap	openSAP《使用 RAP 构建应用》课程示例
cloud-abap-rap	ABAP Cloud + RAP 示例项目
abap-platform-reuse-services	RAP 复用服务示例（编号范围、邮件、Adobe Forms 等）
sap-styleguides	SAP Clean ABAP 风格指南和最佳实践
dsag-abap-leitfaden	DSAG ABAP Leitfaden（德语）开发指南
btp-cloud-platform	SAP BTP 概念、开发、安全和管理
sap-artificial-intelligence	SAP AI Core 和 SAP AI Launchpad 文档
ui5	SAPUI5 / OpenUI5 框架文档
cap	SAP Cloud Application Programming Model（CAP）文档
cloud-sdk	SAP Cloud SDK 文档
terraform-provider-btp	用于 BTP 的 SAP Terraform Provider——资源和数据源
architecture-center	SAP Architecture Center 参考架构和指南
wdi5	wdi5（WebdriverIO + UI5）测试框架文档

其他 SAP 文档来源

sap-docs 配置文件还会索引以下官方文档。这些来源使用现有的 Markdown/MDX 流程，并链接到上游文件。

来源 ID	覆盖范围
btp-connectivity	目标、Cloud Connector、主体传播、HTTP/RFC
cloud-sdk-python、cloud-sdk-ai-python	Python BTP 和 AI SDK 文档及示例
odata-vocabularies	OData 注解术语和类型；保留实验性标签
btp-job-scheduling-service、btp-cloud-logging	应用程序作业和可观测性
btp-cloud-identity-services、btp-cloud-identity-integration	Identity Authentication、Identity Provisioning 和系统集成
btp-integration-suite、btp-event-mesh	整合后的集成与 API 指南，以及 Event Mesh
btp-business-application-studio	开发空间、开发和故障排查
btp-continuous-integration-and-delivery、btp-cloud-transport-management	托管流水线和云传输

Integration Suite 索引 docs/ISuite_Integrations_APIs 和 docs/ISuite_Event_Mesh。为避免内容重复和导航术语混用，不包含并行的 Cloud Integration/API Management 指南副本。Python SDK 来源包含当前的 docs-python 内容；不包含历史版本目录。

SAP-docs 存储库带有 CC-BY-4.0 声明；SAP Cloud SDK、AI SDK 和 OData 词汇表带有 Apache-2.0 声明。源代码检出会保留其上游许可证文件，搜索/获取结果会链接到原始文档。有关验证和范围，请参阅来源扩展计划。

在线来源（实时查询，默认启用）

来源	说明
SAP Help Portal	SAP 官方产品文档（范围广泛）
SAP Community	社区博客、问答和故障排查帖子
Software Heroes	ABAP/RAP 文章和教程（EN + DE，已去重）

可用工具

共享工具（两个变体均适用）

工具	说明
search	在离线文档和可选在线来源中进行统一搜索（BM25，可选语义排序）。支持 query、k、includeOnline、includeSamples、abapFlavor、sources 参数。
fetch	按 search 返回的 ID 获取完整文档内容。
abap_feature_matrix	使用 Software Heroes 功能矩阵检查不同 SAP 版本（7.40–LATEST）的 ABAP 功能可用性。
sap_community_search	通过 Khoros LiQL API 专门搜索 SAP Community——返回热门帖子的完整内容。若 search 的结果不足以解决特定错误或查找变通方法，请使用此工具。
sap_search_objects	根据名称/组件/类型搜索 SAP 已发布对象（类、接口、表、CDS 视图，…），数据来自官方 SAP/abap-atc-cr-cv-s4hc 发布状态仓库。适用于发现符合 clean core 要求的对象。
sap_get_object_details	获取特定 SAP 对象的完整发布状态详情，包括 clean core 级别（A/B/C/D）、后继对象以及可选的合规判定。

仅限 sap-docs 变体

工具	描述
sap_discovery_center_search	按关键词、类别或许可模式搜索 SAP Discovery Center 服务目录中的 BTP 服务。
sap_discovery_center_service	获取全面的 BTP 服务详情：定价方案、产品路线图、文档链接和主要功能。接受服务 UUID 或名称。
ui5_version_diff	从本地 all-changes bundle（dist/data/ui5-lib-diff/all-changes.json）列出指定版本或版本范围内所有匹配的 FEATURE / FIX / DEPRECATED 变更和 SAPUI5 What's New 条目。npm run setup 会自动刷新该文件；设置或重新构建时，可使用 npm run download:ui5-lib-diff 手动刷新。搭配 ui5-version-upgrade skill 和 @ui5/mcp-server，即可完成完整的升级工作流。

仅限 abap 变体

工具	描述
abap_lint	使用 abaplint 对 ABAP 源代码执行静态代码分析。根据代码模式自动检测文件类型。返回包含行号、严重级别和规则键的检查结果。

架构概览

• 上游事实来源：mcp-sap-docs
• 单向同步目标：abap-mcp-server
• 搜索默认使用 BM25 关键词排序；可选的语义分数通过 Reciprocal Rank Fusion（RRF）合并
• 嵌入模型：Xenova/all-MiniLM-L6-v2（约 90 MB，缓存在 dist/models/ 中）

变体选择

解析顺序：

1. MCP_VARIANT 环境变量
2. 仓库根目录中的 .mcp-variant 文件
3. 回退值：sap-docs

示例：

# Run as full sap-docs profile
MCP_VARIANT=sap-docs npm run setup
MCP_VARIANT=sap-docs npm run build
MCP_VARIANT=sap-docs npm run start:streamable

# Run as ABAP profile
MCP_VARIANT=abap npm run setup
MCP_VARIANT=abap npm run build
MCP_VARIANT=abap npm run start:streamable

搜索行为

search 会对以下来源执行融合检索：

• 离线 FTS 索引（本地子模块内容）
• 可选在线来源（includeOnline=true）：
  • SAP Help
  • SAP Community
  • Software Heroes 内容搜索（EN/DE 合并并去重）

排序和筛选要点：

• BM25 搜索，可选语义排序——关键词和含义通过 RRF 融合
• 对离线和在线来源使用 Reciprocal Rank Fusion（RRF）
• 根据元数据提升来源级别的排序权重
• includeSamples 可移除示例内容较多的来源
• abapFlavor（standard / cloud / auto）筛选官方 ABAP 文档库，同时保留非 ABAP 来源
• sources 可明确限制离线库范围

内容获取限制

社区帖子正文以 Markdown 格式返回，包括代码、链接、图片和表格。此前解析原始 Community HTML 的客户端必须改为处理 Markdown。文档 ID、来源 URL 和响应架构保持不变。 如果转换失败，该帖子会保留原始 HTML 并附带提示；同一批次中的其他帖子仍会正常返回。

SAP Help 和 Community 的获取默认限制为 75,000 个字符。截短的结果会在 metadata.truncation 中列出精确的截短字符数。可自托管的服务可在启动前设置 MAX_CONTENT_LENGTH；请参阅内容大小限制。

混合搜索

离线搜索默认使用 BM25 关键词排序。可选的语义排序使用 Xenova/all-MiniLM-L6-v2 对词法候选结果重新排序；它不会搜索候选结果池以外的内容。请先构建完整的文档和章节嵌入，并评估自己的查询，再通过 EMBEDDING_WEIGHT=0.7 显式启用。

嵌入存储在 docs.sqlite 中，模型缓存在 dist/models/ 中。旧版或不完整的嵌入数据会回退到词法排序，并发出重建警告。有关设置、限制和成本，请参阅 docs/HYBRID-SEARCH.md。

仅离线模式

search 默认包含在线来源。若要仅离线运行，请：

• 仅使用本地索引/子模块（npm run setup + npm run build）
• 在每个 search 请求中设置 includeOnline=false

search 请求正文示例：

{
  "query": "RAP draft",
  "k": 8,
  "includeOnline": false
}

Docker（仅离线）

使用主机绑定运行容器，并调用 search，将 includeOnline=false：

docker run --rm -p 3122:3122 \
  -e MCP_VARIANT=sap-docs \
  -e MCP_PORT=3122 \
  -e MCP_HOST=0.0.0.0 \
  mcp-sap-docs

如需严格的气隙执行，请禁用容器网络：

docker run --rm --network none -p 3122:3122 \
  -e MCP_VARIANT=sap-docs \
  -e MCP_PORT=3122 \
  -e MCP_HOST=0.0.0.0 \
  mcp-sap-docs

说明：

• 使用 --network none 时，运行时隔离会阻止在线获取。
• 启动时可能会记录在线预取尝试的警告（例如 ABAP 功能矩阵）；这不会影响离线使用 search。

快速开始（本地）

npm ci
npm run setup
npm run build

npm run setup 会将所选变体的文档源更新到其配置的分支最新提交，并构建索引（包括嵌入）。嵌套子模块会保留在这些源中记录的提交上。若要省略可选的嵌套仓库（例如其上游 URL 需要 SSH 凭据时），请在 Bash 中使用 SKIP_NESTED_SUBMODULES=1 npm run setup；Windows 上的 Git Bash 也适用。

npm run setup:submodules 则会检出仓库中记录的源提交。它不会获取最新文档，也不会应用变体筛选。刷新现有安装时，请运行 npm run setup。

启动服务模式：

# MCP stdio
npm start

# HTTP status/dev server
npm run start:http

# MCP streamable HTTP
npm run start:streamable

各变体的默认端口：

• sap-docs：HTTP 3001，可流式传输的端口 3122
• abap：HTTP 3002，可流式传输的端口 3124

健康检查：

curl -sS http://127.0.0.1:3122/health | jq .
curl -sS http://127.0.0.1:3001/status | jq .

运行 abap 配置文件时，请使用对应变体的端口。

构建和设置脚本

脚本名称保持一致（setup、build、start、start:streamable）。 具体行为由变体配置决定：

• setup.sh 仅初始化该变体允许的子模块
• build-index 仅包含该变体允许的库
• build-fts 仅为该变体允许的库建立索引

这样可以让 abap 更快、更精简，无需维护单独的一套构建脚本。

Docker

为某个变体构建镜像：

# sap-docs image
docker build --build-arg MCP_VARIANT=sap-docs -t mcp-sap-docs .

# abap image
docker build --build-arg MCP_VARIANT=abap -t abap-mcp-server .

运行可流式传输的服务：

# sap-docs
docker run --rm -p 3122:3122 \
  -e MCP_VARIANT=sap-docs \
  -e MCP_PORT=3122 \
  mcp-sap-docs

# abap
docker run --rm -p 3124:3124 \
  -e MCP_VARIANT=abap \
  -e MCP_PORT=3124 \
  abap-mcp-server

SAP BTP Cloud Foundry

对于 BTP CF，推荐的 sap-docs 部署方式是使用 MTA 部署维护中的 ghcr.io/marianfoo/mcp-sap-docs:sap-docs 镜像。Cloud Foundry 只会 拉取并运行准备好的镜像（包括嵌入产物）。除非显式配置了大于零的 EMBEDDING_WEIGHT，否则排序仍采用词法方式。

请参阅 docs/BTP-CF-DEPLOYMENT.md，了解以公有资源优先的 部署指南。请先阅读 部署选项和权衡， 以便在 MTA、直接 cf push、自定义注册表镜像和刷新设置之间进行选择。

单向同步到 abap-mcp-server

此仓库包含直接同步自动化：

• 工作流：.github/workflows/sync-to-abap-main.yml
• 脚本：scripts/sync-to-abap.sh

流程：

1. 合并发布 PR 后，Release Please 会在 mcp-sap-docs 中发布一个版本
2. 发布工作流会显式触发 ABAP 同步工作流
3. 同步工作流会克隆 abap-mcp-server
4. 同步受跟踪的上游文件（应用排除规则），然后应用 ABAP 覆盖层
5. 强制将 .mcp-variant 设为 abap，并修补 ABAP 包标识
6. 将同步提交推送到 abap-mcp-server/main
7. 该推送会触发 ABAP 部署工作流

同步工作流也支持手动运行，包括试运行和自定义目标分支。 只有推送到下游 main 分支才会触发自动部署。

mcp-sap-docs 仓库中所需的机密：

• ABAP_REPO_SYNC_TOKEN：专用令牌，需具备向 abap-mcp-server 推送代码和工作流 更改的权限。请将其与 GITHUB_TOKEN 分开使用，因为后者推送的更改不会触发后续工作流。

部署模型

• mcp-sap-docs：负责管理发布版本，并在创建发布版本时触发部署和 ABAP 同步
• abap-mcp-server：在推送到 main（包括上游同步提交）时部署，或通过 workflow_dispatch 部署

下游仓库不会发布 GitHub 版本。因此，其部署必须监听同步推送，而不是监听 release: published。上游版本发布决定自动同步何时发生。

ABAP 部署工作流维护在 sync/abap.overlay/.github/workflows/deploy-abap-mcp-server.yml 中。请修改该上游覆盖文件，以确保修复在后续同步中保留。

合并部署修复后，请发布下一个上游版本，或手动针对上游 main 运行 sync-to-abap-main.yml。确认下游部署运行成功，并确认 https://mcp-abap.marianzeis.de/health 报告的版本与同步后的 ABAP package.json 中的版本一致；仅同步成功并不能确认部署成功。

PM2 运行时

ecosystem.config.cjs 可识别变体，并从以下文件解析：

• 进程名称
• 端口
• 部署路径

config/variants/*.json。

验证命令

npm run build:tsc
npm run test:url-generation
npm run test:integration
npm run test:software-heroes
npm run test:discovery-center # mocked Discovery Center REST contract tests
npm run test:discovery-center:live # opt-in live API smoke test
npm run test:sap-objects       # SAP Released Objects unit tests

# Variant-specific build checks
MCP_VARIANT=sap-docs npm run build:index
MCP_VARIANT=abap npm run build:index
MCP_VARIANT=sap-docs npm run build:fts
MCP_VARIANT=abap npm run build:fts

其他文档

• docs/ARCHITECTURE.md
• docs/DEV.md
• docs/TESTS.md
• docs/UPSTREAM-ONE-WAY-SYNC-IMPLEMENTATION.md
• REMOTE_SETUP.md

精选 SAP 教程

SAP Docs 配置文件包含 sap-tutorials-ai、sap-tutorials-hana 和 sap-tutorials-integration 中的 32 个额外官方教程： AI Core 编排 V2 和 grounding、HANA Cloud SQLScript 和 CAP、Integration Suite MCP Gateway，以及 Cloud Transport Management。现有的 Fiori OPA 指南仍可单独获取。

请使用产品和任务相关术语，例如 SAP HANA Cloud SQLScript stored procedure tutorial 或 SAP Integration Suite MCP Gateway tutorial。使用 sources 缩小含义不明确的搜索范围；若要跨来源查找，则不设置该项。教程提供完整示例并保留其先决条件；产品和 SDK 文档仍是详细 API 行为的参考资料。

具体选择见 config/tutorials.json。 获取的教程包含易读的选项标签、绝对资源和先决条件链接，以及其已发布页面的 URL。尚未发布的传输概览链接到其官方 GitHub 源。源内容及其原始署名均予以保留；原始教程仓库的许可证仍然适用。