# SAP Cloud ALM ITSM MCP Server

A Model Context Protocol (MCP) server for querying installations in SAP Cloud ALM ITSM API.

## Features

- **OAuth 2.0 Authentication**: Automatically handles token requests and caching
- **Installation Queries**: Multiple query methods for flexible data retrieval
  - Get all installations with pagination
  - Filter by system type (BTP, Public Cloud, etc.)
  - Filter by customer number
  - Filter by product name
  - Full-text search across multiple fields

## Prerequisites

- Node.js 18+ 
- TypeScript
- SAP Cloud ALM ITSM API credentials (client ID, client secret, endpoints)

## Installation

1. Clone or navigate to the project directory:
   ```bash
   cd cloud-alm-itsm-mcp
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Create a `.env` file from the template:
   ```bash
   cp .env.example .env
   ```

4. Update `.env` with your SAP Cloud ALM credentials:
   ```env
   cloud_alm_token_endpoint=https://your-tenant.authentication.eu10.hana.ondemand.com
   cloud_alm_api=https://your-api-endpoint.eu10.alm.cloud.sap
   cloud_alm_itsm_api_clientid=your_client_id
   cloud_alm_itsm_api_clientsecret=your_client_secret
   reporter=your_reporter_email
   ```

## Building

Build the TypeScript code to JavaScript:

```bash
npm run build
```

This creates compiled JavaScript files in the `dist/` directory.

## Running

### Development Mode
For development with automatic TypeScript compilation:
```bash
npm run dev
```

### Production Mode
After building:
```bash
npm start
```

## Available Tools

### 1. `get_installations`
Retrieve installations from SAP Cloud ALM ITSM API with optional pagination.

**Parameters:**
- `offset` (number, optional): Starting index for pagination (default: 0)
- `limit` (number, optional): Maximum number of results (default: 50)

**Example:**
```json
{
  "offset": 0,
  "limit": 50
}
```

### 2. `get_installations_by_system_type`
Filter installations by system type (e.g., BTP, Public Cloud).

**Parameters:**
- `system_type` (string, required): The system type to filter by
- `offset` (number, optional): Starting index (default: 0)
- `limit` (number, optional): Maximum results (default: 50)

**Example:**
```json
{
  "system_type": "BTP",
  "offset": 0,
  "limit": 50
}
```

### 3. `get_installations_by_customer`
Filter installations by customer number.

**Parameters:**
- `customer_nbr` (string, required): The customer number
- `offset` (number, optional): Starting index (default: 0)
- `limit` (number, optional): Maximum results (default: 50)

**Example:**
```json
{
  "customer_nbr": "0001801161",
  "offset": 0,
  "limit": 50
}
```

### 4. `get_installations_by_product`
Filter installations by product name.

**Parameters:**
- `product_txt` (string, required): Product name to filter by
- `offset` (number, optional): Starting index (default: 0)
- `limit` (number, optional): Maximum results (default: 50)

**Example:**
```json
{
  "product_txt": "SAP HANA Cloud",
  "offset": 0,
  "limit": 50
}
```

### 5. `search_installations`
Full-text search across multiple fields (system name, customer, product, installation name, etc.).

**Parameters:**
- `query` (string, required): Search query string
- `offset` (number, optional): Starting index (default: 0)
- `limit` (number, optional): Maximum results (default: 50)

**Example:**
```json
{
  "query": "BTP",
  "offset": 0,
  "limit": 50
}
```

## MCP Client Configuration

To use this server with an MCP client (like Claude Desktop), add it to your client configuration:

### Claude Desktop (`.config/claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "cloud-alm-itsm": {
      "command": "node",
      "args": ["/path/to/cloud-alm-itsm-mcp/dist/index.js"],
      "env": {
        "cloud_alm_token_endpoint": "https://your-tenant.authentication.eu10.hana.ondemand.com",
        "cloud_alm_api": "https://your-api-endpoint.eu10.alm.cloud.sap",
        "cloud_alm_itsm_api_clientid": "your_client_id",
        "cloud_alm_itsm_api_clientsecret": "your_client_secret",
        "reporter": "your_reporter_email"
      }
    }
  }
}
```

## Authentication Details

The server uses OAuth 2.0 with the client credentials flow:

1. **Token Request**: Uses client ID and secret to obtain an access token
2. **Token Caching**: Tokens are cached and automatically refreshed when expired (with a 5-minute buffer)
3. **API Requests**: All API calls include the Bearer token in the Authorization header

## Error Handling

The server includes comprehensive error handling:
- Token acquisition errors are caught and reported
- API errors include response details
- Missing required parameters are validated
- Network errors are handled gracefully

## Response Format

All tools return JSON responses with the following structure:

**For single installation queries:**
```json
{
  "count": 50,
  "totalCount": 202,
  "results": [
    {
      "customerNbr": "...",
      "productNbr": "...",
      ...
    }
  ]
}
```

**For filtered/search queries:**
```json
[
  {
    "customerNbr": "...",
    "productNbr": "...",
    ...
  }
]
```

## Project Structure

```
cloud-alm-itsm-mcp/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   ├── auth.ts           # OAuth 2.0 authentication client
│   ├── api.ts            # SAP Cloud ALM ITSM API client
├── dist/                 # Compiled JavaScript (generated)
├── tests/                # Test data and API examples
├── package.json
├── tsconfig.json
├── .env.example          # Environment variables template
└── README.md            # This file
```

## Development

### Type Safety
The project uses TypeScript with strict mode enabled for full type safety.

### Dependencies
- `@modelcontextprotocol/sdk`: MCP server implementation
- `axios`: HTTP client for API requests
- `dotenv`: Environment variable management

## Troubleshooting

### Token expires before token refresh
If you get authentication errors, ensure your OAuth client credentials are valid and the token endpoint is accessible.

### API endpoint not responding
Check your `.env` configuration, particularly:
- `cloud_alm_api`: Correct API endpoint URL
- `reporter`: Valid reporter email for the API

### Missing environment variables
Ensure all required variables are set in your `.env` file:
- `cloud_alm_token_endpoint`
- `cloud_alm_api`
- `cloud_alm_itsm_api_clientid`
- `cloud_alm_itsm_api_clientsecret`
- `reporter`

## License

MIT