# 🤖 HR-Assist — Agentic AI HR Helpdesk

**HR-Assist** is an Agentic AI system that helps HR teams automate routine workflows using Claude Desktop as the MCP client and a custom Python MCP server as the backend.

This project demonstrates end-to-end automation of the **employee onboarding process** — tasks that typically require multiple manual steps are handled by the AI agent in a single prompt.

---

## ✨ What It Does

| Task | Automated? |
|---|---|
| Add employee to HRMS | ✅ |
| Send welcome email with credentials | ✅ |
| Notify the manager | ✅ |
| Raise tickets for laptop, ID card & equipment | ✅ |
| Schedule introductory meeting | ✅ |
| Leave management | ✅ |
| Ticket tracking & updates | ✅ |

---

## 🏗️ Architecture

```
┌─────────────────────┐         MCP Protocol        ┌─────────────────────┐
│                     │ ◄─────────────────────────► │                     │
│   Claude Desktop    │                              │   HR-Assist Server  │
│   (MCP Client)      │                              │   (Python + uv)     │
│                     │                              │                     │
└─────────────────────┘                              └─────────────────────┘
                                                              │
                                              ┌───────────────┼───────────────┐
                                              ▼               ▼               ▼
                                     employee_manager  leave_manager  ticket_manager
                                     meeting_manager   schemas        utils
```

- **MCP Client** → Claude Desktop
- **MCP Server** → This codebase (`server.py` + `hrms/` modules)
- **Email** → SMTP via Gmail App Password

---

## 📁 Project Structure

```
HR_helpdesk/
│
├── hrms/
│   ├── __init__.py
│   ├── employee_manager.py    # Add & fetch employee logic
│   ├── leave_manager.py       # Leave apply, balance, history
│   ├── meeting_manager.py     # Schedule & fetch meetings
│   ├── ticket_manager.py      # Create & update tickets
│   └── schemas.py             # Pydantic data models
│
├── server.py                  # MCP server entry point
├── utils.py                   # Shared utility functions
├── emails.py                  # Email sending logic (SMTP)
├── pyproject.toml             # Project config (uv)
├── sample.env                 # Environment variable template
└── README.md
```

---

## ⚙️ Setup Instructions

### Prerequisites
- [Claude Desktop](https://claude.ai/download) installed
- [uv](https://docs.astral.sh/uv/getting-started/installation/) installed
- Gmail account with [App Password](https://myaccount.google.com/apppasswords) enabled

---

### 1. Clone the Repository

```bash
git clone https://github.com/saibalajijammu/HR_helpdesk.git
cd HR_helpdesk
```

### 2. Install Dependencies

```bash
uv init
uv add mcp[cli]
```

### 3. Set Up Environment Variables

```bash
cp sample.env .env
```

Edit `.env` and fill in:
```
CB_EMAIL=your_email@gmail.com
CB_EMAIL_PWD=your_gmail_app_password
```

### 4. Configure Claude Desktop

Open your `claude_desktop_config.json` file and add the following:

> **Location of config file:**
> - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
> - Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "hr-assist": {
      "command": "C:\\Users\\<your-username>\\.local\\bin\\uv",
      "args": [
        "--directory",
        "<full-path-to-project>\\HR_helpdesk",
        "run",
        "server.py"
      ],
      "env": {
        "CB_EMAIL": "YOUR_EMAIL",
        "CB_EMAIL_PWD": "YOUR_APP_PASSWORD"
      }
    }
  }
}
```

> Replace `<your-username>` and `<full-path-to-project>` with your actual values.

### 5. Restart Claude Desktop

After saving the config, fully restart Claude Desktop. You should see **hr-assist** appear as a connected MCP server.

---

## 💬 Usage

### Option 1 — Quick Onboarding via UI
1. Click the **`+`** icon in Claude Desktop
2. Select **`Add from hr-assist`**
3. Fill in the employee details when prompted

### Option 2 — Custom Prompt (Recommended)

Just type a natural language prompt like:

```
Onboard a new employee named Priya Mehta under manager Raj Kumar.
```

The agent will automatically:
- ✅ Add her to the HRMS
- ✅ Send a welcome email
- ✅ Notify her manager
- ✅ Raise tickets for laptop, ID card & equipment
- ✅ Schedule an intro meeting

---

## 🔑 Environment Variables

| Variable | Description |
|---|---|
| `CB_EMAIL` | Your Gmail address used for sending emails |
| `CB_EMAIL_PWD` | Gmail App Password (not your regular password) |

---

## 🧰 Tech Stack

| Component | Technology |
|---|---|
| AI Model | Claude (Anthropic) |
| MCP Client | Claude Desktop |
| MCP Server | Python + `mcp[cli]` |
| Package Manager | `uv` |
| Email | SMTP (Gmail) |
| Data Validation | Pydantic (`schemas.py`) |

---

## 🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you'd like to change.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).

---

<p align="center">Built with 🧠 by <a href="https://github.com/saibalajijammu">Saibalaji Jammu</a></p>