HRMS Tool

<!-- markdownlint-disable MD033 MD041 --> <h1 align="center">🧑‍💼 HRMS Tool</h1> <p align="center"><b>An AI-native HR Management System, exposed as an MCP server.</b></p> <p align="center">Give Claude (or any MCP-compatible client) real tools to manage employees, leave, meetings, tickets, and email — all through natural conversation.</p> <p align="center"> <img src="https://img.shields.io/badge/python-3.14%2B-3776AB?logo=python&logoColor=white" alt="Python"> <img src="https://img.shields.io/badge/protocol-MCP-6f42c1" alt="MCP"> <img src="https://img.shields.io/badge/validation-pydantic%20v2-e92063" alt="Pydantic"> <img src="https://img.shields.io/badge/package%20manager-uv-de5fe9" alt="uv"> </p>

---

Overview

HRMS Tool is a Model Context Protocol server that turns a set of core HR workflows — onboarding, offboarding, leave tracking, meeting scheduling, IT ticketing, and email — into tools an AI agent can call directly.

Instead of clicking through an HR portal, you can ask an MCP-connected assistant things like:

"Onboard Marcus Webb as a new report under Elena Cross, starting Monday." "Who on Naomi Steele's team is running low on leave?" "Close out all of Diego Ramos's open tickets and cancel his upcoming meetings — he's leaving Friday."

The assistant plans the steps, calls the right tools in the right order, and reports back — using the guided prompts below for multi-step workflows, or individual tools for one-off actions.

✨ Features

• 👤 Employee management — add, update, look up, and search employees; resolve manager/report relationships
• 🌴 Leave management — check balances, apply for leave, review history
• 📅 Meeting scheduling — book, list, and cancel meetings with conflict detection
• 🎫 Ticket system — raise equipment/resource requests, track status, filter and inspect tickets
• 📧 Email — send transactional email via Gmail SMTP (plain text, HTML, and attachments)
• 🧭 Guided prompts — pre-built, multi-tool workflows for onboarding, offboarding, and team leave reporting
• 🌱 Seeded demo data — spins up with a realistic org chart, leave history, meetings, and tickets so you can try it immediately

🏗️ Architecture

flowchart LR
    Client(["MCP Client<br/>(Claude Desktop, etc.)"])

    subgraph MCPServer["mcp-server/"]
        Server["server.py<br/>MCPServer('HRMS Tool')"]
    end

    subgraph HRMSPkg["hrms/"]
        EM["EmployeeManager"]
        LM["LeaveManager"]
        MM["MeetingManager"]
        TM["TicketManager"]
        MAIL["EmailManager"]
    end

    subgraph UtilsPkg["utils/"]
        Seed["seed_services()"]
    end

    Client <-->|stdio| Server

    Server --> EM
    Server --> LM
    Server --> MM
    Server --> TM
    Server --> MAIL
    Server -->|once, at startup| Seed

    EM -->|holds a reference to| LM
    Seed --> EM
    Seed --> LM
    Seed --> MM
    Seed --> TM

    MAIL -->|SMTP| Gmail[(Gmail)]

hrms/schemas.py isn't drawn separately above — it's the Pydantic model layer that every manager and every tool signature depends on.

All data lives in memory for the lifetime of the process — there's no database. Every restart re-seeds a fresh, randomized dataset (see Data & Persistence below).

📁 Project Structure

hrms-claude-tool/
├── hrms/
│   ├── email_manager.py      # Gmail SMTP sender
│   ├── employee_manager.py   # employee CRUD, org chart, name search
│   ├── leave_manager.py      # leave balances & history
│   ├── meeting_manager.py    # meeting scheduling & cancellation
│   ├── schemas.py            # Pydantic models (Employee, Leave, Meeting, Ticket, Email)
│   └── ticket_manager.py     # ticket lifecycle
├── mcp-server/
│   └── server.py             # MCP server entrypoint: tools + prompts
├── utils/
│   └── utils.py              # seed_services() — dummy data generator
├── .env                       # Gmail credentials (not committed)
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
└── uv.lock

⚙️ Prerequisites

• Python 3.14+
• uv for dependency management (recommended)
• A Gmail account with an App Password, if you want the email tool to work (2-Step Verification must be enabled first)

🚀 Installation

# Clone the repo
git clone <your-repo-url>
cd hrms-claude-tool

# Install dependencies
uv sync

<details> <summary>Using pip instead of uv</summary>

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp[cli]>=2.0.0" "pydantic>=2.13.4" "requests>=2.34.2" python-dotenv

Note: email_manager.py imports python-dotenv to load .env, but it isn't currently listed in pyproject.toml's dependencies — add it there too if you're using uv sync. </details>

🔐 Environment Variables

Email sending needs Gmail SMTP credentials. Populate the .env file in the project root with:

GMAIL_SENDER_EMAIL=your-address@gmail.com
GMAIL_APP_PASSWORD=your-16-character-app-password

Generate an App Password at myaccount.google.com/apppasswords (Security → 2-Step Verification → App passwords). A regular Gmail password will not work.

▶️ Running the Server

uv run mcp-server/server.py

This starts the MCP server over stdio and seeds it with demo employees, leave records, meetings, and tickets.

Connecting from Claude Desktop / Claude Code

Add an entry to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "hrms-tool": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/hrms-claude-tool", "run", "mcp-server/server.py"]
    }
  }
}

Restart the client, and the tools and prompts below become available in conversation.

🛠️ Available Tools

Employee & Org Chart

Tool	Description
add_employee	Add a new employee (auto-generates emp_id and hire date)
update_employee	Update an existing employee's fields, looked up by name
get_employee_details	Full profile lookup by name
get_employee_details_by_id	Full profile lookup by emp_id
search_employees	Fuzzy name search — returns all close matches
list_employees	List every employee in the system
get_manager_details_by_name / get_manager_details_by_id	Find an employee's manager
get_direct_reports_by_name / get_direct_reports_by_id	List a manager's direct reports

Leave

Tool	Description
get_employee_leave_balance	Check remaining leave days
apply_leave	Apply for one or more leave dates as a single request
get_leave_history	Full leave history for an employee

Meetings

Tool	Description
schedule_meeting	Book a meeting (rejects exact-time conflicts)
get_meetings	List an employee's meetings, chronologically
cancel_meeting	Cancel a meeting by date/time (and topic, if needed)

Tickets

Tool	Description
raise_ticket	Open an equipment/resource request
get_ticket_details	Look up a single ticket by ID
list_tickets	List tickets, filterable by employee and/or status
update_ticket_status	Move a ticket to Open, In Progress, Closed, or Rejected

Email

Tool	Description
send_email	Send plain-text or HTML email via Gmail, with optional attachments

🧭 Available Prompts

Prompts chain multiple tools into a complete workflow — hand one a name and let the agent drive.

Prompt	What it does
onboard_new_employee	Looks up the manager, creates the employee, emails login credentials to the new hire and a heads-up to the manager, raises laptop + ID card tickets, and schedules an intro meeting
offboard_employee	Looks up the employee, closes their open/in-progress tickets, cancels upcoming meetings, and emails both the manager and the departing employee
team_leave_summary	Resolves a manager's direct reports and reports their leave balances as a sorted table, flagging anyone running low

💾 Data & Persistence

• All data is held in memory — nothing survives a server restart.
• On every startup, seed_services() generates a coherent demo dataset: an 8-person org chart across two teams, randomized leave balances/history, 2–6 upcoming meetings per employee, and 8–15 tickets in mixed states.
• Employee IDs follow E001, E002, …; ticket IDs follow T0001, T0002, …
• New employees default to a 20-day leave balance unless seeded otherwise.

If you need data to persist across restarts, you'll want to swap the in-memory dicts/lists in each manager class for a real datastore.

⚠️ Known Limitations

• No authentication or authorization on tool calls — access control is left entirely to the MCP client.
• No persistence layer (see above).
• Email sending is Gmail-only, via SMTP + App Password.
• Meeting conflict detection only checks for an exact timestamp match, not overlapping ranges.

📄 License

This project is licensed under the MIT License.