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

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

Related MCP server: MCP FactorialHR

🏛️ 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

📚 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).