# attendance-mcp

MCP server that exposes **BIPO attendance tools** to the BIPO AI assistant.

It is a **thin, stateless proxy**: each tool authenticates the caller (BIPO),
then forwards the logged-in user's HRMS token to the existing BIPO HRMS /
attendance API, which enforces all role permissions (Employee, Coordinator,
Manager, HR).

- **Language / framework:** Python + [FastMCP](https://gofastmcp.com)
- **Transport:** remote streamable-HTTP
- **Auth:**
  - *Inbound* (BIPO → server): `x-service-key` validated against `MCP_SERVICE_KEY`;
    the user's HRMS token arrives in `X-HRMS-Authorization`.
  - *Outbound* (server → HRMS API): the user's HRMS token forwarded as `X-HRMS-Authorization`.

## Status: skeleton (pending HRMS API)

All 13 tools are wired and callable, but the real HRMS endpoints are not yet
known. Every tool currently returns a structured `PENDING_HRMS_API` placeholder.
**Only `src/attendance_mcp/bipo_client.py` needs to change** once the HRMS team
provides the endpoints — replace each `self._pending(...)` with `self._request(...)`.

See `bipo-attendance-mcp-tools.html` for the tool list shared with the HRMS team.

## Tools

| Role | Tools | Scenarios |
|---|---|---|
| Employee | `clock_punch`, `submit_clock_amendment`, `submit_leave_request`, `submit_ot_request`, `get_ot_request`, `cancel_ot_request` | 1–5 |
| Shared | `get_attendance_status` | 6 |
| Coordinator | `submit_batch_ot_request` | 7 |
| Manager | `list_pending_approvals`, `approve_request`, `reject_request` | 8 |
| HR | `get_daily_exceptions`, `send_clock_reminders`, `generate_attendance_report` | 9–11 |

> **Scenario 5 guardrail:** OT requests cannot be deleted — only cancelled.
> There is intentionally no `delete_ot_request` tool.

## Setup

```bash
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -e ".[dev]"
cp .env.example .env          # then edit BIPO_API_BASE_URL etc.
```

## Run

```bash
attendance-mcp                # streamable-HTTP on MCP_HOST:MCP_PORT (default 127.0.0.1:8000)
```

## Test

```bash
pytest
```

## Layout

```
src/attendance_mcp/
  server.py        FastMCP app + transport
  config.py        env settings
  auth.py          reads the caller's bearer token
  bipo_client.py   HRMS API client (placeholder calls; the only file to edit later)
  tools/           one module per role, each exposing register(mcp)
tests/             in-memory tests (no live API needed)
```