# 🧑‍💼 HR Assist — MCP Server

An **MCP (Model Context Protocol) server** that automates HR onboarding tasks — HRMS registration, welcome emails, IT ticketing, meeting scheduling, and leave management — so an AI agent like Claude can handle the entire new-hire workflow from a single prompt. 🚀

---

## ✨ Features

| Area | What it does |
|---|---|
| 👤 **Employee Management** | Add employees, fetch details by (fuzzy) name search, look up managers & direct reports |
| 📧 **Email** | Send plain-text or HTML emails (with optional attachments) via SMTP |
| 🎫 **Ticketing** | Raise, update, and list IT/equipment tickets (laptop, ID card, etc.) |
| 📅 **Meetings** | Schedule, list, and cancel meetings for any employee |
| 🌴 **Leave Management** | Check leave balance, apply for leave, view leave history |
| ⚡ **Ready-made Prompt** | Built-in `onboard_new_employee` MCP prompt that chains all of the above into one onboarding flow |

---

## 🗂️ Project Structure

```
atliq-hr-assist/
├── server.py              # FastMCP server — defines all MCP tools & the onboarding prompt
├── emails.py              # EmailSender — SMTP email utility (plain/HTML + attachments)
├── utils.py               # seed_services() — seeds in-memory demo data
├── HRMS/
│   ├── __init__.py
│   ├── employee_manager.py   # EmployeeManager — employee CRUD + org hierarchy
│   ├── meeting_manager.py    # MeetingManager — schedule/list/cancel meetings
│   ├── leave_manager.py      # LeaveManager — leave balance & history
│   ├── ticket_manager.py     # TicketManager — IT/equipment tickets
│   └── schemas.py            # Pydantic models for all entities
├── pyproject.toml
├── .python-version
├── .gitignore
└── .env                   # 🔒 local secrets — never committed
```

> 📌 Note: `server.py` does `from HRMS import *`, so the manager classes (`employee_manager.py`, `meeting_manager.py`, etc.) and `schemas.py` should live inside an `HRMS/` package folder alongside `__init__.py`.

---

## 🛠️ Requirements

- 🐍 Python **3.10+**
- Dependencies (see `pyproject.toml`):
  - `fastmcp>=3.4.5`
  - `mcp[cli]>=1.9.4`
  - `pydantic>=2.13.4`
  - `python-dotenv`

---

## ⚙️ Setup

### 1. Clone & install

```bash
git clone https://github.com/Vraj-Data-Scientist/hr-onboarding-agent-with-MCP.git
cd hr-onboarding-agent-with-MCP

# using uv (recommended)
uv sync

# or using pip
pip install -e .
```

### 2. Configure environment variables

Create a `.env` file in the project root (already git-ignored 🔒):

```env
EMAIL=your-smtp-email@gmail.com
EMAIL_PWD=your-app-specific-password
```

> ⚠️ **Security note:** Use a Gmail **App Password**, not your real account password, and never commit `.env` to version control. If real credentials were ever pushed to a repo, rotate/revoke them immediately.

### 3. Run the server standalone (optional, for testing)

```bash
python server.py
```

This starts the MCP server over **stdio** transport.

---

## 🔌 Connecting to Claude as an MCP Client

This server speaks MCP over stdio, so it plugs directly into any MCP-compatible Claude client.

### 🖥️ Option A — Claude Desktop

1. Open your Claude Desktop config file:
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
2. Add this server under `mcpServers`:

```json
{
  "mcpServers": {
    "hr-onboarding-agent": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/hr-onboarding-agent-with-MCP",
        "mcp",
        "run",
        "server.py"
      ],
      "env": {
        "EMAIL": "your-smtp-email@gmail.com",
        "EMAIL_PWD": "your-app-specific-password"
      }
    }
  }
}
```

  

3. Restart Claude Desktop. A 🔨 tools icon should appear, showing the `hr-assist` server connected with tools like `add_employee`, `send_email`, `create_ticket`, `schedule_meeting`, and more.
4. Prompt Claude naturally, e.g.:
   > "Onboard a new employee named Priya Nair reporting to Tony Sharma."


### 💡 Using the built-in onboarding prompt

The server exposes a ready-made MCP prompt, `onboard_new_employee`, which Claude Desktop (via the `/` prompt picker) and Claude Code can surface directly — just supply `employee_name` and `manager_name`, and the full onboarding flow runs end-to-end.

---

## 🧪 Example

**Prompt:**
```
Onboard a new employee with the following details:
- Name: Vraj Dobariya
- Manager Name: Tony Sharma
```

**What happens automatically:**
1. 👤 Employee added to HRMS with correct manager mapping
2. 📧 Welcome email sent with generated login 
3. 📨 Manager notified of the new hire
4. 🎫 Tickets raised for laptop, ID card, and other equipment
5. 📅 Introductory meeting scheduled between employee and manager

---