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

[!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

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

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:

   git clone https://github.com/Harish-Mathematican/GyanLabs-Agentic-HRMS.git
   cd GyanLabs-Agentic-HRMS
   

2. Create and activate a virtual environment:

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # macOS/Linux:
   source .venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

Option 2: Using uv (Ultra-Fast)

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:

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

{
  "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)

---

💬 Example Agentic Prompts

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

1. New Hire Onboarding

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

Execute offboarding for employee E005 (Olivier Roy) due to career transition.

3. Leave & IT Asset Inquiry

What is Liam Tremblay's current leave balance, and does he have any open IT equipment requests?

---

🧪 Testing & Verification

Run the automated smoke test:

python test_mcp_server.py

Run the unit test suite:

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.
Developed by Harish Dhakal (#Gyan Labs AI Systems Demo).