Scan to join WeChat grouparticle
README
🚀 🤖 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，你需要生成一个应用密码：
- 在你的Google账户上启用两步验证。
- 转到Google账户设置 → 安全 → 两步验证 → 应用密码。
- 为“邮件”生成一个新的应用密码。
- 在
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桌面版：
- 重启Claude桌面版。
- 查找表示MCP连接的 🔌 图标。
- 开始与你的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工具交互。
| 📸 截图 | 🔍 描述 |
|--------------|----------------|
| 
| 完整入职流程 - 展示Claude为“Shabnam Kumari”安排的完整员工入职流程，包含16个自动化步骤，包括添加到HRMS、发送欢迎邮件、通知上级、创建设备票务和安排会议。|
| 
| 入职完成总结 - 详细分解显示所有任务已成功完成：已向shabnam82101@gmail.com发送欢迎邮件，已通知上级Tony Sharma，已创建三张设备票务（笔记本电脑、身份证、办公用品），并已安排于2026年1月15日举行入职会议。|
| 
| 幕后MCP工具调用 - 展示技术执行过程，显示针对Tony Sharma (E004) 的get_employee_details请求/响应，以及使用JSON参数为经理E004下的“Nishant”办理入职的add_employee工具调用。|
| 
| 最终入职确认 - 显示“Nishant” (E009) 已成功入职，所有步骤均已完成：员工已添加，欢迎邮件已发送，上级通知已送达，已创建三张设备票务（T0011 - T0013），并已安排于2026年1月15日上午10点举行入职会议。|
为什么它很重要
解决的问题
- 手动HR流程：消除了重复性的手动数据输入和表单填写。
- 分散的系统：将多个HR功能统一到一个对话式界面中。
- 入职复杂性：通过自动化工作流程将多天的入职流程缩短至几分钟。
- 沟通负担：自动处理日常通知和提醒。
- 数据可访问性：无需在多个系统中导航即可即时访问员工信息。
实际影响
- 节省时间：将入职时间从数小时缩短至数分钟。
- 减少错误：自动化工作流程最大限度地减少了数据输入中的人为错误。
- 可扩展性：无需按比例增加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 # 依赖项锁定文件
🛠️ 技术栈
核心技术
| 技术 | 用途 | 版本 | |-----------|---------|---------| | Python | 主要语言 | 3.8+ | | FastMCP | MCP服务器框架 | 最新版本 | | Pydantic | 数据验证 | 2.0+ | | Claude AI | 对话式界面 | Sonnet 4.5 |
关键库
- 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等
🔒 安全考虑
已实施的最佳实践
- 环境变量：敏感凭证存储在
.env文件中。 - TLS/SSL：加密邮件通信。
- 无硬编码秘密：所有密码和令牌都外部化。
- 输入验证：Pydantic模式验证所有输入。
- 错误处理：提供优雅的错误消息，不暴露内部信息。
额外建议
- 切勿将
.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）
- [ ] 绩效评估模块
- [ ] 薪资集成
- [ ] 高级报表和分析
- [ ] 多语言支持
- [ ] 移动应用
如何贡献
- 分叉仓库。
- 创建一个功能分支 (
git checkout -b feature/amazing-feature)。 - 提交你的更改 (
git commit -m 'Add amazing feature')。 - 推送到分支 (
git push origin feature/amazing-feature)。 - 打开一个拉取请求。
代码标准
- 遵循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 提供强大的数据验证
- 开源社区提供灵感
📞 支持
👨💻 作者
NISHU KUMAR
- GitHub: 我的GitHub个人资料
- LinkedIn: 领英
- 邮箱: nishantranjan8875@gmail.com