🤖 人力资源助理代理
一个由MCP驱动的智能人力资源管理系统，通过对话式人工智能自动化员工入职、休假管理、会议安排和IT票务。
📖 概述
HR Assistant Agent是一个基于模型上下文协议（MCP）的人工智能人力资源管理系统。它通过为常见的人力资源任务提供对话界面来简化人力资源运营，减少行政开销，使人力资源团队能够专注于战略举措而不是重复任务。
该系统将员工管理、休假跟踪、会议协调和IT设备配置集成到一个统一的平台中，该平台可通过与Claude AI的自然语言交互访问。
📊 视觉洞察
以下是HR Assistant Agent在实际操作中的示例，展示了其自动入职流程和MCP工具交互。
| 📸 屏幕截图 | 🔍 说明 |
|---|---|
| 完整的入职流程-显示Claude为“Shabnam Kumari”精心策划了完整的员工入职流程，包括16个自动化步骤，包括人力资源管理系统添加、欢迎电子邮件、经理通知、设备票和会议安排 | |
| 入职完成总结-显示所有任务成功完成的详细明细：欢迎电子邮件发送至shabnam82101@gmail.com经理托尼·夏尔马通知，筹集了三张设备票（笔记本电脑、身份证、办公用品），并定于2026年1月15日举行介绍会 | |
| 幕后MCP工具调用-演示技术执行，显示Tony Sharma的get_employee_details请求/响应（E004）和带有JSON参数的add_employeee工具调用，用于在经理E004下引导“Nishant” | |
| 最终入职确认-显示“Nishant”（E009）已成功入职，所有步骤均已完成：添加员工、发送欢迎电子邮件、发送经理通知、创建三张设备票（T0011-T0013），以及定于2026年1月15日上午10:00举行的介绍会 |
主要特点
- 🧑💼 员工管理：添加员工、检索详细信息、按姓名搜索和管理组织层次结构
- 📅 休假管理：跟踪休假余额、处理申请并维护休假历史记录
- 🗓️ 会议日程安排：使用冲突检测来安排、查看和取消会议
- 🎫 IT票务：创建和跟踪设备请求（笔记本电脑、显示器、配件）
- 📧 电子邮件自动化：用于入职、审批和更新的自动电子邮件通知
- 🚀 智能登机：只需一个提示即可完成员工入职流程
🎯 为何重要
它解决的问题
- 人力资源手动流程：消除了重复的手动数据输入和表单填写
- 分散的系统：将多个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)
- 将人力资源运营作为MCP工具公开
- 处理请求路由和验证
- 管理复杂工作流的提示模板
- 不同管理者之间的协调
2.业务逻辑层
- 员工经理：处理员工CRUD操作和组织结构
- 离职经理：处理休假申请并保持余额/历史记录
- 会议经理：安排冲突检测会议
- 票务经理：在IT设备的整个生命周期中跟踪其请求
3.通信层(emails.py)
- SMTP集成用于自动电子邮件通知
- 支持HTML电子邮件和附件
- TLS/SSL安全连接
4.数据层(utils.py)
- 用于开发的种子测试数据
- 包含8名员工的模拟员工数据库
- 休假记录、会议和门票样本
📁 项目结构
HR-Assistant-Agent/
│
├── HRMS/ # Core HR management modules
│ ├── __init__.py # Package initialization
│ ├── employee_manager.py # Employee operations
│ ├── leave_manager.py # Leave tracking
│ ├── meeting_manager.py # Meeting scheduling
│ ├── ticket_manager.py # IT ticketing system
│ └── schemas.py # Pydantic data models
│
├── server.py # FastMCP server & tool definitions
├── emails.py # Email automation module
├── utils.py # Data seeding utilities
│
├── .env # Environment variables (not in repo)
├── .gitignore # Git ignore rules
├── pyproject.toml # Project dependencies
├── python-version.txt # Python version specification
├── README.md # This file
└── uv.lock # Dependency lock file🛠️ 技术栈
核心技术
| 技术 | 目的 | 版本 |
|---|---|---|
| python | 主要语言 | 3.8+ |
| FastMCP | MCP服务器框架 | 最新 |
| 派丹蒂克 | 数据验证 | 2.0+ |
| 克劳德·艾 | 对话界面 | Sonnet 4.5 |
关键库
- smtplib：SMTP电子邮件协议
- 安全套接层：安全的电子邮件连接
- Dotenv。：环境变量管理
- 日期时间：日期/时间处理
- 打字：类型提示和验证
- difflib：模糊名称匹配
开发工具
- 紫外线：快速Python包安装程序
- VS Code：推荐IDE
- Git：版本控制
🚀 设置和安装
先决条件
- Python 3.8或更高版本
- Gmail帐户（用于电子邮件功能）
- uv包管理器 （可选但推荐）
- Claude Desktop或API访问
步骤1：克隆存储库
git clone https://github.com/yourusername/hr-assistant-agent.git
cd hr-assistant-agent步骤2：安装依赖项
使用紫外线（推荐）：
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，您需要生成 应用程序密码:
- 在您的Google帐户上启用双因素身份验证
- 转到Google帐户设置→ 安全→ 2-步骤验证→ 应用程序密码
- 为“邮件”生成新的应用程序密码
- 在中使用此密码
SENDER_EMAIL_PWD
步骤4：配置Claude桌面
将服务器添加到您的Claude Desktop配置中：
位置:
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%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使用克劳德桌面：
- 重新启动克劳德桌面
- 寻找🔌 指示MCP连接的图标
- 开始与您的人力资源助理互动！
💡 使用示例
示例1：新员工入职
You: Onboard a new employee named Alex Thompson with email alex.thompson@bluparrot.in
reporting to Sarah Johnson
Claude: I'll help you onboard Alex Thompson. Let me:
1. Add them to the system
2. Send welcome email
3. Notify their manager
4. Create equipment tickets
5. Schedule introductory meeting
✅ Alex Thompson (E009) added successfully
✅ Welcome email sent
✅ Manager Sarah Johnson notified
✅ Tickets created: Laptop, ID Card
✅ Meeting scheduled for tomorrow at 10 AM示例2：检查假期余额
You: What's Tony Sharma's leave balance?
Claude: Tony Sharma (E004) has 12 leave days remaining.示例3：安排会议
You: Schedule a team sync meeting for David Wilson on January 20, 2026 at 2 PM
Claude: Meeting scheduled for E003 on 2026-01-20T14:00:00 about 'Team Sync'.示例4：创建IT票证
You: Create a ticket for Lisa Wong requesting a new monitor for dual screen setup
Claude: Ticket T0012 created for E008 requesting 'Monitor' for dual screen setup.📊 种子试验数据
该系统预先填充了测试数据，以便立即进行实验：
组织结构
Sarah Johnson (E001) - CEO
├── David Wilson (E003) - Engineering Manager
│ ├── Tony Sharma (E004) - Software Engineer
│ └── James Rodriguez (E005) - Software Engineer
│
Michael Chen (E002) - CPO
└── Emily Kim (E006) - Product Manager
├── Carlos Mendez (E007) - Product Designer
└── Lisa Wong (E008) - Product Analyst示例数据包括
- 8名员工 跨领导层、工程和产品团队
- 随机休假余额 （每位员工5-20天）
- 历史休假记录 （1-90天前）
- 预定会议 （接下来的10天）
- IT门票 （笔记本电脑、显示器、配件）
🔧 配置选项
电子邮件设置
修改 EmailSender 初始化中 server.py:
emailer = EmailSender(
smtp_server="smtp.gmail.com", # Change for other providers
port=587, # 587 for TLS, 465 for SSL
username=os.getenv("SENDER_EMAIL"),
password=os.getenv("SENDER_EMAIL_PWD"),
use_tls=True # False for SSL
)休假余额默认值
调整 leave_manager.py:
self.employee_leaves: Dict[str, Dict] = defaultdict(
lambda: {"balance": 20, "history": []} # Change default balance
)门票ID格式
修改 ticket_manager.py:
ticket_id = f"T{self._next_id:04d}" # Format: T0001, T0002, etc.🔒 安全注意事项
已实施的最佳实践
- 环境变量：敏感凭据存储在
.env文件 - TLS/SSL：加密电子邮件通信
- 没有硬编码的秘密：所有密码和令牌都外部化
- 输入验证：Pydantic模式验证所有输入
- 错误处理：优雅的错误消息，不暴露内部
其他建议
- 永不承诺
.env文件 到版本控制 - 使用特定于应用程序的密码 适用于Gmail（不是您的主密码）
- 实施速率限制 用于生产部署
- 添加身份验证 如果作为web服务公开
- 审计日志 适用于敏感的人力资源运营
- 加密存储的数据 生产数据库
🐛 故障排除
常见问题
1.电子邮件未发送
问题: SMTPAuthenticationError: Username and Password not accepted
解决方案:
- 确保您的Google帐户已启用2FA
- 生成应用程序密码（不是常规密码）
- 验证
.env文件具有正确的凭据
2.MCP服务器未连接
问题：Claude Desktop未显示MCP连接
解决方案:
- 检查
claude_desktop_config.json具有正确的绝对路径 - 完全重新启动克劳德桌面
- 验证配置中的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仪表板用户界面
- \[\]Slack/团队集成
- \[\]日历同步（谷歌日历、Outlook）
- \[\]绩效评估模块
- \[\]工资单集成
- \[\]高级报告和分析
- \[\]多语言支持
- \[\]移动应用程序
如何做出贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
代码规范
- 遵循PEP 8风格指南
- 为所有函数添加类型提示
- 为公共方法编写文档字符串
- 包括新功能的单元测试
- 更新README以获取新功能
📝 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
- Anthropic 用于Claude AI和MCP协议
- FastMCP 优秀MCP框架团队
- 派丹蒂克 用于稳健的数据验证
- 开源社区激发灵感
📞 支持
- 问题:
- 讨论:
- 电子邮件: nishantranjan8875@gmail.com
🗺️ 路线图
版本2.0（2026年第二季度）
- \[\]PostgreSQL数据库后端
- \[\]带有FastAPI的REST API
- \[\]身份验证和授权
- \[\]审核日志记录
版本3.0（2026年第3季度）
- \[\]基于Web的管理仪表板
- \[\]实时通知
- \[\]文件管理
- \[\]绩效评估工作流程
版本4.0（2026年第4季度）
- \[\]人工智能驱动的人力资源洞察
- \[\]预测分析
- \[\]移动应用程序
- \[\]多租户支持
👨💻 作者
西久久
- github：
- 领英： 领英
- 电子邮件：nishantranjan8875@gmail.com
______________________________________________________________________
建于❤️ 使用Claude AI和FastMCP
⭐ 如果你觉得这个repo有用，请将其标记为星号！