> ## ⚠️ This repository is obsolete
>
> **[MCP-Datasphere-InteractiveUser](https://github.com/DimiDR/MCP-Datasphere-InteractiveUser)** replaces this project and [SAP-Datasphere-CLI](https://github.com/DimiDR/SAP-Datasphere-CLI). That MCP covers **both** former functions in one place:
>
> | Former repo | What it did |
> |---|---|
> | [SAP-Datasphere-MCP](https://github.com/DimiDR/SAP-Datasphere-MCP) (this repo) | Consumption / catalog — read rows, search, query |
> | [SAP-Datasphere-CLI](https://github.com/DimiDR/SAP-Datasphere-CLI) | Design-time / admin via the official `datasphere` CLI |
>
> Use **[github.com/DimiDR/MCP-Datasphere-InteractiveUser](https://github.com/DimiDR/MCP-Datasphere-InteractiveUser)** instead. This repository is no longer maintained.

# 🚀 SAP Datasphere MCP Server

> **CLI + MCP are a combo.** This repo owns **consumption / catalog** (read rows, search, profile). Its counterpart owns **design-time / admin** (create and change objects). Use them together — not as alternatives.
>
> | Half | Repository |
> |---|---|
> | **MCP** (this repo) | [DimiDR/SAP-Datasphere-MCP](https://github.com/DimiDR/SAP-Datasphere-MCP) |
> | **CLI** | [DimiDR/SAP-Datasphere-CLI](https://github.com/DimiDR/SAP-Datasphere-CLI) |

[![PyPI version](https://badge.fury.io/py/sap-datasphere-mcp.svg)](https://pypi.org/project/sap-datasphere-mcp/)
[![npm version](https://img.shields.io/npm/v/@mariodefe/sap-datasphere-mcp.svg)](https://www.npmjs.com/package/@mariodefe/sap-datasphere-mcp)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP Protocol](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> Model Context Protocol server that lets AI assistants explore and query SAP Datasphere — metadata discovery, catalog search, OData and SQL queries, ETL extraction, data lineage and column profiling — with built-in config-driven PII masking so sensitive fields never reach the LLM.

**Version 1.4.0** · 42 tools advertised by default (51 with `DATASPHERE_TOOL_PROFILE=full`)

> 🙌 **Shout-out:** this repository is a modified copy of
> [MarioDeFelipe/sap-datasphere-mcp](https://github.com/MarioDeFelipe/sap-datasphere-mcp).
> All credit for the original server goes to Mario de Felipe — this fork adapts it
> for a specific tenant setup and CLI integration.

---

## 🤝 Relationship to the SAP Datasphere CLI

This server and the `@sap/datasphere-cli` are complementary halves, not
alternatives. They reach **different API families**, and nearly every difference
follows from that:

| | Reaches | Therefore owns |
|---|---|---|
| **MCP server** (this repo) | Consumption and Catalog APIs | Reading data and metadata, catalog search, profiling |
| **CLI** | Design-time and admin APIs | Creating and changing objects, tenant administration |

### What each side does

| Function | MCP | CLI |
|---|---|---|
| **Read data rows** | **yes** — `execute_query`, `smart_query`, `query_relational_entity`, `query_analytical_data` | **no** — no command returns table contents |
| Catalog search, asset lookup | `search_catalog`, `find_assets_by_column`, `get_asset_details`, … | — |
| Column profiling, distributions, outliers | `analyze_column_distribution` | — |
| Analytical/relational metadata (dimensions vs. measures, OData→SQL types) | `get_analytical_metadata`, `get_relational_metadata` | — |
| PII masking, SQL sanitizing, consent gating, audit logging | **yes** | — |
| Create/change/delete modeling objects (18 types) | local tables only (`create_table`) | **yes** |
| Spaces, users, global & scoped roles, workload, certificates | read-only or not at all | **yes** |
| Connections: create/change | read-only (`list_connections`, `test_connection`) | **yes** |
| Read an object **definition** (CSN) | — | `objects <type> read` |
| See deployed but non-exposed objects | via CLI (`list_repository_objects`) | `objects <type> list` |
| Task chains, task logs | `run_task_chain`, `get_task_log`, `get_task_status`, `get_task_history` | `tasks …` |
| Database users | `create_database_user`, … | `dbusers` |

**The CLI cannot read data rows** — that is this server's reason to exist.
**This server does not create objects**, apart from local tables (`create_table`),
because the payload there is derived from data it has already read. Views,
analytic models, flows, spaces, users and roles belong to the CLI.

Neither writes data rows. Rows arrive through a data/replication flow, a database
user with a SQL client, or a CSV upload in the Data Builder UI. Neither manages
folders — those are UI-only.

### How they combine in practice

A typical build-then-verify loop:

1. **CLI** creates the layers — staging/cleansing/integration views, target
   tables, transformation flows, task chain, analytic model.
2. **CLI** runs the chain and reports task status.
3. **MCP** verifies the *result*: row counts, value distributions, whether data
   quality flags actually fire — everything the CLI structurally cannot see.
4. Findings flow back into step 1 as CSN changes.

Keep the visibility gap in mind: Consumption and Catalog endpoints only show
objects that are deployed **and** exposed for consumption. A view that exists in
the repository but is not exposed is invisible here while the CLI still sees it —
that is what `list_repository_objects` exists for.

| Guide | Content |
|---|---|
| [docs/MCP_VS_CLI.md](docs/MCP_VS_CLI.md) | Authoritative capability split and routing rules |
| [docs/TENANT_CONFIG.md](docs/TENANT_CONFIG.md) | The two config files, two OAuth clients, and App Integration screenshots |
| [docs/CLI_LINEAGE_LOOKUP.md](docs/CLI_LINEAGE_LOOKUP.md) | Finding objects the Consumption API cannot see |

A few tools shell out to the CLI (`create_table`, the `*_database_user*` tools,
`list_repository_objects`). The CLI keeps its **own** session, separate from this
server's OAuth credentials — check it with the `datasphere_cli_status` tool.

---

## 🚀 Quick Start

```bash
# npm
npm install -g @mariodefe/sap-datasphere-mcp && npx @mariodefe/sap-datasphere-mcp

# PyPI
pip install sap-datasphere-mcp && sap-datasphere-mcp

# From source
git clone https://github.com/MarioDeFelipe/sap-datasphere-mcp.git
cd sap-datasphere-mcp
pip install -r requirements.txt && pip install -e .
cp .env.example .env      # fill in your credentials
sap-datasphere-mcp
```

Full walkthrough: [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) ·
OAuth setup: [docs/OAUTH_SETUP.md](docs/OAUTH_SETUP.md)

### Configuration

```bash
DATASPHERE_BASE_URL=https://your-tenant.eu10.hcs.cloud.sap
DATASPHERE_TENANT_ID=your-tenant-id
DATASPHERE_CLIENT_ID=your-client-id
DATASPHERE_CLIENT_SECRET=your-client-secret
DATASPHERE_TOKEN_URL=https://your-tenant.authentication.eu10.hana.ondemand.com/oauth/token
USE_MOCK_DATA=false
```

Optional settings for the CLI-backed tools (`DATASPHERE_CLI_PATH`, `_HOST`,
`_SECRETS_FILE`) are documented in [`.env.example`](.env.example) and
[docs/TENANT_CONFIG.md](docs/TENANT_CONFIG.md).

**Never commit `.env`.**

### Claude Desktop

```json
{
  "mcpServers": {
    "sap-datasphere": {
      "command": "npx",
      "args": ["@mariodefe/sap-datasphere-mcp"],
      "env": {
        "DATASPHERE_BASE_URL": "https://your-tenant.eu20.hcs.cloud.sap",
        "DATASPHERE_CLIENT_ID": "your-client-id",
        "DATASPHERE_CLIENT_SECRET": "your-client-secret",
        "DATASPHERE_TOKEN_URL": "https://your-tenant.authentication.eu20.hana.ondemand.com/oauth/token"
      }
    }
  }
}
```

Config location — Windows: `%APPDATA%\Claude\claude_desktop_config.json` ·
macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` ·
Linux: `~/.config/Claude/claude_desktop_config.json`

---

## 🛠️ Tool Catalog

42 tools in the default `lean` profile. Set `DATASPHERE_TOOL_PROFILE=full` to
also advertise overlapping metadata tools, and `DATASPHERE_EXPOSE_DIAGNOSTICS=true`
for the endpoint probes — 51 in total. Hiding them by default improves the
model's tool selection; every handler stays reachable.

### Foundation (5)
`test_connection` · `get_current_user` · `get_tenant_info` · `get_available_scopes` · `list_spaces`

### Space discovery (3)
`get_space_info` · `get_table_schema` · `search_tables`

### Catalog and search (5)
`list_catalog_assets` · `get_asset_details` · `get_asset_by_compound_key` · `get_space_assets` · `search_catalog`

Catalog search runs client-side: `/catalog/search` returns 404 on the tenants
tested, so these tools fetch assets and filter locally across name, label,
businessName and description.

### Data discovery and quality (2)
| Tool | Purpose |
|---|---|
| `find_assets_by_column` | Which assets contain a given column — lineage and impact analysis across spaces |
| `analyze_column_distribution` | Null rate, distinct values, percentiles, IQR outlier detection |

### Querying data (4)
| Tool | Purpose |
|---|---|
| `smart_query` | SQL router: picks analytical vs relational, falls back to client-side aggregation when the asset cannot aggregate |
| `execute_query` | SELECT over one entity (columns/`*`, WHERE, ORDER BY, LIMIT), max 1000 rows. JOIN / GROUP BY / aggregates are rejected with a pointer to the right tool |
| `query_relational_entity` | Relational OData, up to 50,000 records per batch for ETL |
| `query_analytical_data` | Analytical OData with `$apply`, `$filter`, `$orderby` |

Supported SQL: `SELECT *`/column lists, `WHERE`, `LIMIT`, `GROUP BY`,
aggregations with and without grouping, `ORDER BY`. No JOINs — OData is
single-entity. Names are case-sensitive.

### Metadata (7)
`get_relational_metadata` · `list_relational_entities` · `get_relational_entity_metadata` ·
`get_analytical_metadata` · `get_analytical_model` · `list_analytical_datasets` · `get_asset_variables`

`get_relational_entity_metadata` maps OData types to SQL (`Edm.String` →
`NVARCHAR(MAX)`, `Edm.Int64` → `BIGINT`, `Edm.Decimal` → `DECIMAL(18,2)`, …) for
data-warehouse loading. `get_asset_variables` surfaces input parameters a
parameterised view or analytic model expects.

### Repository (3)
| Tool | Purpose |
|---|---|
| `list_repository_objects` | Lists design-time objects **via the CLI**, so it also sees objects not exposed for consumption |
| `get_deployed_objects` | Deployed objects in a space |
| `get_object_definition` | Object definition (deprecated — prefer `get_asset_details`) |

### Database users (5) — CLI-backed
`list_database_users` · `create_database_user` · `update_database_user` ·
`delete_database_user` · `reset_database_user_password`

High-risk operations require consent, cached for 60 minutes.

### Tasks (4)
`get_task_status` · `run_task_chain` · `get_task_log` · `get_task_history`

### Object provisioning (1) — CLI-backed
`create_table` — builds a CSN definition from your column list and runs
`datasphere objects local-tables create`. Local tables only; see the CLI split above.

### Operations (4)
`list_connections` · `browse_marketplace` · `datasphere_cli_status` · `get_relational_odata_service` *(full profile)*

`datasphere_cli_status` reports whether the CLI is installed, which version, which
host, and whether a session exists. Run it first when a CLI-backed tool fails.

---

## 🔏 PII / Sensitive-Field Masking

A config-driven, **fail-closed** masking layer runs inside the response pipeline.
Every data-returning tool (`smart_query`, `query_relational_entity`,
`query_analytical_data`, `get_space_assets`, `analyze_column_distribution`) funnels
results through `apply_masking()` before they reach the LLM. No prompt bypasses it.

> **Defense in depth.** The authoritative access control stays upstream — SAP
> Datasphere Data Access Controls, and not granting the technical user access to
> PII tables. This layer is the enforced, auditable net on top.

| Environment variable | Values | Default | Purpose |
|---|---|---|---|
| `DATASPHERE_PII_POLICY` | path to YAML or JSON | *(unset)* | Policy file. **Unset = masking fully disabled.** |
| `DATASPHERE_PII_MODE` | `enforce` \| `audit_only` \| `off` | `enforce` when a policy is present | `audit_only` logs what would be masked without changing data |
| `DATASPHERE_PII_SALT` | secret string | *(empty)* | Salt for deterministic `hash`/`tokenize`. **Treat as a secret.** |

If the policy file is configured but missing or unparseable, the server raises at
startup and refuses to run. It never silently serves raw data with a broken policy.

```yaml
mode: enforce
default_action: redact

rules:
  # Most specific wins: asset > space > global; exact > glob
  - space: ZDCS_08
    asset: ZR_SAP_CUSTOMER
    columns:
      EMAIL:  redact       # → "***"
      PHONE:  partial:4    # keep last 4 → "******1234"
      TAXID:  hash         # sha256(salt:value) — deterministic, safe for GROUP BY
      SSN:    drop         # column removed from every row
  - space: "*"
    columns:
      "*IBAN*": tokenize   # glob on column name → "TKN_<8hex>"

allowlist:
  enabled: true
  assets:
    ZDCS_08.ZR_OTC_CUST_MONTH: [CUSTOMER, MONTH, REVENUE]   # ONLY these returned

patterns:
  email: '[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}'
  iban:  '\b[A-Z]{2}\d{2}[A-Z0-9]{10,30}\b'
```

**Precedence:** allowlist (drops everything unlisted) → column rules → value-pattern
scan on remaining strings.

**Audit log** — one structured line per call, values never logged:

```
[pii_masking] space=ZDCS_08 asset=ZR_SAP_CUSTOMER rows=42
              masked_fields=['EMAIL', 'PHONE', 'SSN'] mode=enforce
```

The response also carries `masked_fields`, so the client can see what was withheld.
Annotated example: [`pii_policy.yaml`](pii_policy.yaml).

---

## 🔒 Security

**Authentication** — OAuth 2.0 client credentials, tokens refreshed 60s before
expiry and encrypted in memory (Fernet). No credentials in code.

**Authorization** — four permission levels (READ, WRITE, ADMIN, SENSITIVE),
interactive consent for high-risk operations, full audit logging.

**Query safety** — the SQL sanitizer is fail-closed on `SELECT`:
`INSERT`/`UPDATE`/`DELETE`/`DROP` and SQL comments are blocked, along with 15+
injection patterns. Write paths do not exist.

---

## 🌐 Transports

stdio by default; Streamable HTTP (spec 2025-03-26) at `/mcp` for long-lived
service deployments.

| Flag | Env var | Default | Purpose |
|---|---|---|---|
| `--transport` | `MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
| `--host` | `MCP_HTTP_HOST` | `127.0.0.1` | Bind address |
| `--port` | `MCP_HTTP_PORT` | `8080` | Bind port |
| `--path` | `MCP_HTTP_PATH` | `/mcp` | Endpoint path |
| `--auth-token` | `MCP_HTTP_AUTH_TOKEN` | *(none)* | Require `Authorization: Bearer <token>` |

```bash
pip install 'sap-datasphere-mcp[http]'
sap-datasphere-mcp --transport http --port 8080
```

The server warns when bound to a non-loopback interface without a token.
`/health` serves a plain JSON liveness probe.

---

## 📊 Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │◄──►│   MCP Server     │◄──►│  SAP Datasphere │
│ (Claude, Cursor)│    │  Authorization   │    │   (OAuth 2.0)   │
│                 │    │  PII masking     │    │                 │
│                 │    │  Caching         │    │  datasphere CLI │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

```
src/sap_datasphere_mcp/
├── server.py              # MCP server and all tool handlers
├── cli_runner.py          # Single entry point for `datasphere` CLI calls
├── pii_masking.py         # Config-driven, fail-closed masking
├── cache_manager.py       # TTL cache
├── telemetry.py           # Request metrics
├── tool_descriptions.py   # Tool metadata
├── error_helpers.py       # Error formatting
├── auth/
│   ├── oauth_handler.py             # Token management and refresh
│   ├── datasphere_auth_connector.py # Authenticated API connector
│   ├── authorization.py             # Permission levels
│   ├── consent_manager.py           # Consent tracking
│   ├── input_validator.py           # Input validation
│   ├── sql_sanitizer.py             # SELECT-only enforcement
│   └── data_filter.py               # Credential redaction
└── config/settings.py     # Environment-based settings
```

**Caching TTLs** — spaces 1h · assets 30min · metadata 15min · users 5min, LRU eviction.

**Response times** — cached metadata under 100ms · catalog 100–500ms ·
OData queries 500–2000ms depending on volume.

---

## 🧪 Testing

```bash
pytest                                              # full suite
pytest tests/test_cli_runner.py                     # CLI integration layer
npx @modelcontextprotocol/inspector sap-datasphere-mcp
```

`tests/test_cli_runner.py` verifies every CLI command the server hardcodes
against the `--help` dumps in the DataphereCLI repo. Point
`DATASPHERE_CLI_HELP_DIR` at `tools/cli-help` to enable it; it skips otherwise.

**Known failure:** `tests/test_mcp_server.py` uses `await server.list_resources()()`,
an idiom the current MCP SDK no longer supports. Pre-existing, unrelated to the
server itself.

---

## 🚀 Deployment

```bash
docker build -t sap-datasphere-mcp:latest .
docker run -d --name sap-mcp --env-file .env sap-datasphere-mcp:latest
# or
docker-compose up -d
```

Full guide incl. Kubernetes: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)

---

## 📚 Documentation

| Guide | Content |
|---|---|
| [Getting Started](docs/GETTING_STARTED.md) | Setup walkthrough with examples |
| [API Reference](docs/API_REFERENCE.md) | Technical API docs, Python and cURL |
| [OAuth Setup](docs/OAUTH_SETUP.md) | App Integration and OAuth client |
| [Tenant Config](docs/TENANT_CONFIG.md) | Config files, the two identities |
| [MCP vs CLI](docs/MCP_VS_CLI.md) | Which tool owns which task |
| [CLI Lineage Lookup](docs/CLI_LINEAGE_LOOKUP.md) | Objects invisible to Consumption |
| [Deployment](docs/DEPLOYMENT.md) | Docker, Kubernetes, PyPI |
| [Developer Guide](docs/DEVELOPER_GUIDE.md) | Contributing to the codebase |
| [Changelog](CHANGELOG.md) | Version history |

---

## 🙏 Acknowledgments

This repository started as a modified copy of
[MarioDeFelipe/sap-datasphere-mcp](https://github.com/MarioDeFelipe/sap-datasphere-mcp).
Shout-out to Mario de Felipe for the original server — the tool catalog, PII
masking design and OAuth flow this fork builds on all trace back there.

Built with [Amazon Kiro](https://aws.amazon.com/kiro/) (specifications and
architectural steering) and [Claude Code](https://claude.ai/claude-code) (security
and authentication, tool descriptions and error handling, caching and telemetry,
repository and analytics tools, CLI integration layer).

---

## 📄 License

MIT — see [LICENSE](LICENSE).

## 📞 Support

[Issues](https://github.com/MarioDeFelipe/sap-datasphere-mcp/issues) ·
[Discussions](https://github.com/MarioDeFelipe/sap-datasphere-mcp/discussions) ·
[SAP Datasphere docs](https://help.sap.com/docs/SAP_DATASPHERE) ·
[Model Context Protocol](https://modelcontextprotocol.io/)