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