Cloud Alm Itsm MCP

SAP云ALM ITSM MCP服务器

模型上下文协议（MCP）服务器，用于查询SAP Cloud ALM ITSM API中的安装。

特性

• OAuth 2.0身份验证：自动处理令牌请求和缓存
• 安装查询：多种查询方法，实现灵活的数据检索

- 获取所有带分页的安装 - 按系统类型筛选（BTP、公共云等） - 按客户编号筛选 - 按产品名称筛选 - 跨多个字段的全文搜索

先决条件

• Node.js 18+
• TypeScript
• SAP Cloud ALM ITSM API凭据（客户端ID、客户端机密、端点）

安装

1. 克隆或导航到项目目录：

   cd cloud-alm-itsm-mcp

1. 安装依赖项：

   npm install

1. 创建一个 .env 模板中的文件：

   cp .env.example .env

1. 更新 .env 使用您的SAP Cloud ALM凭据：

   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

建筑

将TypeScript代码构建为JavaScript：

npm run build

这将在 dist/ 目录。

跑步

发展模式

对于使用TypeScript自动编译的开发：

npm run dev

生产模式

建成后：

npm start

可用工具

1. get_installations

使用可选分页从SAP Cloud ALM ITSM API检索安装。

参数：

• offset （数字，可选）：分页起始索引（默认值：0）
• limit （数字，可选）：最大结果数（默认值：50）

例子：

{
  "offset": 0,
  "limit": 50
}

2. get_installations_by_system_type

按系统类型（如BTP、公共云）过滤安装。

参数：

• system_type （string，必填）：要筛选的系统类型
• offset （数字，可选）：起始索引（默认值：0）
• limit （数字，可选）：最大结果（默认值：50）

例子：

{
  "system_type": "BTP",
  "offset": 0,
  "limit": 50
}

3. get_installations_by_customer

按客户编号过滤安装。

参数：

• customer_nbr （string，必填）：客户编号
• offset （数字，可选）：起始索引（默认值：0）
• limit （数字，可选）：最大结果（默认值：50）

例子：

{
  "customer_nbr": "0001801161",
  "offset": 0,
  "limit": 50
}

4. get_installations_by_product

按产品名称筛选安装。

参数：

• product_txt （string，必填）：要筛选的产品名称
• offset （数字，可选）：起始索引（默认值：0）
• limit （数字，可选）：最大结果（默认值：50）

例子：

{
  "product_txt": "SAP HANA Cloud",
  "offset": 0,
  "limit": 50
}

5. search_installations

在多个字段（系统名称、客户、产品、安装名称等）中进行全文搜索。

参数：

• query （string，必填）：搜索查询字符串
• offset （数字，可选）：起始索引（默认值：0）
• limit （数字，可选）：最大结果（默认值：50）

例子：

{
  "query": "BTP",
  "offset": 0,
  "limit": 50
}

MCP客户端配置

要将此服务器与MCP客户端（如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"
      }
    }
  }
}

身份验证详细信息

服务器在客户端凭据流中使用OAuth 2.0：

1. 令牌请求：使用客户端ID和secret获取访问令牌
2. 令牌缓存：令牌被缓存并在过期时自动刷新（有5分钟的缓冲区）
3. API请求：所有API调用都在Authorization头中包含Bearer令牌

错误处理

服务器包括全面的错误处理：

• 捕获并报告令牌获取错误
• API错误包括响应详细信息
• 验证缺少的必需参数
• 网络错误得到妥善处理

响应格式

所有工具都返回具有以下结构的JSON响应：

对于单次安装查询：

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

对于筛选/搜索查询：

[
  {
    "customerNbr": "...",
    "productNbr": "...",
    ...
  }
]

项目结构

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

发展

类型安全

该项目使用TypeScript，并启用了严格模式以实现完全类型安全。

依赖项

• @modelcontextprotocol/sdk：MCP服务器实现
• axios：API请求的HTTP客户端
• dotenv：环境变量管理

故障排除

令牌刷新前令牌过期

如果您遇到身份验证错误，请确保您的OAuth客户端凭据有效，并且令牌端点可访问。

API终结点未响应

检查你的 .env 配置，特别是：

• cloud_alm_api：正确的API终结点URL
• reporter：API的有效报告人电子邮件

缺少环境变量

确保在您的 .env 文件：

• cloud_alm_token_endpoint
• cloud_alm_api
• cloud_alm_itsm_api_clientid
• cloud_alm_itsm_api_clientsecret
• reporter

许可证

麻省理工学院