{"_id":"@attendance-engine/mcp","name":"@attendance-engine/mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@attendance-engine/mcp","version":"0.1.0","description":"Model Context Protocol server giving AI agents tools for workforce attendance, overtime, overnight handling, rosters, and wage-and-hour compliance via @attendance-engine/core.","keywords":["mcp","model-context-protocol","attendance","workforce","ai-agents","claude","cursor","anthropic","openai","hr","payroll","wage-and-hour","compliance","typescript"],"license":"MIT","author":{"name":"Md. Arifur Rahman","email":"arifur.rahman210@gmail.com"},"homepage":"https://github.com/arifur9993/attendance-engine-mcp#readme","bugs":{"url":"https://github.com/arifur9993/attendance-engine-mcp/issues"},"repository":{"type":"git","url":"git+https://github.com/arifur9993/attendance-engine-mcp.git"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"bin":{"attendance-engine-mcp":"dist/cli.js"},"sideEffects":false,"publishConfig":{"access":"public"},"scripts":{"build":"tsup","prepack":"tsup","test":"vitest run","test:cov":"vitest run --coverage","typecheck":"tsc --noEmit","dev":"tsup --watch","start":"node dist/cli.js"},"engines":{"node":">=18"},"packageManager":"pnpm@9.12.0","dependencies":{"@modelcontextprotocol/sdk":"^1.18.0","zod":"^3.23.8"},"peerDependencies":{"@attendance-engine/core":">=0.4.0 <1.0.0"},"devDependencies":{"@attendance-engine/core":"^0.4.0","@types/node":"^20.16.13","@vitest/coverage-v8":"^2.1.4","tsup":"^8.3.5","typescript":"^5.6.3","vitest":"^2.1.4"},"gitHead":"ab8ccb334e12243f2051b52cd36e51d53bf87349","_id":"@attendance-engine/mcp@0.1.0","_nodeVersion":"22.21.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-8inT/rIkooEcY3kdJDKBMwdhhaIVrxdTAhHWoxIkwv/COEgNb94K3LLr9XLcZFsHujzKW8CLfO1APP1LQw9H3A==","shasum":"eb4c36027975cad309bb01f61d457b85bfbd999d","tarball":"https://registry.npmjs.org/@attendance-engine/mcp/-/mcp-0.1.0.tgz","fileCount":17,"unpackedSize":212245,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDblAH7X8TOBHDopZrdTt0ZLk3vgSMUMUVR5TLqKrq+5QIgYl6cBwMrrAoS1b/SqFfFrQ0Y2c3okyydQlnuyJ19r8s="}]},"_npmUser":{"name":"arifur9993","email":"arifur.rahman210@gmail.com"},"directories":{},"maintainers":[{"name":"arifur9993","email":"arifur.rahman210@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.1.0_1778765153029_0.157650602003653"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-14T13:25:52.887Z","0.1.0":"2026-05-14T13:25:53.176Z","modified":"2026-05-14T13:25:53.454Z"},"maintainers":[{"name":"arifur9993","email":"arifur.rahman210@gmail.com"}],"description":"Model Context Protocol server giving AI agents tools for workforce attendance, overtime, overnight handling, rosters, and wage-and-hour compliance via @attendance-engine/core.","homepage":"https://github.com/arifur9993/attendance-engine-mcp#readme","keywords":["mcp","model-context-protocol","attendance","workforce","ai-agents","claude","cursor","anthropic","openai","hr","payroll","wage-and-hour","compliance","typescript"],"repository":{"type":"git","url":"git+https://github.com/arifur9993/attendance-engine-mcp.git"},"author":{"name":"Md. Arifur Rahman","email":"arifur.rahman210@gmail.com"},"bugs":{"url":"https://github.com/arifur9993/attendance-engine-mcp/issues"},"license":"MIT","readme":"\n\n# ๐ attendance-engine MCP\n\n### Wage-and-hour answers your AI agent can actually trust.\n\n**Ask Claude *\"Did anyone miss a meal break last Tuesday?\"* โ and have it actually be right.**\n\n[](https://www.npmjs.com/package/@attendance-engine/mcp)\n[](https://github.com/arifur9993/attendance-engine-mcp/actions)\n[](LICENSE)\n[](https://modelcontextprotocol.io/)\n\n
\n\n---\n\n## ๐ค The problem\n\nEvery HR / payroll / time-tracking team eventually asks Claude (or Cursor, or Windsurf) something like:\n\n> *\"Rahim's punches yesterday were 09:00, 13:00, 14:00, and 18:00. Did he get his meal break under California rules?\"*\n\nAnd 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.\n\n**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.\n\n## ๐ก What this is\n\nA small **Model Context Protocol** server that gives your AI agent **deterministic, tested, fixture-backed tools** for:\n\n- Resolving a duty day from raw clock punches (overnight, breaks, OT, all of it).\n- Auditing meal/rest compliance under the **California** rule pack (Labor Code ยงยง 226.7, 512; IWC wage orders), including *Donohue v. AMN* rebuttable-presumption signals.\n- Rounding worked time without losing the exact-minute baseline (so you can prove your rounding is neutral).\n- Building rotating rosters: 2-2-3, 4-on-4-off, DuPont, Pitman.\n- Triaging suspicious punch streams *before* you trust them.\n- 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.\n\nThe 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.\n\n## ๐ง How it actually works\n\n```mermaid\nflowchart LR\n A[You: \"Did Rahim miss his meal break last Tuesday?\"]\n B[Claude / Cursor / Windsurf]\n C[attendance-engine MCP]\n D[(\"@attendance-engine/core\n pure-function engine\n 100% coverage\")]\n\n A -->|prompt| B\n B -->|tool call| C\n C -->|function call| D\n D -->|\"DayResult + ComplianceResult\"| C\n C -->|\"JSON content block\"| B\n B -->|\"plain-English answer with citations\"| A\n\n classDef user fill:#0b3d91,stroke:#fff,color:#fff\n classDef host fill:#5b1ea3,stroke:#fff,color:#fff\n classDef mcp fill:#1f6f43,stroke:#fff,color:#fff\n classDef core fill:#7c4a03,stroke:#fff,color:#fff\n class A user\n class B host\n class C mcp\n class D core\n```\n\nTwo important properties:\n\n1. **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.\n2. **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.\n\n## ๐ Install โ pick your host\n\nPick the MCP host you're already using. Same one-liner everywhere:\n\n\nClaude Desktop (macOS / Windows)
\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows:\n\n```json\n{\n \"mcpServers\": {\n \"attendance-engine\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@attendance-engine/mcp\"]\n }\n }\n}\n```\n\nFully quit and relaunch Claude Desktop (Cmd-Q on macOS โ closing the window isn't enough).\n \n\n\nCursor
\n\n`~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"attendance-engine\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@attendance-engine/mcp\"]\n }\n }\n}\n```\n \n\n\nWindsurf
\n\n`~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"attendance-engine\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@attendance-engine/mcp\"]\n }\n }\n}\n```\n \n\n\nAny other MCP host
\n\nLaunch the stdio binary directly:\n\n```bash\nnpx -y @attendance-engine/mcp\n```\n\nThe server speaks JSON-RPC over stdin/stdout โ that's the whole contract.\n \n\n## ๐ฌ See it in action\n\n> **๐ผ๏ธ 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).\n\n### Scenario 1 โ Did the night-shift nurse get her meal break?\n\n\n\n> **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.\"*\n>\n> **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.\"*\n\n### Scenario 2 โ Find every late-meal day this month\n\n\n\n> **You:** *\"Run an `audit_period_compliance` for employee EMP-007 across June 2026. Here are 30 days of punches and shifts. Use California.\"*\n>\n> **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.\"*\n\n### Scenario 3 โ Are these punches even usable?\n\n\n\n> **You:** *\"I have punches 09:00, 13:00, 14:00 for June 1st. Can I trust these?\"*\n>\n> **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.\"*\n\n### Scenario 4 โ Plan a 4-on-4-off roster for next month\n\n\n\n> **You:** *\"Build me a 4-on-4-off roster for July 2026.\"*\n>\n> **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?\"*\n\n## ๐ ๏ธ Tools at a glance\n\n| Tool | When you'd use it |\n|---|---|\n| **`resolve_day`** | \"What happened on this single day? Lateness, OT, segments, flags.\" |\n| **`resolve_period`** | \"Roll up a week or a month: per-day results plus an aggregated summary.\" |\n| **`evaluate_break_compliance`** | \"Did this person get their meal/rest breaks under California law? Is any premium owed?\" |\n| **`audit_period_compliance`** | \"Audit a whole pay period. Show me total premium hours, high-risk days, and the flag heatmap.\" |\n| **`apply_rounding`** | \"Round worked/OT minutes to a unit โ and keep the exact view alongside it so I can prove neutrality.\" |\n| **`diagnose_punches`** | \"Triage this raw punch stream. Should I trust it?\" |\n| **`generate_roster`** | \"Build a 2-2-3 / 4-on-4-off / DuPont / Pitman / custom rotation.\" |\n| **`list_rule_packs`** | \"What jurisdictions are supported?\" *(currently CA; more arrive in minor releases)* |\n\n## ๐ Resources & prompts\n\nResources you can paste into a chat:\n\n| URI | What it is |\n|---|---|\n| `attendance://docs/overview` | One-pager about the engine, time-zone rules, and how the tools compose. |\n| `attendance://docs/api` | Compact field-by-field API reference. |\n| `attendance://rules/CA` | The California rule pack as JSON โ meal/rest thresholds, waiver limits, premium caps, the citation source. |\n\nGuided prompts (the host's `/` menu, or `prompts/get`):\n\n- **`analyse_timecard`** โ walks the model through the right tool calls to analyse a single duty day.\n- **`roster_planner`** โ generates a roster and renders it as a Markdown table.\n\n## ๐ฐ๏ธ The time-zone rule (read this once and you're fine)\n\nEvery ISO timestamp must carry its own offset:\n\n- โ
`2026-06-01T08:57:00+06:00`\n- โ
`2026-06-01T08:57:00Z`\n- โ `2026-06-01T08:57:00` *(rejected โ the engine won't guess)*\n\nThe 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.\n\nFor days with no punches (an absence, a holiday), pass `policy.tzOffsetMinutes` explicitly so the engine has something to anchor the shift window to.\n\n## ๐ค Embedding (advanced)\n\nBuilding your own host? Skip the CLI:\n\n```ts\nimport { createServer } from '@attendance-engine/mcp';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\n\nconst server = createServer({ name: 'my-hr-server', version: '1.0.0' });\nawait server.connect(new StdioServerTransport());\n```\n\nUse 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.\n\n## ๐ช What it's good for\n\n- Internal HR / payroll / workforce-analytics chat assistants\n- Audit-prep workflows for California employers\n- Customer-support tools at HR-tech vendors who need their AI to actually be right\n- Pre-payroll compliance triage (\"which days need a human to review?\")\n- Schedule planners that need a real roster engine, not vibes\n\n## ๐งฑ What it's not\n\n- A leave-balance / accrual system (the engine deals in minutes, not entitlements).\n- A payroll-money calculator (it gives you the hour buckets โ *you* multiply by the rate).\n- A biometric device protocol (pair it with whatever ingest layer you've got).\n- A UI. There's no dashboard in here; that's a separate concern.\n\n## ๐ Compatibility\n\n| | |\n|---|---|\n| **Node** | 18+ (CI runs 20 LTS) |\n| **MCP SDK** | 1.x |\n| **Engine** | `@attendance-engine/core` โฅ 0.4 (peer dep) |\n| **Hosts tested** | Claude Desktop 1.x ยท Cursor ยท Windsurf ยท any stdio MCP client |\n\n## ๐ More reading\n\n- ๐ [Detailed scenarios with full tool transcripts](docs/scenarios.md)\n- ๐ผ๏ธ [How to capture your own demo screenshots](docs/screenshots/README.md)\n- ๐ [Engine API reference](https://github.com/arifur9993/attendance-engine/blob/main/packages/core/docs/api.md)\n- ๐ [Time-zone semantics](https://github.com/arifur9993/attendance-engine/blob/main/packages/core/docs/timezones.md)\n- ๐๏ธ [California Labor Code ยงยง 226.7, 512](https://www.dir.ca.gov/dlse/faq_mealperiods.htm)\n- ๐๏ธ [Donohue v. AMN Services (Cal. 2021)](https://law.justia.com/cases/california/supreme-court/2021/s253677.html)\n\n## โค๏ธ Credits\n\nBuilt 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.\n\n## License\n\nMIT โ see [LICENSE](LICENSE).\n","readmeFilename":"README.md","_rev":"1-50e9be7197e5a9c6c342b7548f604c36"}