dsh-hr-payroll-mcp：本地化算薪 MCP 服务

前言¶

在 DSH 生态中构建工作流时，处理敏感的 HR 数据（社保、公积金、个税）需要一个本地计算层。现有的 SaaS 工具通常要求 PII 上传云端，而开源 payroll 库多为某国税法特化。本插件通过三层架构将算薪差异外部化，使引擎保持公司无关，同时满足“本地优先、PII 不出机”的数据安全需求。

这是什么¶

通用 HR 算薪 MCP 服务。零依赖 Node ESM，本地优先。它由 helibeiqi 维护，旨在解决企业算薪规则不同、数据源格式各异的问题，提供一套标准化的本地计算引擎。

核心功能¶

通用表头适配：通过 Import Adapter 推断列名映射，处理各企业表格格式的差异。
企业配置读写：支持属地质检、公积金比例、薪资拆分比、免税项字典等配置。
法定计算引擎：覆盖五险一金（含工伤）、个税累计预扣法，输出公司总人力成本。
安全绩效公式求值：使用受限表达式求值器（仅支持 + - * / % ( ) 与变量），避免执行恶意代码。
算薪编排：拆分绩效、应发、社保、个税、实发，并累计 YTD。
工资条导出：支持 CSV/JSON 格式导出。
参数库版本刷新：支持扩展未收录城市及年度参数更新。

安装与启用¶

安装：将插件复制到本机指定目录（示例路径）：

    C:\Users\helib\dsh-hr-payroll-mcp\

配置：在 dsh 的 cordis.patch.yml 中注入 mcp server。

    - type: stdio
      command: "C:\\Users\\helib\\dsh-hr-payroll-mcp\\payroll-mcp-server.mjs"
      args:
        - "--stdio"
      env:
        PAYROLL_STATUTORY: "C:\\Users\\helib\\dsh-hr-payroll-mcp\\data\\statutory.json"

*注意：仓库中的 `args`/`cwd` 写的是作者本机绝对路径，部署到你的机器需修改对应路径。也可设置环境变量指向你的文件。*

典型用法¶

配置绩效公式¶

在计算绩效时，使用受限表达式安全求值。例如，计算绩效奖金为基本工资的 1.1 倍：

basic_salary * 1.1

此表达式仅包含允许的运算符和变量，引擎在本地执行，不涉及危险代码。

配置企业参数¶

在 Company Profile 中配置属地、公积金比例、薪资拆分比及免税项字典。对于工伤险，需单独配置行业风险系数（injury_rate），该费用仅由单位缴纳，不进个人工资但计入公司总成本。

刷新参数库¶

社保/公积金比例与基数上下限每年调整。使用 refresh_statutory 工具扩展未收录城市，或覆盖本地参数库版本。当前数据为 2026-ref 版本，覆盖 12 个城市（8 个已更新至 2026 官方通告，4 个暂沿用 2025）。

适用场景与注意¶

适用场景：对数据安全敏感的 HR、需离线审计/复核、或想把算薪接入本地 AI 工作流的场景。
重要边界：
1. 数据时效性：参数库需年度刷新，使用前务必以属地当年官方文件为准。
2. 工伤险：仅单位缴纳，比例按行业风险配置，不进个人工资但计入公司成本。
3. 基数差异：医保基数可能与养老/失业不同（如深圳、广州、杭州等），引擎已按险种单独标注上下限。
4. 绩效逻辑：绩效公式由用户自供，引擎仅提供计算环境。
5. 未收录城市：目前覆盖北京、上海、深圳、广州、杭州、成都、武汉、天津、重庆、苏州、南京、西安。其他城市需通过 refresh_statutory 扩展。