# SAP Datasphere MCP Server

A TypeScript [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that enables AI assistants like Claude and Cursor to interact with SAP Datasphere for data exploration, querying, and administration.

**49 tools | 4 resources | 4 prompts | Mock data mode for instant development**

## Features

- **Catalog & Discovery** — List spaces, search assets, explore schemas
- **Data Querying** — Query views and analytic models with full OData V4 support ($select, $filter, $orderby, $top, $skip, $count)
- **Space Management** — Create, read, update, delete spaces
- **Modeling Objects** — Full CRUD for 14 object types (tables, views, analytic models, data flows, task chains, etc.)
- **Connections** — Manage and validate data connections
- **User Management** — SCIM 2.0 users + database users
- **Role Management** — Global roles and scoped roles with member/space assignment
- **Task Execution** — Run task chains, check logs, view execution history
- **Repository** — Browse repository objects and deployed objects with runtime metrics
- **Audit** — Export audit log entries
- **Diagnostics** — Test connectivity, check server health

## Quick Start

```bash
# Clone and install
git clone <this-repo>
cd mcp-datasphere-tools
npm install

# Configure credentials
cp .env.example .env
# Edit .env with your Datasphere OAuth credentials (see Configuration below)

# Build and run
npm run build
npm start
```

## Configuration

### 1. Create OAuth Credentials

Create credentials via **SAP Datasphere UI** (not BTP service keys):
1. Log into SAP Datasphere
2. Go to **System → Administration → App Integration**
3. Create a new **OAuth2.0 Client** (Technical User)
4. Copy the **Client ID**, **Client Secret**, and **Token URL**

### 2. Configure `.env`

Copy `.env.example` to `.env` and fill in your credentials:

```env
DATASPHERE_BASE_URL=https://<tenant-id>.eu30.hcs.cloud.sap
DATASPHERE_CLIENT_ID=<oauth-client-id>
DATASPHERE_CLIENT_SECRET=<oauth-client-secret>
DATASPHERE_TOKEN_URL=https://<tenant-id>.authentication.eu30.hana.ondemand.com/oauth/token
USE_MOCK_DATA=false
LOG_LEVEL=info
CACHE_TTL_SECONDS=300
```

Authentication uses `client_credentials` grant type — fully non-interactive, no browser login required.

Set `USE_MOCK_DATA=true` to explore all 49 tools without any SAP credentials.

## Integration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sap-datasphere": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-datasphere-tools/src/index.ts"]
    }
  }
}
```

### Cursor IDE

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "sap-datasphere": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"]
    }
  }
}
```

## Tools Reference (49)

| Category | Tools | Count |
|---|---|---|
| Catalog & Discovery | `list_spaces`, `get_space_info`, `list_space_assets`, `get_asset_details`, `search_assets`, `search_catalog` | 6 |
| Data Querying | `query_view`, `query_analytic_model`, `get_view_metadata`, `get_model_metadata` | 4 |
| Space Management | `read_space_definition`, `create_space`, `update_space`, `delete_space` | 4 |
| Modeling Objects | `list_modeling_objects`, `read_modeling_object`, `create_modeling_object`, `update_modeling_object`, `delete_modeling_object` | 5 |
| Connections | `list_connections`, `get_connection`, `test_connection`, `create_connection`, `delete_connection` | 5 |
| User Management | `list_users`, `get_user`, `create_user`, `update_user`, `delete_user`, `list_database_users`, `create_database_user`, `delete_database_user` | 8 |
| Role Management | `list_global_roles`, `list_global_role_users`, `manage_global_role_users`, `list_scoped_roles`, `read_scoped_role`, `manage_scoped_role`, `manage_scoped_role_members` | 7 |
| Task Management | `run_task_chain`, `get_task_log`, `get_task_history` | 3 |
| Repository | `list_repository_objects`, `get_object_definition`, `get_deployed_objects` | 3 |
| Audit | `export_audit_log` | 1 |
| Diagnostics | `test_connectivity`, `get_tenant_info`, `get_server_status` | 3 |

## Architecture

```
MCP Client (Claude/Cursor)
  ↓ stdio
McpServer (49 tools, 4 resources, 4 prompts)
  ↓
Handler Classes (11, extend BaseHandler) → Zod validation → SQL sanitization
  ↓
API Clients (11 classes) → Mock mode → Cache → Real API
  ↓
DatasphereClient → OAuth 2.0 + CSRF → axios → SAP Datasphere APIs
```

**Key patterns:**
- Handler Classes: each domain has a handler extending `BaseHandler` with `getTools()` and `handle()`
- Dependency Injection: API clients passed via handler constructor, no globals
- Mock-First: all tools work without credentials via `USE_MOCK_DATA=true`
- Caching: TTL-based in-memory cache (catalog 5min, queries 2min)
- Type Safety: TypeScript + Zod runtime validation

## Development

```bash
npm run dev       # Hot reload with tsx
npm run build     # Compile TypeScript
npm start         # Run production build
npm run inspect   # MCP Inspector UI
```

## Supported Object Types (Modeling)

local-tables, remote-tables, views, analytic-models, data-flows, replication-flows, transformation-flows, task-chains, intelligent-lookups, er-models, data-access-controls, business-entities, fact-models, consumption-models

## Reference

Inspired by [MarioDeFelipe/sap-datasphere-mcp](https://github.com/MarioDeFelipe/sap-datasphere-mcp) (Python, 48 tools). This TypeScript implementation provides a clean, type-safe, handler-based architecture with 49 tools.

## License

ISC