# 🏢 Atliq HRMS Assist — MCP Server

An AI-powered **Human Resource Management System (HRMS)** built as a **Model Context Protocol (MCP) server**. It connects directly to Claude Desktop, allowing you to manage employees, leaves, meetings, tickets, and emails using natural language.

---

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Project Structure](#project-structure)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Running the MCP Server](#running-the-mcp-server)
- [Connecting to Claude Desktop](#connecting-to-claude-desktop)
- [Available Tools](#available-tools)
- [Available Prompts](#available-prompts)
- [Usage Examples](#usage-examples)

---

## 🌟 Overview

Atliq HRMS Assist is an MCP server that exposes HR management capabilities as tools and prompts for AI assistants. Built with [FastMCP](https://github.com/jlowin/fastmcp) and [Pydantic](https://docs.pydantic.dev/), it enables Claude to perform real HR operations — from onboarding employees to scheduling meetings — all through natural language.

---

## ✨ Features

| Category | Capability |
|---|---|
| 👤 **Employee Management** | Add employees, search by name, get details |
| 🌴 **Leave Management** | Check balances, apply leaves, view history |
| 📅 **Meeting Scheduler** | Schedule, view, and cancel meetings |
| 🎫 **Ticket System** | Create and update equipment/IT request tickets |
| 📧 **Email Notifications** | Send welcome emails, meeting invites, leave confirmations |
| 🤖 **AI Prompts** | Pre-built prompts for onboarding, leave, and meeting workflows |

---

## 📁 Project Structure

```
atliq-hrms-assist/
├── HRMS/
│   ├── __init__.py          # Exports all managers and schemas
│   ├── employee_manager.py  # Employee CRUD and search
│   ├── leave_manager.py     # Leave balance and application
│   ├── meeting_manager.py   # Meeting scheduling and cancellation
│   ├── ticket_manager.py    # Equipment/IT ticket management
│   └── schemas.py           # Pydantic data models
├── src/
│   └── atliq_hrms_assist/
│       └── __init__.py
├── email_sender.py          # SMTP email utility
├── server.py                # MCP server — tools & prompts
├── utils.py                 # Seed data for demo employees
├── pyproject.toml           # Project dependencies
└── .env                     # Environment variables (not committed)
```

---

## ✅ Prerequisites

- Python **3.12+**
- [uv](https://docs.astral.sh/uv/) package manager
- [Claude Desktop](https://claude.ai/download) (for MCP integration)
- A **Gmail account** with an [App Password](https://myaccount.google.com/apppasswords) (for email sending)

---

## ⚙️ Installation

### 1. Clone the repository

```bash
git clone https://github.com/Ayush-og/atliq-hrms-assist.git
cd atliq-hrms-assist
```

### 2. Install dependencies using `uv`

```bash
uv sync
```

Or install manually:

```bash
uv add "mcp[cli]<2.0.0" pydantic python-dotenv
```

---

## 🔐 Configuration

Create a `.env` file in the project root:

```env
CB_EMAIL=your_gmail_address@gmail.com
CB_EMAIL_PWD=your_gmail_app_password
```

> **Note:** Use a [Gmail App Password](https://myaccount.google.com/apppasswords), not your regular Gmail password. Enable 2FA on your account first.

---

## 🚀 Running the MCP Server

Test that the server runs without errors:

```bash
uv run python server.py
```

---

## 🔗 Connecting to Claude Desktop

1. Open **Claude Desktop** → Settings → **Developer** → **Edit Config**.
2. Add the following to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "atliq-hr-assist": {
      "command": "C:\\Users\\<your-username>\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "C:\\path\\to\\atliq-hrms-assist",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}
```

3. **Save** and **restart Claude Desktop**.
4. The `atliq-hr-assist` connector will appear as 🟢 **Connected**.

---

## 🛠️ Available Tools

### 👤 Employee Tools
| Tool | Description | Parameters |
|---|---|---|
| `add_employee` | Add a new employee | `emp_name`, `manager_id`, `email` |
| `get_employee_details` | Get employee details by name | `name` |

### 🌴 Leave Manager Tools
| Tool | Description | Parameters |
|---|---|---|
| `get_leave_balance` | Check remaining leave days | `employee_id` |
| `apply_leave` | Apply for leave on specific dates | `employee_id`, `leave_dates` |
| `get_leave_history` | View past leave records | `employee_id` |

### 📅 Meeting Scheduler Tools
| Tool | Description | Parameters |
|---|---|---|
| `schedule_meeting` | Schedule a meeting | `emp_id`, `meeting_dt`, `topic` |
| `get_meetings` | View all scheduled meetings | `employee_id` |
| `cancel_meeting` | Cancel an existing meeting | `emp_id`, `meeting_dt`, `topic` |

### 🎫 Ticket Tools
| Tool | Description | Parameters |
|---|---|---|
| `create_ticket` | Raise an equipment/IT request | `emp_id`, `item`, `reason` |
| `update_ticket_status` | Update ticket status | `ticket_id`, `status` |

### 📧 Email Tool
| Tool | Description | Parameters |
|---|---|---|
| `send_email` | Send email to one or more recipients | `subject`, `body`, `to_emails` |

---

## 🤖 Available Prompts

These are pre-built multi-step workflows you can invoke from Claude Desktop via **"Add from atliq-hr-assist"**.

### 1. `onboard_new_employee`
Onboards a new employee end-to-end.

| Input | Description |
|---|---|
| `employee_name` | Full name of the new employee |
| `manager_name` | Full name of the reporting manager |

**Steps performed automatically:**
- Adds employee to HRMS
- Sends welcome email with login credentials
- Notifies the manager
- Raises equipment tickets (laptop, ID card, etc.)

---

### 2. `apply_leave_request`
Processes a leave application for an employee.

| Input | Description |
|---|---|
| `employee_name` | Full name of the employee |
| `leave_dates` | Dates for leave (e.g. `"2026-08-22, 2026-08-23"`) |

**Steps performed automatically:**
- Looks up employee ID
- Checks leave balance
- Applies leave if balance is sufficient
- Sends confirmation email

---

### 3. `schedule_meeting_request`
Schedules a meeting and sends invites.

| Input | Description |
|---|---|
| `employee_name` | Employee's full name |
| `manager_name` | Manager's full name |
| `meeting_date` | ISO datetime (e.g. `"2026-08-20T10:00:00"`) |
| `topic` | Meeting subject |

**Steps performed automatically:**
- Looks up both employee and manager IDs
- Schedules the meeting
- Sends invitation email to both parties

---

## 💡 Usage Examples

Ask Claude in natural language:

```
"Onboard Peter Pandey with Tony Sharma as his manager."
```

```
"Apply leave for Tony Sharma on August 22 and 23, 2026."
```

```
"Schedule a 1:1 meeting between Peter Pandey and Tony Sharma on August 20 at 10 AM."
```

```
"Check leave balance for employee E004."
```

```
"Create a ticket for Peter Pandey to get a new laptop."
```

---

## 🧑‍💻 Author

**Ayush** — [@Ayush-og](https://github.com/Ayush-og)

---

## 📄 License

This project is open source and available under the [MIT License](LICENSE).