<!-- 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](https://modelcontextprotocol.io) 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

```mermaid
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](#-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`](https://docs.astral.sh/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

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

# Install dependencies
uv sync
```

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

```bash
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:

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

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

## ▶️ Running the Server

```bash
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`):

```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](LICENSE).