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
• 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

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

Run

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

Test

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)