Cloud Alm Itsm

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:

   cd cloud-alm-itsm-mcp
   

2. Install dependencies:

   npm install
   

3. Create a .env file from the template:

   cp .env.example .env
   

4. Update .env with your SAP Cloud ALM credentials:

   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:

npm run build

This creates compiled JavaScript files in the dist/ directory.

Running

Development Mode

For development with automatic TypeScript compilation:

npm run dev

Production Mode

After building:

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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)

{
  "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:

{
  "count": 50,
  "totalCount": 202,
  "results": [
    {
      "customerNbr": "...",
      "productNbr": "...",
      ...
    }
  ]
}

For filtered/search queries:

[
  {
    "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