arifur9993/attendance-engine-mcp

Wage-and-hour answers your AI agent can actually trust.
**Ask Claude *"Did anyone miss a meal break last Tuesday?"* — and have it actually be right.**
---
🤔 The problem
Every HR / payroll / time-tracking team eventually asks Claude (or Cursor, or Windsurf) something like:
> *"Rahim's punches yesterday were 09:00, 13:00, 14:00, and 18:00. Did he get his meal break under California rules?"*
And the LLM does what LLMs do: it eyeballs the timestamps, mumbles something about "yes probably, his lunch looks fine," and moves on. Sometimes it's right. Sometimes it forgets that California requires the meal to *start before the end of the 5th hour*. Sometimes it counts a 25-minute break as compliant. Sometimes, for an overnight shift that crosses midnight, it just gives up.
**You can't put that in front of an auditor.** You can't ship it inside a payroll product. You can't trust it with overtime calculations that turn into back-pay liability if they're wrong.
💡 What this is
A small **Model Context Protocol** server that gives your AI agent **deterministic, tested, fixture-backed tools** for:
- Resolving a duty day from raw clock punches (overnight, breaks, OT, all of it).
- Auditing meal/rest compliance under the **California** rule pack (Labor Code §§ 226.7, 512; IWC wage orders), including *Donohue v. AMN* rebuttable-presumption signals.
- Rounding worked time without losing the exact-minute baseline (so you can prove your rounding is neutral).
- Building rotating rosters: 2-2-3, 4-on-4-off, DuPont, Pitman.
- Triaging suspicious punch streams *before* you trust them.
- Running a multi-day **wage-and-hour audit** across a whole pay period and rolling up premium hours owed, days at risk, and the flag heatmap.
The math lives in @attendance-engine/core — a pure-function, zero-deps TypeScript library with 100% test coverage. This MCP server is the thin agent surface on top.
🧠 How it actually works
Two important properties:
1. **Claude doesn't do the math.** It picks a tool, fills the arguments, and forwards the answer. If the engine says "this was a late meal," the agent says "this was a late meal." If you re-ask the same question, you get the same answer — every time.
2. **Time zones are explicit, not guessed.** Every timestamp carries its own offset. The engine never reads the host clock, never assumes UTC, never silently converts. DST days work because *you* told it the offset, not because it inferred it.
🚀 Install — pick your host
Pick the MCP host you're already using. Same one-liner everywhere:
Claude Desktop (macOS / Windows)
Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows:
Fully quit and relaunch Claude Desktop (Cmd-Q on macOS — closing the window isn't enough).
Cursor
~/.cursor/mcp.json:
Windsurf
~/.codeium/windsurf/mcp_config.json:
Any other MCP host
Launch the stdio binary directly:
The server speaks JSON-RPC over stdin/stdout — that's the whole contract.
🎬 See it in action
> **🖼️ Scenario cards below are publish-ready SVG mockups** (render inline on GitHub, npm, LinkedIn). Real-product screenshots can replace them when you capture them — see docs/screenshots/README.md.
Scenario 1 — Did the night-shift nurse get her meal break?
> **You:** *"Sara was on the 22:00→06:00 shift on June 1st. Punches: 21:54, 02:00, 02:30, 06:18. Apply California rules."*
>
> **Claude (calls evaluate_break_compliance):** *"Sara worked 7h54m on her duty date of June 1st (her clock-out fell on June 2nd but belongs to this shift). She took a 30-minute meal beginning at her 4-hour mark, which is compliant under California's mandate to start the first meal before the end of the 5th hour. Worked time spans midnight; flagged accordingly. She left 18 minutes past schedule — that 18m counts as overtime."*