内容
<div align="center">
# 🕒 考勤引擎 MCP
### 人工智能代理可信赖的工资和工时答案。
**询问 Claude *"有人在上周二错过了用餐休息吗?"* — 然后确保答案正确。**
[](https://www.npmjs.com/package/@attendance-engine/mcp)
[](https://github.com/arifur9993/attendance-engine-mcp/actions)
[](LICENSE)
[](https://modelcontextprotocol.io/)
</div>
---
## 🤔 问题
每个人力资源 / 薪酬 / 时间跟踪团队最终都会向 Claude（或 Cursor，或 Windsurf）提出类似的问题：
> *"Rahim 昨天的打卡记录是 09:00, 13:00, 14:00 和 18:00。根据加利福尼亚州的规定，他是否获得了用餐休息？"*
而大型语言模型（LLM）会像往常一样：它会大致检查时间戳，嘟囔着说些关于“是的，可能他的午餐看起来不错”的话，然后继续下去。有时它是正确的，有时它会忘记加利福尼亚州要求用餐休息必须在**第 5 个小时结束前开始**。有时它会将 25 分钟的休息时间算作符合规定。有时，对于跨越午夜的夜班，它直接放弃。
**你不能把这个拿给审计师看。** 你不能把它放到工资单产品中。你不能相信它来进行加班费计算，否则如果计算错误，就可能导致赔偿责任。
## 💡 这是什么
一个小的 **模型上下文协议** 服务器，为您的人工智能代理提供**确定性、经过测试、固定支持的工具**，用于：
- 解析原始打卡记录以确定工作日（包括夜间工作、休息时间和加班时间）。
- 根据**加利福尼亚州**规则包（劳动法典 §§ 226.7, 512；工业福利委员会工资令）审计用餐/休息时间合规性，包括 *Donohue v. AMN* 反驳推定信号。
- 在不丢失精确分钟基线的情况下，舍入工作时间（以便您可以证明舍入是中立的）。
- 构建轮换排班：2-2-3，4-on-4-off，DuPont，Pitman。
- 在信任之前**筛选可疑的打卡记录**。
- 运行多天的**工资和工时审计**，汇总应得的加班费、风险日和旗帜热图。
数学运算位于 [`@attendance-engine/core`](https://www.npmjs.com/package/@attendance-engine/core) 中 — 一个纯函数、零依赖的 TypeScript 库，测试覆盖率 100%。这个 MCP 服务器是其上的薄代理接口。
## 🧠 它是如何工作的
```mermaid
flowchart LR
A[您：”Did Rahim miss his meal break last Tuesday?”]
B[Claude / Cursor / Windsurf]
C[attendance-engine MCP]
D[("@attendance-engine/core
纯函数引擎
100% 覆盖率")]
A -->|prompt| B
B -->|tool calls| 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
```
两个重要的属性：
1. **Claude 不进行数学运算。** 它选择一个工具，填写参数，然后转发答案。如果引擎说“这是迟到的用餐”，代理就说“这是迟到的用餐”。如果您再次询问同一个问题，您会得到相同的答案 — 每次都一样。
2. **时区是显式的，不是猜测的。** 每个时间戳都带有自己的偏移量。引擎永远不会读取主机时钟，永远不会假设 UTC，永远不会悄悄转换。DST 天数有效，因为 **您**告诉它偏移量，而不是因为它推断出来。
## 🚀 安装 — 选择您的主机
选择您已经使用的 MCP 主机。所有地方都使用相同的单行命令：
<details>
<summary><b>Claude Desktop (macOS / Windows)</b></summary>
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"attendance-engine": {
"command": "npx",
"args": ["-y", "@attendance-engine/mcp"]
}
}
}
```
完全退出并重新启动 Claude Desktop（macOS 上使用 Cmd-Q，关闭窗口是不够的）。
</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>任何其他 MCP 主机</b></summary>
直接启动_stdio二进制文件：
```bash
npx -y @attendance-engine/mcp
```
服务器通过 stdin/stdout 以 JSON-RPC 协议通信。
</details>
## 🎬 看看它在行动
> **🖼️ 场景卡片下面是可发布的 SVG 模拟图**（在 GitHub、npm、LinkedIn 上内联渲染）。当您捕获实际产品截图时，可以用它们替换 — 请参阅 [`docs/screenshots/README.md`](docs/screenshots/README.md)。
### 场景 1 — 夜班护士是否获得了用餐休息？
> **您：** *"Sara 在 6 月 1 日值班，时间是 22:00→06:00。打卡记录：21:54, 02:00, 02:30, 06:18。应用加利福尼亚州规则。"*
>
> **Claude（调用 `evaluate_break_compliance`）：** *"Sara 在 6 月 1 日的工作时间为 7h54m（她的时钟退出时间落在 6 月 2 日，但属于此班次）。她在 4 小时标记处开始了 30 分钟的用餐休息，这根据加利福尼亚州的法规在第 5 个小时结束前开始是合规的。工作时间跨越午夜；相应标记。 她比预定时间早 18 分钟离开 — 这 18 分钟计为加班。"*
### 场景 2 — 查找本月所有延迟用餐日
> **您：** *"为员工 EMP-007 运行 6 月 2026 期间的 `audit_period_compliance`。这里有 30 天的打卡记录和班次。使用加利福尼亚州规则。"*
>
> **Claude：** *"3 天处于高推定风险 — 6 月 4 日、6 月 12 日、6 月 22 日。所有这三天都是延迟用餐（在第 5 小时后开始）。应得的总用餐期间加班小时：3。小计 22 日也低于 12 小时第二餐门槛。未检测到休息期间违规。"*
### 场景 3 — 这些打卡记录是否可用？
> **您：** *"我有 6 月 1 日的打卡记录 09:00, 13:00, 14:00。可以信任这些记录吗？"*
>
> **Claude（调用 `diagnose_punches`）：** *"建议：** 拒绝。打卡记录数量为奇数 — 缺少一个进出记录。没有它，工作时间和加班时间将成为猜测。此外，每个打卡记录都落在 5 分钟的边界上，这通常表明是手动输入而不是设备读取。建议在解决之前与源系统进行验证。"*
### 场景 4 — 为下个月计划 4-on-4-off 排班
> **您：** *"为 2026 年 7 月创建一个 4-on-4-off 排班。"*
>
> **Claude（调用 `generate_roster`）：** *"31 天 — 7 月 1-4 日、9-12 日、17-20 日、25-28 日的工作日（12 小时日班，07:00-19:00）。休息日填充空白。是否要在此模式下分配团队轮换？"*
## 🛠️ 工具一览
| 工具 | 何时使用 |
|---|---|
| **`resolve_day`** | "某一天发生了什么？迟到、加班、时间段、标记。" |
| **`resolve_period`** | "汇总一个星期或一个月：每天的结果加上汇总摘要。" |
| **`evaluate_break_compliance`** | "这个人根据加利福尼亚州法律是否获得了用餐/休息时间？是否应得溢价？" |
| **`audit_period_compliance`** | "审计整个工资期。给我总溢价小时、高风险日和旗帜热图。" |
| **`apply_rounding`** | "将工作/加班分钟数舍入到一个单位 — 并保留精确视图以证明中立性。" |
| **`diagnose_punches`** | "排查此原始打卡流。我可以信任它吗？" |
| **`generate_roster`** | "构建 2-2-3 / 4-on-4-off / DuPont / Pitman / 自定义轮换排班。" |
| **`list_rule_packs`** | "支持哪些司法管辖区？" *(目前为加利福尼亚州；更多将在小版本中发布)* |
## 📚 资源和提示
您可以粘贴到聊天中的资源：
| URI | 它是什么 |
|---|---|
| `attendance://docs/overview` | 引擎、时区规则和工具组合的简介。 |
| `attendance://docs/api` | 简洁的字段 API 参考。 |
| `attendance://rules/CA` | 加利福尼亚州规则包为 JSON — 用餐/休息门槛、豁免限制、溢价上限、引用来源。 |
引导提示（主机 `/` 菜单，或 `prompts/get`）：
- **`analyse_timecard`** — 引导模型通过正确的工具调用来分析单个工作日。
- **`roster_planner`** — 生成排班并将其渲染为 Markdown 表。
## 🕰️ 时区规则（阅读一次即可）
每个 ISO 时间戳必须携带其自己的偏移量：
- ✅ `2026-06-01T08:57:00+06:00`
- ✅ `2026-06-01T08:57:00Z`
- ❌ `2026-06-01T08:57:00` *(拒绝 — 引擎不会猜测)*
引擎将所有内容减少到单个时间线上的绝对瞬间。由于偏移量是显式的，因此 DST 有效。工作日和班次的 `HH:MM` 是工作地点的本地时钟 — 与您的业务日历匹配，而不是 UTC。
对于没有打卡记录的日子（缺勤、假期），请显式传递 `policy.tzOffsetMinutes`，以便引擎有锚点来确定班次窗口。
## 🤝 嵌入（高级）
构建自己的主机？跳过 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());
```
用于：自定义 HTTP/SSE 适配器、Claude Agent SDK 设置、测试工具、在-house 部署等。
## 💪 它的优势
- 内部 HR / 薪酬 / 劳动力分析聊天助手
- 加利福尼亚州雇主的审计准备工作流
- HR-tech 供应商的客户支持工具，需要 AI 准确性
- 预工资合规性排查（“哪些日子需要人工审核？”）
- 需要真正的排班引擎的排班计划器，而不是凭感觉
## 🧱 它不是
- 假期余额 / 累积系统（引擎处理分钟数，不处理权益）
- 工资计算器（它为您提供小时桶 — **您**乘以费率）
- 生物识别设备协议（将其与您拥有的摄入层配对）
- UI。这里没有仪表板；这是一个单独的关注点。
## 🌍 兼容性
| | |
|---|---|
| **Node** | 18+（CI 运行 20 LTS） |
| **MCP SDK** | 1.x |
| **引擎** | `@attendance-engine/core` ≥ 0.4（对等依赖） |
| **已测试的主机** | Claude Desktop 1.x · Cursor · Windsurf · 任何 stdio MCP 客户端 |
## 📖 更多阅读
- 📑 [详细场景和完整工具记录](docs/scenarios.md)
- 🖼️ [如何捕获您自己的演示截图](docs/screenshots/README.md)
- 📚 [引擎 API 参考](https://github.com/arifur9993/attendance-engine/blob/main/packages/core/docs/api.md)
- 🌐 [时区语义](https://github.com/arifur9993/attendance-engine/blob/main/packages/core/docs/timezones.md)
- 🏛️ [加利福尼亚州劳动法 § 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)
## ❤️ 致谢
由 [Md. Arifur Rahman](https://www.linkedin.com/in/md-arifur-rahman-mar/) 构建。[`@attendance-engine/core`](https://github.com/arifur9993/attendance-engine) （TypeScript）和 [`arifur9993/attendance-engine`](https://github.com/arifur9993/attendance-engine-php) （PHP）的配套工具。相同的作者，相同的固定装置，相同的答案 — 在您的堆栈可以访问的三个位置。
## License
MIT — 见 [LICENSE](LICENSE)。
