Cumulocity MCP Server

🚀 MCP Cumulocity 服務器

MCP Cumulocity 服務器是一個基於 Python 的服務器，藉助 MCP（模型控制協議）接口，提供 Cumulocity IoT 平臺功能。它能夠與 Cumulocity 的設備管理、測量和告警系統實現無縫交互。

🚀 快速開始

MCP Cumulocity 服務器可讓你輕鬆與 Cumulocity IoT 平臺進行交互。以下是使用該服務器的基本步驟：

1. 確保滿足先決條件。
2. 按照安裝步驟完成安裝。
3. 進行必要的配置。
4. 若有需求，可將其集成到 Claude Desktop 中。

✨ 主要特性

設備管理

• 列出並篩選設備，方便你快速定位所需設備。
• 獲取設備詳細信息，深入瞭解設備狀態。
• 查看設備層次結構（子設備），清晰掌握設備間的關係。
• 訪問設備片段和屬性，滿足多樣化的管理需求。

測量值

• 帶時間過濾獲取設備測量值，精準獲取特定時間段的數據。
• 查看測量歷史記錄，便於進行數據分析和趨勢預測。

告警

• 監控活動告警，及時發現設備異常。
• 根據嚴重性篩選告警，優先處理重要問題。
• 跟蹤告警狀態，確保問題得到妥善解決。

可用工具

• 設備管理：可列表設備、獲取單個設備詳細信息以及更新設備屬性。
• 測量值：能查詢歷史測量數據、添加新測量值和刪除指定時間範圍內的測量值。
• 告警：支持創建新告警規則、查看活動告警和管理告警狀態。

📦 安裝指南

先決條件

• Python 3.13 或更高版本。
• 訪問 Cumulocity IoT 平臺實例。
• 配置所需的環境變量。

安裝步驟

1. 克隆倉庫：

git clone <repository-url>
cd mcp-c8y

2. 創建並激活虛擬環境：

python -m venv .venv
source .venv/bin/activate  # 在 macOS/Linux 上
# 或者
.venv\Scripts\activate  # 在 Windows 上

3. 安裝 uv（如果尚未安裝）：

# 在 macOS/Linux 上
curl -LsSf https://astral.sh/uv/install.sh | sh

# 在 Windows PowerShell 上
irm https://astral.sh/uv/install.ps1 | iex

4. 使用 uv 安裝依賴項：

uv install

5. 運行服務器：

uv run main:app

📚 詳細文檔

配置說明

將以下內容添加到項目根目錄的 .env 文件中，以配置 Cumulocity 服務：

CUMULOCITY_API_KEY=your_api_key_here
CUMULOCITY_API_SECRET=your_api_secret_here
CUMULOCITY_BASE_URL=https://api.cumulocity.com

與 Claude Desktop 的集成

按照以下步驟將 MCP Cumulocity Server 集成到 Claude Desktop 中：

1. 安裝並運行 Claude Desktop。
2. 在 Claude 中創建新項目，並指定 MCP Cumulocity Server 作為數據源。
3. 配置項目的環境變量，包括 Cumulocity API 密鑰和密鑰。
4. 使用 Claude 的工作流設計器集成服務器功能。

貢獻指南

我們歡迎來自各方的貢獻！以下是您如何為該項目做貢獻的步驟：

1. Fork 此倉庫。
2. 為功能或修復創建新分支。
3. 按照以下最佳實踐進行更改：
   • 編寫清晰、描述性的提交消息。
   • 遵循現有的代碼風格和慣例。
   • 為新功能添加測試。
   • 根據需要更新文檔。
   • 確保所有測試通過。
4. 提交 Pull Request。

開發指南

• 使用有意義的變量名和函數命名。
• 為複雜邏輯添加註釋。
• 為新功能編寫單元測試。
• 保持提交專注且原子化。
• 遵循 PEP 8 樣式指南。
• 為函數參數和返回值使用類型提示。

Pull Request 流程

1. 如果需要，更新 README.md 以反映更改。
2. 如有功能變更，請更新相關文檔。
3. 在獲得至少一位維護者的批准後，Pull Request 將被合併。

如需更詳細的貢獻指南，請參考我們的 [CONTRIBUTING.md] 文件。

📄 許可證

MCP Cumulocity Server 的使用受 Apache License Version 2.0 的約束。

除非適用法律或書面協議另有要求，否則軟件按“原樣”分發，不附帶任何形式的擔保。