MCP Maximo Server

MCP Maximo Server

遠端 MCP (Model Context Protocol) 伺服器，將 IBM Maximo API 服務包裝為 MCP Tools，供 Dify Agent 等 AI 應用程式使用。

功能特點

支援的 Maximo 功能

資產管理 (Asset Management)

• get_asset - 查詢資產詳細資訊
• search_assets - 搜尋資產（支援多種篩選條件）
• create_asset - 建立新資產
• update_asset_status - 更新資產狀態

工單管理 (Work Order Management)

• get_work_order - 查詢工單詳細資訊
• search_work_orders - 搜尋工單
• create_work_order - 建立新工單
• update_work_order_status - 更新工單狀態

庫存管理 (Inventory Management)

• get_inventory - 查詢庫存項目
• search_inventory - 搜尋庫存（支援低庫存篩選）
• issue_inventory - 發料作業

架構特性

• ✅ FastMCP 框架 - 使用官方 MCP SDK
• ✅ HTTP + SSE 傳輸 - 符合 MCP 2025 標準
• ✅ API Key 雙層認證 - Dify→MCP 及 MCP→Maximo
• ✅ Redis 快取 - 降低 Maximo 負載，提升效能
• ✅ 速率限制 - Token Bucket 演算法保護系統
• ✅ 結構化日誌 - JSON 格式，含 Correlation ID
• ✅ 連接池 - HTTP 連接重用，優化效能
• ✅ 重試機制 - 自動重試暫時性錯誤
• ✅ 健康檢查 - 監控 Maximo 和 Redis 連接狀態
• ✅ Docker 容器化 - 易於部署和擴展

快速開始

前置需求

• Docker & Docker Compose
• Maximo API Key（在 Maximo 中生成）
• 安全的 MCP API Key（用於 Dify 連接）

1. 複製專案

git clone 
cd mcp-maximo-server

2. 配置環境變數

cp .env.example .env

編輯 .env 檔案，設定以下必要參數：

# MCP 認證
MCP_API_KEY=your-secure-mcp-api-key-here

# Maximo 設定
MAXIMO_API_URL=https://maximo.yourcompany.com/maximo
MAXIMO_API_KEY=your-maximo-api-key-here

3. 啟動服務

docker-compose up -d

4. 驗證服務

檢查健康狀態：

curl http://localhost:8000/health

預期回應：

{
  "status": "healthy",
  "cache": "healthy",
  "maximo": "healthy",
  "version": "1.0.0",
  "environment": "production"
}

5. 使用測試頁面

🎉 新功能！ 我們提供了一個互動式測試頁面來驗證 Maximo 連接和測試所有工具。

開啟瀏覽器訪問：

http://localhost:8000/

或

http://localhost:8000/test

測試頁面功能：

• ✅ 系統健康檢查 - 即時檢查 MCP Server、Redis、Maximo 連接狀態
• ✅ Maximo 連接測試 - 驗證 Maximo API 連接是否正常
• ✅ 工具功能測試 - 測試資產、工單、庫存管理的各項工具

- 查詢資產/工單/庫存 - 搜尋功能 - 提供測試參數輸入介面

• ✅ 即時結果顯示 - 美觀的 UI 即時顯示測試結果
• ✅ 錯誤診斷 - 清楚的錯誤訊息和除錯建議

測試頁面使用方式：

1. 頁面載入時會自動執行健康檢查
2. 點擊「測試 Maximo 連接」驗證 Maximo API 是否正常
3. 在相應欄位輸入測試資料（Asset Number、Site ID 等）
4. 點擊各個測試按鈕驗證工具功能
5. 查看結果區域的詳細回應

提示： 如果您的 MCP Server 不在 localhost:8000，可以在頁面 URL 加上參數： http://localhost:8000/test?server=http://your-server:port

Dify 整合

在 Dify 中配置 MCP Server

1. 開啟 Dify 設定
2. 新增 MCP Server 連接
3. 使用以下配置：

{
  "mcpServers": {
    "maximo": {
      "url": "http://your-server-host:8000/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}

MCP 配置範例：

{
  "mcpServers": {
    "maximo": {
      "url": "http://your-server-host:8000",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}

重要說明：

• MCP 端點：服務器根路徑 /（使用 SSE 傳輸）
• 傳輸模式：SSE (Server-Sent Events)
• 確保 YOUR_MCP_API_KEY 與 .env 文件中的 MCP_API_KEY 一致
• 替換 your-server-host:8000 為您的實際服務器地址和端口

實際使用範例：

{
  "mcpServers": {
    "maximo": {
      "url": "http://traapi1.mas4dev.xyz:8001",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer your-mcp-api-key"
      }
    }
  }
}

在 Dify Agent 中使用

MCP Tools 會自動出現在 Dify Agent 的工具列表中：

• 資產管理工具（4 個）
• 工單管理工具（4 個）
• 庫存管理工具（3 個）

API 文件

可用的 MCP Tools

資產管理

get_asset

get_asset(assetnum="PUMP001", siteid="BEDFORD")

search_assets

search_assets(
    query="pump",
    status="OPERATING",
    location="BLDG-100"
)

create_asset

create_asset(
    assetnum="PUMP123",
    siteid="BEDFORD",
    description="新的水泵設備",
    assettype="PUMP",
    location="BLDG-100"
)

update_asset_status

update_asset_status(
    assetnum="PUMP001",
    siteid="BEDFORD",
    new_status="OPERATING",
    memo="設備已完成維護"
)

工單管理

get_work_order

get_work_order(wonum="WO1001", siteid="BEDFORD")

search_work_orders

search_work_orders(
    status="WAPPR",
    worktype="PM",
    assetnum="PUMP001"
)

create_work_order

create_work_order(
    description="例行維護",
    siteid="BEDFORD",
    assetnum="PUMP001",
    worktype="PM",
    priority=2
)

update_work_order_status

update_work_order_status(
    wonum="WO1001",
    siteid="BEDFORD",
    new_status="INPRG"
)

庫存管理

get_inventory

get_inventory(
    itemnum="FILTER-001",
    siteid="BEDFORD",
    location="STOREROOM"
)

search_inventory

search_inventory(
    query="filter",
    low_stock=True,
    siteid="BEDFORD"
)

issue_inventory

issue_inventory(
    itemnum="FILTER-001",
    quantity=5,
    siteid="BEDFORD",
    location="STOREROOM",
    to_wonum="WO1001"
)

效能調校

快取設定

在 .env 中調整快取 TTL：

CACHE_TTL_ASSET=600        # 資產快取 10 分鐘
CACHE_TTL_WORKORDER=300    # 工單快取 5 分鐘
CACHE_TTL_INVENTORY=600    # 庫存快取 10 分鐘

速率限制

調整速率限制以符合您的需求：

RATE_LIMIT_PER_MINUTE=100           # 一般請求
RATE_LIMIT_SEARCH_PER_MINUTE=50     # 搜尋請求
RATE_LIMIT_CREATE_PER_MINUTE=20     # 建立請求

監控與日誌

查看日誌

# 即時日誌
docker-compose logs -f mcp-server

# 查看特定數量的日誌
docker-compose logs --tail=100 mcp-server

結構化日誌格式

日誌以 JSON 格式輸出，包含以下欄位：

• timestamp - ISO 8601 時間戳
• correlation_id - 請求追蹤 ID
• level - 日誌等級
• message - 日誌訊息
• app - 應用程式名稱
• version - 版本號

範例：

{
  "timestamp": "2025-01-06T10:30:00Z",
  "correlation_id": "abc-123",
  "level": "INFO",
  "message": "Maximo GET success",
  "url": "/oslc/os/mxapiasset",
  "status_code": 200,
  "duration_ms": 245
}

部署選項

Docker Compose（本地/開發）

docker-compose up -d

Google Cloud Run

# 建置並推送映像
docker build -t gcr.io/your-project/mcp-maximo-server .
docker push gcr.io/your-project/mcp-maximo-server

# 部署到 Cloud Run
gcloud run deploy mcp-maximo-server \
  --image gcr.io/your-project/mcp-maximo-server \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated

Azure App Service

# 使用 Azure CLI
az webapp create --resource-group myResourceGroup \
  --plan myAppServicePlan \
  --name mcp-maximo-server \
  --deployment-container-image-name your-registry/mcp-maximo-server:latest

故障排除

連接 Maximo 失敗

檢查：

1. MAXIMO_API_URL 是否正確
2. MAXIMO_API_KEY 是否有效
3. 防火牆規則是否允許連接
4. Maximo API 是否啟用

Redis 連接失敗

檢查：

1. Redis 容器是否運行：docker-compose ps
2. Redis 健康檢查：docker-compose exec redis redis-cli ping
3. 網路連接：確保容器在同一網路中

Dify 無法連接

檢查：

1. MCP Server URL 是否正確
2. MCP_API_KEY 在 .env 和 Dify 配置中是否一致
3. 使用 /health 端點驗證服務可用性

安全建議

1. 使用強 API Key - 使用 openssl rand -hex 32 生成
2. 啟用 HTTPS - 在生產環境使用 TLS
3. 定期輪換密鑰 - 每 60-90 天輪換 API Keys
4. 限制 CORS - 設定特定的允許來源
5. 使用 Secrets Manager - 不要在環境變數中存放敏感資訊（生產環境）

專案結構

mcp-maximo-server/
├── src/
│   ├── main.py                 # FastMCP 應用程式主檔案
│   ├── config.py               # 配置管理
│   ├── auth/
│   │   └── api_key.py          # API Key 認證
│   ├── clients/
│   │   └── maximo_client.py    # Maximo API 客戶端
│   ├── tools/
│   │   ├── asset_tools.py      # 資產管理工具
│   │   ├── workorder_tools.py  # 工單管理工具
│   │   └── inventory_tools.py  # 庫存管理工具
│   ├── middleware/
│   │   ├── cache.py            # Redis 快取
│   │   └── rate_limiter.py     # 速率限制
│   └── utils/
│       └── logger.py           # 結構化日誌
├── Dockerfile                  # Docker 映像定義
├── docker-compose.yml          # Docker Compose 配置
├── requirements.txt            # Python 依賴套件
├── .env.example                # 環境變數範例
└── README.md                   # 本檔案

授權

[指定您的授權]

支援

如有問題或需要協助，請：

1. 查看本文件的故障排除部分
2. 檢查健康檢查端點：/health
3. 查看應用程式日誌
4. 聯繫技術支援團隊