greenlake-reporting-mcp

HPE GreenLake MCP 服务

一组 Model Context Protocol (MCP) 服务，使 AI 助手能够与 HPE GreenLake 平台服务交互。

目录

• 什么是 Model Context Protocol？
• 此代码库包含什么？
• 可用的 MCP 服务
• 快速入门
• MCP 客户端配置
• 工具模式
• 架构概览
• 安全注意事项
• 故障排除
• 获取帮助
• 资源
• 许可证

什么是 Model Context Protocol？

Model Context Protocol (MCP) 是一种开放协议，可实现 LLM 应用与外部数据源和工具之间的无缝集成。 无论你是在构建 AI 驱动的 IDE、增强聊天界面，还是创建自定义 AI 工作流，MCP 都能提供一种标准化方式，将 LLM 与所需上下文连接起来。

此代码库包含什么？

此代码库包含适用于 HPE GreenLake 平台服务、可用于生产环境的 MCP 服务。每个服务都为 AI 助手提供对特定 GreenLake API 的安全只读访问能力，从而支持使用自然语言与 HPE 基础设施交互。

主要功能

• 标准化架构：所有服务都遵循一致的身份验证、配置和错误处理模式
• OAuth2 身份验证：使用 HPE GreenLake 工作区凭据安全访问，并自动管理令牌
• 双工具模式：每个服务都支持静态（每个端点对应单独的工具）和动态（元工具）运行模式
• 类型安全：使用 Pydantic 模型进行运行时验证并确保类型安全
• 可用于生产环境：提供全面的日志记录、错误处理和 Docker 支持
• 测试完善：包含广泛的单元测试和集成测试覆盖

可用的 MCP 服务

服务	类别	描述	主要功能
设备	基础设施与平台	管理和查询工作区中的 HPE GreenLake 设备	按类型、序列号和标签筛选；按 ID 获取设备详情
工作区	基础设施与平台	使用 HPE GreenLake 工作区管理 API	列出／查询工作区；获取详情和配置
订阅	基础设施与平台	访问订阅信息和许可详情	查看有效订阅；查询许可；监控订阅状态
审计日志	安全与合规	查询和分析 HPE GreenLake 审计日志	按类别、用户和时间戳筛选；跟踪用户活动和系统事件
用户	用户与访问管理	管理用户账户和访问控制	列出／查询用户；查看权限；监控用户活动
报告	报告与分析	生成和获取有关工作区、设备和订阅的报告	可自定义报告类型；异步报告跟踪；日期范围和列筛选
服务目录	基础设施与平台	访问服务目录和预配信息	查看服务报价、预配项、管理器、管理器预配项和区域

快速开始

前提条件

• Python 3.10 或更高版本
• uv 包管理器
• 配有 API 凭据的 HPE GreenLake 工作区

配置

所有服务都需要以下 HPE GreenLake 凭据：

export GREENLAKE_API_BASE_URL="https://global.api.greenlake.hpe.com"
export GREENLAKE_CLIENT_ID="your-client-id"
export GREENLAKE_CLIENT_SECRET="your-client-secret"
export GREENLAKE_WORKSPACE_ID="your-workspace-id"

运行服务

# Navigate to a server directory
cd src/audit-logs

# Install dependencies
uv sync

# Run the server
uv run python -m greenlake_audit_logs_mcp

MCP 客户端配置

Claude Desktop

将服务添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "greenlake-audit-logs": {
      "command": "uv",
      "args": ["run", "python", "-m", "greenlake_audit_logs_mcp"],
      "cwd": "/path/to/gl-mcp/src/audit-logs",
      "env": {
        "GREENLAKE_API_BASE_URL": "https://global.api.greenlake.hpe.com",
        "GREENLAKE_CLIENT_ID": "your-client-id",
        "GREENLAKE_CLIENT_SECRET": "your-client-secret",
        "GREENLAKE_WORKSPACE_ID": "your-workspace-id"
      }
    },
    "greenlake-devices": {
      "command": "uv",
      "args": ["run", "python", "-m", "greenlake_devices_mcp"],
      "cwd": "/path/to/gl-mcp/src/devices",
      "env": {
        "GREENLAKE_API_BASE_URL": "https://global.api.greenlake.hpe.com",
        "GREENLAKE_CLIENT_ID": "your-client-id",
        "GREENLAKE_CLIENT_SECRET": "your-client-secret",
        "GREENLAKE_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

其他 MCP 客户端

这些服务使用标准的 stdio 传输方式，可与任何兼容 MCP 的客户端配合使用。有关具体配置示例，请参阅各服务的 README。

工具模式

所有服务都支持两种运行模式，可在运行时通过 MCP_TOOL_MODE 环境变量切换：

静态模式（默认）

• 独立工具：每个 API 端点都会成为专用的 MCP 工具
• 类型安全：明确的工具定义，支持编译时验证
• 易于发现：工具会在 MCP 客户端界面中逐一显示
• 适用于：规模较小的 API 和专注型工作流

export MCP_TOOL_MODE=static

动态模式

• 元工具：3 个可处理任意 API 端点的通用工具
  • list_endpoints - 发现可用的 API 端点
  • get_endpoint_schema - 获取详细的架构信息
  • invoke_dynamic_tool - 在运行时验证后执行 API 调用
• 节省内存：大型 API 的开销更低
• 适用于：包含许多端点的大型 API

export MCP_TOOL_MODE=dynamic

兼容性矩阵

Python 版本	状态	备注
3.12	✅ 支持	推荐
3.11	✅ 支持	推荐
3.10	✅ 支持	最低版本

架构概览

高层架构

flowchart TB
    subgraph clients["<b> MCP Clients </b>"]
        direction TB
        claude["Claude Desktop"]
        vscode["VS Code"]
        other["..."]
    end

    subgraph servers["<b> MCP Servers </b>"]
        direction TB
        audit["Audit Logs"]
        devices["Devices"]
        users["Users"]
        workspaces["Workspaces"]
        subscriptions["Subscriptions"]
        reporting["Reporting"]
        serviceX["..."]
        
        subgraph shared["<i> Shared Components </i>"]
            direction LR
            oauth["OAuth2 Token Manager<br/>(with caching)"]
        end
    end

    subgraph platform["<b>&nbsp; HPE GreenLake Platform &nbsp;</b>"]
        direction TB
        api["APIs"]
    end

    clients ==>|JSON-RPC/stdio| servers
    servers ==>|HTTPS/REST + OAuth2| platform

    classDef clientStyle fill:#2196F3,stroke:none,color:#fff,rx:10,ry:10
    classDef serverStyle fill:#4CAF50,stroke:none,color:#fff,rx:10,ry:10
    classDef authStyle fill:#FF9800,stroke:none,color:#fff,rx:10,ry:10
    classDef platformStyle fill:#01a982,stroke:none,color:#fff,rx:10,ry:10
    classDef clientContainerStyle fill:none,stroke:#2196F3,stroke-width:3px,rx:15,ry:15
    classDef serverContainerStyle fill:none,stroke:#4CAF50,stroke-width:3px,rx:15,ry:15
    classDef authContainerStyle fill:none,stroke:#FF9800,stroke-width:2px,stroke-dasharray:5 5,rx:10,ry:10
    classDef platformContainerStyle fill:none,stroke:#01a982,stroke-width:3px,rx:15,ry:15
    
    class claude,vscode,other clientStyle
    class audit,devices,users,workspaces,subscriptions,reporting,serviceX serverStyle
    class oauth authStyle
    class api platformStyle
    class clients clientContainerStyle
    class servers serverContainerStyle
    class shared authContainerStyle
    class platform platformContainerStyle

请求流程

1. 客户端请求：MCP 客户端通过 stdio 使用 JSON-RPC 发送工具调用
2. 身份验证：服务使用 OAuth2 向 HPE GreenLake 进行身份验证（令牌会缓存并自动刷新）
3. API 调用：服务向 GreenLake API 发起经过身份验证的 HTTPS 请求
4. 响应：服务处理响应，并通过 MCP 协议将数据返回给客户端

共享组件

所有服务都采用相同的架构：

src/<service>/
├── greenlake_<service>_mcp/   # Main package (e.g. greenlake_audit_logs_mcp)
│   ├── __main__.py            # Entry point (python -m greenlake_<service>_mcp)
│   ├── auth/                  # OAuth2 authentication
│   ├── config/                # Settings and logging
│   ├── models/                # Pydantic data models
│   ├── server/                # MCP server core
│   ├── tools/                 # Tool implementations
│   │   ├── base.py           # Base tool class
│   │   ├── registry.py       # Tool registration
│   │   └── implementations/  # Tool implementations
│   └── utils/                 # HTTP client and utilities
├── tests/                     # Unit and integration tests
└── pyproject.toml             # Package definition and entry points

身份验证

所有服务都使用 OAuth2 客户端凭据流程，并自动管理令牌：

• 令牌会缓存并自动刷新
• 线程安全的令牌管理
• 支持配置重试逻辑，并采用指数退避策略

日志记录

服务器使用符合 MCP 协议规范的结构化日志记录：

• stderr：诊断日志（由 GREENLAKE_LOG_LEVEL 控制）
• 文件日志：可选的详细日志，写入 ~/.hpe/mcp-logs/
• stdout：仅用于 JSON-RPC 消息

安全注意事项

• 只读访问：所有服务器在设计上均仅提供只读 API 访问
• 凭据管理：切勿将凭据提交到版本控制中
• 令牌安全：OAuth2 令牌仅缓存在内存中
• 工作区隔离：操作范围限定在已配置的工作区内
• 仅限 HTTPS：所有 API 通信均使用 TLS 加密

故障排除

常见问题

服务器无法启动：

• 确认已设置所有必需的环境变量
• 检查是否已安装 uv 并同步依赖项
• 查看 stderr 输出中的配置错误

身份验证失败：

• 确认客户端凭据对你的工作区有效
• 确保 GREENLAKE_WORKSPACE_ID 与凭据的适用范围相符
• 检查到 GreenLake API 的网络连接

MCP 客户端连接问题：

• 确认客户端配置中的 cwd 路径正确
• 检查手动运行时服务器能否成功启动
• 查看客户端日志中的具体错误消息

调试日志记录

启用详细日志记录以排查问题：

export GREENLAKE_LOG_LEVEL=DEBUG
export GREENLAKE_FILE_LOGGING=true

日志文件写入位置：~/.hpe/mcp-logs/{service-name}/

获取帮助

GitHub Issues

本项目的主要支持渠道是 GitHub Issues。报告问题时，请提供以下信息：

• 环境详情：操作系统、Python 版本、uv 版本
• 服务器名称：你正在使用的 MCP 服务（audit-logs、devices 等）
• 错误消息：完整的错误输出和堆栈跟踪
• 配置：相关环境变量设置（请勿包含凭据）
• 复现步骤：如何复现问题的详细说明

提交 Issue 前

1. 检查现有 Issue：搜索未解决的问题和已关闭的问题
2. 查看故障排除内容：检查上方的故障排除部分
3. 启用调试日志记录：使用 GREENLAKE_LOG_LEVEL=DEBUG 和 GREENLAKE_FILE_LOGGING=true 运行，以收集详细日志
4. 测试身份验证：确认你的凭据可直接用于 GreenLake API

Issue 类型

• 错误报告：用于报告意外行为、错误或崩溃
• 功能请求：用于提出新功能或改进建议
• 问题：用于询问用法、配置或架构相关问题
• 文档：用于报告文档问题或提出改进建议

资源

• Model Context Protocol 文档
• HPE GreenLake API 文档
• MCP 规范

许可证

本项目采用 Apache 2.0 许可证授权，详情请参阅 LICENSE 文件。