@markcolabs/mcp 0.1.0

package/README.md

@@ -0,0 +1,263 @@
+# @markcolabs/mcp
+
+Model Context Protocol (MCP) server for **digitalcalculator.info** financial calculators.
+
+**Status:** v0.1.0 — first public release. Sprint 136 hits the P12 O5-KR1 **5-tool target** and lifts the `private:true` flag for `npm publish`.
+
+Locks in the contract from **ADR-0039** (MCP Tool Contract & Calc-Engine Lift).
+
+---
+
+## What ships in v0.1.0
+
+| Tool | Purpose |
+|---|---|
+| `dc.calculator.mortgage.monthlyPayment` | Monthly principal & interest, total interest, total paid for a fixed-rate mortgage. |
+| `dc.calculator.compoundInterest.futureValue` | Future value of a principal with optional monthly contributions, at a chosen compounding frequency. |
+| `dc.calculator.401k.projection` | Year-by-year 401(k) projection through retirement, honoring IRS 2026 contribution limits (incl. SECURE 2.0 super catch-up for ages 60-63). |
+| `dc.calculator.socialSecurity.estimate` | SSA bend-point PIA estimate with early-claim reduction, delayed-credit math, and lifetime projection. |
+| `dc.calculator.paycheck.netPay` | IRS 2026 federal Percentage Method + FICA + simplified state-tax estimate (no state-specific tables, SDI, or local taxes — see methodology link). |
+
+| Resource | Purpose |
+|---|---|
+| `dc://disclaimers/ymyl` | Canonical YMYL disclaimer string returned in every tool response. |
+
+Every tool response carries the `ToolResult<T>` envelope:
+
+```jsonc
+{
+  "result": { /* tool-specific structured payload */ },
+  "disclaimer": "Estimates only — for educational purposes...",
+  "methodology": {
+    "url": "https://www.digitalcalculator.info/mortgage-calculator/",
+    "version": "2026-05-09"
+  },
+  "calculatedAt": "2026-05-09T18:32:11.123Z",
+  "engineVersion": "0.1.0"
+}
+```
+
+Failures funnel through the `ToolError` shape (never thrown to the transport):
+
+```jsonc
+{
+  "error": {
+    "code": "INPUT_VALIDATION",
+    "message": "Number must be greater than or equal to 0",
+    "field": "principal",
+    "retriable": false
+  }
+}
+```
+
+Code namespaces: `INPUT_VALIDATION`, `BUSINESS_RULE`, `INTERNAL`, `RATE_LIMIT` (only `RATE_LIMIT` is retriable).
+
+---
+
+## Local install + test
+
+```bash
+cd packages/mcp
+npm install
+npm test       # run parity + envelope tests
+npm run build  # compile TypeScript to dist/
+npm start      # boot MCP server over stdio
+```
+
+Vitest runs `test/parity/*.test.ts` (per-tool parity vs site source) and `test/envelope.test.ts` (envelope contract). Parity tests must pass before any engine change is shipped.
+
+---
+
+## Connecting from a local MCP client
+
+After `npm run build`, point your MCP-compatible client at `node /path/to/packages/mcp/dist/index.js` over stdio. Example Claude Desktop config snippet:
+
+```jsonc
+{
+  "mcpServers": {
+    "digitalcalculator": {
+      "command": "node",
+      "args": ["/absolute/path/to/packages/mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+The server emits a single startup line on stderr and then speaks JSON-RPC over stdio per the MCP spec.
+
+---
+
+## Tool input/output sketches
+
+### `dc.calculator.401k.projection`
+
+```jsonc
+// Input
+{
+  "currentBalance": 25000,
+  "annualSalary": 80000,
+  "contributionPercent": 6,           // % of salary
+  "employerMatchPercent": 50,         // 50% match...
+  "employerMatchLimitPercent": 6,     // ...up to 6% of salary
+  "annualSalaryGrowthPercent": 3,     // 3%/yr; 0 mirrors site engine
+  "annualReturnPercent": 7,
+  "currentAge": 35,
+  "retirementAge": 65,
+  "catchUpEnabled": true              // optional, default true
+}
+
+// Result payload
+{
+  "futureBalance": 873421.55,
+  "totalContributions": 228450.12,
+  "employerContribTotal": 114225.06,
+  "growthEarned": 530746.37,
+  "yearByYear": [
+    { "year": 1, "age": 36, "employeeContribution": 4944.00,
+      "employerMatch": 2472.00, "growth": 1750.00,
+      "endingBalance": 34166.00 }
+    /* ...30 rows */
+  ]
+}
+```
+
+### `dc.calculator.socialSecurity.estimate`
+
+```jsonc
+// Input
+{
+  "birthYear": 1965,
+  "currentEarnings": 80000,
+  "claimAge": 67,                     // 62..70
+  "yearsWorked": 35,                  // optional, default 35
+  "lifeExpectancy": 85                // optional, default 85
+}
+
+// Result payload
+{
+  "monthlyBenefitAtFRA": 2104.50,
+  "adjustedMonthlyBenefit": 2104.50,
+  "lifetimeBenefitProjection": 454572,
+  "fraAge": 67.0,
+  "eligibilityYear": 2027,
+  "bendPointsEstimated": true
+}
+```
+
+For an authoritative estimate based on actual 35-year earnings history,
+direct callers to <https://www.ssa.gov/myaccount/>.
+
+### `dc.calculator.paycheck.netPay`
+
+```jsonc
+// Input
+{
+  "grossAnnualSalary": 80000,
+  "payFrequency": "biweekly",         // weekly | biweekly | semimonthly | monthly | quarterly | annual
+  "federalFilingStatus": "single",    // single | married | marriedSeparate | headOfHousehold
+  "state": "CA",
+  "dependents": 0,
+  "preTaxDeductionsAnnual": 4800,
+  "postTaxDeductionsAnnual": 0
+}
+
+// Result payload
+{
+  "grossPerPaycheck": 3076.92,
+  "federalTax": 320.45,
+  "ficaTax": 215.61,
+  "stateTax": 116.91,
+  "netPay": 2240.43,
+  "payPeriodsPerYear": 26,
+  "federalTaxAnnual": 8331.70,
+  "ficaTaxAnnual": 5605.86,
+  "stateTaxAnnual": 3039.66,
+  "netPayAnnual": 58282.78,
+  "noStateIncomeTax": false
+}
+```
+
+> v0.2.0 limitation: state withholding is `$0` for the 9 no-income-tax states
+> (AK, FL, NV, NH, SD, TN, TX, WA, WY) and a flat 5% estimate over taxable
+> income elsewhere. Per-state brackets, SDI, and local taxes are NOT modeled.
+> See the methodology link for the full site calculator.
+
+---
+
+## Architecture
+
+```
+packages/mcp/
+├── package.json                # private:false (v0.1.0)
+├── CHANGELOG.md
+├── tsconfig.json
+├── vitest.config.ts
+├── src/
+│   ├── index.ts                # MCP server entry; tools/list, tools/call, resources/list
+│   ├── envelope.ts             # ToolResult<T>, ToolError types + helpers
+│   ├── disclaimers/ymyl.ts     # Canonical YMYL disclaimer (single source of truth)
+│   ├── shared/bounds.ts        # Numeric bounds shared by Zod schemas + engines
+│   ├── engines/
+│   │   ├── mortgage.ts             # Pure math + ENGINE_VERSION
+│   │   ├── compoundInterest.ts     # Pure math + ENGINE_VERSION
+│   │   ├── retirement401k.ts       # Pure math + ENGINE_VERSION (S136)
+│   │   ├── socialSecurity.ts       # Pure math + ENGINE_VERSION (S136)
+│   │   ├── paycheck.ts             # Pure math + ENGINE_VERSION (S136)
+│   │   └── data/                   # Self-contained data subset (S136)
+│   │       ├── ssa.ts                # SSA bend points + wage base
+│   │       ├── irs2026.ts            # IRS 2026 401(k) limits
+│   │       └── federalTax.ts         # 2026 federal brackets/standard ded/FICA
+│   ├── tools/
+│   │   ├── mortgage.ts
+│   │   ├── compoundInterest.ts
+│   │   ├── retirement401k.ts       # (S136)
+│   │   ├── socialSecurity.ts       # (S136)
+│   │   └── paycheck.ts             # (S136)
+│   └── util/zod-to-json-schema.ts
+└── test/
+    ├── envelope.test.ts        # Envelope contract tests
+    └── parity/
+        ├── mortgage.test.ts            # parity + envelope checks
+        ├── compoundInterest.test.ts    # parity + envelope checks
+        ├── retirement401k.test.ts      # 5 parity + envelope checks (S136)
+        ├── socialSecurity.test.ts      # 5 parity + envelope checks (S136)
+        └── paycheck.test.ts            # 5 parity + envelope checks (S136)
+```
+
+Engines are pure synchronous TypeScript ports of the corresponding browser-side calculator JS at `site/src/pages/<calculator>/<calculator>.js` (mortgage, compound-interest, 401k) and `site/src/utils/<x>-engine.js` (Social Security, paycheck). The site files are not imported directly (they mix DOM bindings with math, and npm consumers cannot reach `site/src/`); parity tests guard that the lift remains numerically identical. Where the engines depend on regulatory data (IRS limits, SSA bend points, federal tax brackets), a curated subset is mirrored in `src/engines/data/` and updated in lockstep with the site source.
+
+---
+
+## Versioning
+
+- **`@markcolabs/mcp` SemVer**: package version. New tool = minor; renamed tool = major.
+- **Per-engine `ENGINE_VERSION`**: independent SemVer per engine module. Bumps when math changes.
+- **`methodology.version`**: ISO date of the methodology document's `last-modified` field (per ADR-0035).
+
+`engineVersion` and `methodology.version` are **independent** — callers should not assume they move in lockstep.
+
+---
+
+## What's next (post-S136)
+
+1. Methodology resources `dc://methodologies/<calculator>` populated from the
+   `.md` companions (ADR-0033).
+2. The `plan-retirement` prompt template (O5-KR2).
+3. Per-state withholding tables for the paycheck tool (replace v0.2.0's flat
+   5% estimate with bracket-accurate state math).
+
+---
+
+## References
+
+- ADR-0039 — MCP Tool Contract & Calc-Engine Lift
+- ADR-0033 — Markdown Companion Strategy (powers `methodology.url`)
+- ADR-0035 — JSON-LD `dateModified` Propagation (powers `methodology.version`)
+- ADR-0038 — Centralized Shared-Data Architecture (regulatory constants source)
+- P12 OKR O5 — AI-Native Distribution
+
+---
+
+## License
+
+MIT. Markcolabs LLC.

package/dist/disclaimers/ymyl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical YMYL disclaimer — single source of truth.
+ *
+ * Per ADR-0039 § 3 and § Implementation Notes / "YMYL disclaimer canonicalization":
+ * - Every ToolResult.disclaimer field embeds this exact string.
+ * - The same string is exposed as the `dc://disclaimers/ymyl` MCP resource.
+ * - Tools do NOT author their own disclaimers. All MCP responses use this constant.
+ *
+ * Authoring is owned by Content. Updates here propagate to every tool response.
+ */
+export declare const YMYL_DISCLAIMER: string;
+/**
+ * MCP resource URI under which the disclaimer is exposed (O5-KR2).
+ */
+export declare const YMYL_DISCLAIMER_URI = "dc://disclaimers/ymyl";
+//# sourceMappingURL=ymyl.d.ts.map

package/dist/disclaimers/ymyl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ymyl.d.ts","sourceRoot":"","sources":["../../src/disclaimers/ymyl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,QAKqE,CAAC;AAElG;;GAEG;AACH,eAAO,MAAM,mBAAmB,0BAA0B,CAAC"}

package/dist/disclaimers/ymyl.js

@@ -0,0 +1,20 @@
+/**
+ * Canonical YMYL disclaimer — single source of truth.
+ *
+ * Per ADR-0039 § 3 and § Implementation Notes / "YMYL disclaimer canonicalization":
+ * - Every ToolResult.disclaimer field embeds this exact string.
+ * - The same string is exposed as the `dc://disclaimers/ymyl` MCP resource.
+ * - Tools do NOT author their own disclaimers. All MCP responses use this constant.
+ *
+ * Authoring is owned by Content. Updates here propagate to every tool response.
+ */
+export const YMYL_DISCLAIMER = "Estimates only — for educational purposes. Results are computed in USD using deterministic " +
+    "formulas and the inputs you provided. They do not constitute financial, tax, legal, or " +
+    "investment advice. Actual rates, fees, taxes, and outcomes vary by lender, jurisdiction, " +
+    "and personal circumstances. Verify with a licensed professional before making financial " +
+    "decisions. Source: digitalcalculator.info — see methodology link for formula and assumptions.";
+/**
+ * MCP resource URI under which the disclaimer is exposed (O5-KR2).
+ */
+export const YMYL_DISCLAIMER_URI = "dc://disclaimers/ymyl";
+//# sourceMappingURL=ymyl.js.map

package/dist/disclaimers/ymyl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ymyl.js","sourceRoot":"","sources":["../../src/disclaimers/ymyl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,6FAA6F;IAC7F,yFAAyF;IACzF,2FAA2F;IAC3F,0FAA0F;IAC1F,+FAA+F,CAAC;AAElG;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAuB,CAAC"}

package/dist/engines/compoundInterest.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Compound-interest engine — lifted from
+ * site/src/pages/compound-interest-calculator/compound-interest-calculator.js
+ * (function `calculateFutureValue`).
+ *
+ * Per ADR-0039 § 5: pure synchronous functions, ENGINE_VERSION constant,
+ * parity test against the site source as the gate.
+ *
+ * Math reference:
+ *   FV_principal = P * (1 + r/n)^(nt)
+ *   FV_contributions = PMT_per_period * [((1 + r/n)^(nt) - 1) / (r/n)]   (if r > 0)
+ *   FV_contributions = PMT_per_period * (n * t)                           (if r == 0)
+ *   where:
+ *     P  = initial principal
+ *     PMT_per_period = monthlyContribution * (12 / n)
+ *     r  = annual rate as decimal (e.g., 0.07 for 7%)
+ *     n  = compounding periods per year
+ *     t  = years
+ *
+ * The engine accepts the rate as a percent and compounding as a label
+ * (per ADR-0039 § 2 Percent-suffix convention + sprint prompt enum).
+ */
+import { type CompoundingFrequencyLabel } from "../shared/bounds.js";
+/**
+ * SemVer of the compound-interest engine math. Bumps when math changes OR when
+ * the package's overall surface area changes (S136 batch bump).
+ * - 0.1.0: initial v1 lift from compound-interest-calculator.js (Sprint 135 Item 5).
+ * - 0.2.0: minor batch bump on S136 (no math change here; package surface grew
+ *   from 2 → 5 engines).
+ */
+export declare const ENGINE_VERSION = "0.2.0";
+/**
+ * Inputs to the compound-interest future-value engine.
+ *
+ * Per ADR-0039 § 2:
+ * - Monetary fields are bare USD numbers.
+ * - Percentage fields use whole-number-percent units (e.g., 7 for 7%).
+ * - Optional fields default to 0 inside the engine.
+ */
+export interface CompoundInterestFutureValueInput {
+    /** Initial principal in USD. */
+    principal: number;
+    /** Annual interest rate as whole-number percent (e.g., 7 for 7%). */
+    annualRatePercent: number;
+    /** Investment period in years. May be 0 (returns principal alone). */
+    years: number;
+    /** Compounding frequency label. */
+    compoundingFrequency: CompoundingFrequencyLabel;
+    /** Monthly contribution in USD. Optional — defaults to 0. */
+    monthlyContribution?: number;
+}
+/**
+ * Result payload (what goes inside ToolResult.result).
+ */
+export interface CompoundInterestFutureValueResult {
+    /** Future value (principal + contributions + interest), in USD. */
+    futureValue: number;
+    /** Total contributed (principal + sum of monthly contributions over the period), in USD. */
+    totalContributions: number;
+    /** Interest earned (futureValue - totalContributions), in USD. */
+    interestEarned: number;
+}
+/**
+ * Compute the future value of a compound-interest investment with optional
+ * regular monthly contributions.
+ *
+ * 1-to-1 port of site/src/pages/compound-interest-calculator/compound-interest-calculator.js
+ * function `calculateFutureValue`. Site uses `annualRate` as decimal; this engine
+ * accepts whole-number percent and converts internally so the contract is
+ * Percent-suffix consistent (ADR-0039).
+ */
+export declare function futureValue(input: CompoundInterestFutureValueInput): CompoundInterestFutureValueResult;
+//# sourceMappingURL=compoundInterest.d.ts.map

package/dist/engines/compoundInterest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compoundInterest.d.ts","sourceRoot":"","sources":["../../src/engines/compoundInterest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,WAAW,gCAAgC;IAC/C,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,oBAAoB,EAAE,yBAAyB,CAAC;IAChD,6DAA6D;IAC7D,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,iCAAiC;IAChD,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,gCAAgC,GACtC,iCAAiC,CAyCnC"}

package/dist/engines/compoundInterest.js

@@ -0,0 +1,72 @@
+/**
+ * Compound-interest engine — lifted from
+ * site/src/pages/compound-interest-calculator/compound-interest-calculator.js
+ * (function `calculateFutureValue`).
+ *
+ * Per ADR-0039 § 5: pure synchronous functions, ENGINE_VERSION constant,
+ * parity test against the site source as the gate.
+ *
+ * Math reference:
+ *   FV_principal = P * (1 + r/n)^(nt)
+ *   FV_contributions = PMT_per_period * [((1 + r/n)^(nt) - 1) / (r/n)]   (if r > 0)
+ *   FV_contributions = PMT_per_period * (n * t)                           (if r == 0)
+ *   where:
+ *     P  = initial principal
+ *     PMT_per_period = monthlyContribution * (12 / n)
+ *     r  = annual rate as decimal (e.g., 0.07 for 7%)
+ *     n  = compounding periods per year
+ *     t  = years
+ *
+ * The engine accepts the rate as a percent and compounding as a label
+ * (per ADR-0039 § 2 Percent-suffix convention + sprint prompt enum).
+ */
+import { COMPOUNDING_FREQUENCY, } from "../shared/bounds.js";
+/**
+ * SemVer of the compound-interest engine math. Bumps when math changes OR when
+ * the package's overall surface area changes (S136 batch bump).
+ * - 0.1.0: initial v1 lift from compound-interest-calculator.js (Sprint 135 Item 5).
+ * - 0.2.0: minor batch bump on S136 (no math change here; package surface grew
+ *   from 2 → 5 engines).
+ */
+export const ENGINE_VERSION = "0.2.0";
+/**
+ * Compute the future value of a compound-interest investment with optional
+ * regular monthly contributions.
+ *
+ * 1-to-1 port of site/src/pages/compound-interest-calculator/compound-interest-calculator.js
+ * function `calculateFutureValue`. Site uses `annualRate` as decimal; this engine
+ * accepts whole-number percent and converts internally so the contract is
+ * Percent-suffix consistent (ADR-0039).
+ */
+export function futureValue(input) {
+    const { principal, annualRatePercent, years, compoundingFrequency, monthlyContribution = 0, } = input;
+    // Percent → decimal at the engine boundary.
+    const r = annualRatePercent / 100;
+    const n = COMPOUNDING_FREQUENCY[compoundingFrequency];
+    const t = years;
+    const periods = n * t;
+    const periodicRate = r / n;
+    // FV of principal.
+    const fvPrincipal = principal * Math.pow(1 + periodicRate, periods);
+    // FV of regular contributions (annuity-due-like, contributions split per period).
+    const contributionPerPeriod = monthlyContribution * (12 / n);
+    let fvContributions = 0;
+    if (periodicRate > 0 && contributionPerPeriod > 0) {
+        fvContributions =
+            contributionPerPeriod *
+                ((Math.pow(1 + periodicRate, periods) - 1) / periodicRate);
+    }
+    else if (contributionPerPeriod > 0) {
+        // 0% rate: contributions just sum.
+        fvContributions = contributionPerPeriod * periods;
+    }
+    const futureValueTotal = fvPrincipal + fvContributions;
+    const totalContributions = principal + monthlyContribution * 12 * t;
+    const interestEarned = futureValueTotal - totalContributions;
+    return {
+        futureValue: futureValueTotal,
+        totalContributions,
+        interestEarned,
+    };
+}
+//# sourceMappingURL=compoundInterest.js.map

package/dist/engines/compoundInterest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compoundInterest.js","sourceRoot":"","sources":["../../src/engines/compoundInterest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,qBAAqB,GAEtB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAmCtC;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,KAAuC;IAEvC,MAAM,EACJ,SAAS,EACT,iBAAiB,EACjB,KAAK,EACL,oBAAoB,EACpB,mBAAmB,GAAG,CAAC,GACxB,GAAG,KAAK,CAAC;IAEV,4CAA4C;IAC5C,MAAM,CAAC,GAAG,iBAAiB,GAAG,GAAG,CAAC;IAClC,MAAM,CAAC,GAAG,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;IACtD,MAAM,CAAC,GAAG,KAAK,CAAC;IAEhB,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;IACtB,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,CAAC;IAE3B,mBAAmB;IACnB,MAAM,WAAW,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,YAAY,EAAE,OAAO,CAAC,CAAC;IAEpE,kFAAkF;IAClF,MAAM,qBAAqB,GAAG,mBAAmB,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7D,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,YAAY,GAAG,CAAC,IAAI,qBAAqB,GAAG,CAAC,EAAE,CAAC;QAClD,eAAe;YACb,qBAAqB;gBACrB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC;IAC/D,CAAC;SAAM,IAAI,qBAAqB,GAAG,CAAC,EAAE,CAAC;QACrC,mCAAmC;QACnC,eAAe,GAAG,qBAAqB,GAAG,OAAO,CAAC;IACpD,CAAC;IAED,MAAM,gBAAgB,GAAG,WAAW,GAAG,eAAe,CAAC;IACvD,MAAM,kBAAkB,GAAG,SAAS,GAAG,mBAAmB,GAAG,EAAE,GAAG,CAAC,CAAC;IACpE,MAAM,cAAc,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;IAE7D,OAAO;QACL,WAAW,EAAE,gBAAgB;QAC7B,kBAAkB;QAClB,cAAc;KACf,CAAC;AACJ,CAAC"}

package/dist/engines/data/federalTax.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Self-contained 2026 federal tax data subset for the @markcolabs/mcp
+ * package's paycheck engine.
+ *
+ * Mirrored from site/src/data/annual-limits.js. See engines/data/ssa.ts for the
+ * full rationale on the mirror pattern (npm consumers cannot reach site/src/).
+ *
+ * Filing status keys mirror the paycheck engine's camelCase convention:
+ *   "single" | "married" | "marriedSeparate" | "headOfHousehold"
+ *
+ * Source of truth: IRS Rev. Proc. 2025-32 (2026 inflation adjustments).
+ * Last verified: 2026-05-09.
+ */
+import { SS_WAGE_BASE } from "./ssa.js";
+export type FilingStatus = "single" | "married" | "marriedSeparate" | "headOfHousehold";
+/** FICA statutory rates (unchanged since 1990 / ACA 2013). */
+export declare const FICA_RATES: {
+    readonly socialSecurityRate: 0.062;
+    readonly medicareRate: 0.0145;
+    readonly additionalMedicareRate: 0.009;
+};
+/** Additional Medicare Tax 0.9% kicks in above these wage thresholds (filing-status keyed). */
+export declare const ADDITIONAL_MEDICARE_THRESHOLDS_2026: Record<FilingStatus, number>;
+/** 2026 standard deductions (IRS Rev. Proc. 2025-32). */
+export declare const STANDARD_DEDUCTIONS_2026: Record<FilingStatus, number>;
+/** Tax bracket entry. `max: null` indicates the top open-ended bracket. */
+export interface TaxBracket {
+    min: number;
+    max: number | null;
+    rate: number;
+    /** Cumulative tax at this bracket's floor (Percentage Method). */
+    baseTax: number;
+}
+/**
+ * 2026 federal tax brackets (IRS Rev. Proc. 2025-32; verified AL-2026-001 S134).
+ * Filing-status keyed; values match site/src/data/annual-limits.js TAX_BRACKETS[2026].
+ */
+export declare const FEDERAL_TAX_BRACKETS_2026: Record<FilingStatus, TaxBracket[]>;
+/** Pay periods per year. Matches site/src/utils/paycheck-tax-engine.js PAY_PERIODS. */
+export declare const PAY_PERIODS_PER_YEAR: Record<"weekly" | "biweekly" | "semimonthly" | "monthly" | "quarterly" | "annual", number>;
+export type PayFrequencyLabel = keyof typeof PAY_PERIODS_PER_YEAR;
+/** US states with no income tax (paycheck engine NO_TAX_STATES). */
+export declare const NO_TAX_STATES: readonly ["AK", "FL", "NV", "NH", "SD", "TN", "TX", "WA", "WY"];
+export type NoTaxStateCode = (typeof NO_TAX_STATES)[number];
+/** Re-export SS wage base for paycheck engine (FICA SS cap). */
+export { SS_WAGE_BASE };
+//# sourceMappingURL=federalTax.d.ts.map

package/dist/engines/data/federalTax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federalTax.d.ts","sourceRoot":"","sources":["../../../src/engines/data/federalTax.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAExF,8DAA8D;AAC9D,eAAO,MAAM,UAAU;;;;CAIb,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,mCAAmC,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAK5E,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAKjE,CAAC;AAEF,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAgBD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,YAAY,EAAE,UAAU,EAAE,CAqCxE,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CACvC,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,EAC1E,MAAM,CAQP,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAElE,oEAAoE;AACpE,eAAO,MAAM,aAAa,iEAUhB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,gEAAgE;AAChE,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/engines/data/federalTax.js

@@ -0,0 +1,111 @@
+/**
+ * Self-contained 2026 federal tax data subset for the @markcolabs/mcp
+ * package's paycheck engine.
+ *
+ * Mirrored from site/src/data/annual-limits.js. See engines/data/ssa.ts for the
+ * full rationale on the mirror pattern (npm consumers cannot reach site/src/).
+ *
+ * Filing status keys mirror the paycheck engine's camelCase convention:
+ *   "single" | "married" | "marriedSeparate" | "headOfHousehold"
+ *
+ * Source of truth: IRS Rev. Proc. 2025-32 (2026 inflation adjustments).
+ * Last verified: 2026-05-09.
+ */
+import { SS_WAGE_BASE } from "./ssa.js";
+/** FICA statutory rates (unchanged since 1990 / ACA 2013). */
+export const FICA_RATES = {
+    socialSecurityRate: 0.062,
+    medicareRate: 0.0145,
+    additionalMedicareRate: 0.009,
+};
+/** Additional Medicare Tax 0.9% kicks in above these wage thresholds (filing-status keyed). */
+export const ADDITIONAL_MEDICARE_THRESHOLDS_2026 = {
+    single: 200_000,
+    married: 250_000,
+    marriedSeparate: 125_000,
+    headOfHousehold: 200_000,
+};
+/** 2026 standard deductions (IRS Rev. Proc. 2025-32). */
+export const STANDARD_DEDUCTIONS_2026 = {
+    single: 15_750,
+    married: 31_500,
+    marriedSeparate: 15_750,
+    headOfHousehold: 23_625,
+};
+/** Build cumulative `baseTax` for each bracket (used by the Percentage Method). */
+function withBaseTax(brackets) {
+    let cumulative = 0;
+    return brackets.map((b) => {
+        const baseTax = cumulative;
+        if (b.max !== null) {
+            cumulative += (b.max - b.min) * b.rate;
+        }
+        return { min: b.min, max: b.max, rate: b.rate, baseTax };
+    });
+}
+/**
+ * 2026 federal tax brackets (IRS Rev. Proc. 2025-32; verified AL-2026-001 S134).
+ * Filing-status keyed; values match site/src/data/annual-limits.js TAX_BRACKETS[2026].
+ */
+export const FEDERAL_TAX_BRACKETS_2026 = {
+    single: withBaseTax([
+        { min: 0, max: 12_400, rate: 0.10 },
+        { min: 12_400, max: 50_400, rate: 0.12 },
+        { min: 50_400, max: 105_700, rate: 0.22 },
+        { min: 105_700, max: 201_775, rate: 0.24 },
+        { min: 201_775, max: 256_225, rate: 0.32 },
+        { min: 256_225, max: 640_600, rate: 0.35 },
+        { min: 640_600, max: null, rate: 0.37 },
+    ]),
+    married: withBaseTax([
+        { min: 0, max: 24_800, rate: 0.10 },
+        { min: 24_800, max: 100_800, rate: 0.12 },
+        { min: 100_800, max: 211_400, rate: 0.22 },
+        { min: 211_400, max: 403_550, rate: 0.24 },
+        { min: 403_550, max: 512_450, rate: 0.32 },
+        { min: 512_450, max: 768_700, rate: 0.35 },
+        { min: 768_700, max: null, rate: 0.37 },
+    ]),
+    marriedSeparate: withBaseTax([
+        { min: 0, max: 12_400, rate: 0.10 },
+        { min: 12_400, max: 50_400, rate: 0.12 },
+        { min: 50_400, max: 105_700, rate: 0.22 },
+        { min: 105_700, max: 201_775, rate: 0.24 },
+        { min: 201_775, max: 256_225, rate: 0.32 },
+        { min: 256_225, max: 384_350, rate: 0.35 },
+        { min: 384_350, max: null, rate: 0.37 },
+    ]),
+    headOfHousehold: withBaseTax([
+        { min: 0, max: 17_700, rate: 0.10 },
+        { min: 17_700, max: 67_450, rate: 0.12 },
+        { min: 67_450, max: 105_700, rate: 0.22 },
+        { min: 105_700, max: 201_775, rate: 0.24 },
+        { min: 201_775, max: 256_200, rate: 0.32 },
+        { min: 256_200, max: 640_600, rate: 0.35 },
+        { min: 640_600, max: null, rate: 0.37 },
+    ]),
+};
+/** Pay periods per year. Matches site/src/utils/paycheck-tax-engine.js PAY_PERIODS. */
+export const PAY_PERIODS_PER_YEAR = {
+    weekly: 52,
+    biweekly: 26,
+    semimonthly: 24,
+    monthly: 12,
+    quarterly: 4,
+    annual: 1,
+};
+/** US states with no income tax (paycheck engine NO_TAX_STATES). */
+export const NO_TAX_STATES = [
+    "AK",
+    "FL",
+    "NV",
+    "NH",
+    "SD",
+    "TN",
+    "TX",
+    "WA",
+    "WY",
+];
+/** Re-export SS wage base for paycheck engine (FICA SS cap). */
+export { SS_WAGE_BASE };
+//# sourceMappingURL=federalTax.js.map

package/dist/engines/data/federalTax.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federalTax.js","sourceRoot":"","sources":["../../../src/engines/data/federalTax.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAIxC,8DAA8D;AAC9D,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,kBAAkB,EAAE,KAAK;IACzB,YAAY,EAAE,MAAM;IACpB,sBAAsB,EAAE,KAAK;CACrB,CAAC;AAEX,+FAA+F;AAC/F,MAAM,CAAC,MAAM,mCAAmC,GAAiC;IAC/E,MAAM,EAAE,OAAO;IACf,OAAO,EAAE,OAAO;IAChB,eAAe,EAAE,OAAO;IACxB,eAAe,EAAE,OAAO;CACzB,CAAC;AAEF,yDAAyD;AACzD,MAAM,CAAC,MAAM,wBAAwB,GAAiC;IACpE,MAAM,EAAE,MAAM;IACd,OAAO,EAAE,MAAM;IACf,eAAe,EAAE,MAAM;IACvB,eAAe,EAAE,MAAM;CACxB,CAAC;AAWF,mFAAmF;AACnF,SAAS,WAAW,CAClB,QAA0E;IAE1E,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACxB,MAAM,OAAO,GAAG,UAAU,CAAC;QAC3B,IAAI,CAAC,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;YACnB,UAAU,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;QACzC,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAuC;IAC3E,MAAM,EAAE,WAAW,CAAC;QAClB,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE;QACnC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE;QACxC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QACzC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;KACxC,CAAC;IACF,OAAO,EAAE,WAAW,CAAC;QACnB,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE;QACnC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QACzC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;KACxC,CAAC;IACF,eAAe,EAAE,WAAW,CAAC;QAC3B,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE;QACnC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE;QACxC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QACzC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;KACxC,CAAC;IACF,eAAe,EAAE,WAAW,CAAC;QAC3B,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE;QACnC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE;QACxC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QACzC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;QAC1C,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;KACxC,CAAC;CACH,CAAC;AAEF,uFAAuF;AACvF,MAAM,CAAC,MAAM,oBAAoB,GAG7B;IACF,MAAM,EAAE,EAAE;IACV,QAAQ,EAAE,EAAE;IACZ,WAAW,EAAE,EAAE;IACf,OAAO,EAAE,EAAE;IACX,SAAS,EAAE,CAAC;IACZ,MAAM,EAAE,CAAC;CACV,CAAC;AAIF,oEAAoE;AACpE,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;CACI,CAAC;AAIX,gEAAgE;AAChE,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/engines/data/irs2026.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Self-contained 2026 IRS retirement-plan limits subset for the MCP package's
+ * 401(k) projection engine.
+ *
+ * Mirrored from site/src/data/annual-limits.js LIMITS_401K_2026. See
+ * engines/data/ssa.ts for full rationale on the mirror pattern.
+ *
+ * Source: IRS Notice 2025-67 (2026 retirement-plan limits) +
+ *         SECURE 2.0 Act §109 (super catch-up provision for ages 60-63).
+ * Last verified: 2026-05-09.
+ */
+export declare const LIMITS_401K_2026: {
+    /** Base employee deferral limit. */
+    readonly base: 24500;
+    /** Regular catch-up amount for ages 50-59 or 64+. */
+    readonly catchUp: 8000;
+    /** Super catch-up amount for ages 60-63 (SECURE 2.0). */
+    readonly superCatchUp: 11250;
+    /** Total deferral limit with regular catch-up. */
+    readonly totalWithCatchUp: 32500;
+    /** Total deferral limit with super catch-up. */
+    readonly totalWithSuperCatchUp: 35750;
+    /** Minimum age for any catch-up. */
+    readonly catchUpAge: 50;
+    /** Start of super catch-up window. */
+    readonly superCatchUpAgeStart: 60;
+    /** End of super catch-up window. */
+    readonly superCatchUpAgeEnd: 63;
+};
+//# sourceMappingURL=irs2026.d.ts.map