SAP Documentation MCP Server

MCP SAP文档（上游）

一个MCP服务器，通过统一的搜索和获取界面，让AI助手（Claude、Cursor、ChatGPT等）访问SAP文档。它将git克隆的SAP文档上的本地全文+语义索引与对SAP帮助、SAP社区和软件英雄的可选实时查询相结合，所有这些都作为MCP工具公开。

公共托管端点

即用型——无需设置 |变量|URL| |---------|-----| |SAP文档| http://mcp-sap-docs.marianzeis.de/mcp | |ABAP| https://mcp-abap.marianzeis.de/mcp |

变体

mcp-sap-docs 是共享一个代码库且配置不同的两个MCP服务器变体的上游存储库(MCP_VARIANT / .mcp-variant):

文档来源

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

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

可用工具

共享工具（两种变体）

sap-docs 仅限变体

abap 仅限变体

架构概述

• 真相的上游来源： mcp-sap-docs
• 单向同步目标： abap-mcp-server
• 搜索用途 混合BM25+语义（嵌入） 互序融合（RRF）
• 嵌入模型： Xenova/all-MiniLM-L6-v2 （约90 MB，缓存在 dist/models/)

变体选择

解决顺序：

1. MCP_VARIANT 环境变量
2. .mcp-variant repo根目录中的文件
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帮助 - SAP社区 - 软件英雄内容搜索（EN/DE合并+重复数据消除）

排名和过滤亮点：

• 混合BM25+语义（嵌入）搜索 --关键字和含义，通过RRF融合
• 跨离线和在线来源的互惠排名融合（RRF）
• 元数据的源代码级别提升
• includeSamples 可以去除样本重源
• abapFlavor (standard / cloud / auto)过滤官方ABAP文档库，同时保留非ABAP源
• sources 可以明确限制脱机库

混合搜索

离线搜索结合了BM25（FTS5关键字匹配）和语义相似性 （通过密集嵌入 Xenova/all-MiniLM-L6-v2).这使得自然语言和 即使缺少确切的关键字，也可以对查询进行意译以查找相关文档。

例子： _“如何检查用户是否有权限”_ 发现 AUTHORITY-CHECK 文档。

嵌入在构建时预先计算并存储在 docs.sqlite. 模型（约90 MB）缓存在 dist/models/ （gitignored，在项目中）。

看 docs/HYBRID-SEARCH.md 了解完整细节、尺寸影响和调整。

仅离线模式

search 默认情况下包括在线资源。要仅脱机运行，请使用：

• 仅限本地索引/子模块(npm run setup + npm run build)
• includeOnline=false 每一个 search 请求

示例 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

启动服务器模式：

# 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 更快、更小，而无需维护单独的构建脚本集。

码头工人

为变体构建映像：

# 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

单向同步到 abap-mcp-server

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

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

流量：

1. 推至 mcp-sap-docs/main
2. 工作流克隆 abap-mcp-server
3. 同步跟踪的上游文件（使用排除规则）
4. 应用ABAP覆盖
5. .mcp-variant 被迫 abap
6. ABAP包标识已修补
7. 提交被推到 abap-mcp-server/main

需要保密 mcp-sap-docs 回购：

• ABAP_REPO_SYNC_TOKEN

提交消息控件：

• [skip-sync] 跳过同步工作流

部署模型

• mcp-sap-docs：上游实现+同步触发
• abap-mcp-server：部署触发器仍将推送到该存储库中的main

这保留了ABAP部署自动化，同时保留了一个共享的上游代码库。

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: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