Metadata-Version: 2.4
Name: kasra-mcp-server
Version: 1.0.0
Summary: Model Context Protocol (MCP) server for Kasra Lite Attendance and Personnel Management System
Author-email: Emad Razavi <razavioo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/razavioo/kasra-mcp-server
Project-URL: Repository, https://github.com/razavioo/kasra-mcp-server
Keywords: mcp,model-context-protocol,kasra,attendance,fastmcp
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: pycryptodome>=3.18.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# Kasra Lite Attendance & Personnel MCP Server

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-FastMCP-brightgreen.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server for the **Kasra Lite Attendance, Personnel, Cartable, and Leave Management System** ([app.kasralite.com](https://app.kasralite.com)).

Connect your AI agents (Claude Desktop, OpenCode, Cursor, Windsurf, etc.) directly to Kasra Lite to view attendance, punches, leaves, cardex, cartable requests, work periods, and submit leave/mission requests autonomously.

> 🚀 **100% Pure HTTP & Async API — No Headless Browser Required!**  
> Runs via standard HTTP/2 APIs and AES-128-CBC encryption without downloading Chromium or running Playwright/Puppeteer. Works in any environment including headless Linux servers, Docker containers, macOS, and Windows.

---

## 🌟 Available MCP Tools (17 Tools)

### 1. Personnel Profile & Dashboard
- **`kasra_get_profile`**: Retrieve user identity, personnel code, system ID, role, department, and recent login IP history.
- **`kasra_get_dashboard_summary`**: Real-time summary:
  - Last registered punch of today (time & status)
  - Cardex leave balance (hours)
  - Total presence & worked hours in current period
  - Permissions needed (incomplete punches, overtime, deficit)
  - Request approval counters (in progress, confirmed, rejected)
  - Pending cartable documents count
- **`kasra_get_desktop_shortcuts`**: Get user's pinned/favorite desktop bookmarks.
- **`kasra_get_messages`**: Retrieve broadcast announcements and system messages.

### 2. Attendance & Reports
- **`kasra_get_daily_report`**: Day-by-day detailed breakdown of punches, hours, shift, structure, surplus presence, and deficit presence with date filtering.
- **`kasra_get_monthly_report`**: Aggregate monthly attendance report with period selection.
- **`kasra_get_work_periods`**: List of all available financial and attendance work periods (e.g., Shahrivar 1405, Mordad 1405, ...).
- **`kasra_export_daily_report_excel`**: Generate and download daily attendance reports directly as an Excel (`.xls`) file.

### 3. Permissions, Leaves & Missions
- **`kasra_get_credit_types`**: List all permission types with codes:
  - Hourly deficit: Hourly leave (`11001`), Hourly sick leave (`11011`), Hourly mission (`11021`), Hourly remote work (`14087`), etc.
  - Daily deficit: Daily leave (`11002`), Daily sick leave (`11012`), Daily mission (`11022`), Daily remote work (`14084`), etc.
  - Surplus presence: Regular overtime (`11101`), Remote overtime (`14088`), Friday overtime (`60023`), etc.
- **`kasra_submit_credit_request`**: Submit a new hourly or daily leave, mission, remote work, or overtime request with automated security tokens.
- **`kasra_get_submitted_requests`**: View all submitted permission requests and their approval/rejection status.
- **`kasra_delete_credit_request`**: Cancel/delete a submitted permission request.

### 4. Cartable & Workflow
- **`kasra_get_cartable_items`**: View workflow documents in cartable by tab:
  - `in_wait`: Requests awaiting your approval
  - `confirmed`: Approved documents
  - `rejected`: Rejected documents
  - `refer`: Referred documents

### 5. System Base Information
- **`kasra_get_system_shifts`**: Retrieve all defined organizational shifts (Administrative shift, Remote work shift, etc.).
- **`kasra_get_personnel_groups`**: Retrieve all organizational personnel groups and permission categories.
- **`kasra_get_holidays`**: Official holiday calendar defined in the system.
- **`kasra_get_user_menu`**: Complete hierarchy of accessible system menus and subsystems.

---

## 📦 Installation

```bash
git clone https://github.com/razavioo/kasra-mcp-server.git
cd kasra-mcp-server
pip install -r requirements.txt
```

---

## ⚙️ Configuration

Copy the example environment file:
```bash
cp .env.example .env
```

Edit `.env`:
```env
KASRA_BASE_URL=https://app.kasralite.com
KASRA_USERNAME=your_national_id_or_username
KASRA_PASSWORD=your_password
```

---

## 🔌 Agent Integration

You can run this MCP server either **directly without cloning** using `uvx`, via **`pip`**, or from a **local clone**.

### Option A: Zero-Install with `uvx` (Recommended)

No need to clone the repo or manage python environments!

#### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "kasra": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/razavioo/kasra-mcp-server.git",
        "kasra-mcp-server"
      ],
      "env": {
        "KASRA_BASE_URL": "https://app.kasralite.com",
        "KASRA_USERNAME": "your_username",
        "KASRA_PASSWORD": "your_password"
      }
    }
  }
}
```

#### OpenCode (`~/.config/opencode/opencode.jsonc` or `opencode.json`)
```json
{
  "mcp": {
    "kasra": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/razavioo/kasra-mcp-server.git",
        "kasra-mcp-server"
      ],
      "environment": {
        "KASRA_BASE_URL": "https://app.kasralite.com",
        "KASRA_USERNAME": "your_username",
        "KASRA_PASSWORD": "your_password"
      },
      "enabled": true
    }
  }
}
```

#### Cursor (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "kasra": {
      "command": "uvx --from git+https://github.com/razavioo/kasra-mcp-server.git kasra-mcp-server",
      "env": {
        "KASRA_BASE_URL": "https://app.kasralite.com",
        "KASRA_USERNAME": "your_username",
        "KASRA_PASSWORD": "your_password"
      }
    }
  }
}
```

---

### Option B: Installed via `pip`

```bash
pip install git+https://github.com/razavioo/kasra-mcp-server.git
```

Then in your MCP configuration:
```json
{
  "mcpServers": {
    "kasra": {
      "command": "kasra-mcp-server",
      "env": {
        "KASRA_BASE_URL": "https://app.kasralite.com",
        "KASRA_USERNAME": "your_username",
        "KASRA_PASSWORD": "your_password"
      }
    }
  }
}
```

---

### Option C: From Local Source

```bash
git clone https://github.com/razavioo/kasra-mcp-server.git
cd kasra-mcp-server
pip install -r requirements.txt
```

```json
{
  "mcpServers": {
    "kasra": {
      "command": "python3",
      "args": [
        "/path/to/kasra-mcp-server/main.py"
      ],
      "env": {
        "KASRA_BASE_URL": "https://app.kasralite.com",
        "KASRA_USERNAME": "your_username",
        "KASRA_PASSWORD": "your_password"
      }
    }
  }
}
```

---

## 🧪 Testing

Test all tools directly in python:
```bash
python3 test_tools.py
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).
