mcpPaylocity MCP サーバー

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

コンポーネント

リソース

サーバーは、次の Paylocity API リソースを実装します。

• Paylocity データにアクセスするためのカスタムpaylocity:// URI スキーム
• 利用可能なリソースは次のとおりです。
  • paylocity://employees/{company_id} - 会社の全従業員を一覧表示する
  • paylocity://employees/{company_id}/{employee_id} - 特定の従業員の詳細を取得します
  • paylocity://earnings/{company_id}/{employee_id} - 特定の従業員の収入データを取得する
  • paylocity://codes/{company_id}/{code_resource} - 特定のリソースの会社コードを取得します
  • paylocity://localtaxes/{company_id}/{employee_id} - 特定の従業員の地方税を取得します
  • paylocity://paystatement/{company_id}/{employee_id}/{year}/{check_date} - 特定の日付の給与明細の詳細を取得します

ツール

サーバーは次のツールを実装します。

• fetch_employees - 会社のすべての従業員を取得します
  • オプションのcompany_idパラメータを取る
• fetch_employee_details - 特定の従業員の詳細を取得します
  • 必須のemployee_idとオプションのcompany_idパラメータを取ります
• fetch_employee_earnings - 特定の従業員の収入データを取得します
  • 必須のemployee_idとオプションのcompany_idパラメータを取ります
• fetch_company_codes - 特定のリソースの会社コードを取得します
  • 必須のcode_resourceとオプションのcompany_idパラメータを取ります
• fetch_employee_local_taxes - 特定の従業員の地方税を取得します
  • 必須のemployee_idとオプションのcompany_idパラメータを取ります
• fetch_employee_paystatement_details - 特定の日付の給与明細の詳細を取得します
  • 必須のemployee_id 、 year 、 check_date 、およびオプションのcompany_idパラメータを取ります。

将来の実装

今後のアップデートでは、次のエンドポイントが実装される予定です。

• [ ] 高レベルの洞察（例：離職率、部門別の従業員数、レートの比較など）

構成

サーバーでは次の環境変数を設定する必要があります。

• PAYLOCITY_CLIENT_ID - Paylocity APIクライアントID
• PAYLOCITY_CLIENT_SECRET - Paylocity APIクライアントシークレット
• PAYLOCITY_COMPANY_IDS - 使用する会社IDのカンマ区切りリスト
• PAYLOCITY_ENVIRONMENT - 使用する API 環境 ( productionまたはtesting )

これらは、プロジェクトのルート ディレクトリ内の.envファイルで設定できます。

安全

⚠️重要：このアプリケーションは認証トークンをsrc/mcppaylocity/access_token/ディレクトリにキャッシュします。これらのファイルには機密性の高い認証情報が含まれているため、バージョン管理にコミットしないでください。

リポジトリには.gitignoreにこれらのパスが含まれていますが、変更をプッシュするときにトークン ファイルが誤ってコミットされないように注意してください。

誤ってトークン ファイルをコミットした場合は、次の手順に従ってください。

1. リポジトリからファイルを削除します: git rm --cached src/mcppaylocity/access_token/token.json src/mcppaylocity/access_token/token_info.txt
2. 削除をコミットします: git commit -m "Remove accidentally committed token files"
3. Paylocity APIの認証情報が侵害されている可能性があるため、ローテーションを検討してください。

クイックスタート

インストール

クロードデスクトップ

MacOS の場合: ~/Library/Application\ Support/Claude/claude_desktop_config.json Windows の場合: %APPDATA%/Claude/claude_desktop_config.json

発達

建築と出版

配布用のパッケージを準備するには:

1. 依存関係を同期し、ロックファイルを更新します。

2. パッケージディストリビューションをビルドします。

これにより、 dist/ディレクトリにソースとホイールのディストリビューションが作成されます。

3. PyPI に公開:

注: 環境変数またはコマンド フラグを使用して PyPI 資格情報を設定する必要があります。

• トークン: --tokenまたはUV_PUBLISH_TOKEN
• またはユーザー名/パスワード: --username / UV_PUBLISH_USERNAMEおよび--password / UV_PUBLISH_PASSWORD

デバッグ

MCPサーバーはstdio経由で実行されるため、デバッグが困難になる場合があります。最適なデバッグ環境を実現するには、 MCP Inspectorの使用を強くお勧めします。

次のコマンドを使用して、 npm経由で MCP Inspector を起動できます。

起動すると、ブラウザでアクセスしてデバッグを開始できる URL がインスペクタに表示されます。

建築

サーバーは次のコンポーネントで構築されています。

1. PaylocityClient - Paylocity APIとの通信を処理します
2. TokenManager - キャッシュや更新を含む認証トークンを管理します
3. FastMCP Server - MCPのリソースとツールを通じてPaylocityデータを公開します

ライセンス

MITライセンス

Copyright (c) 2024 MJ Zou ( @mjzou )

本ソフトウェアおよび関連ドキュメント ファイル (以下「本ソフトウェア」) のコピーを入手したすべての人物は、以下の条件に従い、本ソフトウェアを無制限に扱う権利 (使用、コピー、変更、統合、公開、配布、サブライセンス、および/または販売する権利を含みますが、これに限定されません) および本ソフトウェアの提供を受けた人物が同様の行為を行うことを許可する権利を無償で付与されます。

上記の著作権表示およびこの許可通知は、ソフトウェアのすべてのコピーまたは大部分に含めるものとします。

本ソフトウェアは「現状有姿」で提供され、明示的または黙示的を問わず、商品性、特定目的への適合性、非侵害性を含むがこれらに限定されない、いかなる種類の保証も付与されません。いかなる場合においても、著作者または著作権者は、契約違反、不法行為、またはその他の行為にかかわらず、本ソフトウェア、本ソフトウェアの使用、またはその他の取り扱いに起因または関連して発生するいかなる請求、損害、またはその他の責任についても責任を負わないものとします。