MCP Maximo Server

MCP Maximo Server

Wraps IBM Maximo API services as MCP tools, enabling AI applications like Dify Agent to manage assets, work orders, and inventory through natural language interactions with enterprise asset management systems.

Category
访问服务器

README

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 <repository-url>
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. 使用以下配置：
{
  "maximo_server": {
    "url": "http://your-server-host:8000/mcp/sse",
    "headers": {
      "Authorization": "Bearer YOUR_MCP_API_KEY"
    },
    "timeout": 30
  }
}

在 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. 聯繫技術支援團隊

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选