MCP SAP Docs (Upstream)

An MCP server that gives AI assistants (Claude, Cursor, ChatGPT, etc.) access to SAP documentation through a unified search and fetch interface. It combines a local full-text + semantic index over git-cloned SAP docs with optional live queries to SAP Help, SAP Community, and Software Heroes — all exposed as MCP tools.

Install

[![Add to Werkbank][werkbank-badge]][werkbank-install]

Or add it to any MCP client that supports streamable HTTP:

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

No API key or login required — the server is public and read-only.

Public Hosted Endpoint

> Ready to use — no setup required

>

Variants

`mcp-sap-docs` is the upstream repository for two MCP server variants that share one codebase and differ by configuration (`MCP_VARIANT` / `.mcp-variant`):

Documentation Sources

Offline sources (local index, always available)

Online sources (live queries, enabled by default)

Available Tools

Shared tools (both variants)

`sap-docs` variant only

`abap` variant only

Architecture Overview

• Upstream source of truth: `mcp-sap-docs`
• One-way sync target: `abap-mcp-server`
• Search uses Hybrid BM25 + Semantic (embedding) fusion via Reciprocal Rank Fusion (RRF)
• Embeddings model: `Xenova/all-MiniLM-L6-v2` (~90 MB, cached in `dist/models/`)

Variant Selection

Resolution order:

1. `MCP_VARIANT` environment variable

2. `.mcp-variant` file in repo root

3. fallback: `sap-docs`

Examples:

# 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 Behavior

`search` performs fused retrieval over:

• Offline FTS index (local submodule content)
• Optional online sources (`includeOnline=true`):
  • SAP Help
  • SAP Community
  • Software Heroes content search (EN/DE merge + dedupe)

Ranking and filtering highlights:

• Hybrid BM25 + Semantic (embedding) search — keyword and meaning, fused via RRF
• Reciprocal Rank Fusion (RRF) across offline and online sources
• Source-level boosts from metadata
• `includeSamples` can remove sample-heavy sources
• `abapFlavor` (`standard` / `cloud` / `auto`) filters official ABAP docs libraries while keeping non-ABAP sources
• `sources` can restrict offline libraries explicitly

Hybrid Search

The offline search combines BM25 (FTS5 keyword matching) with semantic similarity

(dense embeddings via `Xenova/all-MiniLM-L6-v2`). This allows natural-language and

paraphrase queries to find relevant docs even when the exact keywords are missing.

Example: _"how to check if a user has permission"_ finds `AUTHORITY-CHECK` docs.

Embeddings are pre-computed at build time and stored in `docs.sqlite`.

The model (~90 MB) is cached in `dist/models/` (gitignored, in-project).

See docs/HYBRID-SEARCH.md for full details, size impact, and tuning.

Offline-Only Mode

`search` includes online sources by default. To run offline-only, use:

• local index/submodules only (`npm run setup` + `npm run build`)
• `includeOnline=false` in each `search` request

Example `search` request body:

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

Docker (offline-only)

Run the container with host binding and call `search` with `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

For strict air-gapped execution, disable container networking:

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

Notes:

• With `--network none`, online fetches are impossible by runtime isolation.
• Startup may log warnings for online prefetch attempts (for example ABAP feature matrix); this does not prevent offline `search` usage.

Quick Start (Local)

npm ci
npm run setup
npm run build

Start server modes:

# MCP stdio
npm start

# HTTP status/dev server
npm run start:http

# MCP streamable HTTP
npm run start:streamable

Default ports by variant:

• `sap-docs`: HTTP `3001`, streamable `3122`
• `abap`: HTTP `3002`, streamable `3124`

Health checks:

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

Use variant-specific ports when running `abap` profile.

Build and Setup Scripts

Script names remain shared (`setup`, `build`, `start`, `start:streamable`).

Behavior changes by variant config:

• `setup.sh` only initializes variant-allowed submodules
• `build-index` only includes variant-allowed libraries
• `build-fts` only indexes variant-allowed libraries

This keeps `abap` faster and smaller without maintaining a separate build script set.

Docker

Build image for a variant:

# 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 .

Run streamable 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

For BTP CF, the recommended `sap-docs` path is to deploy the maintained

`ghcr.io/marianfoo/mcp-sap-docs:sap-docs` image with MTA. Cloud Foundry only

pulls and runs the prepared semantic image.

See docs/BTP-CF-DEPLOYMENT.md for the public-first

deployment guide. Start with

Deployment Options and Tradeoffs

to choose between MTA, direct `cf push`, custom registry images, and refresh

setup.

One-Way Sync to `abap-mcp-server`

This repository contains direct sync automation:

• Workflow: `.github/workflows/sync-to-abap-main.yml`
• Script: `scripts/sync-to-abap.sh`

Flow:

1. Push to `mcp-sap-docs/main`

2. Workflow clones `abap-mcp-server`

3. Tracked upstream files are synced (with exclude rules)

4. ABAP overlay is applied

5. `.mcp-variant` is forced to `abap`

6. ABAP package identity is patched

7. Commit is pushed to `abap-mcp-server/main`

Required secret in `mcp-sap-docs` repo:

• `ABAP_REPO_SYNC_TOKEN`

Commit message controls:

• `[skip-sync]` skips sync workflow

Deployment Model

• `mcp-sap-docs`: upstream implementation + sync trigger
• `abap-mcp-server`: deployment trigger remains push-to-main in that repository

This preserves ABAP deployment automation while keeping one shared upstream codebase.

PM2 Runtime

`ecosystem.config.cjs` is variant-aware and resolves:

• process names
• ports
• deploy path

from `config/variants/*.json`.

Validation Commands

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

Additional Docs

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

[werkbank-badge]: assets/add-to-werkbank.svg

[werkbank-install]: https://getwerkbank.com/install-mcp?name=sap-docs&config=eyJ0eXBlIjoic3RyZWFtYWJsZV9odHRwIiwidXJsIjoiaHR0cHM6Ly9tY3Atc2FwLWRvY3MubWFyaWFuemVpcy5kZS9tY3AiLCJkZXNjcmlwdGlvbiI6IlNBUCBkb2N1bWVudGF0aW9uLCBub3RlcyBhbmQgY29tbXVuaXR5IHNlYXJjaCJ9