Leavemanagementmcp

🚀 休暇管理MCPサーバー

このプロジェクトは、LeaveManagementSystemというモデルコンテキストプロトコル（MCP）サーバーを提供します。CursorやClaudeなどのAIアシスタントがHRのコパイロットのように機能できるようにします。休暇の詳細を収集し、ポリシーを検証し、リクエストを即時承認し、人間が読みやすい確認メッセージを送信します。このサーバーはfastmcpを使用してPythonで実装されているため、軽量で状態を保持し、拡張が容易です。

🚀 クイックスタート

1. 依存関係のインストール (uvを使用して決定論的な環境を構築します):

   uv pip install -r pyproject.toml
   

2. MCPサーバーを手動で実行する（オプション）:

   uv run --with mcp[cli] mcp run main.py
   

3. MCPクライアント（CursorまたはClaude）にサーバーを登録する。以下のコマンドを使用します:

   C:\Users\Asus\.local\bin\uv.EXE run --with mcp[cli] mcp run C:\Users\Asus\Desktop\leavemanagementMCP\main.py
   

4. クライアントを再起動して、新しいサーバーを読み込みます。

✨ 主な機能

解決する問題

• 手動の休暇申請フローは遅い。HRチームは従業員情報の収集、ポリシーの検証、承認メールの作成に時間を費やします。
• アシスタントは重要なコンテキストを欠くことが多い。一般的なAI自動化は、すべての詳細を確認せずにツールを起動するため、エラーややり取りによるクラリファイケーションが発生します。
• 承認には監査可能な記録が必要。管理者は誰が休暇を申請し、何日休んだか、なぜ休暇が承認されたかを可視化したいと考えています。

ソリューションのハイライト

• 構造化されたMCPツール：apply_leave、approve_leave、reject_leave、およびleave-statusリソースは、すべての主要なHRアクションを決定論的なAPIとして公開します。
• ガードレールの組み込み：ツールの検証により、アシスタントはアクションを実行する前にemployee_id、days、および具体的なreasonを収集することが保証されます。
• 自動承認ワークフロー：apply_leaveが呼び出されると、システムは自動的にリクエストを承認し、残高を更新し、メール通知をシミュレートします。Claude（またはMCP対応のアシスタント）は、人間の管理者の待ち時間なしに即座に応答できます。
• リアルタイムのステータス追跡：アシスタントはleave-status://{emp_id}をクエリして、従業員に現在の残高と決定履歴を共有できます。

このソリューションが最先端の理由

• アシスタントを重視した設計：REST APIを公開するのではなく、LLMツールプラットフォームに特化したネイティブMCPサーバーを提供します。Claude、Cursor、および将来のMCPクライアントは、最小限のグルーコードで機能を発見し、パラメータ契約を適用し、高度なフローをオーケストレーションできます。
• AIエージェントの運用上の安全性：検証、ポリシー制限、および監査トレイルはサーバー側で強制されるため、自律的なエージェントが休暇を承認することがより安全になります。
• 構成可能なHR自動化：すべてがMCPサーバー内で実行されるため、これを他のMCPサービス（カレンダー同期、給与計算、分析）とベスポークな統合なしに連鎖させることができます。
• リアルタイムコラボレーションに対応：メモリ内モデルはセッション中に状態を保持します。データベースまたはSaaSバックエンドに移行するには、ストレージ層を交換するだけです。

📚 ドキュメント

技術スタック

コアテクノロジー

• Python 3.11+：型ヒントを備えた最新のPythonで、堅牢な開発が可能です。
• FastMCP：MCP互換クライアントとのシームレスな統合を提供する高性能MCPサーバーフレームワーク。
• モデルコンテキストプロトコル（MCP）：AIアシスタントが外部ツールとリソースとやり取りするための標準化されたプロトコル。
• uv：再現可能な環境のための高速なPythonパッケージインストーラーと依存関係マネージャー。

データ層

• 現在の実装：迅速なプロトタイピングと開発のためのメモリ内データ構造（辞書とリスト）。
• 本番環境対応：データベース抽象化を念頭に設計されており、以下のデータベースにシームレスに接続できます。
  • SQLite：中小規模のデプロイメントに最適な軽量なファイルベースのデータベース。
  • PostgreSQL：本番環境向けのエンタープライズグレードのリレーショナルデータベース。
  • MySQL/MariaDB：代替のリレーショナルデータベースオプション。
  • MongoDB：柔軟なドキュメントストレージのためのNoSQLオプション。
  • SaaS HRIS API：既存のHR管理システム（Workday、BambooHRなど）との直接統合。

統合ポイント

• MCPクライアント：Claude Desktop、Cursor IDE、およびすべてのMCP互換クライアントをサポート。
• メール通知：シミュレートされたメールシステム（SendGrid、AWS SES、SMTPサーバーとの統合に対応）。
• 将来の拡張：カレンダーAPI、Slack/Teamsウェブフック、給与システム。

開発ツール

• pyproject.toml：依存関係管理を備えた最新のPythonプロジェクト構成。
• uv.lock：再現可能なビルドのためのロックされた依存関係バージョン。

アーキテクチャの概要

Claude / Cursor ──► MCP Transport ──► LeaveManagementSystem (fastmcp)
                                   ├─ apply_leave()  → 検証 → 承認 → 通知送信
                                   ├─ approve_leave() → 手動上書き
                                   ├─ reject_leave()  → 手動上書き
                                   └─ leave-statusリソース → 人間が読みやすい要約の生成
                                   
データ層（設定可能）:
├─ メモリ内（開発用） ──► Python辞書/リスト
└─ データベース（本番用） ───► SQLite / PostgreSQL / MySQL / MongoDB / HRIS API

💻 使用例

基本的な使用法

• 休暇申請：emp_id、days、およびreasonを収集します。ツールは自動的に申請を承認し、フォーマットされた確認メッセージとシミュレートされたメール通知を返します。
• 決定の上書き：必要に応じて、approve_leaveまたはreject_leaveを手動で呼び出してステータスを調整します。
• ステータスの確認：leave-status://emp001（任意の従業員IDに置き換え）をクエリして、残高と決定履歴を確認します。

高度な使用法

データベース統合

システムは直接的なデータベース接続をサポートするように設計されています。メモリ内データ構造をデータベースクエリに置き換えることができます。

• SQLite：小規模なチームに最適で、ゼロコンフィギュレーションの単一ファイルデータベース。
• PostgreSQL/MySQL：ACID準拠、トランザクション、および複雑なクエリを備えたエンタープライズ対応。
• MongoDB：柔軟なスキーマ進化のためのドキュメントベースのストレージ。
• HRIS API：REST/GraphQL APIを介して既存のHRシステム（Workday、BambooHR、ADP）に直接接続します。

データベース統合の例パターン：

# メモリ内辞書をデータベースクエリに置き換える
employees = db.query("SELECT emp_id, name, leaves_taken FROM employees")
leave_requests = db.query("SELECT * FROM leave_requests WHERE emp_id = ?", [emp_id])

追加の機能拡張

• 認証と承認：ロールベースのアクセス制御（RBAC）を追加して、誰が休暇を承認/拒否できるかを制限します。
• 実際のメール/SMS統合：トランザクションメールプロバイダー（SendGrid、AWS SES）またはSMSゲートウェイ（Twilio）に接続します。
• 分析とレポート：年初からの要約、チームの休暇カレンダー、およびポリシー遵守レポートのためのMCPリソースを公開します。
• ウェブフックサポート：休暇が承認/拒否されたときに外部システムをトリガーします。
• マルチテナントサポート：SaaSデプロイメントのために組織/会社ごとにデータを分離します。