sap-bdc-mcp 0.1.0

Model Context Protocol (MCP) server for SAP Business Data Cloud (BDC): contract-first, safe-by-default tooling for AI agents.

SAP Business Data Cloud MCP Server (sap-bdc-mcp)

An MCP (Model Context Protocol) server that exposes safe, well-scoped SAP Business Data Cloud (BDC) discovery + contract tooling for AI agents (Cursor, Claude Desktop, LibreChat, etc.) — with enterprise-first guardrails (redaction, policy gating, bounded outputs, and read-only defaults).

Release: v0.1.0
Focus (v0.1): contract-first open-core foundation — ORD discovery, CSN contract checks, and share planning (non-executing).

---

Why this exists

Modern enterprises increasingly want AI agents to act — not just chat. But real enterprise action requires:

• controlled access to systems of record,
• strict governance and auditability,
• safe defaults (no accidental writes),
• predictable, machine-readable tool contracts.

MCP provides the standard “tool bus” that lets external clients call tools safely. This project provides that tool bus specifically for SAP Business Data Cloud so agents can:

• discover data products and resources (ORD),
• validate and diff schema contracts (CSN),
• plan data sharing contracts before execution (share plans),
• operate safely (redaction + permissions + bounded outputs).

---

Where sap-bdc-mcp fits in the enterprise landscape

In most enterprise setups, you’ll have:

• AI clients (Cursor, Claude Desktop, LibreChat, internal copilots)
• MCP servers (tool providers) running inside a controlled network boundary
• SAP platforms (BDC, Datasphere, BW, etc.)
• Governance (identity, policies, approvals, logging, DLP)

SAPBDCMCP is intended to run inside your boundary (developer laptop, jump host, or a controlled runtime) and act as the policy-gated integration layer between agentic tooling and SAP BDC.

A typical flow:

1. User asks an AI client to find / validate / plan something.
2. The client calls MCP tools exposed by sap-bdc-mcp.
3. The server enforces:
   • output size limits,
   • redaction of secrets,
   • permission levels (READ/WRITE/ADMIN),
   • “no writes by default”.
4. Results are returned to the client in structured form.

Important: v0.1 focuses on read-only and contract-first operations. It does not execute shares or mutate BDC resources.

---

Architecture (plugin-based, safety-first)

This repository follows a plugin-friendly pattern inspired by the SAP Datasphere MCP server approach: core server + modular tool packs, with shared safety primitives.

Component view

MCP Client (Cursor / Claude / LibreChat)
            |
            | stdio (v0.1)
            v
+---------------------------+
|  FastMCP Server           |
|  (tool registry)          |
+------------+--------------+
             |
             v
+---------------------------+        +--------------------------+
| Policy + Redaction        |        | Connectors / Parsers     |
| - Permission gates        |------->| - ORD loader + search    |
| - Secret redaction        |        | - JSON Schema validation |
| - Output bounds           |        | - CSN validation + diff  |
+------------+--------------+        +--------------------------+
             |
             v
+---------------------------+
| Tool Packs (v0.1)         |
| - Core                    |
| - ORD                     |
| - CSN                     |
| - Share Plan              |
+---------------------------+

Design principles

• Safe defaults: write tools are off unless explicitly enabled.
• Contract-first: validate structures before “doing” anything.
• Composable: tools are grouped into “packs” that can evolve independently.
• Enterprise-friendly: minimal data retention, predictable behavior, and clear boundaries.

---

What’s included in v0.1

Core tooling (safe diagnostics)

• Health + wiring checks
• Configuration diagnostics (with redaction)
• Tenant/user “identity” introspection (mock-friendly)

ORD (Open Resource Discovery)

• Fetch ORD documents from URLs and local files
• Expand ORD Configuration documents (to resolve referenced documents)
• Search resources by type (data products, APIs, events, etc.)
• Validate documents against shipped JSON Schemas

CSN (Common Schema Notation / contract checks)

• Validate CSN structure for interoperability / tooling assumptions
• Diff CSNs to detect breaking vs non-breaking changes
• Render CSN → Markdown documentation (quick contract docs)

Share planning (non-executing)

• Build share plan objects with a stable contract shape
• Validate share plans against safety limits (asset limits, duplicates, required fields)
• No execution in v0.1 (planning + validation only)

---

Installation

Install from PyPI (recommended)

pip install sap-bdc-mcp

Install from source (development)

git clone https://github.com/rahulsethi/SAPBDCMCP.git
cd SAPBDCMCP
python -m venv .venv
# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Prerequisites

• Python 3.11+
• pip

Install from source (recommended for v0.1)

git clone https://github.com/rahulsethi/SAPBDCMCP.git
cd SAPBDCMCP

python -m venv .venv

# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1

# macOS/Linux
# source .venv/bin/activate

pip install -e ".[dev]"

Environment file (optional)

cp .env.example .env

---

Configuration

The server is configured via environment variables (or a .env file).

Required (for v0.1)

Nothing is strictly required — mock mode supports local development without a BDC tenant.

Common settings

Variable	Default	Purpose
BDC_MODE	local	Runtime mode label (local/dev/prod)
BDC_MOCK_MODE	1	Use fixtures/local inputs instead of calling external endpoints
BDC_VERIFY_TLS	1	Verify TLS certificates for HTTPS fetches
BDC_MAX_DOC_KB	512	Max size for fetched ORD docs (prevents “LLM ate my RAM” moments)
BDC_ORD_SOURCES	(empty)	Comma-separated list of ORD sources (URLs or file paths)
BDC_PLUGINS	(empty)	Comma-separated plugin module paths to load
BDC_ENABLE_WRITE_TOOLS	0	Enables write tools (keep OFF in v0.1)

Optional tenant identity (informational in v0.1)

Variable	Purpose
BDC_TENANT_ID	Tenant identifier (redacted in outputs)
BDC_REGION	Region label
BDC_BASE_URL	Base URL label (redacted where appropriate)
BDC_USER	User label (redacted)
BDC_SERVICE_ACCOUNT	Service account label (redacted)

---

Running the server

Stdio mode (default)

sap-bdc-mcp

This starts the MCP server on stdio, suitable for:

• Cursor MCP integration
• Claude Desktop MCP servers
• LibreChat MCP connectors
• custom MCP clients

Alternative entry (useful for debugging)

python -m sap_bdc_mcp

---

Using from MCP clients

Cursor

This repo includes a Cursor MCP configuration file at .cursor/mcp.json.

Typical workflow:

1. Open the repository in Cursor
2. Ensure your venv is active and dependencies are installed
3. Cursor will detect MCP config and can start the server automatically

Claude Desktop

Add an MCP server entry (stdio) and point it to your environment’s sap-bdc-mcp executable.

LibreChat

Configure an MCP server as a stdio tool provider and run it inside the same host/container boundary as LibreChat.

Exact configuration formats differ by client; the important invariant is: this server speaks MCP over stdio in v0.1.

---

Tool catalog (v0.1)

This section is intentionally detailed so you can:

• understand expected inputs/outputs,
• write deterministic agent prompts,
• validate behavior without a BDC tenant.

Core tools

bdc_ping

Purpose: lightweight health check for server wiring and config surface.

Returns (example):

{
  "ok": true,
  "server": "sap-bdc-mcp",
  "version": "0.1.0",
  "mode": "local",
  "mock_mode": true,
  "write_enabled": false
}

Test prompts:

• “Call bdc_ping and tell me whether write tools are enabled.”
• “Check if the SAP BDC MCP server is alive and report version + mode.”

---

bdc_diagnostics

Purpose: structured readiness report (all sensitive values redacted).

Returns (high level):

• runtime mode, TLS settings, limits
• ORD source configuration
• plugin status
• redacted environment summary

Test prompts:

• “Run bdc_diagnostics and summarize what is configured vs missing.”
• “Show me current safety limits and plugin status.”

---

bdc_get_tenant_info

Purpose: returns configured tenant labels (redacted), useful for client sanity checks.

Returns (high level):

• tenant id, region, base url (if configured)
• mode + mock mode

Test prompts:

• “Use bdc_get_tenant_info and confirm whether a tenant is configured.”
• “Show tenant metadata (redacted) and current mode.”

---

bdc_whoami

Purpose: returns identity labels (mock identity in mock mode).

Returns (high level):

• user / service account identity (redacted)
• mock identity when BDC_MOCK_MODE=1

Test prompts:

• “Call bdc_whoami and tell me who this server thinks it is.”
• “Show identity info, but ensure secrets are not displayed.”

---

ORD tools (Open Resource Discovery)

bdc_ord_fetch_documents

Purpose: fetch ORD documents from sources (URLs or local files). Supports ORD Configuration expansion.

Parameters:

• sources (optional): list of URLs/file paths. If omitted, uses BDC_ORD_SOURCES.

Returns:

• document count
• full ORD documents (expanded if configuration docs are used)

Test prompts:

• “Fetch ORD docs from the configured sources, then summarize how many documents were loaded.”
• “Load the local ORD sample fixture and list the available resource types.”

---

bdc_ord_search

Purpose: search across loaded ORD documents.

Parameters:

• query (required): search query string
• resource_type (optional): default dataProduct
  (e.g., apiResource, eventResource, entityType, capability)
• sources (optional): override sources (defaults to config)
• limit (optional): default 25

Returns:

• query + resource_type
• count
• matching resources (ordId, title, description, metadata)

Test prompts:

• “Search ORD for data products matching ‘finance’ and show top 5.”
• “Search for ‘sales’ in apiResource and summarize results.”
• “Find entity types containing ‘Customer’ and list ordIds.”

---

bdc_ord_validate

Purpose: validate ORD documents against JSON Schema.

Parameters:

• sources (optional): list of sources to validate (defaults to config)

Returns:

• ok/not ok
• issues with paths + messages (capped per document)

Test prompts:

• “Validate the currently configured ORD sources and report any schema errors.”
• “Validate the ORD fixture and show me the first 10 issues (if any).”

---

CSN tools (Common Schema Notation)

bdc_csn_validate

Purpose: validate a CSN object for tooling compatibility.

Parameters:

• csn (required): CSN JSON object

Returns:

• ok/not ok
• issues with codes + messages

Test prompts:

• “Validate this CSN and explain what’s missing or malformed.”
• “Check whether this CSN is safe to publish as a contract.”

---

bdc_csn_diff

Purpose: compare two CSNs and classify changes.

Parameters:

• old_csn (required)
• new_csn (required)

Returns:

• breaking changes: removals, incompatible type changes, kind changes
• non-breaking changes: additive changes
• summary stats

Test prompts:

• “Diff these two CSNs and list breaking changes first, then non-breaking.”
• “Tell me if upgrading from old_csn to new_csn is backward compatible.”

---

bdc_csn_render_docs

Purpose: render CSN → Markdown documentation (contract docs).

Parameters:

• csn (required)

Returns:

• Markdown string describing entities, fields, types, constraints

Test prompts:

• “Generate Markdown docs for this CSN and include entity + field summaries.”
• “Create a compact schema reference for this CSN.”

---

Share planning tools (non-executing in v0.1)

bdc_share_plan

Purpose: create a share plan object (does not execute anything).

Parameters:

• share_name (required)
• assets (required): list of assets:
  • type: table | view | file
  • name: asset identifier
  • schema (optional): namespace/schema
  • comment (optional)
• description (optional)
• provider (optional): default sap-bdc

Returns:

• normalized, validated share plan object

Test prompts:

• “Create a share plan called ‘demo_share’ with 2 tables in schema ‘FIN’.”
• “Generate a share plan for these assets and return the resulting JSON.”

---

bdc_share_validate_contract

Purpose: validate a share plan contract and safety limits.

Parameters:

• plan (required): share plan JSON

Validations:

• required fields + structure
• max asset count (50)
• duplicate asset detection
• asset naming/shape checks

Returns:

• ok/not ok
• issues list (if any)

Test prompts:

• “Validate this share plan and tell me what I need to fix.”
• “Check whether this plan exceeds safety limits or contains duplicates.”

---

Testing & quality

Run tests

pytest

Run with coverage

pytest --cov=src/sap_bdc_mcp --cov-report=term-missing

Test coverage (v0.1): 100% statement coverage for src/sap_bdc_mcp is the quality bar for this repo (and should remain enforced as changes land).
If you ever see lower numbers, treat it as a regression and tighten tests before merging.

---

Safety, security, and governance notes

This project is designed to be safe by default, but enterprise safety is a system property, not a single feature. Recommended posture:

Safe defaults baked in

• Write tools disabled by default (BDC_ENABLE_WRITE_TOOLS=0)
• Automatic secret redaction across tool outputs
• Bounded outputs to prevent oversized data egress
• Mock mode to develop without connecting to production

Data handling expectations

• v0.1 tools focus on discovery + contract validation, not data movement.
• The server is intended to run within your controlled boundary.
• When future versions add live BDC operations, they should be deployed with:
  • least-privileged service accounts,
  • strict network controls,
  • centralized logging/monitoring,
  • approvals for write actions (where appropriate).

Redaction scope

The server automatically redacts common sensitive patterns including:

• API keys, secrets, passwords
• bearer tokens
• credentials embedded in URLs
• fields with sensitive key names

If you are deploying this inside an enterprise, treat this as one layer of defense-in-depth, not a substitute for DLP, IAM, and network security.

---

Contributing

Contributions are welcome. Please see CONTRIBUTING.md.

---

License

MIT — see LICENSE.