# HR Management System (MCP Server)

> ⚠️ **Work in progress.** This project is still under active development and is
> not production-ready. The manager functions in `HRMS/` are **mock
> implementations that mimic the API calls of [Keka](https://www.keka.com/) HR
> software**, using in-memory sample data instead of real Keka API integration.


An HR assistant exposed as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io)
server. It lets an MCP-compatible client (e.g. Claude Desktop) manage employees,
tickets, leaves, and meetings, and send emails — backed by in-memory data that is
seeded with sample employees on startup.

## Features

The MCP server (`server.py`) exposes the following tools and prompt:

| Tool | Description |
| --- | --- |
| `add_employee` | Add a new employee to the HRMS. |
| `get_employee_details` | Look up an employee's details by name. |
| `create_ticket` | Raise a ticket for equipment/items (laptop, ID card, etc.). |
| `update_ticket_status` | Update a ticket's status. |
| `list_tickets` | List tickets for an employee, optionally filtered by status. |
| `send_email` | Send an email via SMTP. |

| Prompt | Description |
| --- | --- |
| `onboard_new_employee` | Guided workflow to onboard a new hire end-to-end. |

Additional domain logic lives in the `HRMS/` package (employee, leave, meeting,
and ticket managers plus Pydantic `schemas.py`). These managers currently mock
Keka's HR API; sample data is loaded by `utils.seed_services` on server start.

## Requirements

- Python >= 3.12
- [uv](https://docs.astral.sh/uv/) (recommended) for dependency management

## Setup

1. Clone the repository:

   ```bash
   git clone <your-repo-url>
   cd HR_Management_System
   ```

2. Install dependencies:

   ```bash
   uv sync
   ```

3. Configure environment variables. Copy the example file and fill in your
   SMTP credentials:

   ```bash
   cp .env.example .env
   ```

   | Variable | Description |
   | --- | --- |
   | `MS_EMAIL` | Sender email address / SMTP login. |
   | `MS_EMAIL_PWD` | SMTP password or app password. |

   For Gmail, generate an [App Password](https://support.google.com/accounts/answer/185833)
   rather than using your account password.

## Running

Start the MCP server (uses stdio transport):

```bash
uv run server.py
```

To use it with an MCP client such as Claude Desktop, add an entry to the
client's MCP server configuration pointing at this command, for example:

```json
{
  "mcpServers": {
    "atliq-hr-assist": {
      "command": "uv",
      "args": ["run", "server.py"],
      "cwd": "/absolute/path/to/HR_Management_System"
    }
  }
}
```

You can also test the email sender directly:

```bash
uv run emails.py
```

## Project structure

```
.
├── server.py          # MCP server entry point (tools & prompts)
├── emails.py          # SMTP email sender
├── utils.py           # Seeds the managers with sample data
├── main.py            # Hello-world placeholder
├── HRMS/              # Core domain package (mocks Keka HR API)
│   ├── employee_manager.py
│   ├── leave_manager.py
│   ├── meeting_manager.py
│   ├── ticket_manager.py
│   └── schemas.py     # Pydantic models
├── .env.example       # Template for required environment variables
└── pyproject.toml
```

## Roadmap / TODO

- Replace the mock `HRMS/` managers with real Keka HR API integration.
- Persist data instead of using in-memory seeded sample data.
- Expand MCP tool coverage for leave and meeting management.

## Notes

- Data is stored **in memory** and re-seeded on every start; it is not persisted.
- Never commit your `.env` file — it contains secrets and is git-ignored.