Paylocity

🚀 MCP Paylocity サーバー

Paylocity API エンドポイントからデータを取得するためのモデルコンテキストプロトコル (MCP) サーバーです。

🚀 クイックスタート

このセクションでは、MCP Paylocity サーバーの迅速なセットアップと起動方法を説明します。

インストールと起動

ターミナルで以下のコマンドを実行して、サーバーをインストールし起動します。

cd /path/to/mcpPaylocity
npm install
npm start

Claude Desktop の設定

環境に応じて以下の設定方法を選択してください。

開発環境の設定

{
  "development": {
    "command": "uv --directory . run mcppaylocity",
    "args": []
  }
}

本番環境の設定

{
  "production": {
    "command": "uv --directory . run mcppaylocity",
    "args": []
  }
}

✨ 主な機能

リソースへのアクセス

• カスタム URI スキーム: paylocity:// というカスタム URI スキームを使用して、以下のパスで Paylocity データにアクセスできます。
  • /employees: 従業員情報を取得します。
  • /departments: 部署情報を取得します。
  • /jobs: 職種情報を取得します。
  • /salary-slips: 給与明細情報を取得します。

ツールの実装

• データ取得ツール:

  • fetch_employees: フィルタ条件（部署、職種など）に基づいて従業員リストを取得します。
  • fetch_departments: すべての部署情報を取得します。
  • fetch_jobs: すべての職種情報を取得します。
  • fetch_salary_slips: 従業員 ID に基づいて給与明細の詳細を取得します。

• 将来の計画:

  • パフォーマンスデータや勤怠記録などの高度な機能を追加する予定です。現在は開発中です。

📦 インストール

環境変数の設定

サーバーを正常に動作させるために、以下の環境変数を設定し、.env ファイルに保存してください。

注意事項

• 機密情報の管理: 認証トークンはローカルファイルにキャッシュされます。サーバーの実行環境の安全性を確保してください。
• バージョン管理の注意: 機密情報を含む .env ファイルをコードリポジトリにコミットしないでください。

🔧 技術詳細

コンポーネント構造

1. PaylocityClient: Paylocity API との通信を担当します。
2. TokenManager: 認証トークンのキャッシュと自動更新機能を管理します。
3. FastMCP サーバー: Paylocity データを MCP リソースとツールを通じて外部に公開します。

📚 ドキュメント

ビルドと公開

1. ビルド:

   npm run build
   

2. パッケージ化:

   npm run package
   

3. 公開:

   npm run publish
   

   • npm ユーザートークンを設定するか、環境変数を使用して認証することを確認してください。

デバッグテクニック

MCP サーバーは標準入出力で動作するため、デバッグが難しい場合があります。MCP インスペクター を使用してデバッグすることをおすすめします。

npx @modelcontextprotocol/inspector uv --directory /path/to/mcpPaylocity run mcppaylocity

実行後、インスペクターはブラウザでアクセスできるアドレスを表示し、デバッグを支援します。

📄 ライセンス

MIT License

Copyright (c) 2024 MJ Zou (@mjzou)

許諾条件:

• 著作権表示の保持: いかなる形式で複製または配布する場合でも、著作権表示を含める必要があります。
• 責任制限の表示: このソフトウェアの使用または使用不能によって生じる損害（直接的、間接的、付随的、特別的、派生的または結果的な損害を含む）について、著作権所有者は一切の責任を負いません。

以上が mcpPaylocity サーバーの主な内容です。詳細については、具体的な実装コードを参照するか、開発者に連絡してください。

⚠️ 重要提示

サーバーは認証トークンをキャッシュするため、以下の操作を厳禁とします。

1. .env ファイルをバージョン管理システムにコミットしないでください。
2. 誤ってコミットした場合は、直ちに以下の措置を講じてください。
   • リモートリポジトリからファイルを削除します。
   • コミット履歴を修正して、該当ファイルを削除します。
   • ローカル環境を更新し、再デプロイします。