Hr Assistant Agent

🚀 🤖 HR助理代理

這是一款由MCP驅動的智能人力資源管理系統，藉助對話式AI自動處理員工入職、休假管理、會議安排和IT票務等事務。

🚀 快速開始

HR助理代理是基於模型上下文協議（MCP）構建的人工智能人力資源管理系統。它通過為常見的人力資源任務提供對話式界面，簡化了人力資源操作，減少了行政負擔，使人力資源團隊能夠專注於戰略計劃，而非重複性任務。

該系統將員工管理、休假跟蹤、會議協調和IT設備供應集成到一個統一的平臺，可通過與Claude AI進行自然語言交互來訪問。

✨ 主要特性

• 🧑‍💼 員工管理：添加員工、檢索詳細信息、按姓名搜索並管理組織層級。
• 📅 休假管理：跟蹤休假餘額、處理申請並維護休假歷史記錄。
• 🗓️ 會議安排：安排、查看和取消會議，並進行衝突檢測。
• 🎫 IT票務：創建和跟蹤設備請求（筆記本電腦、顯示器、配件）。
• 📧 郵件自動化：自動發送入職、審批和更新的郵件通知。
• 🚀 智能入職：通過單個提示完成員工入職流程。

📦 安裝指南

前提條件

• 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. 轉到Google賬戶設置 → 安全 → 兩步驗證 → 應用密碼。
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的新員工辦理入職，其郵箱為alex.thompson@bluparrot.in，直屬上級是Sarah Johnson

Claude：我將幫助你為Alex Thompson辦理入職。我會：
        1. 將他們添加到系統中
        2. 發送歡迎郵件
        3. 通知他們的上級
        4. 創建設備票務
        5. 安排入職會議
        
        ✅ Alex Thompson (E009) 已成功添加
        ✅ 歡迎郵件已發送
        ✅ 上級Sarah Johnson已收到通知
        ✅ 已創建票務：筆記本電腦、身份證
        ✅ 會議已安排在明天上午10點

示例2：查詢休假餘額

你：Tony Sharma的休假餘額是多少？

Claude：Tony Sharma (E004) 還剩12天休假。

示例3：安排會議

你：為David Wilson安排一場於2026年1月20日下午2點的團隊同步會議

Claude：已為E003安排了一場關於“團隊同步”的會議，時間為2026-01-20T14:00:00。

示例4：創建IT票務

你：為Lisa Wong創建一張票務，請求為雙屏設置配備一臺新顯示器

Claude：已為E008創建票務T0012，請求為雙屏設置配備“顯示器”。

📚 詳細文檔

📊 可視化洞察

以下是HR助理代理在實際應用中的示例，展示了其自動化入職流程和MCP工具交互。

為什麼它很重要

解決的問題

1. 手動HR流程：消除了重複性的手動數據輸入和表單填寫。
2. 分散的系統：將多個HR功能統一到一個對話式界面中。
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) - 首席執行官
├── David Wilson (E003) - 工程經理
│   ├── Tony Sharma (E004) - 軟件工程師
│   └── James Rodriguez (E005) - 軟件工程師
│
Michael Chen (E002) - 首席產品官
└── 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賬戶已啟用兩步驗證。
• 生成應用密碼（而非常規密碼）。
• 驗證 .env 文件中的憑證是否正確。

2. MCP服務器未連接

問題：Claude桌面版未顯示MCP連接

解決方案：

• 檢查 claude_desktop_config.json 中的絕對路徑是否正確。
• 完全重啟Claude桌面版。
• 驗證配置中的Python路徑。
• 檢查 server.py 是否能獨立無錯誤運行。

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。

🗺️ 路線圖

版本2.0（2026年第二季度）

• [ ] PostgreSQL數據庫後端
• [ ] 帶有FastAPI的REST API
• [ ] 身份驗證和授權
• [ ] 審計日誌記錄

版本3.0（2026年第三季度）

• [ ] 基於Web的管理儀表盤
• [ ] 即時通知
• [ ] 文檔管理
• [ ] 績效評估工作流程

版本4.0（2026年第四季度）

• [ ] 人工智能驅動的HR洞察
• [ ] 預測分析
• [ ] 移動應用
• [ ] 多租戶支持

📄 許可證

本項目根據MIT許可證授權 - 有關詳細信息，請參閱 LICENSE 文件。

🙏 致謝

• Anthropic 提供Claude AI和MCP協議
• FastMCP 團隊提供出色的MCP框架
• Pydantic 提供強大的數據驗證
• 開源社區提供靈感

📞 支持

• 問題反饋：GitHub問題
• 討論：GitHub討論
• 郵箱：nishantranjan8875@gmail.com

👨‍💻 作者

NISHU KUMAR

• GitHub: 我的GitHub個人資料
• LinkedIn: 領英
• 郵箱: nishantranjan8875@gmail.com