@attendance-engine/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Md. Arifur Rahman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+<div align="center">
+
+# 🕒 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.**
+
+[![npm](https://img.shields.io/npm/v/@attendance-engine/mcp.svg?style=for-the-badge&color=4c8eda)](https://www.npmjs.com/package/@attendance-engine/mcp)
+[![CI](https://img.shields.io/github/actions/workflow/status/arifur9993/attendance-engine-mcp/ci.yml?style=for-the-badge&label=tests)](https://github.com/arifur9993/attendance-engine-mcp/actions)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-1.x-purple.svg?style=for-the-badge)](https://modelcontextprotocol.io/)
+
+</div>
+
+---
+
+## 🤔 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`](https://www.npmjs.com/package/@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
+
+```mermaid
+flowchart LR
+    A[You: "Did Rahim miss his meal break last Tuesday?"]
+    B[Claude / Cursor / Windsurf]
+    C[attendance-engine MCP]
+    D[("@attendance-engine/core
+    pure-function engine
+    100% coverage")]
+
+    A -->|prompt| B
+    B -->|tool call| C
+    C -->|function call| D
+    D -->|"DayResult + ComplianceResult"| C
+    C -->|"JSON content block"| B
+    B -->|"plain-English answer with citations"| A
+
+    classDef user fill:#0b3d91,stroke:#fff,color:#fff
+    classDef host fill:#5b1ea3,stroke:#fff,color:#fff
+    classDef mcp fill:#1f6f43,stroke:#fff,color:#fff
+    classDef core fill:#7c4a03,stroke:#fff,color:#fff
+    class A user
+    class B host
+    class C mcp
+    class D core
+```
+
+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:
+
+<details>
+<summary><b>Claude Desktop (macOS / Windows)</b></summary>
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "attendance-engine": {
+      "command": "npx",
+      "args": ["-y", "@attendance-engine/mcp"]
+    }
+  }
+}
+```
+
+Fully quit and relaunch Claude Desktop (Cmd-Q on macOS — closing the window isn't enough).
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "attendance-engine": {
+      "command": "npx",
+      "args": ["-y", "@attendance-engine/mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "attendance-engine": {
+      "command": "npx",
+      "args": ["-y", "@attendance-engine/mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Any other MCP host</b></summary>
+
+Launch the stdio binary directly:
+
+```bash
+npx -y @attendance-engine/mcp
+```
+
+The server speaks JSON-RPC over stdin/stdout — that's the whole contract.
+</details>
+
+## 🎬 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`](docs/screenshots/README.md).
+
+### Scenario 1 — Did the night-shift nurse get her meal break?
+
+![night-shift compliance demo](docs/screenshots/01-night-shift-compliance.svg)
+
+> **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."*
+
+### Scenario 2 — Find every late-meal day this month
+
+![multi-day audit demo](docs/screenshots/02-period-audit.svg)
+
+> **You:** *"Run an `audit_period_compliance` for employee EMP-007 across June 2026. Here are 30 days of punches and shifts. Use California."*
+>
+> **Claude:** *"3 days at high presumption risk — June 4, June 12, June 22. All three are late meals (started past the 5th hour). Total meal-period premium hours owed: 3. June 22 also drops below the 12-hour second-meal threshold. No rest-period violations detected."*
+
+### Scenario 3 — Are these punches even usable?
+
+![diagnose punches demo](docs/screenshots/03-diagnose-punches.svg)
+
+> **You:** *"I have punches 09:00, 13:00, 14:00 for June 1st. Can I trust these?"*
+>
+> **Claude (calls `diagnose_punches`):** *"Recommendation: **reject**. The punch count is odd — one in or out is missing. Without that, worked-time and overtime would be guesses. Also: every punch falls on a 5-minute boundary, which often indicates manual entry rather than a device read. Worth verifying with the source system before resolving."*
+
+### Scenario 4 — Plan a 4-on-4-off roster for next month
+
+![roster demo](docs/screenshots/04-roster.svg)
+
+> **You:** *"Build me a 4-on-4-off roster for July 2026."*
+>
+> **Claude (calls `generate_roster`):** *"31 days — work days on July 1–4, 9–12, 17–20, 25–28 (12h day shifts, 07:00–19:00). Rest days fill the gaps. Want me to assign team rotations across this pattern?"*
+
+## 🛠️ Tools at a glance
+
+| Tool | When you'd use it |
+|---|---|
+| **`resolve_day`** | "What happened on this single day? Lateness, OT, segments, flags." |
+| **`resolve_period`** | "Roll up a week or a month: per-day results plus an aggregated summary." |
+| **`evaluate_break_compliance`** | "Did this person get their meal/rest breaks under California law? Is any premium owed?" |
+| **`audit_period_compliance`** | "Audit a whole pay period. Show me total premium hours, high-risk days, and the flag heatmap." |
+| **`apply_rounding`** | "Round worked/OT minutes to a unit — and keep the exact view alongside it so I can prove neutrality." |
+| **`diagnose_punches`** | "Triage this raw punch stream. Should I trust it?" |
+| **`generate_roster`** | "Build a 2-2-3 / 4-on-4-off / DuPont / Pitman / custom rotation." |
+| **`list_rule_packs`** | "What jurisdictions are supported?" *(currently CA; more arrive in minor releases)* |
+
+## 📚 Resources & prompts
+
+Resources you can paste into a chat:
+
+| URI | What it is |
+|---|---|
+| `attendance://docs/overview` | One-pager about the engine, time-zone rules, and how the tools compose. |
+| `attendance://docs/api` | Compact field-by-field API reference. |
+| `attendance://rules/CA` | The California rule pack as JSON — meal/rest thresholds, waiver limits, premium caps, the citation source. |
+
+Guided prompts (the host's `/` menu, or `prompts/get`):
+
+- **`analyse_timecard`** — walks the model through the right tool calls to analyse a single duty day.
+- **`roster_planner`** — generates a roster and renders it as a Markdown table.
+
+## 🕰️ The time-zone rule (read this once and you're fine)
+
+Every ISO timestamp must carry its own offset:
+
+- ✅ `2026-06-01T08:57:00+06:00`
+- ✅ `2026-06-01T08:57:00Z`
+- ❌ `2026-06-01T08:57:00` *(rejected — the engine won't guess)*
+
+The engine reduces everything to absolute instants on a single timeline. DST works because the offsets are explicit. The duty date and shift `HH:MM` are worksite local wall-clock — match them to your business calendar, not to UTC.
+
+For days with no punches (an absence, a holiday), pass `policy.tzOffsetMinutes` explicitly so the engine has something to anchor the shift window to.
+
+## 🤝 Embedding (advanced)
+
+Building your own host? Skip the CLI:
+
+```ts
+import { createServer } from '@attendance-engine/mcp';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = createServer({ name: 'my-hr-server', version: '1.0.0' });
+await server.connect(new StdioServerTransport());
+```
+
+Use it for: custom HTTP/SSE adapters, Claude Agent SDK setups, test harnesses, in-house deployments where the binary needs to live inside a bigger Node process.
+
+## 💪 What it's good for
+
+- Internal HR / payroll / workforce-analytics chat assistants
+- Audit-prep workflows for California employers
+- Customer-support tools at HR-tech vendors who need their AI to actually be right
+- Pre-payroll compliance triage ("which days need a human to review?")
+- Schedule planners that need a real roster engine, not vibes
+
+## 🧱 What it's not
+
+- A leave-balance / accrual system (the engine deals in minutes, not entitlements).
+- A payroll-money calculator (it gives you the hour buckets — *you* multiply by the rate).
+- A biometric device protocol (pair it with whatever ingest layer you've got).
+- A UI. There's no dashboard in here; that's a separate concern.
+
+## 🌍 Compatibility
+
+| | |
+|---|---|
+| **Node** | 18+ (CI runs 20 LTS) |
+| **MCP SDK** | 1.x |
+| **Engine** | `@attendance-engine/core` ≥ 0.4 (peer dep) |
+| **Hosts tested** | Claude Desktop 1.x · Cursor · Windsurf · any stdio MCP client |
+
+## 📖 More reading
+
+- 📑 [Detailed scenarios with full tool transcripts](docs/scenarios.md)
+- 🖼️ [How to capture your own demo screenshots](docs/screenshots/README.md)
+- 📚 [Engine API reference](https://github.com/arifur9993/attendance-engine/blob/main/packages/core/docs/api.md)
+- 🌐 [Time-zone semantics](https://github.com/arifur9993/attendance-engine/blob/main/packages/core/docs/timezones.md)
+- 🏛️ [California Labor Code §§ 226.7, 512](https://www.dir.ca.gov/dlse/faq_mealperiods.htm)
+- 🏛️ [Donohue v. AMN Services (Cal. 2021)](https://law.justia.com/cases/california/supreme-court/2021/s253677.html)
+
+## ❤️ Credits
+
+Built by [Md. Arifur Rahman](https://www.linkedin.com/in/md-arifur-rahman-mar/). Companion to [`@attendance-engine/core`](https://github.com/arifur9993/attendance-engine) (TypeScript) and [`arifur9993/attendance-engine`](https://github.com/arifur9993/attendance-engine-php) (PHP). Same author, same fixtures, same answers — in three places your stack can reach for.
+
+## License
+
+MIT — see [LICENSE](LICENSE).