calcuris-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-03
+
+### Added
+
+- Initial release of `calcuris-mcp`, an MCP stdio server exposing the
+  Calcuris (calcuris.com) tax engines. Seven tools:
+  - `us_income_tax` — US federal (2026 IRS brackets, post-OBBBA) + estimated
+    state income tax, with progressive bracket breakdown.
+  - `us_paycheck` — US take-home pay per pay period (federal withholding,
+    Social Security, Medicare, Additional Medicare, state tax).
+  - `us_property_tax` — annual/monthly US property tax from a home value and
+    either a custom rate or a state's real 2026 effective rate.
+  - `ca_income_tax` — Canadian federal + provincial/territorial income tax,
+    CPP/QPP + CPP2/QPP2, EI/QPIP, net take-home pay; optional
+    `compareAllProvinces`.
+  - `au_income_tax` — Australian resident income tax (2025-26 ATO brackets)
+    + Medicare levy, Medicare Levy Surcharge, LITO, HELP/HECS repayment.
+  - `au_stamp_duty` — Australian state/territory stamp duty with
+    first-home-buyer concessions and foreign purchaser surcharge; optional
+    `compareAllStates`.
+  - `uk_dividend_tax` — UK dividend tax (HMRC stacking method, tapered
+    Personal Allowance, £500 dividend allowance, year-over-year comparison).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tresor4k
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# calcuris-mcp
+
+![npm version](https://img.shields.io/npm/v/calcuris-mcp)
+![license](https://img.shields.io/npm/l/calcuris-mcp)
+
+An MCP (Model Context Protocol) server that exposes the tax engines behind
+[Calcuris](https://calcuris.com) — real 2026 US income tax & paycheck math, US
+state property tax, Canadian federal + provincial income tax, Australian
+income tax & stamp duty, and UK dividend tax. No API key, no network calls:
+every number is computed locally from data sourced from the IRS, Tax
+Foundation, CRA/Revenu Québec, the ATO and state revenue offices, and HMRC.
+
+## Quick Start
+
+Run directly with `npx` — no install required.
+
+### Claude Desktop / Claude Code
+
+Add to your MCP config (`claude_desktop_config.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "calcuris": {
+      "command": "npx",
+      "args": ["-y", "calcuris-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "calcuris": {
+      "command": "npx",
+      "args": ["-y", "calcuris-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+Every response includes a `source` note and a `reference_url` pointing to the
+live calculator on [calcuris.com](https://calcuris.com) that uses the same
+engine.
+
+| Tool | Description | Example call | Example response (excerpt) |
+|---|---|---|---|
+| `us_income_tax` | US federal (2026 IRS brackets, post-OBBBA) + estimated state income tax, with a full progressive bracket breakdown. | `{ "grossIncome": 95000, "filingStatus": "single", "stateCode": "CA" }` | `{ "federalTax": 12070, "stateTax": 4758.42, "totalTax": 16828.42, "marginalRate": 0.22, "takeHome": 78171.58 }` |
+| `us_paycheck` | US take-home pay per pay period: federal withholding, Social Security, Medicare (+ Additional Medicare), state tax, net pay. | `{ "payType": "salary", "annualSalary": 80000, "payFrequency": "biweekly", "filingStatus": "single", "stateCode": "TX" }` | `{ "net": { "annual": 65110, "perPeriod": 2504.23 }, "federal": { "annual": 8770 }, "socialSecurity": { "annual": 4960 } }` |
+| `us_property_tax` | Annual/monthly property tax from a home value and either a custom rate or a state's real 2026 effective rate. | `{ "homeValue": 450000, "stateCode": "TX" }` | `{ "annualTax": 6300, "monthlyTax": 525, "effectiveRatePct": 1.4 }` |
+| `ca_income_tax` | Canadian federal + provincial/territorial income tax, CPP/QPP (+ CPP2/QPP2), EI/QPIP, and net take-home pay. Optional `compareAllProvinces`. | `{ "grossIncome": 75000, "provinceCode": "ON", "rrspContribution": 0 }` | `{ "federalTax": 8468.74, "provincialTax": 3696.06, "netIncome": 57465.69 }` |
+| `au_income_tax` | Australian resident income tax (2025-26 ATO brackets) + Medicare levy, Medicare Levy Surcharge, LITO offset, HELP/HECS repayment. | `{ "taxableIncome": 95000, "privateHospitalCover": true, "hasHelpDebt": false }` | `{ "incomeTax": 19288, "medicareLevy": 1900, "totalTax": 21188, "takeHome": 73812 }` |
+| `au_stamp_duty` | Australian state/territory stamp duty, including first-home-buyer concessions and the foreign purchaser surcharge. Optional `compareAllStates`. | `{ "propertyValue": 750000, "stateCode": "NSW", "firstHomeBuyer": false, "foreignResident": false, "principalResidence": true }` | `{ "baseDuty": 28162.5, "totalDuty": 28162.5, "effectiveRate": 3.755 }` |
+| `uk_dividend_tax` | UK dividend tax with HMRC's stacking method (dividends sit on top of other income), tapered Personal Allowance, £500 dividend allowance, year-over-year comparison. | `{ "otherIncome": 40000, "dividends": 15000, "year": "2026/27" }` | `{ "dividendTax": 2741.25, "totalTax": 8227.25, "extraVsPrior": 290 }` |
+
+Each tool's `inputSchema` documents every field (types, enums, defaults) and
+is discoverable via `tools/list` — see the source in
+[`src/index.ts`](./src/index.ts) for the full parameter set.
+
+## Data sources & freshness
+
+All engines target **tax year 2026** (UK: 2026/27, with 2025/26 comparison
+built in). Rates and brackets are sourced from:
+
+- **US** — IRS Rev. Proc. 2025-32 (federal brackets, standard deduction,
+  Child Tax Credit), SSA/IRS FICA wage base and rates, Tax Foundation (state
+  income tax brackets and property tax effective rates), state revenue
+  offices.
+- **Canada** — CRA (federal brackets, BPA, CPP/CPP2), Revenu Québec (QPP,
+  QPIP, Quebec abatement), provincial finance ministries.
+- **Australia** — ATO (2025-26 individual tax rates, Medicare levy, LITO,
+  HELP/HECS repayment thresholds), state and territory revenue offices
+  (stamp duty schedules and first-home-buyer concessions).
+- **UK** — HMRC (Personal Allowance, dividend allowance, Income Tax bands and
+  dividend rates for 2025/26 and 2026/27).
+
+These are the same datasets that power the live calculators:
+
+- [calcuris.com](https://calcuris.com)
+- [US income tax calculator](https://calcuris.com/us/income-tax-calculator/)
+- [US paycheck calculator](https://calcuris.com/us/paycheck-calculator/)
+- [Canada income tax calculator](https://calcuris.com/ca/income-tax-calculator/)
+- [Australia stamp duty calculator](https://calcuris.com/au/stamp-duty-calculator/)
+
+## Disclaimer
+
+Results are **estimates for guidance only** and do not constitute tax,
+legal, or financial advice. Tax situations vary by individual (local taxes,
+deductions, credits, and edge cases are not exhaustively modeled). Always
+confirm figures with a qualified tax professional or the relevant government
+authority before making financial decisions.
+
+## Development
+
+```bash
+npm install
+npm run build   # compiles src/ → dist/ with tsc
+npm test        # spawns the built server and runs the smoke test
+```
+
+## License
+
+MIT © 2026 tresor4k

package/dist/index.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+// calcuris-mcp — MCP stdio server exposing the Calcuris tax engines (calcuris.com).
+// All math is copied verbatim from the production site (src/lib/*.ts) — no rates are
+// re-derived here. This file only wires zod input schemas to the pure functions and
+// shapes the JSON response.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { computeIncomeTax } from "./lib/income-tax-math.js";
+import { computePaycheck } from "./lib/paycheck-math.js";
+import { computePropertyTax } from "./lib/property-tax-math.js";
+import { STATE_PROPERTY_TAX_2026 } from "./lib/us-state-property-tax-2026.js";
+import { computeCaIncomeTax, compareProvinces } from "./lib/ca-income-tax-math.js";
+import { computeAuIncomeTax } from "./lib/au-income-tax-math.js";
+import { computeAuStampDuty, compareStates } from "./lib/au-stamp-duty-math.js";
+import { computeDividendTax } from "./lib/uk-dividend-tax-math.js";
+const FOOTER = "Estimate for guidance — 2026 rates from official sources (IRS/Tax Foundation/CRA/ATO/state revenue offices/HMRC).";
+// ---- Enum tables shared by multiple tools ----
+const US_STATE_CODES = [
+    "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA",
+    "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM",
+    "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA",
+    "WV", "WI", "WY",
+];
+const CA_PROVINCE_CODES = [
+    "AB", "BC", "MB", "NB", "NL", "NS", "NT", "NU", "ON", "PE", "QC", "SK", "YT",
+];
+const AU_STATE_CODES = ["NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT"];
+const FILING_STATUSES = ["single", "mfj", "hoh", "mfs"];
+const PAY_FREQUENCIES = ["weekly", "biweekly", "semimonthly", "monthly"];
+function usStateEnumSchema(optional) {
+    const base = z
+        .enum(US_STATE_CODES)
+        .describe(`Two-letter US state code (or DC for the District of Columbia). Valid codes: ${US_STATE_CODES.join(", ")}.`);
+    return optional ? base.optional() : base;
+}
+function unknownCodeError(kind, code, valid) {
+    throw new Error(`Unknown ${kind} code "${code}". Valid codes: ${valid.join(", ")}.`);
+}
+const server = new McpServer({
+    name: "calcuris-mcp",
+    version: "0.1.0",
+});
+// ---------------------------------------------------------------------------
+// 1) us_income_tax
+// ---------------------------------------------------------------------------
+server.registerTool("us_income_tax", {
+    title: "US federal + state income tax",
+    description: "Computes US federal income tax (2026 IRS brackets, post-OBBBA) plus an estimated state income tax, " +
+        "with a full progressive bracket breakdown. Example: { grossIncome: 95000, filingStatus: \"single\", " +
+        "stateCode: \"CA\" }. " +
+        FOOTER,
+    inputSchema: {
+        grossIncome: z.number().nonnegative().describe("Gross annual income in USD."),
+        filingStatus: z
+            .enum(FILING_STATUSES)
+            .describe("IRS filing status: single, mfj (married filing jointly), hoh (head of household), mfs (married filing separately)."),
+        stateCode: usStateEnumSchema(true).describe("Optional two-letter state code to also estimate state income tax. Omit to skip state estimation."),
+        preTaxContributions: z
+            .number()
+            .nonnegative()
+            .default(0)
+            .describe("Annual pre-tax 401(k)/traditional IRA contributions, reduces taxable income."),
+        useItemized: z.boolean().default(false).describe("Use itemized deductions instead of the standard deduction."),
+        itemizedAmount: z.number().nonnegative().default(0).describe("Total itemized deductions in USD (only used if useItemized is true and it exceeds the standard deduction)."),
+        dependents: z.number().int().nonnegative().default(0).describe("Number of qualifying children for the Child Tax Credit."),
+    },
+}, async (args) => {
+    const stateCode = args.stateCode ?? "";
+    const inputs = {
+        filingStatus: args.filingStatus,
+        grossIncome: args.grossIncome,
+        preTaxContributions: args.preTaxContributions,
+        useItemized: args.useItemized,
+        itemizedAmount: args.itemizedAmount,
+        dependents: args.dependents,
+        stateCode,
+        taxYear: 2026,
+    };
+    const result = computeIncomeTax(inputs);
+    return jsonResult({
+        result,
+        source: "Calcuris US income tax engine — IRS Rev. Proc. 2025-32 (federal), Tax Foundation (state).",
+        reference_url: "https://calcuris.com/us/income-tax-calculator/",
+    });
+});
+// ---------------------------------------------------------------------------
+// 2) us_paycheck
+// ---------------------------------------------------------------------------
+server.registerTool("us_paycheck", {
+    title: "US paycheck / take-home pay",
+    description: "Computes US take-home pay per pay period: federal withholding, Social Security, Medicare (+ Additional " +
+        "Medicare), state tax, and net pay, for salaried or hourly workers. Example: { payType: \"salary\", " +
+        "annualSalary: 80000, payFrequency: \"biweekly\", filingStatus: \"single\", stateCode: \"TX\" }. " +
+        FOOTER,
+    inputSchema: {
+        payType: z.enum(["salary", "hourly"]).describe("Whether pay is a fixed annual salary or an hourly rate."),
+        annualSalary: z.number().nonnegative().default(0).describe("Annual salary in USD (used when payType is \"salary\")."),
+        hourlyRate: z.number().nonnegative().default(0).describe("Hourly rate in USD (used when payType is \"hourly\")."),
+        hoursPerWeek: z.number().nonnegative().default(40).describe("Hours worked per week (used when payType is \"hourly\", or to derive an hourly-equivalent when salaried)."),
+        payFrequency: z.enum(PAY_FREQUENCIES).describe("Pay period frequency."),
+        filingStatus: z.enum(FILING_STATUSES).describe("IRS filing status used for federal withholding."),
+        stateCode: usStateEnumSchema(true).describe("Optional two-letter state code to also withhold state tax. Omit to skip."),
+        preTaxRetirement: z.number().nonnegative().default(0).describe("Pre-tax 401(k) contribution PER PAY PERIOD (reduces federal/state taxable income, not FICA)."),
+        preTaxHealth: z.number().nonnegative().default(0).describe("Pre-tax health/HSA (section 125) contribution PER PAY PERIOD (reduces federal/state AND FICA taxable income)."),
+        dependents: z.number().int().nonnegative().default(0).describe("Number of dependents (informational, not withheld via CTC in this engine)."),
+        extraWithholding: z.number().nonnegative().default(0).describe("Additional federal withholding requested PER PAY PERIOD (W-4 line 4c)."),
+    },
+}, async (args) => {
+    const stateCode = args.stateCode ?? "";
+    const inputs = {
+        payType: args.payType,
+        annualSalary: args.annualSalary,
+        hourlyRate: args.hourlyRate,
+        hoursPerWeek: args.hoursPerWeek,
+        payFrequency: args.payFrequency,
+        filingStatus: args.filingStatus,
+        stateCode,
+        preTaxRetirement: args.preTaxRetirement,
+        preTaxHealth: args.preTaxHealth,
+        dependents: args.dependents,
+        extraWithholding: args.extraWithholding,
+        taxYear: 2026,
+    };
+    const result = computePaycheck(inputs);
+    return jsonResult({
+        result,
+        source: "Calcuris US paycheck engine — IRS Rev. Proc. 2025-32, SSA/IRS FICA limits 2026, Tax Foundation (state).",
+        reference_url: "https://calcuris.com/us/paycheck-calculator/",
+    });
+});
+// ---------------------------------------------------------------------------
+// 3) us_property_tax
+// ---------------------------------------------------------------------------
+server.registerTool("us_property_tax", {
+    title: "US property tax",
+    description: "Estimates annual/monthly US property tax from a home value and either a custom rate or a state's real " +
+        "2026 effective property tax rate. Example: { homeValue: 350000, stateCode: \"NJ\" }. " +
+        FOOTER,
+    inputSchema: {
+        homeValue: z.number().nonnegative().describe("Market value of the home in USD."),
+        stateCode: usStateEnumSchema(true).describe("Optional two-letter state code. When provided (and ratePct is not), the state's real 2026 effective property tax rate is used automatically."),
+        ratePct: z.number().nonnegative().optional().describe("Optional custom effective property tax rate (%). Overrides the state's rate if both are given."),
+        exemption: z.number().nonnegative().default(0).describe("Homestead exemption amount in USD, subtracted from the assessed value."),
+        assessmentRatioPct: z.number().positive().default(100).describe("Percent of market value actually assessed (default 100; some states assess less than market value)."),
+    },
+}, async (args) => {
+    let ratePct = args.ratePct;
+    let stateRow;
+    if (args.stateCode) {
+        stateRow = STATE_PROPERTY_TAX_2026[args.stateCode];
+        if (!stateRow)
+            unknownCodeError("US state", args.stateCode, US_STATE_CODES);
+        if (ratePct === undefined)
+            ratePct = stateRow.effRatePct;
+    }
+    if (ratePct === undefined) {
+        throw new Error("Provide either stateCode (to use the state's real effective rate) or ratePct.");
+    }
+    const result = computePropertyTax({
+        homeValue: args.homeValue,
+        ratePct,
+        exemption: args.exemption,
+        assessmentRatioPct: args.assessmentRatioPct,
+    });
+    return jsonResult({
+        result,
+        stateBaseline: stateRow
+            ? { stateCode: args.stateCode, effectiveRatePct: stateRow.effRatePct, medianTaxUsd: stateRow.medianTaxUsd, medianHomeUsd: stateRow.medianHomeUsd }
+            : undefined,
+        source: "Calcuris US property tax engine — state effective rates from Tax Foundation / Census ACS 2026 dataset.",
+        reference_url: "https://calcuris.com/us/property-tax-calculator/",
+    });
+});
+// ---------------------------------------------------------------------------
+// 4) ca_income_tax
+// ---------------------------------------------------------------------------
+server.registerTool("ca_income_tax", {
+    title: "Canada federal + provincial income tax",
+    description: "Computes Canadian federal + provincial/territorial income tax, CPP/QPP (+ CPP2/QPP2), EI/QPIP, and net " +
+        "take-home pay for a given province, 2026 rates. Example: { grossIncome: 75000, provinceCode: \"ON\" }. " +
+        "Set compareAllProvinces: true to get every province/territory side by side. " +
+        FOOTER,
+    inputSchema: {
+        grossIncome: z.number().nonnegative().describe("Annual employment income in CAD."),
+        provinceCode: z.enum(CA_PROVINCE_CODES).describe(`Two-letter province/territory code. Valid codes: ${CA_PROVINCE_CODES.join(", ")}.`),
+        rrspContribution: z.number().nonnegative().default(0).describe("Annual RRSP contribution in CAD (deducted from taxable income)."),
+        compareAllProvinces: z.boolean().default(false).describe("If true, also return the same calculation for every province/territory (ignores provinceCode for the comparison table, but a single result for provinceCode is still returned as \"result\")."),
+    },
+}, async (args) => {
+    const result = computeCaIncomeTax({
+        grossIncome: args.grossIncome,
+        provinceCode: args.provinceCode,
+        rrspContribution: args.rrspContribution,
+    });
+    const comparison = args.compareAllProvinces
+        ? compareProvinces(args.grossIncome, args.rrspContribution, [...CA_PROVINCE_CODES])
+        : undefined;
+    return jsonResult({
+        result,
+        comparison,
+        source: "Calcuris Canada income tax engine — CRA / Revenu Québec 2026 brackets and payroll rates.",
+        reference_url: "https://calcuris.com/ca/income-tax-calculator/",
+    });
+});
+// ---------------------------------------------------------------------------
+// 5) au_income_tax
+// ---------------------------------------------------------------------------
+server.registerTool("au_income_tax", {
+    title: "Australia resident income tax",
+    description: "Computes Australian resident income tax (2025-26 ATO brackets) plus Medicare levy, Medicare levy " +
+        "surcharge, LITO offset, and HELP/HECS repayment. Example: { taxableIncome: 95000, privateHospitalCover: " +
+        "true, hasHelpDebt: false }. " +
+        FOOTER,
+    inputSchema: {
+        taxableIncome: z.number().nonnegative().describe("Annual taxable income in AUD."),
+        privateHospitalCover: z.boolean().default(true).describe("True if covered by private hospital insurance (avoids the Medicare Levy Surcharge)."),
+        hasHelpDebt: z.boolean().default(false).describe("True if the taxpayer has an outstanding HELP/HECS debt (triggers compulsory repayment)."),
+    },
+}, async (args) => {
+    const result = computeAuIncomeTax(args);
+    return jsonResult({
+        result,
+        source: "Calcuris Australia income tax engine — ATO 2025-26 individual tax rates, Medicare levy, LITO, HELP repayment thresholds.",
+        reference_url: "https://calcuris.com/au/income-tax-calculator/",
+    });
+});
+// ---------------------------------------------------------------------------
+// 6) au_stamp_duty
+// ---------------------------------------------------------------------------
+server.registerTool("au_stamp_duty", {
+    title: "Australia stamp duty (land transfer duty)",
+    description: "Computes Australian state/territory stamp duty on a property purchase, including first-home-buyer " +
+        "concessions and the foreign purchaser surcharge where applicable. Example: { propertyValue: 750000, " +
+        "stateCode: \"NSW\", firstHomeBuyer: false, foreignResident: false, principalResidence: true }. Set " +
+        "compareAllStates: true to compare every state/territory for the same property value. " +
+        FOOTER,
+    inputSchema: {
+        propertyValue: z.number().nonnegative().describe("Purchase price / property value in AUD."),
+        stateCode: z.enum(AU_STATE_CODES).describe(`State/territory code. Valid codes: ${AU_STATE_CODES.join(", ")}.`),
+        firstHomeBuyer: z.boolean().default(false).describe("True if the buyer qualifies as a first home buyer (applies concession where available)."),
+        foreignResident: z.boolean().default(false).describe("True if the buyer is a foreign person (applies the foreign purchaser surcharge)."),
+        principalResidence: z.boolean().default(true).describe("True if this will be the buyer's principal place of residence (owner-occupier); false for an investment purchase."),
+        compareAllStates: z.boolean().default(false).describe("If true, also return the same calculation for every state/territory."),
+    },
+}, async (args) => {
+    const result = computeAuStampDuty({
+        propertyValue: args.propertyValue,
+        stateCode: args.stateCode,
+        firstHomeBuyer: args.firstHomeBuyer,
+        foreignResident: args.foreignResident,
+        principalResidence: args.principalResidence,
+    });
+    const comparison = args.compareAllStates
+        ? compareStates(args.propertyValue, { firstHomeBuyer: args.firstHomeBuyer, foreignResident: args.foreignResident, principalResidence: args.principalResidence }, [...AU_STATE_CODES])
+        : undefined;
+    return jsonResult({
+        result,
+        comparison,
+        source: "Calcuris Australia stamp duty engine — state/territory revenue office schedules 2026.",
+        reference_url: "https://calcuris.com/au/stamp-duty-calculator/",
+    });
+});
+// ---------------------------------------------------------------------------
+// 7) uk_dividend_tax
+// ---------------------------------------------------------------------------
+server.registerTool("uk_dividend_tax", {
+    title: "UK dividend tax",
+    description: "Computes UK dividend tax using HMRC's stacking method (dividends sit on top of other income), including " +
+        "the tapered Personal Allowance and the £500 dividend allowance, with a year-over-year comparison. " +
+        "Example: { otherIncome: 40000, dividends: 15000, year: \"2026/27\" }. " +
+        FOOTER,
+    inputSchema: {
+        otherIncome: z.number().nonnegative().describe("Salary / other taxable income in GBP, excluding dividends."),
+        dividends: z.number().nonnegative().describe("Gross dividends received in GBP."),
+        year: z.enum(["2026/27", "2025/26"]).describe("UK tax year."),
+    },
+}, async (args) => {
+    const result = computeDividendTax(args);
+    return jsonResult({
+        result,
+        source: "Calcuris UK dividend tax engine — HMRC dividend allowance, Personal Allowance taper, Income Tax bands.",
+        reference_url: "https://calcuris.com/uk/dividend-tax-calculator/",
+    });
+});
+function jsonResult(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+}
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("calcuris-mcp fatal error:", err);
+    process.exit(1);
+});

package/dist/lib/au-income-tax-data.js

@@ -0,0 +1,17 @@
+export const AU_INCOME_2026 = {
+    brackets: [{ rate: 0, lower: 0, upper: 18200 }, { rate: 0.16, lower: 18200, upper: 45000 }, { rate: 0.3, lower: 45000, upper: 135000 }, { rate: 0.37, lower: 135000, upper: 190000 }, { rate: 0.45, lower: 190000, upper: null }],
+    medicareLevy: { rate: 0.02, lowerSingle: 28011, upperSingle: 35013, phaseInRate: 0.1 },
+    lito: { max: 700, taper1Start: 37500, taper1Rate: 0.05, taper2Start: 45000, taper2Rate: 0.015, cutout: 66667 },
+    help: { system: "marginal", thresholds: [{ rate: 0, lower: 0, upper: 67000 }, { rate: 0.15, lower: 67000, upper: 125000 }, { rate: 0.17, lower: 125000, upper: 179285 }, { rate: 0.1, lower: 179285, upper: null }] },
+    mls: { thresholds: [{ rate: 0, lower: 0, upper: 101000 }, { rate: 0.01, lower: 101000, upper: 118000 }, { rate: 0.0125, lower: 118000, upper: 158000 }, { rate: 0.015, lower: 158000, upper: null }] },
+    superGuaranteeRate: 0.12,
+};
+export const AU_INCOME_AS_OF = "2025-26";
+export const AU_INCOME_SOURCES = [
+    { label: "ATO - Tax rates - Australian residents (2025-26 resident brackets)", url: "https://www.ato.gov.au/tax-rates-and-codes/tax-rates-australian-residents" },
+    { label: "ATO - Study and training support loans rates and repayment thresholds (2025-26 marginal HELP)", url: "https://www.ato.gov.au/tax-rates-and-codes/study-and-training-support-loans-rates-and-repayment-thresholds" },
+    { label: "ATO - Medicare levy reduction for low-income earners (2025-26 single thresholds)", url: "https://www.ato.gov.au/individuals-and-families/medicare-and-private-health-insurance/medicare-levy/medicare-levy-reduction/medicare-levy-reduction-for-low-income-earners" },
+    { label: "ATO - Medicare levy surcharge income, thresholds and rates (2025-26 singles)", url: "https://www.ato.gov.au/individuals-and-families/medicare-and-private-health-insurance/medicare-levy-surcharge/medicare-levy-surcharge-income-thresholds-and-rates" },
+    { label: "ATO - Low income tax offset (LITO)", url: "https://www.ato.gov.au/individuals-and-families/income-deductions-offsets-and-records/tax-offsets/low-income-tax-offset" },
+    { label: "ATO - How much super to pay (Super Guarantee 12% from 1 Jul 2025)", url: "https://www.ato.gov.au/businesses-and-organisations/super-for-employers/paying-super-contributions/how-much-super-to-pay" },
+];

package/dist/lib/au-income-tax-math.js

@@ -0,0 +1,110 @@
+// Moteur income tax / take-home Australie (résident, 2025-26) — impôt sur le revenu (barème ATO) + Medicare
+// levy (2 % avec phase-in low-income) + LITO + remboursement HELP/HECS (système marginal 2025-26) + Medicare
+// levy surcharge (optionnel) + info Superannuation Guarantee. Logique PURE, testable. Réutilise le cœur
+// progressif partagé (us-tax-engine). Couche "estimate" honnête : résident, employé, déductions standard ;
+// pas de gains en capital / déductions individuelles. SG = sur le brut (à la charge de l'employeur), non retenue.
+import { applyBrackets, effectiveRate } from "./us-tax-engine.js";
+import { AU_INCOME_2026 } from "./au-income-tax-data.js";
+// LITO 2025-26 : 700 $ max, réduit de 5c/$ entre 37 500 et 45 000, puis 1,5c/$ entre 45 000 et 66 667.
+export function litoFor(income) {
+    const l = AU_INCOME_2026.lito;
+    if (income <= l.taper1Start)
+        return l.max;
+    if (income <= l.taper2Start)
+        return Math.max(l.max - l.taper1Rate * (income - l.taper1Start), 0);
+    if (income <= l.cutout) {
+        const afterTaper1 = l.max - l.taper1Rate * (l.taper2Start - l.taper1Start);
+        return Math.max(afterTaper1 - l.taper2Rate * (income - l.taper2Start), 0);
+    }
+    return 0;
+}
+// Medicare levy : 0 sous le seuil bas, phase-in 10c/$ entre les seuils, plein 2 % au-dessus du seuil haut.
+export function medicareLevyFor(income) {
+    const m = AU_INCOME_2026.medicareLevy;
+    if (income <= m.lowerSingle)
+        return 0;
+    if (income >= m.upperSingle)
+        return income * m.rate;
+    return (income - m.lowerSingle) * m.phaseInRate;
+}
+// HELP/HECS 2025-26 (système marginal) : nil sous le 1ᵉʳ seuil, marginal sur les bandes intermédiaires ; la
+// dernière bande (upper=null) = 10 % du revenu de remboursement TOTAL (pas marginal), conformément à l'ATO.
+export function helpRepaymentFor(income) {
+    const t = AU_INCOME_2026.help.thresholds;
+    const last = t[t.length - 1];
+    if (income > last.lower)
+        return income * last.rate; // 10 % du revenu total
+    let rep = 0;
+    for (const b of t) {
+        if (income <= b.lower)
+            break;
+        if (b.upper === null)
+            break;
+        rep += (Math.min(income, b.upper) - b.lower) * b.rate;
+    }
+    return rep;
+}
+// Medicare levy surcharge : taux plat sur le revenu total selon la tranche (singles), seulement sans couverture.
+export function mlsFor(income) {
+    const t = AU_INCOME_2026.mls.thresholds;
+    let rate = 0;
+    for (const b of t) {
+        if (b.upper === null || income <= b.upper) {
+            rate = b.rate;
+            break;
+        }
+    }
+    return income * rate;
+}
+function helpMarginal(income) {
+    const t = AU_INCOME_2026.help.thresholds;
+    const last = t[t.length - 1];
+    if (income > last.lower)
+        return 0; // au-dessus = 10 % du total (pas de marginal au sens dérivée)
+    for (const b of t) {
+        if (b.upper !== null && income > b.lower && income <= b.upper)
+            return b.rate;
+    }
+    return 0;
+}
+export function computeAuIncomeTax(inp) {
+    const income = Math.max(inp.taxableIncome || 0, 0);
+    const prog = applyBrackets(income, AU_INCOME_2026.brackets);
+    const incomeTax = prog.tax;
+    const lito = litoFor(income);
+    const taxAfterOffsets = Math.max(incomeTax - lito, 0);
+    const medicareLevy = medicareLevyFor(income);
+    const medicareLevySurcharge = inp.privateHospitalCover ? 0 : mlsFor(income);
+    const helpRepayment = inp.hasHelpDebt ? helpRepaymentFor(income) : 0;
+    const totalTax = taxAfterOffsets + medicareLevy + medicareLevySurcharge + helpRepayment;
+    const takeHome = income - totalTax;
+    // Taux marginal combiné : barème + Medicare (phase-in 10 % ou 2 %) + taper LITO + HELP.
+    const m = AU_INCOME_2026.medicareLevy;
+    const l = AU_INCOME_2026.lito;
+    let medMarg = 0;
+    if (income > m.lowerSingle && income < m.upperSingle)
+        medMarg = m.phaseInRate;
+    else if (income >= m.upperSingle)
+        medMarg = m.rate;
+    let litoMarg = 0;
+    if (income > l.taper1Start && income <= l.taper2Start)
+        litoMarg = l.taper1Rate;
+    else if (income > l.taper2Start && income <= l.cutout)
+        litoMarg = l.taper2Rate;
+    const marginalRate = prog.marginalRate + medMarg + litoMarg + (inp.hasHelpDebt ? helpMarginal(income) : 0);
+    return {
+        taxableIncome: income,
+        incomeTax,
+        lito,
+        taxAfterOffsets,
+        medicareLevy,
+        medicareLevySurcharge,
+        helpRepayment,
+        totalTax,
+        takeHome,
+        marginalRate,
+        averageRate: effectiveRate(totalTax, income),
+        superGuarantee: income * AU_INCOME_2026.superGuaranteeRate,
+        slices: prog.slices,
+    };
+}

package/dist/lib/au-stamp-duty-data.js

@@ -0,0 +1,22 @@
+// 8 juridictions (6 États + 2 Territoires). Barèmes 2025-26.
+export const AU_STAMP_DUTY_2026 = {
+    NSW: { code: "NSW", name: "New South Wales", brackets: [{ rate: 0.0125, lower: 0, upper: 17000 }, { rate: 0.015, lower: 17000, upper: 37000 }, { rate: 0.0175, lower: 37000, upper: 99000 }, { rate: 0.035, lower: 99000, upper: 372000 }, { rate: 0.045, lower: 372000, upper: 1240000 }, { rate: 0.055, lower: 1240000, upper: 3721000 }, { rate: 0.07, lower: 3721000, upper: null }], foreignSurchargeRate: 0.09, firstHome: { fullExemptThreshold: 800000, concessionUpper: 1000000, method: "linear", note: "First Home Buyers Assistance Scheme: full duty exemption on a new or existing home valued at or under $800,000, with a concessional reduced rate from $800,000 to $1,000,000 (eligible first home buyers only)." } },
+    VIC: { code: "VIC", name: "Victoria", brackets: [{ rate: 0.014, lower: 0, upper: 25000 }, { rate: 0.024, lower: 25000, upper: 130000 }, { rate: 0.06, lower: 130000, upper: 960000 }], pprBrackets: [{ rate: 0.014, lower: 0, upper: 25000 }, { rate: 0.024, lower: 25000, upper: 130000 }, { rate: 0.05, lower: 130000, upper: 440000 }, { rate: 0.06, lower: 440000, upper: 550000 }], pprUpper: 550000, flatBand: { lower: 960000, upper: 2000000, rate: 0.055, aboveRate: 0.065 }, foreignSurchargeRate: 0.08, firstHome: { fullExemptThreshold: 600000, concessionUpper: 750000, method: "linear", note: "First home buyer: full duty exemption up to $600,000 and a tapering concession from $600,001 to $750,000 (no concession above $750,000). Applies to your principal place of residence." } },
+    QLD: { code: "QLD", name: "Queensland", brackets: [{ rate: 0, lower: 0, upper: 5000 }, { rate: 0.015, lower: 5000, upper: 75000 }, { rate: 0.035, lower: 75000, upper: 540000 }, { rate: 0.045, lower: 540000, upper: 1000000 }, { rate: 0.0575, lower: 1000000, upper: null }], homeConcessionBrackets: [{ rate: 0.01, lower: 0, upper: 350000 }, { rate: 0.035, lower: 350000, upper: 540000 }, { rate: 0.045, lower: 540000, upper: 1000000 }, { rate: 0.0575, lower: 1000000, upper: null }], foreignSurchargeRate: 0.08, firstHome: { fullExemptThreshold: 700000, concessionUpper: 800000, method: "linear", note: "Established first home: home concession rate minus a tapered first-home concession, so duty is $0 up to $700,000 and phases out by $800,000. A first home that is a new home or vacant land (eligible from 1 May 2025) gets a full, uncapped concession." } },
+    WA: { code: "WA", name: "Western Australia", brackets: [{ rate: 0.019, lower: 0, upper: 120000 }, { rate: 0.0285, lower: 120000, upper: 150000 }, { rate: 0.038, lower: 150000, upper: 360000 }, { rate: 0.0475, lower: 360000, upper: 725000 }, { rate: 0.0515, lower: 725000, upper: null }], foreignSurchargeRate: 0.07, firstHome: { fullExemptThreshold: 500000, concessionUpper: 700000, method: "linear", note: "First home owner rate of duty (from 21 March 2025): no duty up to $500,000, a concessional rate from $500,000 to $700,000 (Perth metro and Peel; $750,000 outside metro/Peel); vacant land no duty up to $350,000, concession to $450,000." } },
+    SA: { code: "SA", name: "South Australia", brackets: [{ rate: 0.01, lower: 0, upper: 12000 }, { rate: 0.02, lower: 12000, upper: 30000 }, { rate: 0.03, lower: 30000, upper: 50000 }, { rate: 0.035, lower: 50000, upper: 100000 }, { rate: 0.04, lower: 100000, upper: 200000 }, { rate: 0.0425, lower: 200000, upper: 250000 }, { rate: 0.0475, lower: 250000, upper: 300000 }, { rate: 0.05, lower: 300000, upper: 500000 }, { rate: 0.055, lower: 500000, upper: null }], foreignSurchargeRate: 0.07, firstHome: { fullExemptThreshold: 0, concessionUpper: 0, method: "newOnly", note: "From 13 February 2025: full stamp duty relief with no value cap, but only for eligible new homes, off-the-plan apartments or vacant land to build a principal place of residence. Established/existing homes are not eligible. No relief applies to the foreign ownership surcharge." } },
+    TAS: { code: "TAS", name: "Tasmania", brackets: [{ rate: 0, lower: 0, upper: 3000 }, { rate: 0.0175, lower: 3000, upper: 25000 }, { rate: 0.0225, lower: 25000, upper: 75000 }, { rate: 0.035, lower: 75000, upper: 200000 }, { rate: 0.04, lower: 200000, upper: 375000 }, { rate: 0.0425, lower: 375000, upper: 725000 }, { rate: 0.045, lower: 725000, upper: null }], baseFee: 50, foreignSurchargeRate: 0.08, firstHome: { fullExemptThreshold: 750000, concessionUpper: 750000, method: "cliff", note: "100% duty exemption for first home buyers of established homes valued at $750,000 or less, for transactions settling between 18 February 2024 and 30 June 2026 (the scheme closes 30 June 2026). Full duty applies above $750,000." } },
+    ACT: { code: "ACT", name: "Australian Capital Territory", brackets: [{ rate: 0.0028, lower: 0, upper: 260000 }, { rate: 0.022, lower: 260000, upper: 300000 }, { rate: 0.034, lower: 300000, upper: 500000 }, { rate: 0.0432, lower: 500000, upper: 750000 }, { rate: 0.059, lower: 750000, upper: 1000000 }, { rate: 0.064, lower: 1000000, upper: 1455000 }], investmentBrackets: [{ rate: 0.012, lower: 0, upper: 200000 }, { rate: 0.022, lower: 200000, upper: 300000 }, { rate: 0.034, lower: 300000, upper: 500000 }, { rate: 0.0432, lower: 500000, upper: 750000 }, { rate: 0.059, lower: 750000, upper: 1000000 }, { rate: 0.064, lower: 1000000, upper: 1455000 }], flatAbove: { threshold: 1455000, rate: 0.0454 }, foreignSurchargeRate: 0, firstHome: { fullExemptThreshold: 1020000, concessionUpper: 1455000, method: "incomeTest", note: "Home Buyer Concession Scheme is income-tested (not value-tested): full duty concession ($0 duty) if total household taxable income is at or under the threshold (e.g. $250,000 with no dependent children, rising with children). There is no property-value cap on eligibility." } },
+    NT: { code: "NT", name: "Northern Territory", brackets: null, ntFormula: { a: 0.06571441, b: 15, vDivisor: 1000, cutoff: 525000, flatTiers: [[3000000, 0.0495], [5000000, 0.0575], [null, 0.0595]] }, foreignSurchargeRate: 0, firstHome: { fullExemptThreshold: 0, concessionUpper: 0, method: "none", note: "No general first-home stamp duty concession. Support is a cash grant (HomeGrown Territory: $50,000 for first home buyers building/buying a new home) plus the House and Land Package Exemption for new house-and-land packages. No foreign purchaser surcharge in the NT." } },
+};
+export const AU_STAMP_DUTY_AS_OF = "2025-26";
+export const AU_STAMP_DUTY_SOURCES = [
+    { label: "Revenue NSW - Transfer duty rates, surcharge purchaser duty, FHBAS (2025-26)", url: "https://www.revenue.nsw.gov.au/taxes-duties-levies-royalties/transfer-duty" },
+    { label: "State Revenue Office Victoria - Land transfer duty current rates, PPR rates, FHB exemption/concession, foreign purchaser additional duty", url: "https://www.sro.vic.gov.au/land-transfer-duty" },
+    { label: "Queensland Revenue Office - Transfer duty rates, home concession, first home concession, AFAD", url: "https://qro.qld.gov.au/duties/transfer-duty/" },
+    { label: "Government of WA (RevenueWA) - Transfer duty general rate, first home owner rate, foreign transfer duty", url: "https://www.wa.gov.au/organisation/department-of-treasury-and-finance/transfer-duty-assessment" },
+    { label: "RevenueSA - Rate of stamp duty (conveyance), first home buyer relief, foreign ownership surcharge", url: "https://revenuesa.sa.gov.au/stamp-duty/rate-of-stamp-duty" },
+    { label: "State Revenue Office Tasmania - Property transfer duty rates, first home (established) duty relief, foreign investor duty surcharge", url: "https://www.sro.tas.gov.au/property-transfer-duties/rates-of-duty" },
+    { label: "ACT Revenue Office - Conveyance duty for non-commercial property (from 1 July 2025), Home Buyer Concession Scheme", url: "https://www.revenue.act.gov.au/rates-and-property-charges/conveyance-duty-stamp-duty/conveyance-duty-for-non-commercial-property" },
+    { label: "NT Territory Revenue Office - Stamp duty (Stamp Duty Act 1978 conveyance formula + flat tiers)", url: "https://treasury.nt.gov.au/dtf/territory-revenue-office/stamp-duty" },
+];