# AI Core MCP Server

An MCP (Model Context Protocol) server for SAP AI Core, powered by [odata-mcp-proxy](https://www.npmjs.com/package/odata-mcp-proxy). It exposes SAP AI Core APIs as MCP tools, allowing AI assistants like Claude to manage your AI Core landscape through natural language.

The entire server is defined through a single JSON config file -- no custom code required.

## How It Works

This project uses the `odata-mcp-proxy` npm package, which maps OData/REST services to MCP tools based on a configuration file. You provide a config describing your APIs and entity sets, and the proxy generates the corresponding MCP tools automatically.

```
AI Assistant (Claude, Cursor, etc.)
        |
        | MCP Protocol (HTTP or stdio)
        v
  odata-mcp-proxy
        |
        | REST + OAuth2 (via BTP Destination Service)
        v
  SAP AI Core APIs
```

Think of it like the [SAP Application Router](https://www.npmjs.com/package/@sap/approuter) -- a ready-made runtime you configure, not code you write.

## Exposed AI Core APIs

The config file (`ai-core-api-config.json`) defines two API groups:

### Lifecycle Management (`/v2/lm`)

| Tool | Operations | Description |
|------|-----------|-------------|
| `Scenarios` | list, get | AI scenarios -- logical groupings of executables that define a ML use case |
| `ScenarioVersions` | list | Versions of a scenario |
| `Executables` | list, get | Workflow templates (training) and serving templates (inference) under a scenario |
| `Models` | list | Models available in a scenario (e.g. LLMs in the generative AI hub) |
| `Configurations` | list, get, create | Parameter sets binding a scenario/executable to inputs and hyperparameters |
| `Executions` | list, get, create, update, delete | Training or batch inference runs, tracked through lifecycle states |
| `Deployments` | list, get, create, update, delete | Running model-serving instances providing real-time inference endpoints |
| `Artifacts` | list, get, create | Registered references to datasets, models, or files in an object store |
| `ExecutionSchedules` | list, get, create, update, delete | Cron-based schedules that automatically create executions |
| `Metrics` | list, delete | Training and evaluation metrics recorded during executions |
| `Meta` | list | Runtime capabilities, supported features, and API version info |
| `DatasetFiles` | get, create, delete | Upload, download, and delete files in the object store |

### Administration (`/v2/admin`)

| Tool | Operations | Description |
|------|-----------|-------------|
| `Repositories` | list, get, create, update, delete | Onboarded git repos containing workflow/serving templates |
| `Applications` | list, get, create, update, delete | ArgoCD applications that sync git repo content into AI Core |
| `DockerRegistrySecrets` | list, create, update, delete | Credentials for pulling private container images |
| `ObjectStoreSecrets` | list, create, update, delete | Credentials for S3, Azure Blob, GCS, or other object stores |
| `GenericSecrets` | list, get, create, update, delete | Key-value secrets (API keys, tokens) for executions and deployments |
| `ResourceGroups` | list, get, create, update, delete | Tenant isolation units that segregate AI assets and workloads |
| `Services` | list, get | Service broker registrations exposing AI Core capabilities |

## Prerequisites

- **Node.js** 18+ (20+ recommended)
- **SAP BTP account** with SAP AI Core provisioned
- **BTP Destination** configured for the AI Core API (`AI_CORE`) with OAuth2 authentication
- **Cloud Foundry CLI** (`cf`) and **MBT Build Tool** (`mbt`) for deployment

## Project Structure

```
ai-core-mcp-server/
├── package.json                # Start script + odata-mcp-proxy dependency
├── ai-core-api-config.json     # API configuration (defines all MCP tools)
├── mta.yaml                    # BTP Cloud Foundry deployment descriptor
├── xs-security.json            # XSUAA OAuth2 configuration
├── default-env.json            # Local dev credentials (gitignored)
└── LICENSE
```

## Getting Started

### 1. Install dependencies

```bash
npm install
```

### 2. Configure BTP destination

Create a BTP Destination pointing to the AI Core API:

| Destination | URL |
|-------------|-----|
| `AI_CORE` | `https://api.ai.prod.<region>.aws.ml.hana.ondemand.com` |

The destination should use OAuth2 client credentials authentication with the AI Core service key.

### 3. Local development

Create a `default-env.json` with your BTP service bindings (XSUAA, Destination, Connectivity) to run locally:

```bash
npm start
```

This runs `odata-mcp-proxy --config ai-core-api-config.json`.

### 4. Deploy to BTP

```bash
npm run build:btp     # Build MTA archive
npm run deploy:btp    # Deploy to Cloud Foundry
```

The MTA deployment provisions three service instances:
- **Destination** (lite) -- resolves API endpoints and manages OAuth2 tokens
- **Connectivity** (lite) -- enables secure backend connectivity
- **XSUAA** (application) -- handles OAuth2 authentication with role-based access control

## Security

The XSUAA configuration (`xs-security.json`) defines three role templates:

| Role | Scopes | Description |
|------|--------|-------------|
| `MCPViewer` | read | Read-only access |
| `MCPEditor` | read, write | Read and write access |
| `MCPAdmin` | read, write, admin | Full administrative access |

OAuth2 redirect URIs are pre-configured for Claude.ai, Cursor, Microsoft Teams, and local development.

## Creating Your Own MCP Server

This project demonstrates how easy it is to create a custom MCP server using `odata-mcp-proxy`. To build your own:

1. Create a new project and install the dependency:
   ```bash
   mkdir my-mcp-server && cd my-mcp-server
   npm init -y
   npm install odata-mcp-proxy
   ```

2. Add a start script to `package.json`:
   ```json
   {
     "scripts": {
       "start": "odata-mcp-proxy --config my-api-config.json"
     }
   }
   ```

3. Define your APIs in a config file (`my-api-config.json`):
   ```json
   {
     "server": {
       "name": "my-mcp-server",
       "version": "1.0.0",
       "description": "My custom MCP server"
     },
     "apis": [
       {
         "name": "my-api",
         "destination": "MY_BTP_DESTINATION",
         "pathPrefix": "/api/v1",
         "csrfProtected": true,
         "entitySets": [
           {
             "entitySet": "Products",
             "description": "Product catalog",
             "category": "master-data",
             "keys": [{ "name": "Id", "type": "string" }],
             "operations": { "list": true, "get": true, "create": false, "update": false, "delete": false }
           }
         ]
       }
     ]
   }
   ```

4. Add your `mta.yaml`, `xs-security.json`, and BTP Destinations, then deploy. That's it -- no code to write.

## License

MIT