Hr Assistant Agent

🚀 🤖 HRアシスタントエージェント

MCPを搭載したインテリジェントなHR管理システムで、会話型AIを通じて社員の入社手続き、休暇管理、会議スケジューリング、ITチケット管理を自動化します。

🚀 クイックスタート

HRアシスタントエージェントは、Model Context Protocol (MCP) をベースに構築されたAI搭載の人事管理システムです。一般的なHRタスクに会話型インターフェースを提供することで、HR業務を合理化し、管理作業の負担を軽減し、HRチームが戦略的な取り組みに集中できるようにします。

システムは、社員管理、休暇追跡、会議調整、IT機器の提供を統合し、Claude AIとの自然言語対話を通じてアクセス可能な統一プラットフォームにまとめています。

✨ 主な機能

• 🧑‍💼 社員管理：社員の追加、詳細情報の取得、名前での検索、組織階層の管理
• 📅 休暇管理：休暇残高の追跡、申請の処理、休暇履歴の管理
• 🗓️ 会議スケジューラー：会議のスケジュール設定、表示、キャンセル、および衝突検出
• 🎫 ITチケット：機器の要求（ラップトップ、モニター、アクセサリー）の作成と追跡
• 📧 メール自動化：入社手続き、承認、更新に関する自動メール通知
• 🚀 スマート入社手続き：1つのプロンプトで社員の入社手続きを完了

📦 インストール

前提条件

• Python 3.8以上
• Gmailアカウント（メール機能のため）
• uvパッケージマネージャー（オプションだが推奨）
• ClaudeデスクトップまたはAPIアクセス

ステップ1: リポジトリをクローンする

git clone https://github.com/yourusername/hr-assistant-agent.git
cd hr-assistant-agent

ステップ2: 依存関係をインストールする

uvを使用する場合（推奨）:

uv pip install -r requirements.txt

pipを使用する場合:

pip install fastmcp pydantic python-dotenv

ステップ3: 環境変数を設定する

プロジェクトのルートに .env ファイルを作成します。

SENDER_EMAIL=your-email@gmail.com
SENDER_EMAIL_PWD=your-app-password

📌 重要: Gmailの場合、アプリパスワードを生成する必要があります。

1. Googleアカウントで2段階認証を有効にします。
2. Googleアカウント設定 → セキュリティ → 2段階認証 → アプリパスワードにアクセスします。
3. "メール"用の新しいアプリパスワードを生成します。
4. このパスワードを SENDER_EMAIL_PWD に使用します。

ステップ4: Claudeデスクトップを設定する

Claudeデスクトップの設定にサーバーを追加します。

場所:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

設定:

{
  "mcpServers": {
    "hr-assistant": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "SENDER_EMAIL": "your-email@gmail.com",
        "SENDER_EMAIL_PWD": "your-app-password"
      }
    }
  }
}

ステップ5: サーバーを起動する

スタンドアロンモード（テスト用）:

python server.py

Claudeデスクトップと一緒に使用する場合:

1. Claudeデスクトップを再起動します。
2. MCP接続を示す🔌アイコンを探します。
3. HRアシスタントとの対話を開始します！

💻 使用例

例1: 新しい社員の入社手続き

あなた: メールアドレスが alex.thompson@bluparrot.in のAlex Thompsonという新しい社員を入社させて、Sarah Johnsonに報告するように設定してください。

Claude: Alex Thompsonの入社手続きを手伝います。以下のことを行います。
        1. システムに追加する
        2. 歓迎メールを送信する
        3. マネージャーに通知する
        4. 機器チケットを作成する
        5. 紹介会議をスケジュールする
        
        ✅ Alex Thompson (E009) が正常に追加されました
        ✅ 歓迎メールが送信されました
        ✅ マネージャーのSarah Johnsonに通知されました
        ✅ チケットが作成されました: ラップトップ、IDカード
        ✅ 会議が明日の10時にスケジュールされました

例2: 休暇残高の確認

あなた: Tony Sharmaの休暇残高はいくらですか？

Claude: Tony Sharma (E004) の残り休暇日数は12日です。

例3: 会議のスケジュール設定

あなた: 2026年1月20日の午後2時にDavid Wilsonのチーム同期会議をスケジュールしてください。

Claude: 2026-01-20T14:00:00にE003のための「チーム同期」会議がスケジュールされました。

例4: ITチケットの作成

あなた: Lisa Wongがデュアルスクリーン設定用の新しいモニターを要求するチケットを作成してください。

Claude: E008のために「モニター」をデュアルスクリーン設定用に要求するチケットT0012が作成されました。

📚 ドキュメント

可視化インサイト

以下は、HRアシスタントエージェントの実際の動作例で、自動化された入社手続きワークフローとMCPツールの相互作用を示しています。

なぜこのシステムが重要か

解決する問題

1. 手動のHRプロセス：繰り返しの手動データ入力とフォーム記入を排除します。
2. 分散したシステム：複数のHR機能を1つの会話型インターフェースに統合します。
3. 入社手続きの複雑さ：自動化されたワークフローにより、数日間かかる入社手続きを数分に短縮します。
4. コミュニケーションの負担：日常的な通知とリマインダーを自動化します。
5. データのアクセシビリティ：複数のシステムをナビゲートすることなく、社員情報に即座にアクセスできます。

実世界での影響

• 時間の節約：入社手続きにかかる時間を数時間から数分に短縮します。
• エラーの削減：自動化されたワークフローにより、データ入力の人為的エラーを最小限に抑えます。
• スケーラビリティ：HRスタッフを比例的に増やすことなく、増える社員数を容易に処理できます。
• 社員体験：新入社員はタイムリーなコミュニケーションと機器の提供を受けます。

アーキテクチャ

システム設計

┌─────────────────────────────────────────────────────────────┐
│                        Claude AI                            │
│                 (Conversational Interface)                  │
└────────────────────────┬────────────────────────────────────┘
                         │
                         │ MCP Protocol
                         │
┌────────────────────────▼────────────────────────────────────┐
│                    FastMCP Server                           │
│                    (server.py)                              │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              MCP Tools Layer                         │   │
│  │  • add_employee      • schedule_meeting              │   │
│  │  • get_employee      • cancel_meeting                │   │
│  │  • apply_leave       • create_ticket                 │   │
│  │  • send_email        • update_ticket                 │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
            ┌────────────┼────────────┐
            │            │            │
┌───────────▼──┐  ┌──────▼─────┐  ┌──▼──────────┐
│  Employee    │  │   Leave    │  │  Meeting    │
│  Manager     │  │  Manager   │  │  Manager    │
└──────────────┘  └────────────┘  └─────────────┘
            │            │            │
            └────────────┼────────────┘
                         │
                ┌────────▼─────────┐
                │  Ticket Manager  │
                └──────────────────┘
                         │
                ┌────────▼─────────┐
                │  Email Sender    │
                │   (SMTP/Gmail)   │
                └──────────────────┘

コンポーネントの詳細

1. MCPサーバー層 (server.py)

• HR操作をMCPツールとして公開します。
• リクエストのルーティングと検証を処理します。
• 複雑なワークフローのプロンプトテンプレートを管理します。
• 異なるマネージャー間の調整を行います。

2. ビジネスロジック層

• EmployeeManager：社員のCRUD操作と組織構造を処理します。
• LeaveManager：休暇申請を処理し、残高/履歴を管理します。
• MeetingManager：会議のスケジュール設定と衝突検出を行います。
• TicketManager：IT機器の要求をライフサイクル全体で追跡します。

3. 通信層 (emails.py)

• SMTPを介した自動メール通知を行います。
• HTMLメールと添付ファイルのサポートがあります。
• TLS/SSLによる安全な接続を提供します。

4. データ層 (utils.py)

• 開発用のテストデータを用意しています。
• 8人の社員を持つモック社員データベースがあります。
• サンプルの休暇記録、会議、チケットがあります。

プロジェクト構造

HR-Assistant-Agent/
│
├── HRMS/                          # コアHR管理モジュール
│   ├── __init__.py               # パッケージの初期化
│   ├── employee_manager.py       # 社員操作
│   ├── leave_manager.py          # 休暇追跡
│   ├── meeting_manager.py        # 会議スケジューリング
│   ├── ticket_manager.py         # ITチケットシステム
│   └── schemas.py                # Pydanticデータモデル
│
├── server.py                      # FastMCPサーバーとツールの定義
├── emails.py                      # メール自動化モジュール
├── utils.py                       # データシーディングユーティリティ
│
├── .env                          # 環境変数（リポジトリには含まれない）
├── .gitignore                    # Gitの無視ルール
├── pyproject.toml                # プロジェクトの依存関係
├── python-version.txt            # Pythonのバージョン指定
├── README.md                     # このファイル
└── uv.lock                       # 依存関係のロックファイル

技術スタック

コア技術

主要なライブラリ

• smtplib：SMTPメールプロトコル
• ssl：安全なメール接続
• dotenv：環境変数の管理
• datetime：日付/時間の処理
• typing：型ヒントと検証
• difflib：曖昧な名前のマッチング

開発ツール

• uv：高速なPythonパッケージインストーラー
• VS Code：推奨のIDE
• Git：バージョン管理

シード済みテストデータ

システムには、すぐに実験できるようにテストデータが事前に用意されています。

組織構造

Sarah Johnson (E001) - CEO
├── David Wilson (E003) - エンジニアリングマネージャー
│   ├── Tony Sharma (E004) - ソフトウェアエンジニア
│   └── James Rodriguez (E005) - ソフトウェアエンジニア
│
Michael Chen (E002) - CPO
└── Emily Kim (E006) - プロダクトマネージャー
    ├── Carlos Mendez (E007) - プロダクトデザイナー
    └── Lisa Wong (E008) - プロダクトアナリスト

サンプルデータには以下が含まれます

• 8人の社員：リーダーシップ、エンジニアリング、プロダクトチームに所属
• ランダムな休暇残高（社員ごとに5 - 20日）
• 過去の休暇記録（1 - 90日前）
• スケジュールされた会議（次の10日間）
• ITチケット（ラップトップ、モニター、アクセサリー）

設定オプション

メール設定

server.py の EmailSender の初期化を変更します。

emailer = EmailSender(
    smtp_server="smtp.gmail.com",  # 他のプロバイダーの場合は変更
    port=587,                       # TLSの場合は587、SSLの場合は465
    username=os.getenv("SENDER_EMAIL"),
    password=os.getenv("SENDER_EMAIL_PWD"),
    use_tls=True                    # SSLの場合はFalse
)

休暇残高のデフォルト

leave_manager.py で調整します。

self.employee_leaves: Dict[str, Dict] = defaultdict(
    lambda: {"balance": 20, "history": []}  # デフォルトの残高を変更
)

チケットIDの形式

ticket_manager.py で変更します。

ticket_id = f"T{self._next_id:04d}"  # 形式: T0001, T0002, など

🔧 技術詳細

セキュリティに関する考慮事項

実装されたベストプラクティス

1. 環境変数：機密情報は .env ファイルに保存されます。
2. TLS/SSL：暗号化されたメール通信が行われます。
3. ハードコードされたシークレットなし：すべてのパスワードとトークンは外部化されています。
4. 入力検証：Pydanticスキーマによりすべての入力が検証されます。
5. エラーハンドリング：内部情報を公開せずに、適切なエラーメッセージが表示されます。

追加の推奨事項

• .env ファイルをバージョン管理にコミットしないでください
• Gmailにはアプリ固有のパスワードを使用してください（メインパスワードではなく）
• 本番環境ではレート制限を実装してください
• Webサービスとして公開する場合は認証を追加してください
• 機密性の高いHR操作には監査ログを追加してください
• 本番データベースでは保存データを暗号化してください

トラブルシューティング

一般的な問題と解決策

1. メールが送信されない

問題: SMTPAuthenticationError: Username and Password not accepted

解決策:

• Googleアカウントで2FAが有効になっていることを確認してください。
• アプリパスワード（通常のパスワードではなく）を生成してください。
• .env ファイルに正しい資格情報が記載されていることを確認してください。

2. MCPサーバーに接続できない

問題: ClaudeデスクトップにMCP接続が表示されない

解決策:

• claude_desktop_config.json に正しい絶対パスが記載されていることを確認してください。
• Claudeデスクトップを完全に再起動してください。
• 設定内のPythonパスを確認してください。
• サーバーがスタンドアロンでエラーなく実行されることを確認してください。

3. 社員が見つからない

問題: ValueError: Employee ID 'E999' not found

解決策:

• search_employee_by_name() を使用して曖昧な名前のマッチングを行ってください。
• シードデータに社員が存在することを確認してください。
• 社員IDの形式（E001, E002, など）を確認してください。

4. 会議の衝突エラー

問題: ValueError: Conflict: E001 already has a meeting at datetime

解決策:

• get_meetings() を使用して既存の会議を確認してください。
• 別の時間帯を選択してください。
• 必要に応じて、衝突する会議を最初にキャンセルしてください。

デバッグモード

詳細なログを有効にするには、以下のコードを使用します。

import logging
logging.basicConfig(level=logging.DEBUG)

🤝 コントリビューション

コントリビューションは大歓迎です！以下はあなたが支援できる方法です。

改善の余地

• [ ] データベース統合（PostgreSQL/MongoDB）
• [ ] REST APIエンドポイント
• [ ] WebダッシュボードUI
• [ ] Slack/Teams統合
• [ ] カレンダー同期（Googleカレンダー、Outlook）
• [ ] パフォーマンスレビューモジュール
• [ ] 給与統合
• [ ] 高度なレポートと分析
• [ ] 多言語サポート
• [ ] モバイルアプリ

コントリビュートする方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します (git checkout -b feature/amazing-feature)。
3. 変更をコミットします (git commit -m 'Add amazing feature')。
4. ブランチにプッシュします (git push origin feature/amazing-feature)。
5. プルリクエストを作成します。

コード標準

• PEP 8スタイルガイドに従ってください。
• すべての関数に型ヒントを追加してください。
• 公開メソッドにドキュメント文字列を記述してください。
• 新しい機能には単体テストを含めてください。
• 新しい機能についてREADMEを更新してください。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。

🙏 謝辞

• Anthropic のClaude AIとMCPプロトコル
• FastMCP チームの優れたMCPフレームワーク
• Pydantic の堅牢なデータ検証
• オープンソースコミュニティのインスピレーション

📞 サポート

• 問題報告: GitHub Issues
• ディスカッション: GitHub Discussions
• メール: nishantranjan8875@gmail.com

🗺️ ロードマップ

バージョン2.0 (2026年第2四半期)

• [ ] PostgreSQLデータベースバックエンド
• [ ] FastAPIを使用したREST API
• [ ] 認証と承認
• [ ] 監査ログ

バージョン3.0 (2026年第3四半期)

• [ ] Webベースの管理ダッシュボード
• [ ] リアルタイム通知
• [ ] ドキュメント管理
• [ ] パフォーマンスレビューワークフロー

バージョン4.0 (2026年第4四半期)

• [ ] AI搭載のHRインサイト
• [ ] 予測分析
• [ ] モバイルアプリケーション
• [ ] マルチテナントサポート

👨‍💻 作者

NISHU KUMAR

• GitHub: My Github Profile
• LinkedIn: LinkedIn
• Email: nishantranjan8875@gmail.com