🤖 人力资源助理代理

一个由MCP驱动的智能人力资源管理系统，通过对话式人工智能自动化员工入职、休假管理、会议安排和IT票务。

📖 概述

HR Assistant Agent是一个基于模型上下文协议（MCP）的人工智能人力资源管理系统。它通过为常见的人力资源任务提供对话界面来简化人力资源运营，减少行政开销，使人力资源团队能够专注于战略举措而不是重复任务。

该系统将员工管理、休假跟踪、会议协调和IT设备配置集成到一个统一的平台中，该平台可通过与Claude AI的自然语言交互访问。

📊 视觉洞察

以下是HR Assistant Agent在实际操作中的示例，展示了其自动入职流程和MCP工具交互。

📸 屏幕截图	🔍 说明
Viz1	完整的入职流程-显示Claude为“Shabnam Kumari”精心策划了完整的员工入职流程，包括16个自动化步骤，包括人力资源管理系统添加、欢迎电子邮件、经理通知、设备票和会议安排
Viz2	入职完成总结-显示所有任务成功完成的详细明细：欢迎电子邮件发送至shabnam82101@gmail.com经理托尼·夏尔马通知，筹集了三张设备票（笔记本电脑、身份证、办公用品），并定于2026年1月15日举行介绍会
Viz3	幕后MCP工具调用-演示技术执行，显示Tony Sharma的get_employee_details请求/响应（E004）和带有JSON参数的add_employeee工具调用，用于在经理E004下引导“Nishant”
Viz4	最终入职确认-显示“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有用，请将其标记为星号！

HR Assistant Agent

快速接入

详细介绍

🤖 人力资源助理代理

📖 概述

📊 视觉洞察

主要特点

🎯 为何重要

它解决的问题

现实世界影响

🏗️ 建筑

系统设计

组件分解

1.MCP服务器层(server.py)

2.业务逻辑层

3.通信层(emails.py)

4.数据层(utils.py)

📁 项目结构

🛠️ 技术栈

核心技术

关键库

开发工具

🚀 设置和安装

先决条件

步骤1：克隆存储库

步骤2：安装依赖项

步骤3：配置环境变量

步骤4：配置Claude桌面

步骤5：运行服务器

💡 使用示例

示例1：新员工入职

示例2：检查假期余额

示例3：安排会议

示例4：创建IT票证

📊 种子试验数据

组织结构

示例数据包括

🔧 配置选项

电子邮件设置

休假余额默认值

门票ID格式

🔒 安全注意事项

已实施的最佳实践

其他建议

🐛 故障排除

常见问题

1.电子邮件未发送

2.MCP服务器未连接

3.未找到员工

4.会议冲突错误

调试模式

🤝 贡献

改进领域

如何做出贡献

代码规范

📝 许可证

🙏 致谢

📞 支持

🗺️ 路线图

版本2.0（2026年第二季度）

版本3.0（2026年第3季度）

版本4.0（2026年第4季度）

👨‍💻 作者

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1.MCP服务器层(`server.py`)

3.通信层(`emails.py`)

4.数据层(`utils.py`)