# MCP Leave Management Server

A simple **Model Context Protocol (MCP)** server that exposes employee leave-management
operations (apply, cancel, check balance, view history) as tools an AI client
(like Claude Desktop, Claude Code, or the MCP Inspector) can call directly.

Built as a learning project for understanding how MCP servers work — how tools are
defined, registered, and invoked by an LLM client — before extending it into a
real backend (e.g. with persistent storage).

---

## Features

- Add new employees with a default leave balance
- Check an employee's remaining leave balance
- Apply for leave (with automatic balance deduction and history logging)
- View an employee's full leave history
- Cancel a previously applied leave (restores balance)
- List all employees in the system

> **Note:** Data is stored **in-memory** for this version — it resets every time
> the server restarts. Persistence (SQLite/Postgres) is a planned next step.

---

## Tech Stack

- Python 3.10+
- [`mcp`](https://pypi.org/project/mcp/) (Python MCP SDK, `FastMCP`)
- [`uv`](https://docs.astral.sh/uv/) for environment and dependency management

---

## Project Structure

```
mcp-leave-management/
├── leave_server.py      # MCP server with all tool definitions
├── pyproject.toml       # Project metadata & dependencies (created by uv)
├── README.md
└── .gitignore
```

---

## Setup

### 1. Clone the repository

```bash
git clone <your-repo-url>
cd mcp-leave-management
```

### 2. Install dependencies with uv

```bash
uv init --no-workspace
uv add "mcp[cli]"
```

### 3. Run the server with MCP Inspector (for manual testing)

```bash
uv run mcp dev leave_server.py
```

This opens the **MCP Inspector** in your browser, where you can connect to the
server and call each tool manually with test inputs.

---

## Available Tools

| Tool | Parameters | Description |
|---|---|---|
| `add_employee` | `employee_name: str` | Adds a new employee with a default balance of 10 days |
| `get_leave_balance` | `emp_name: str` | Returns the employee's remaining leave balance |
| `apply_leave` | `emp_name: str`, `days: int`, `reason: str` | Deducts leave days and logs the request in history |
| `get_leave_history` | `emp_name: str` | Returns the list of past leave applications |
| `cancel_leave` | `emp_name: str`, `leave_id: str` | Cancels a leave entry and restores the balance |
| `list_employees` | — | Returns a list of all employee names |

### Default seed data

| Employee | Starting Balance |
|---|---|
| Chandu | 10 |
| Sekhar | 15 |

---

## Example Usage (via MCP Inspector)

1. Call `list_employees` → confirms `["Chandu", "Sekhar"]`
2. Call `get_leave_balance` with `emp_name="Chandu"` → returns `10`
3. Call `apply_leave` with `emp_name="Chandu"`, `days=2`, `reason="Personal"` →
   returns a confirmation message and deducts the balance
4. Call `get_leave_balance` again for `Chandu` → returns `8`
5. Call `get_leave_history` for `Chandu` → shows the applied leave entry with its `id`
6. Call `cancel_leave` with that `leave_id` → restores the balance back to `10`

---

## Connecting to Claude Desktop / Claude Code

Once verified in the Inspector, this server can be registered as an MCP tool in
a client's configuration (e.g. `claude_desktop_config.json`), pointing to the
`uv run` command for `leave_server.py`.

---

## Roadmap / Next Steps

- [ ] Replace in-memory dict with persistent storage (SQLite or Postgres)
- [ ] Input validation (e.g. reject negative/zero `days` in `apply_leave`)
- [ ] Role-based access (manager approval flow for leave requests)
- [ ] Unit tests for each tool
- [ ] Docker support for deployment

---

## License

MIT (or update as preferred)