# mcp-sac-tools

MCP (Model Context Protocol) server for **SAP Analytics Cloud** — enables AI assistants to interact with SAC stories, models, data, users, and audit logs via the SAC REST API.

**27 tools** across 7 categories: stories, data export, data import, user/team management (SCIM 2.0), audit, resources, and diagnostics.

## Features

### Stories & Resources
- **sac_list_stories** / **sac_get_story** — Browse stories with optional model metadata
- **sac_list_resources** / **sac_get_resource** — List content resources (stories, models, folders)

### Data Export (Read)
- **sac_list_models** — List all models/providers on the tenant
- **sac_get_model_metadata** — Get model schema (dimensions, measures, types)
- **sac_read_fact_data** — Query fact data with OData filtering, paging, column selection
- **sac_read_master_data** — Read dimension member master data
- **sac_read_audit_data** — Read model-level change logs

### Data Import (Write)
- **sac_create_import_job** — Allocate a staging area for data import
- **sac_post_import_data** — Push rows to staging (does not touch model yet)
- **sac_validate_import** — Validate staged data before committing
- **sac_run_import** — Execute import (async)
- **sac_import_status** — Check import job progress
- **sac_import_invalid_rows** — Retrieve rejected rows

### User & Team Management (SCIM 2.0)
- **sac_list_users** / **sac_get_user** / **sac_create_user** / **sac_update_user** / **sac_delete_user**
- **sac_list_teams** / **sac_get_team** / **sac_create_team** / **sac_update_team** / **sac_delete_team**

### Audit & Diagnostics
- **sac_export_audit_activities** — Export tenant audit/login activities
- **sac_server_status** — MCP server health check

## Prerequisites

1. SAP Analytics Cloud tenant with API access enabled
2. OAuth 2.0 client configured in SAC (Administration → App Integration → OAuth Clients)
   - Grant type: **Client Credentials**
   - Note down: Client ID, Client Secret, Token URL
3. Node.js v18+

## Setup

```bash
# Install dependencies
npm install

# Copy and fill in your credentials
cp .env.example .env
# Edit .env with your SAC tenant details

# Build
npm run build

# Test with MCP Inspector
npm run inspect
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|---|---|---|
| `SAC_TENANT_URL` | Yes | SAC tenant URL (e.g. `https://mytenant.eu10.sapanalytics.cloud`) |
| `SAC_TOKEN_URL` | Yes | OAuth token endpoint (e.g. `https://mytenant.authentication.eu10.hana.ondemand.com/oauth/token`) |
| `SAC_CLIENT_ID` | Yes | OAuth client ID |
| `SAC_CLIENT_SECRET` | Yes | OAuth client secret |
| `CACHE_TTL_SECONDS` | No | Cache TTL in seconds (default: 300) |
| `LOG_LEVEL` | No | Log level: info, debug, error (default: info) |

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sap-analytics-cloud": {
      "command": "node",
      "args": ["c:\\path\\to\\mcp-sac-tools\\dist\\index.js"],
      "env": {
        "SAC_TENANT_URL": "https://mytenant.eu10.sapanalytics.cloud",
        "SAC_TOKEN_URL": "https://mytenant.authentication.eu10.hana.ondemand.com/oauth/token",
        "SAC_CLIENT_ID": "your-client-id",
        "SAC_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

## Example Usage

**"Show me all stories"** → calls `sac_list_stories`

**"What data is in the Revenue model?"** → calls `sac_list_models` → `sac_get_model_metadata` → `sac_read_fact_data`

**"List all users"** → calls `sac_list_users`

**"Import this sales data into model X"** → calls `sac_create_import_job` → `sac_post_import_data` → `sac_validate_import` → `sac_run_import`

## Architecture

```
src/
├── index.ts              # Entry point (stdio transport)
├── server.ts             # Server factory (wires APIs → handlers)
├── auth/
│   ├── oauth.ts          # OAuth 2.0 client credentials
│   └── token-manager.ts  # Token caching with auto-refresh
├── api/
│   ├── sac-client.ts     # Authenticated HTTP client (CSRF handling)
│   ├── stories.ts        # /api/v1/stories
│   ├── data-export.ts    # /api/v1/dataexport (OData CDI)
│   ├── data-import.ts    # /api/v1/dataimport
│   ├── scim.ts           # /api/v1/scim2
│   ├── audit.ts          # /api/v1/audit
│   └── resources.ts      # /api/v1/Resources
├── handlers/
│   ├── BaseHandler.ts    # Abstract base (jsonResponse/errorResponse)
│   ├── StoryHandlers.ts
│   ├── DataExportHandlers.ts
│   ├── DataImportHandlers.ts
│   ├── ScimHandlers.ts
│   ├── AuditHandlers.ts
│   ├── ResourceHandlers.ts
│   └── DiagnosticHandlers.ts
├── cache/
│   └── cache-manager.ts  # TTL-based in-memory cache
└── types/
    └── sac.ts            # TypeScript interfaces
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes (`git commit -am 'Add my feature'`)
4. Push to the branch (`git push origin feature/my-feature`)
5. Open a Pull Request

## License

ISC — see [LICENSE](LICENSE) for details.