dsh-hr-payroll-mcp

Every payroll cycle brings the same headache: the social-insurance sheet calls one column "contributable base," the housing-fund sheet calls it "deposit base," and the performance sheet may not share a single name. Meanwhile the actual math — cumulative withholding for individual income tax, per-city base floors and caps, work-injury rates tied to industry risk classes — is scattered across dozens of policy documents that shift every year. Layer on the reality that mainstream HR SaaS platforms require uploading employee PII to the cloud, and compliance-sensitive teams simply refuse to comply. dsh-hr-payroll-mcp turns the entire payroll pipeline into a zero-dependency, local-first Node ESM MCP service: every number is computed on-machine and nothing ever leaves it.

The architecture has three layers. The bottom is a statutory calculation engine with built-in parameters for 12 Chinese cities (Beijing, Shanghai, Shenzhen, Guangzhou, Hangzhou, Chengdu, Wuhan, Tianjin, Chongqing, Suzhou, Nanjing, Xi'an), supporting per-insurance-type base clamping, work-injury rates applied exclusively to employer cost, and month-by-month cumulative IIT. The middle is an Import Adapter that infers column mappings through synonym matching, confirms with the user, type-checks, and warns on missing fields, dissolving every company's unique headers outside of engine code. The top is a Company Profile that externalises employer-specific settings such as housing-fund ratios, salary-split percentages, special additional deductions, and rounding rules. Performance logic runs through a restricted expression evaluator that permits only arithmetic operators, parentheses, and variables — no arbitrary code execution. Nine MCP tools are exposed, covering table-header adaptation, single-item calculations, full payroll orchestration, consistency validation, and payslip export in CSV or JSON, all drivable over MCP stdio by a dsh agent.

Three groups benefit most: compliance-driven HR teams that will not send payroll data to the cloud; finance and internal-control staff who need offline audit, re-verification, or a sandboxed payroll sandbox; and developers who want to wire payroll into a local AI-agent pipeline alongside other dsh-ecosystem tools. The parameter database is labelled as 2026-reference values with per-city source citations, but users should always confirm against the current official publications in their jurisdiction before relying on the numbers.