Servicefusion MCP

🚀 ServiceFusion MCP Server

ServiceFusion API操作への標準化されたアクセスをAIエージェントに提供するModel Context Protocol (MCP)サーバーです。

🚀 クイックスタート

ServiceFusion MCP Serverは、AIエージェントがServiceFusion API操作に標準化されたアクセスを行うためのMCPサーバーです。以下の手順でサーバーをセットアップしてください。

✨ 主な機能

• OAuth 2.0認証：自動トークン管理と更新
• 完全なCRUD操作：顧客とジョブの作成、読み取り、更新、削除
• 型安全なインターフェイス：検証付きの完全なTypeScriptサポート
• リソースアクセス：顧客とジョブを閲覧するためのMCPリソース
• エラーハンドリング：包括的なエラーハンドリングと検証

📦 インストール

1. 依存関係をクローンしてインストールします。

npm install

2. 環境変数を設定します。

cp .env.example .env
# .envをServiceFusionの資格情報で編集してください

3. プロジェクトをビルドします。

npm run build

💻 使用例

基本的な使用法

MCPサーバーの起動

npm start

開発モード

npm run dev

テスト

npm test

高度な使用法

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"
});

📚 ドキュメント

利用可能なツール

接続管理

• 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の接続ステータス

設定

以下の環境変数を設定してください。

データモデル

顧客

• 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