Servicefusion MCP

🚀 ServiceFusion MCP 服務器

ServiceFusion MCP 服務器是一個基於模型上下文協議（MCP）的服務器，它為 AI 代理提供了標準化的方式來訪問 ServiceFusion API 操作。

✨ 主要特性

• OAuth 2.0 認證：自動進行令牌管理和刷新。
• 完整的 CRUD 操作：可對客戶和工作任務進行創建、讀取、更新和刪除操作。
• 類型安全的接口：全面支持 TypeScript 並進行驗證。
• 資源訪問：提供用於瀏覽客戶和工作任務的 MCP 資源。
• 錯誤處理：具備全面的錯誤處理和驗證機制。

📦 安裝指南

1. 克隆項目並安裝依賴：

npm install

2. 設置環境變量：

cp .env.example .env
# 使用你的 ServiceFusion 憑證編輯 .env 文件

3. 構建項目：

npm run build

💻 使用示例

運行 MCP 服務器

npm start

開發模式

npm run dev

測試

npm test

📚 詳細文檔

可用工具

連接管理

• sf_test_connection - 測試 ServiceFusion API 連接性。
• sf_get_api_status - 獲取當前認證狀態。

客戶操作

• sf_create_customer - 創建帶有聯繫人與地址的新客戶。
• sf_get_customers - 分頁搜索和檢索客戶信息。

工作任務操作

• sf_create_job - 創建新的工作訂單/任務。
• sf_get_jobs - 過濾搜索和檢索工作任務信息。
• sf_update_job - 更新工作任務狀態和詳細信息。
• sf_delete_job - 刪除/取消工作任務。

可用資源

• servicefusion://customers - 客戶的分頁列表。
• servicefusion://jobs - 工作任務的分頁列表。
• servicefusion://customer/{id} - 單個客戶的詳細信息。
• servicefusion://job/{id} - 單個工作任務的詳細信息。
• servicefusion://api-status - API 連接狀態。

配置

設置以下環境變量：

• SERVICEFUSION_CLIENT_ID - 你的 ServiceFusion API 客戶端 ID。
• SERVICEFUSION_CLIENT_SECRET - 你的 ServiceFusion API 客戶端密鑰。
• SERVICEFUSION_BASE_URL - （可選）API 基礎 URL（默認為 https://api.servicefusion.com）。

與 Claude Desktop 集成

將以下內容添加到你的 Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "servicefusion": {
      "command": "node",
      "args": ["/path/to/servicefusion-mcp/build/index.js"],
      "env": {
        "SERVICEFUSION_CLIENT_ID": "your_client_id",
        "SERVICEFUSION_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

API 示例

創建客戶

await sf_create_customer({
  customer_name: "ABC Property Management",
  contacts: [{
    fname: "John",
    lname: "Doe", 
    contact_type: "Primary",
    phone: "555-1234",
    email: "john@abc.com"
  }],
  locations: [{
    street_1: "123 Main St",
    city: "Dallas",
    state_prov: "TX",
    postal_code: "75201"
  }]
});

創建工作任務

await sf_create_job({
  check_number: "WO-12345",
  customer_id: 123456,
  description: "HVAC repair needed",
  category: "Maintenance",
  priority: "High",
  street_1: "123 Main St",
  city: "Dallas",
  state_prov: "TX"
});

搜索工作任務

await sf_get_jobs({
  page: 1,
  customer_name: "ABC Property",
  status: "Scheduled",
  updated_since: "2025-01-01T00:00:00Z"
});

數據模型

客戶

• customer_name（必需）
• parent_customer（可選） - 用於分層客戶。
• contacts[] - 聯繫人信息數組。
• locations[] - 地址信息數組。

工作任務

• check_number（必需） - 唯一標識符。
• customer_id（必需） - 關聯的客戶。
• description（必需） - 工作任務描述。
• status - 工作任務狀態（已安排、進行中、已完成等）。
• priority - 工作任務優先級（正常、高、低）。
• custom_fields[] - 自定義字段值。

錯誤處理

服務器包含全面的錯誤處理，可處理以下情況：

• 認證失敗（自動刷新令牌）。
• API 速率限制和超時。
• 無效輸入驗證。
• 網絡連接問題。

貢獻代碼

1. 在 src/ 目錄下的 TypeScript 文件中進行更改。
2. 使用 npm run build 進行構建。
3. 使用 npm test 進行測試。
4. 提交帶有測試的拉取請求。

📄 許可證

本項目採用 MIT 許可證。