# Leave Management MCP Server

An AI-powered leave management assistant built using Anthropic's **Model Context Protocol (MCP)**. This server connects directly to **Claude Desktop**, enabling HR teams to query and manage employee leave through natural language — no dashboards, no forms, just conversation.

---

## The Problem

HR teams in most organizations manage leave through static spreadsheets or rigid portals that require navigating multiple screens to answer simple questions like:

- *"How many leave days does Rahul have left?"*
- *"Has Anjali taken any leave this quarter?"*
- *"Apply 2 days of leave for Karan on April 17th and 18th"*

These systems are slow, require training, and don't scale well for HR managers handling large teams.

---

## The Solution

This project exposes leave management operations as **MCP tools** that Claude can call in real time. HR can simply open Claude Desktop and ask questions in plain English — Claude intelligently decides which tool to call, passes the right parameters, and returns a human-readable answer.

No UI. No SQL. No form submissions. Just conversation.

---

## Demo

**Check leave balance:**
> *"What is the leave balance for E003?"*
> → `Rahul Verma has 15 leave days remaining.`

**Apply for leave:**
> *"Apply leave for E007 on 2025-07-10 and 2025-07-11"*
> → `Leave applied for 2 day(s). Remaining balance: 17.`

**View leave history:**
> *"Show me the leave history for E006"*
> → `Leave history for E006: 2024-12-31, 2025-01-02, 2025-01-03, ...`

---

## Tech Stack

| Layer | Technology |
|---|---|
| AI Client | Claude Desktop |
| Protocol | Model Context Protocol (MCP) |
| Server Framework | FastMCP (Python) |
| Package Manager | uv |
| Language | Python 3.11 |
| Data Layer | In-memory JSON (mock database) |

---

## Architecture

```
Claude Desktop (MCP Client)
        │
        │  MCP Protocol (stdio transport)
        ▼
  FastMCP Server — main.py
        │
        ├── Tool: get_leave_balance(employee_id)
        ├── Tool: apply_leave(employee_id, leave_dates)
        ├── Tool: get_leave_history(employee_id)
        └── Resource: greeting://{name}
              │
              ▼
    In-memory employee_leaves dictionary
```

**How it works end-to-end:**
1. HR types a natural language query in Claude Desktop
2. Claude identifies the right MCP tool based on the query
3. Claude calls the tool with extracted parameters
4. The Python function runs and returns the result
5. Claude presents the result in a conversational response

---

## Project Structure

```
my_mcp/
├── main.py              # MCP server — all tools and resources defined here
├── pyproject.toml       # Project metadata and dependencies
├── uv.lock              # Locked dependency versions for reproducibility
└── README.md            # This file
```

---

## Getting Started

### Prerequisites
- Python 3.10+
- [uv](https://github.com/astral-sh/uv) package manager
- [Claude Desktop](https://claude.ai/download)

### Setup

```bash
# Clone the repo
git clone <your-repo-url>
cd my_mcp

# Install dependencies
uv sync

# Install the server into Claude Desktop
uv run mcp install main.py

# Restart Claude Desktop
# The LeaveManager tools will now appear in Claude
```

---

## Mock Data

The server comes pre-loaded with 10 employees:

| ID | Name | Leave Balance |
|---|---|---|
| E001 | Amit Sharma | 18 days |
| E002 | Priya Mehta | 20 days |
| E003 | Rahul Verma | 15 days |
| E004 | Sneha Iyer | 17 days |
| E005 | Karan Patel | 20 days |
| E006 | Anjali Singh | 12 days |
| E007 | Vikram Nair | 19 days |
| E008 | Deepa Pillai | 16 days |
| E009 | Rohan Gupta | 20 days |
| E010 | Meera Joshi | 11 days |

Each employee starts with 20 days. Balance reflects days already taken.

---

## MCP Tools Exposed

### `get_leave_balance`
Returns the remaining leave balance for an employee.
- **Input:** `employee_id` (string)
- **Output:** Remaining days as a string

### `apply_leave`
Applies leave for specific dates, deducting from balance and recording in history.
- **Input:** `employee_id` (string), `leave_dates` (list of date strings)
- **Output:** Confirmation with updated balance

### `get_leave_history`
Returns all leave dates taken by an employee.
- **Input:** `employee_id` (string)
- **Output:** Comma-separated list of dates

---

## What This Demonstrates

- **MCP Server Development** — Building a production-pattern MCP server using FastMCP, exposing typed tools and resources that an AI client can discover and invoke
- **AI Tool Integration** — Understanding how LLMs interact with external tools via structured protocols, including tool discovery, parameter extraction, and response handling
- **Python Project Structure** — Using `uv` for dependency management, virtual environments, and reproducible builds with lockfiles
- **Protocol Design** — Designing tool interfaces with clear docstrings that serve as tool descriptions for the LLM, following the principle that the docstring IS the API contract in MCP

---

## Next Steps / Roadmap

- [ ] Replace in-memory dict with a real database (PostgreSQL / SQLite)
- [ ] Add leave approval workflow (manager approval tool)
- [ ] Add leave type support (sick, casual, annual)
- [ ] Add employee lookup by name instead of only by ID
- [ ] Deploy server for remote access

---

## Author

Built by Nishant Kumar as a hands-on exploration of Anthropic's Model Context Protocol and AI tool integration patterns.