# 🏢 #GyanLabs-Agentic-HRMS: Autonomous HR Model Context Protocol (MCP) Server

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Protocol%20v1.0-8A2BE2.svg)](https://modelcontextprotocol.io/)
[![FastMCP](https://img.shields.io/badge/Built%20With-FastMCP-0ea5e9.svg)](https://github.com/jlowin/fastmcp)
[![Claude Desktop](https://img.shields.io/badge/Claude%20Desktop-Compatible-D97706.svg)](https://claude.ai/download)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

> [!NOTE]
> **Educational & Demonstration Disclaimer:**
> This project, including the fictitious company identity ("#Gyan Labs / HashGyan Technologies"), employee personas, email domains (`@gyanlabs.ai`), internal policies, and datasets, is created strictly for **educational, portfolio, and research demonstration purposes**. All characters, roles, and enterprise scenarios are entirely synthetic simulations designed to reflect North American tech market standards (Canada & US). Any resemblance to real persons, living or deceased, or actual corporate entities is purely coincidental.

**#GyanLabs-Agentic-HRMS** is an enterprise-grade **Model Context Protocol (MCP)** server that equips AI assistants (like Claude Desktop, Cursor, and custom agentic frameworks) with the power to autonomously orchestrate the entire employee lifecycle.

From **end-to-end employee onboarding** and **IT asset provisioning** to **smart meeting coordination** and **leave management**, this server provides 20+ production-ready tools and agentic prompts.

---

## 🌟 Key Highlights & Capabilities

- 🤖 **Agentic Multi-Step Workflows (`@mcp.prompt`)**:
  - `onboard_new_employee`: Single command to look up manager, generate corporate email, add to directory, trigger hardware requisitions, schedule 1:1 sync, and dispatch branded welcome credentials.
  - `offboard_employee`: Reclaim IT assets, compute leave encashment, and schedule exit interviews.
  - `conduct_quarterly_performance_review`: Traverse reporting tree and coordinate sprint review sessions.
- 🗂️ **Employee Directory & Org Hierarchy**:
  - Fuzzy name resolution, manager chain tracking, and department filtering across North American hubs (Toronto, Montreal, Vancouver, Seattle, San Francisco).
- 🌴 **North American Leave & PTO Subsystem**:
  - Tracks Paid Vacation (PTO), Sick & Mental Health days, Personal/Flex days with automatic accrual checks and historical audit logs.
- 💻 **IT Requisition & Asset Lifecycle**:
  - Provision developer workstations (MacBook Pro 16" M3 Max, Linux Workstations, Cloud GPU Clusters), software licenses, with priority levels (`Low`, `Medium`, `High`, `Critical`) and status transitions.
- 📅 **Intelligent Calendar Coordination**:
  - Prevents double-booking across organizers and attendees with automated ISO datetime conflict resolution.
- 📚 **HR Policy Knowledge Base**:
  - Instant retrieval of company benefits, remote work stipends, Group RRSP / 401(k) matching, probation review guidelines, and role-specific 30-day onboarding roadmaps.
- ✉️ **Branded HTML Email Dispatcher with Mock Fallback**:
  - Dispatches beautiful, responsive HTML emails with #Gyan Labs styling. Operates seamlessly in **Mock Mode** when running locally without SMTP credentials so tests never fail!

---

## 🏛️ System Architecture

```mermaid
flowchart TD
    subgraph ClientLayer ["MCP Client Layer (Claude Desktop / Cursor / IDE)"]
        User["HR Manager / User"]
        Claude["Claude Desktop Assistant"]
        PromptCatalog["Agentic Prompts (@mcp.prompt)"]
    end

    subgraph MCPServer ["#Gyan Labs FastMCP Server (server.py)"]
        Tools["MCP Tools Catalog (20+ Tools)"]
        FastMCPRuntime["FastMCP Runtime (stdio / sse)"]
    end

    subgraph CoreEngine ["Enterprise HRMS Subsystems (hrms/)"]
        Emp["Employee Directory & Org Hierarchy"]
        Leave["Leave & PTO Tracker (Vacation / Sick / Flex)"]
        Ticket["IT Hardware & GPU Compute Requisitions (SLA / Priority)"]
        Meet["Calendar & Meeting Conflict Resolver"]
        Policy["HR Policy Knowledge Base & Checklist Generator"]
        Mailer["Responsive HTML Emailer & Mock Fallback"]
    end

    subgraph Persistence ["Data Layer"]
        Seed["#Gyan Labs Data Seeder (utils.py)"]
        State["State Stores & Audit Logs"]
    end

    User -->|Voice / Natural Language| Claude
    Claude <-->|JSON-RPC via STDIO| FastMCPRuntime
    PromptCatalog -.-> FastMCPRuntime
    FastMCPRuntime --> Tools
    Tools --> CoreEngine
    CoreEngine --> Persistence
    Mailer -.->|SMTP TLS / Mock Mode| Inbox["Employee Corporate Inbox"]
```

---

## 📁 Repository Structure

```text
GyanLabs-Agentic-HRMS/
├── hrms/                            # Core HRMS Subsystems & Managers
│   ├── __init__.py                  # Unified package exports
│   ├── schemas.py                   # Pydantic v2 data models with strict validation
│   ├── employee_manager.py          # Directory, fuzzy search & org tree
│   ├── leave_manager.py             # North American PTO & leave balance tracking
│   ├── meeting_manager.py           # Meeting scheduler & conflict detection
│   ├── ticket_manager.py            # IT asset requisitions & status lifecycle
│   └── policy_manager.py            # HR handbook & onboarding roadmap generator
├── tests/
│   ├── __init__.py
│   └── test_hrms_services.py        # Pytest unit tests for all domain models
├── emails.py                        # Responsive HTML templates & Mock SMTP engine
├── utils.py                         # Enterprise data seeder (15 North American tech roles)
├── server.py                        # FastMCP Server entrypoint & Tool registry
├── setup_claude_desktop.py          # 1-Click configuration for Claude Desktop
├── test_mcp_server.py               # Standalone smoke test runner
├── run_server.bat                   # Windows batch launcher
├── pyproject.toml                   # Packaging specification (uv & pip compatible)
├── requirements.txt                 # Frozen dependencies
├── .env.example                     # Environment variables sample
├── POLICIES.md                      # Complete Employee Policy & Benefits Handbook
├── LICENSE                          # MIT License
└── README.md                        # Production GitHub documentation
```

---

## ⚡ Quickstart & Installation

### Option 1: Standard Python (`pip` / `venv`)

1. **Clone the repository:**
   ```bash
   git clone https://github.com/Harish-Mathematican/GyanLabs-Agentic-HRMS.git
   cd GyanLabs-Agentic-HRMS
   ```

2. **Create and activate a virtual environment:**
   ```bash
   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # macOS/Linux:
   source .venv/bin/activate
   ```

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

### Option 2: Using `uv` (Ultra-Fast)

```bash
uv pip install -r requirements.txt
```

---

## 🖥️ 1-Click Setup with Claude Desktop

We provide an automated setup script that automatically registers the server in your `claude_desktop_config.json`:

```bash
python setup_claude_desktop.py
```

### Manual Configuration (Alternative)

Add the following to your `claude_desktop_config.json`:

* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gyanlabs-hr-agent": {
      "command": "python",
      "args": [
        "C:\\Users\\Administrator\\Desktop\\Project HashGyan\\GyanLabs-Agentic-HRMS\\server.py"
      ],
      "env": {
        "GYAN_EMAIL": "",
        "GYAN_EMAIL_PWD": ""
      }
    }
  }
}
```

> **Note:** If `GYAN_EMAIL` and `GYAN_EMAIL_PWD` are left blank, the server automatically operates in **Mock Mode**, simulating email delivery directly in the logs without errors.

---

## 🧰 Comprehensive MCP Tool Reference

| Category | Tool Name | Description |
| :--- | :--- | :--- |
| **Directory** | `add_employee` | Provision new employee with ID and department assignment. |
| | `get_employee_details` | Profile lookup by ID or fuzzy name matching. |
| | `get_manager_details` | Retrieve manager contact and hierarchy. |
| | `get_direct_reports` | Query all subordinates under a manager. |
| | `list_employees_by_department` | Filter company roster by department. |
| **Leave / PTO**| `get_employee_leave_balance` | Breakdown of Vacation PTO, Sick, and Personal/Flex days. |
| | `apply_leave` | Submit multi-day time off with balance deduction. |
| | `get_leave_history` | Audit log of all past leaves. |
| **IT & Assets**| `create_it_ticket` | Raise hardware/cloud compute tickets with SLA priorities. |
| | `update_ticket_status` | Advance ticket (`Open` -> `In Progress` -> `Resolved` -> `Closed`). |
| | `list_it_tickets` | Filter tickets by employee, status, or priority. |
| **Calendar** | `schedule_meeting` | Book meetings with multi-attendee conflict detection. |
| | `get_employee_meetings` | Retrieve sorted schedule for an employee. |
| | `cancel_meeting` | Cancel sync and clear all participant calendars. |
| **Knowledge** | `search_hr_policy` | Search handbook (probation, remote work, RRSP/401k, learning grants). |
| | `generate_onboarding_checklist`| Build tailored 30-day onboarding roadmaps. |
| **Email** | `send_email` | Dispatch general notifications. |
| | `send_branded_welcome_email` | Send rich HTML welcome cards with login details. |

---

## 📚 Company Policy Handbook

All organizational rules, leave accrual matrices, hybrid work policies, and employee benefits are documented in our complete handbook:  
👉 **[View the Complete #Gyan Labs Employee Policy Handbook (POLICIES.md)](POLICIES.md)**

---

## 💬 Example Agentic Prompts

Try pasting any of these natural language instructions into Claude Desktop:

### 1. New Hire Onboarding
```text
Onboard a new employee named Liam Davis as a Senior ML Engineer in the AI Research team reporting to Harish Dhakal.
```
*Claude will autonomously look up Harish's ID, generate `liam.davis@gyanlabs.ai`, create the directory profile, generate the 30-day onboarding checklist, dispatch the welcome email, raise IT tickets for a MacBook Pro 16" M3 Max + GPU cluster, and book the intro 1:1 meeting.*

### 2. Employee Offboarding
```text
Execute offboarding for employee E005 (Olivier Roy) due to career transition.
```

### 3. Leave & IT Asset Inquiry
```text
What is Liam Tremblay's current leave balance, and does he have any open IT equipment requests?
```

---

## 🧪 Testing & Verification

Run the automated smoke test:
```bash
python test_mcp_server.py
```

Run the unit test suite:
```bash
pytest tests/ -v
```

---

## ⚖️ Legal & Educational Disclaimer

This software and its associated datasets, documentation, and simulated company structures ("#Gyan Labs / HashGyan Technologies") are developed strictly for **educational, instructional, research, and non-commercial portfolio demonstrations**. 

- **Fictional Entity:** "#Gyan Labs" is a fictional entity created solely to demonstrate Model Context Protocol (MCP) tool design and agentic workflows.
- **Synthetic Data:** All employee records, names, email addresses (`@gyanlabs.ai`), dates, and policies are generated synthetically. Any resemblance to real persons, living or deceased, or actual organizations is purely coincidental.
- **No Warranty:** This software is provided under the open-source MIT License "as is", without warranty of any kind. Users are responsible for ensuring compliance with applicable data privacy, email dispatching, and security policies in their respective jurisdictions.

---

## 📜 License

This project is open-source under the [MIT License](LICENSE).  
Developed by **Harish Dhakal** (#Gyan Labs AI Systems Demo).