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 擴展。