PrismHR MCP

prismhr-mcp

面向 PrismHR 的开源模型上下文协议（MCP）服务。 将 Claude、Cursor 或任何兼容 MCP 的 AI Agent 直接连接到你的 PrismHR PEO 平台。自动处理薪资发放、福利注册、合规报告、 应收账款／计费、承运商 EDI 文件以及 Microsoft 365 操作——借助 经过验证的架构工具、按权限范围控制的同意机制，无需编写自定义集成代码。

专为 PEO、经纪人和薪资运营人员打造，让他们获得真正能在 PrismHR 上工作的 AI Agent—— 而不是又一堆脆弱的脚本。

由 Simploy 维护。采用 MIT 许可、通过 PyPI 分发， 支持插件。为 PrismHR × Agentic AI 提供基础层。

mcp-name: io.github.nikulk2992-jpg/prismhr-mcp

**关键词：**PrismHR API、PrismHR 集成、MCP 服务、模型上下文 协议、PEO 自动化、薪资自动化、HR AI、适用于 PrismHR 的 Claude、 Agentic AI、福利注册自动化、834 EDI、401(k) 文件自动化、 HRIS AI Agent、PEO 软件集成。

---

为什么要开发这个项目

每个使用 PrismHR 的 PEO 最终都会搭建出同一套杂乱的技术栈：Python 脚本、Postman 集合、Playwright 自动化，以及一次性的 Node 应用。 每个工具都要重新实现登录、会话保活、重试逻辑、分页， 以及处理 PrismHR 的各种特殊情况（camelCase 架构、500 "No data found" 陷阱、 每批最多 20 条的限制、静默的 401 错误）。

prismhr-mcp 将这些功能集中到一个生产级 MCP 服务中，一次性解决。 AI Agent 负责编排；服务负责身份验证、缓存、重试、 数据规范化和 PEO 领域逻辑。任何 PEO 都可以接入该服务，让 AI 在自有 PrismHR 租户上高效工作——无需胶水代码、 无需猜测，也不会虚构端点。

适用对象：

• 使用 PrismHR、希望将 Claude / Cursor / ChatGPT Desktop 直接接入运营技术栈的 PEO
• 构建注册自动化流程的福利经纪人和承运商
• 用于取代脆弱的 Postman / Playwright 工作流的薪资团队
• 希望在紧迫的时间安排下交付 PEO AI 试点项目的顾问

---

状态

核心功能已达到生产就绪状态。已发布至 PyPI 并收录于 MCP Registry。

• **身份验证 + 会话 + HTTP 客户端：**已完成。集成 1Password CLI， 使用 scrypt 加密的磁盘凭证缓存，PrismHR 会话支持主动保活（工作流中途不会出现 401）， 失败时自动刷新，并发上限，带抖动退避的重试，处理 500→空结果特殊情况， 分页和批处理。
• **已验证架构门禁：**每个工具都基于实时 UAT 探测结果—— 不猜测端点，不虚构字段。已验证 102 种响应结构，并在持续增加。
• **447 个方法目录：**已为 18 个服务编入完整的 PrismHR REST 接口目录。meta_call 允许 Agent 安全地调用任何已验证的方法。
• **连接时同意机制：**包含 15 项权限范围的清单，按 (peo, env) 保存 JSON 同意记录，支持前置条件扩展和级联撤销。默认策略 = 全部拒绝。工具会在调用时强制执行权限范围。
• **生产环境安全门禁：**要连接生产环境 PrismHR，必须设置 PRISMHR_MCP_ALLOW_PROD=true。 防止首次运行时意外造成大范围影响。
• **已收录于 MCP Registry：**每个支持 MCP 的客户端都可以发现此服务。
• **测试套件：**pytest + respx 测试通过。

完整路线图请参阅 .planning/architecture.md， 付费层级详情请参阅 .planning/assistants-roadmap.md。

---

为 PEO 解锁的能力

接入 PrismHR 租户后，AI Agent（Claude、ChatGPT、 Cursor）即可对实时数据执行以下任一工作流——默认只读，写入操作需选择启用并指定权限范围。

日常运营

• 新员工入职审核 — 检查每位新员工是否缺少 SSN、地址、E-Verify 审核通过记录、必需的扣款项目和工资扣押 设置。在首次发薪前标记问题。
• 工资批次健康检查 — 实时查看每个未结批次的状态；发现停滞的 INIT、卡住的审批、发薪日期已过但尚未 过账、净工资为负以及缺少付款凭证等问题。
• 离职员工清理 — 离职后检查清单：已发放最后一笔工资、已停止扣款、福利已终止、已创建 COBRA 记录、已支付 PTO、ACH 已停用。
• 手动支票审核 — 标记缺少原因代码、金额过高、在指定时间范围内重复，以及每月重复出现 模式的非周期支票。

合规

• ACA 配置完整性 — 发现 PrismHR 本身指出的设置错误；这些错误是导致 1094-C/1095-C 罚款风险的首要原因。
• 1095-C 数值一致性审核 — 生成后审核每份 1095-C 表格；标记员工已参保但填报了代码 1H、安全港冲突、由状态类型变更导致的代码偏差、 等待期代码错误，以及在 2020 年之前的纳税年度使用 ICHRA 代码。
• 受抚养人保障年龄届满 — 查找超过 ACA 年龄 门槛，或将在未来 30/60/90 天内达到该年龄的受抚养人。
• COBRA 资格检查 — 符合条件的事件、通知期限 倒计时和选择期限警告。
• 工资扣押付款历史 — 查找没有付款记录的有效工资扣押、逾期汇款，以及多个工资扣押的优先级检查。
• W-2 准备情况检查 — 1 月前的预检：已填写 SSN 且 格式正确、已配置联邦预扣税、YTD 合理性检查。

对账

• YTD 工资对账 — 批量对比年初至今总额与 付款凭证历史总和；在 W-2 季到来前发现不易察觉的偏差。
• 941 季度对账 — 按季度核对联邦纳税申报表；工资、联邦所得税、社会保障税、Medicare 税和额外 Medicare 税。
• 福利与扣款审核 — 已参保但未扣款、已扣款但未参保的不匹配；发现不易察觉的保费损失。
• 账单与工资清账审核 — 按员工和计划级别进行检查。
• 账单与工资对账（客户级别） — 每月控制对账。
• 401(k) 匹配规则合规性 — 雇主匹配金额与计划公式对比、402(g) 限额监控，以及 50 岁以上人员的补缴资格。
• 401(k) 年末补足计算 — 计算提前达到延期缴款限额、因而少获按比例匹配金额的员工在年末应得的匹配金额。

福利 + 应收账款

• FSA/HSA 缴款限额跟踪器 — 监控 IRS 2026 年限额，并报告超限、接近限额和预计超额缴款情况。
• 退休计划贷款状态 — 违约风险、逾期贷款和视同分配风险。
• 工伤赔偿风险敞口 — 根据当前工资 × 费率 × 经验修正系数，按各州的类别代码估算保费。
• 未结发票账龄 — 应收账款分档 + 高风险客户标记。
• PTO 余额对账 — 负余额、超过上限、应计记录过期、缺少类别分配。
• 文件到期检查 — 检查未来 30/60/90 天内到期的 I-9 和身份证明文件。
• 客户上线准备情况 — 为新 PEO 客户提供工资处理前检查清单和准备度评分。

承保机构 + 分发

• 承保机构参保（834 5010） — 通用写入器 + 各承保机构的配套指南配置。Guardian 模型已上线；BCBS Michigan、Sun Life EDX、Voya PDI、Empower PDI 已列入试点路线图。
• W-2 分发助手 — 批量下载、挂号信邮寄、经同意检查后的电子送达、SharePoint 归档——均可组合使用。

每个工作流都会返回带有严重程度和修复提示的结构化发现，因此 AI Agent 可以将其串联起来，生成更高阶的报告（如月末结账资料包、年末申报资料包、新客户上线资料包等）。

**分级：**开源核心免费。上述工作流包含在付费的 prismhr-mcp-simploy 版本中——源代码可用，按 PEO 授权。 请联系 [email protected]。

---

版本

prismhr-mcp 提供三个版本。Core 永久免费。付费版本在此基础上叠加商业 PEO 智能能力。

Tier 1 — prismhr-mcp（本仓库，MIT，免费）

基础版本。包含以下内容：

• PrismHR 会话管理器，支持保活和自动刷新
• 包含 447 个方法的目录，以及经过验证的架构 meta_call
• 按范围控制的授权、生产环境安全门控、加密凭据缓存
• meta_find、meta_describe、meta_capabilities
• 基于实时 UAT 的客户端、员工和薪资读取工具
• MCP Registry 上架、PyPI 分发

如果你想立即通过 Claude 操作自己的 PrismHR 租户，且不编写任何自定义代码，请使用此版本。

Tier 2 — prismhr-mcp-simploy（付费，源码可用）— 正在积极构建中

提供端到端 PEO 工作流的命名 AI 助手。基于开源核心构建。按 PEO 授权。

目前正在交付：

• 承运商参保助手 — 通用 834 5010 EDI 生成器，以及承运商配套指南配置。Guardian 模型原型已上线（8 项测试全部通过）。BCBS Michigan、Sun Life EDX、Voya PDI、Empower PDI 已列入 Phase 1 试点计划。接下来将实现 SFTP 交付和增量跟踪。
• 401(k) 文件自动化 — 支持 Empower PDI、Voya 薪资，以及 Fidelity tape-spec 定宽格式。

路线图：

• 薪资运营助手 — 撤销／更正工作流、扣款冲突检测、加班异常标记、superbatch 对账
• 福利管理助手 — 福利选择审计、COBRA 资格、ACA 状态、承运商同步验证
• 合规助手 — W2/941 对账、扣押款跟踪、州税设置、I-9 审计、工伤赔偿代码
• 应收账款／计费助手 — 计费与薪资审计、发票摘要、雇主税务责任
• 品牌化报表 — 通过可插拔的品牌和模板注册表生成 Simploy 品牌的 PDF/XLSX（支持白标）
• Microsoft 365 连接器 — Graph API 邮件、SharePoint 上传、Teams 帖子、Outlook 事件／任务

Tier 3 — prismhr-mcp-broker（付费，托管）— 计划中

多租户托管 MCP 端点，让承运商、ERP 和 EDI 提供商通过一次集成即可访问任意 PrismHR PEO。一个端点，多个租户，集中式合规。在 Tier 2 服务第二个 PEO 之前，暂缓此计划。

对 Tier 2 或 Tier 3 感兴趣？请联系 [email protected]。

---

快速开始 — UAT 冒烟测试

目前只有 UAT 受支持；如需使用生产环境，必须明确选择加入。生产环境受 PRISMHR_MCP_ALLOW_PROD=true 保护。

1. 安装

cd C:\path\to\prismhr-mcp    # or wherever you cloned
uv sync --extra dev

2. 配置凭据

将 .env.example 复制为 .env（或设置环境变量）。选择一种方式：

方式 A — 1Password CLI（推荐）：

$env:PRISMHR_MCP_ONEPASSWORD_VAULT = "YourVault"
$env:PRISMHR_MCP_ONEPASSWORD_ITEM_PRISMHR = "PrismHR UAT"

需要先登录 op CLI（op signin）。条目必须包含标记为 username 和 password 的字段（可选 peoId）。

方式 B — 直接设置环境变量（快捷，适合 CI）：

$env:PRISMHR_MCP_USERNAME = "<your-api-username>"
$env:PRISMHR_MCP_PASSWORD = "<paste>"
$env:PRISMHR_MCP_PEO_ID   = "<your-peo-id>"

3. 检查配置

uv run python -c "from prismhr_mcp.server import build; b = build(); import asyncio; print([t.name for t in asyncio.run(b.server.list_tools())])"

预期有 9 个工具。

4. 注册到 Claude Code

将以下内容添加到 Claude Code 的 .mcp.json：

{
  "mcpServers": {
    "prismhr-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\prismhr-mcp", "prismhr-mcp"],
      "env": {
        "PRISMHR_MCP_ENVIRONMENT": "uat",
        "PRISMHR_MCP_USERNAME": "<your-api-username>",
        "PRISMHR_MCP_PASSWORD": "<paste or reference>",
        "PRISMHR_MCP_PEO_ID": "<your-peo-id>"
      }
    }
  }
}

重启 Claude Code。/mcp 应显示 prismhr-mcp 已连接，并包含 9 个工具。

5. 开始首次对话

You: Tell me about the prismhr-mcp server.
Claude: [calls meta_about] → explains what's available + commercial options.

You: What permissions does it want?
Claude: [calls meta_request_permissions] → shows 14 scopes grouped by category.

You: Grant everything recommended (reads only, no writes).
Claude: [calls meta_grant_permissions(accept_recommended_defaults=true)]

You: List all clients in UAT.
Claude: [calls client_list] → returns the full client roster.

6. 运行测试

uv run pytest -q      # expect 60 passing

---

一句话了解架构

┌──────────────────────────────────────────────────────────────┐
│ Claude / Cowork / any MCP client                             │
└──────────────────┬───────────────────────────────────────────┘
                   │ stdio (MCP JSON-RPC)
┌──────────────────▼───────────────────────────────────────────┐
│ prismhr-mcp server (FastMCP)                                 │
│   ├── Permissions (deny-default, scope-gated tools)          │
│   ├── Tool groups: meta • client • payroll • benefits        │
│   │                 compliance • billing • report • m365     │
│   ├── Runtime: PrismHR client, Graph client, SQLite cache    │
│   └── Auth: 1Password → scrypt-AES cache → session / MSAL    │
└────┬─────────────────────────────────────────────────┬───────┘
     │                                                 │
     ▼                                                 ▼
┌──────────────┐                           ┌──────────────────┐
│ PrismHR REST │                           │ Microsoft Graph   │
│ (UAT / Prod) │                           │ (Outlook / Teams /│
└──────────────┘                           │  SharePoint)      │
                                           └──────────────────┘

关键设计原则：

• 工厂模式 + 严格注册表。 工具只能通过 server.build() 注册；重复名称或未知的分组前缀会在启动时失败（不会在导入时静默处理）。
• 默认拒绝的权限范围。 用户必须运行 meta_grant_permissions 才能启用工具访问权限。前置权限会自动扩展，撤销权限会级联生效。
• 异步优先。 使用 httpx.AsyncClient、asyncio.Semaphore(5) 和异步工具。
• 处理 PrismHR 的特殊情况。 401 时自动刷新；列表端点返回 404 时映射为 []；500 "No data found" 映射为空；连续 10 次出现 500 时强制刷新。
• 输出采用 snake_case。 使用 Pydantic 的 validation_alias=AliasChoices(...)，让 PrismHR 的 camelCase 负载映射为 snake_case 输出，同时避免 camelCase 泄漏到 MCP 工具契约中。
• 按 (peo, env) 隔离授权。 从 UAT 切换到生产环境不会继承已有授权。

---

商业支持

OSS 核心永久免费。Simploy 提供两项付费服务：

解决方案架构师 — 白标部署

为您的 PEO 品牌交付开箱即用的 prismhr-mcp 部署：

• 品牌配置编写（徽标、配色、字体排印、PDF 页脚、法律免责声明）
• 按客户端配置 SharePoint 站点映射 + Azure AD / Graph 租户
• 针对 PEO 特定工作流定制 PrismHR 工具
• 将电子表格 / 旧版脚本迁移到 MCP 工具
• 为 PEO 运营团队提供入门培训 + Claude/Cowork 工作流指导
• 根据上游版本进行季度更新
• 优先响应问题 + 专属 Slack/电子邮件联系人

适合拥有 50–5,000 个客户端、希望采用 Claude 优先运营模式且不想自行构建的 PEO。联系：[email protected]

企业支持

为已运行 OSS 服务的团队提供有 SLA 保障的支持：

• Sev-1（生产环境中断）问题 4 小时内响应
• 年度安全审查 + 符合 SOC-2 要求的部署指导
• 已签名的发布制品 + SBOM
• 私密漏洞披露渠道

适合受监管行业，或有采购要求的中大型 PEO。联系：[email protected]

Claude 可以通过 meta_about 介绍这两项服务——询问“prismhr-mcp 有哪些商业选项？”即可了解详情。

---

故障排查

No PrismHR credentials configured — 设置 1Password 条目环境变量，或直接设置 PRISMHR_MCP_USERNAME/_PASSWORD 变量对。

PrismHR login rejected (status=401) — 用户名、密码或 peo_id 错误。peo_id 因租户而异；请咨询 PrismHR 管理员。生产环境和 UAT 使用不同的值。

environment=prod requires PRISMHR_MCP_ALLOW_PROD=true — 安全保护机制。准备就绪后，明确设置 PRISMHR_MCP_ALLOW_PROD=true。

PERMISSION_NOT_GRANTED — 调用工具时未提供相应权限范围。请让 Claude 先运行 meta_request_permissions，然后运行 meta_grant_permissions 并指定所需的权限范围。

Claude Code 启动服务时服务立即退出 — 几乎总是缺少环境变量。使用第 3 步的检查来排查问题。

---

许可证

MIT — 参见 LICENSE。欢迎贡献；路线图请参阅 .planning/ 下的规划文档。