Introduction

When building workflows in the DSH ecosystem, processing sensitive HR data (social insurance, housing fund, individual income tax) requires a local computation layer. Existing SaaS tools usually require PII to be uploaded to the cloud, while open-source payroll libraries are often tailored to one country’s tax laws. This plugin externalizes payroll calculation differences through a three-layer architecture, keeping the engine company-agnostic while meeting the data security requirements of “local-first and PII stays on the machine.”

What Is This

A general-purpose HR payroll MCP service. Zero-dependency Node ESM, local-first. It is maintained by helibeiqi and is designed to address differing company payroll rules and inconsistent data source formats, providing a standardized local calculation engine.

Core Features

  1. Generic header adaptation: Infers column name mappings through an Import Adapter to handle discrepancies in company spreadsheet formats.
  2. Company configuration read/write: Supports configurations such as regional jurisdiction checks, housing fund ratios, salary split ratios, and tax-exempt item dictionaries.
  3. Statutory calculation engine: Covers social insurance and housing fund (including work-injury insurance), the cumulative withholding method for individual income tax, and outputs the company’s total labor cost.
  4. Safe performance formula evaluation: Uses a restricted expression evaluator (supports only + - * / % ( ) and variables) to avoid executing malicious code.
  5. Payroll orchestration: Splits performance pay, gross pay, social insurance deductions, income tax, and net pay, and accumulates YTD values.
  6. Payslip export: Supports CSV/JSON export.
  7. Parameter library version refresh: Supports extending cities not yet included and refreshing annual parameters.

Installation and Activation

  1. Install: Copy the plugin to a designated local directory (example path):
    C:\Users\helib\dsh-hr-payroll-mcp\
  1. Configure: Inject the MCP server into dsh’s cordis.patch.yml.
    - 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"

*Note: The `args`/`cwd` in the repository are the author's local absolute paths. When deploying to your machine, update the corresponding paths. You can also set environment variables to point to your files.*

Typical Usage

Configure Performance Formula

When calculating performance pay, use the restricted expression evaluator for safe evaluation. For example, set the performance bonus to 1.1 times the basic salary:

basic_salary * 1.1

This expression contains only allowed operators and variables; the engine executes it locally and does not involve dangerous code.

Configure Company Parameters

In Company Profile, configure the local jurisdiction, housing fund ratio, salary split ratio, and tax-exempt item dictionary. For work-injury insurance, separately configure the industry risk coefficient (injury_rate). This cost is paid by the employer only; it is not deducted from the individual’s salary but is included in the company’s total cost.

Refresh Parameter Library

Social insurance and housing fund ratios and contribution base limits are adjusted annually. Use the refresh_statutory tool to add cities not yet included or override the local parameter library version. The current data uses the 2026-ref version and covers 12 cities (8 have been updated to 2026 official announcements, and 4 temporarily continue to use 2025 values).

Applicable Scenarios and Notes

  • Applicable scenarios: HR scenarios with strong data security concerns, offline auditing/review, or integrating payroll into a local AI workflow.
  • Important boundaries:
    1. Data freshness: The parameter library requires annual refresh. Before use, always rely on the current year’s official local documents.
    2. Work-injury insurance: Paid by the employer only, with the rate configured by industry risk; it is not deducted from the individual’s salary but is included in company costs.
    3. Contribution base differences: The medical insurance base may differ from the pension/unemployment insurance base (for example, in Shenzhen, Guangzhou, and Hangzhou). The engine separately marks upper and lower limits by insurance type.
    4. Performance logic: Performance formulas are supplied by the user; the engine only provides the calculation environment.
    5. Unlisted cities: Currently covered cities include Beijing, Shanghai, Shenzhen, Guangzhou, Hangzhou, Chengdu, Wuhan, Tianjin, Chongqing, Suzhou, Nanjing, and Xi’an. Other cities must be extended via refresh_statutory.