Opyconymcpy

🚀 OpCon MCP 服務器

OpCon MCP 服務器是一個基於 模型上下文協議（MCP） 的服務器，用於與 SMA OpCon REST API 進行交互。該服務器使 AI 代理和應用程序能夠通過標準化協議與 OpCon 自動化平臺進行交互。

🚀 快速開始

• 確保滿足以下前提條件：
  • Node.js 18 或更高版本
  • 能夠訪問 OpCon API 服務器
  • 擁有 OpCon API 憑證（令牌或用戶名/密碼）
• 安裝依賴：

npm install

• 配置環境變量，具體變量說明見下方「配置」部分。
• 啟動服務器：

# 開發模式
npm run dev

# 生產模式（構建後）
npm run build
node dist/index.js

✨ 主要特性

• ✅ 完整的 API 覆蓋：根據 OpenAPI 規範自動生成 MCP 工具。
• ✅ 認證支持：支持基於令牌和用戶名/密碼的認證方式。
• ✅ 類型安全：使用 TypeScript 編寫，具有完整的類型定義。
• ✅ 全面測試：使用 Jest 進行單元測試。
• ✅ CI/CD：通過 GitHub Actions 工作流進行測試、代碼檢查和安全掃描。
• ✅ 開發工具：支持 DevContainer 和 VSCode 集成。
• ✅ 最佳實踐：使用 ESLint、Prettier 進行代碼規範檢查和格式化，同時進行安全掃描。
• ✅ Grafana 支持：提供 Prometheus 指標，用於監控和可觀測性。

📦 安裝指南

安裝依賴

npm install

📚 詳細文檔

查看完整文檔 - 完整指南包括：

• 快速入門指南 - 幾分鐘內即可開始使用
• 工具參考 - 所有 257 個可用工具及其詳細參數
• 配置指南 - 環境設置
• 集成指南 - MCP 客戶端集成
• 示例 - 使用示例

💻 使用示例

運行服務器

# 開發模式
npm run dev

# 生產模式（構建後）
npm run build
node dist/index.js

與 MCP 客戶端配合使用

配置你的 MCP 客戶端（例如 Claude Desktop、MCP Inspector）以使用此服務器：

{
  "mcpServers": {
    "opcon": {
      "command": "node",
      "args": ["/path/to/OpyConyMcpy/dist/index.js"],
      "env": {
        "OPCON_BASE_URL": "https://your-opcon-server:9010",
        "OPCON_TOKEN": "your-token-here"
      }
    }
  }
}

可用工具

服務器根據 OpCon OpenAPI 規範自動生成 MCP 工具。每個 API 端點都成為一個可調用的工具。

涵蓋 65 個類別，共 257 個工具，例如：

• DailyJobs（40 個工具） - 監控和管理日常作業執行
• DailySchedules（11 個工具） - 日常調度操作
• Machines（10 個工具） - 機器配置和監控
• Calendars（8 個工具） - 日曆管理
• AccessCodes（5 個工具） - 訪問代碼管理
• Resources（5 個工具） - 資源管理
• 還有 59 個其他類別...

完整列表請參閱 工具參考。

🔧 技術細節

配置

服務器通過環境變量進行配置：

*OPCON_TOKEN 或 OPCON_USERNAME 和 OPCON_PASSWORD 兩者都需要提供。

開發

環境搭建

# 安裝依賴
npm install

# 以開發模式運行
npm run dev

測試

# 運行所有測試
npm test

# 以監視模式運行測試
npm run test:watch

# 運行帶覆蓋率的測試
npm run test:coverage

代碼檢查和格式化

# 運行 ESLint
npm run lint

# 修復 ESLint 問題
npm run lint:fix

# 檢查代碼格式
npm run format:check

# 修復代碼格式
npm run format

構建

npm run build

監控

OpCon MCP 服務器支持 Prometheus 指標，可在 Grafana 中可視化。

快速開始

1. 啟用指標收集：

export OPCON_METRICS_ENABLED=true

2. 啟動指標 HTTP 服務器：

# 開發模式
npm run dev:metrics

# 生產模式（構建後）
node dist/metrics-server.js

3. 在 http://localhost:9090/metrics 訪問指標。

可用指標

• 請求計數：按工具和方法統計的 MCP 工具總請求數
• 錯誤率：按工具、方法和錯誤類型統計的錯誤數
• 請求持續時間：帶有 p95、p99 百分位數的延遲直方圖
• 可用工具：已註冊的 MCP 工具數量

設置 Grafana 儀表盤

1. 設置 Prometheus 以抓取指標端點
2. 從 grafana/dashboard.json 導入儀表盤
3. 在 Grafana 中配置 Prometheus 數據源

詳細說明請參閱 grafana/README.md。

項目結構

OpyConyMcpy/
├── .devcontainer/          # DevContainer 配置
├── .github/
│   └── workflows/          # GitHub Actions 工作流
├── .vscode/                # VS Code 設置
├── src/
│   ├── index.ts           # 主服務器入口點
│   ├── client.ts          # OpCon API 客戶端
│   ├── parser.ts          # OpenAPI 規範解析器
│   └── types.ts           # 類型定義
├── tests/                  # 單元測試
├── swagger.json           # OpCon OpenAPI 規範
├── package.json           # 項目依賴
├── tsconfig.json          # TypeScript 配置
├── jest.config.js         # Jest 配置
├── .eslintrc.json         # ESLint 配置
└── .prettierrc            # Prettier 配置

架構

MCP 服務器架構包括：

1. 解析器：讀取 OpenAPI 規範並生成 MCP 工具定義
2. 客戶端：處理與 OpCon API 的 HTTP 通信，包括認證
3. 服務器：實現 MCP 協議並將工具調用路由到相應的 API 端點

流程

MCP 客戶端 → MCP 服務器 → OpCon 客戶端 → OpCon REST API

🤝 貢獻代碼

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 運行測試和代碼檢查
5. 提交拉取請求

🔒 安全注意事項

• 生產環境中始終使用 HTTPS
• 安全存儲憑證（使用環境變量，切勿提交到代碼庫）
• 除非絕對必要，否則啟用 TLS 驗證
• 定期更新依賴項
• 查看 GitHub Actions 中的安全掃描結果

📄 許可證

本項目採用 MIT 許可證。

🛠️ 支持

如有問題和疑問，請使用 GitHub 問題跟蹤器。