@markcolabs/mcp 0.2.0 → 0.3.0

package/dist/engines/rmd.js

@@ -0,0 +1,109 @@
+/**
+ * RMD (Required Minimum Distribution) engine — lifted from
+ * site/src/utils/rmd-engine.js (functions `calculateRMD`,
+ * `getDistributionPeriod`, `getRMDStartAge`).
+ *
+ * Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
+ * parity test against the site source as the gate.
+ *
+ * Scope (S141 Wave 1B Item #3): SINGLE-YEAR RMD distribution-amount
+ * calculation only. The site calculator's multi-year projection
+ * (`generateRMDProjection`) and pre-RMD age-projection path are OUT of
+ * scope for v1 — callers needing year-by-year projections should call the
+ * tool repeatedly with the projected balance for each year.
+ *
+ * Table coverage: ONLY the Uniform Lifetime Table (Pub. 590-B Table III,
+ * post-2022 version) is implemented, mirroring the site source which uses
+ * `UNIFORM_LIFETIME_TABLE` exclusively. The Joint Life Expectancy Table
+ * (Table II, applied when spouse is sole beneficiary AND 10+ years younger)
+ * is NOT in the site engine and is therefore NOT in this tool — adding it
+ * here would create a parity gap with the site calculator. The `tableUsed`
+ * field is always `"uniform-lifetime"` for v1; the union type leaves room
+ * for `"joint-life-expectancy"` in a future minor bump when the site adds it.
+ *
+ * Math reference (per IRC §401(a)(9) + Pub. 590-B):
+ *   distributionPeriod = UNIFORM_LIFETIME_TABLE[ownerAge]
+ *   rmdAmount          = accountBalance / distributionPeriod
+ *
+ * Missed-RMD penalty (SECURE 2.0 §302, effective 2023+):
+ *   penaltyIfMissed    = rmdAmount × 0.25                (default 25% excise tax)
+ *   reduced to 10% if corrected within IRS correction window (typically 2 years)
+ *   (down from 50% pre-SECURE-2.0)
+ *
+ * Source: IRS Publication 590-B (Uniform Lifetime Table III, post-2022) +
+ *         SECURE 2.0 Act §107 (RMD age tiers) + §302 (25% excise tax).
+ * Last verified: 2026-05-27.
+ */
+import { UNIFORM_LIFETIME_TABLE_2026, UNIFORM_LIFETIME_MIN_AGE, UNIFORM_LIFETIME_MAX_AGE, RMD_MISSED_EXCISE_RATE, RMD_TABLE_SOURCE, } from "./data/rmd2026.js";
+/**
+ * SemVer of the RMD engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041
+ * Position #4a): major bump = math change; minor = additive output; patch =
+ * numerical correction. NOT bumped for cosmetic refactors.
+ * - 1.0.0: initial v1 lift from rmd-engine.js (S141 Wave 1B).
+ */
+export const ENGINE_VERSION = "1.0.0";
+/**
+ * Compute the required minimum distribution for the given inputs.
+ *
+ * 1-to-1 logic port of site/src/utils/rmd-engine.js `calculateRMD` +
+ * `getDistributionPeriod` (single-year path; multi-year projection out of
+ * scope). The site engine clamps lookups to [72, 120]; we additionally
+ * require ownerAge ≥ 73 (SECURE 2.0 floor for the 1951-1959 cohort, the
+ * common case in 2026) at the tool boundary via RMD_BOUNDS.
+ *
+ * Throws on undefined-period lookup — should be unreachable because bounds
+ * validation in the tool wrapper rejects out-of-range ages first.
+ */
+export function distributionAmount(input) {
+    const { accountBalance, ownerAge } = input;
+    // Edge: zero balance → zero RMD. Mirror the site's balance ≤ 0 short-circuit
+    // but still report the (clamped) distribution period for caller transparency.
+    if (accountBalance <= 0) {
+        const factor = lookupDistributionPeriod(ownerAge);
+        return {
+            rmdAmount: 0,
+            distributionPeriod: factor,
+            lifeExpectancyFactor: factor,
+            tableUsed: "uniform-lifetime",
+            penaltyIfMissed: 0,
+            meta: {
+                tableYear: 2026,
+                source: RMD_TABLE_SOURCE,
+            },
+        };
+    }
+    const distributionPeriod = lookupDistributionPeriod(ownerAge);
+    // Site rounds to cents (Math.round * 100 / 100). Keep the same rounding for
+    // parity correctness in the test file.
+    const rmdRaw = accountBalance / distributionPeriod;
+    const rmdAmount = Math.round(rmdRaw * 100) / 100;
+    const penaltyIfMissed = Math.round(rmdAmount * RMD_MISSED_EXCISE_RATE * 100) / 100;
+    return {
+        rmdAmount,
+        distributionPeriod,
+        lifeExpectancyFactor: distributionPeriod,
+        tableUsed: "uniform-lifetime",
+        penaltyIfMissed,
+        meta: {
+            tableYear: 2026,
+            source: RMD_TABLE_SOURCE,
+        },
+    };
+}
+/**
+ * Look up the distribution period from the Uniform Lifetime Table.
+ * Mirrors site `getDistributionPeriod`: clamps to [72, 120] and floors
+ * fractional ages.
+ */
+function lookupDistributionPeriod(age) {
+    const lookupAge = Math.min(Math.max(Math.floor(age), UNIFORM_LIFETIME_MIN_AGE), UNIFORM_LIFETIME_MAX_AGE);
+    const factor = UNIFORM_LIFETIME_TABLE_2026[lookupAge];
+    if (factor === undefined) {
+        // Defensive: bounds validation should prevent this. If we ever hit it,
+        // throwing surfaces it as INTERNAL via the tool wrapper rather than
+        // silently returning NaN.
+        throw new Error(`RMD: no distribution-period factor for age ${age} (lookupAge=${lookupAge})`);
+    }
+    return factor;
+}
+//# sourceMappingURL=rmd.js.map

package/dist/engines/rmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rmd.js","sourceRoot":"","sources":["../../src/engines/rmd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAuDtC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAiC;IAEjC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAE3C,6EAA6E;IAC7E,8EAA8E;IAC9E,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;QAClD,OAAO;YACL,SAAS,EAAE,CAAC;YACZ,kBAAkB,EAAE,MAAM;YAC1B,oBAAoB,EAAE,MAAM;YAC5B,SAAS,EAAE,kBAAkB;YAC7B,eAAe,EAAE,CAAC;YAClB,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI;gBACf,MAAM,EAAE,gBAAgB;aACzB;SACF,CAAC;IACJ,CAAC;IAED,MAAM,kBAAkB,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAE9D,4EAA4E;IAC5E,uCAAuC;IACvC,MAAM,MAAM,GAAG,cAAc,GAAG,kBAAkB,CAAC;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;IAEjD,MAAM,eAAe,GACnB,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,sBAAsB,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;IAE7D,OAAO;QACL,SAAS;QACT,kBAAkB;QAClB,oBAAoB,EAAE,kBAAkB;QACxC,SAAS,EAAE,kBAAkB;QAC7B,eAAe;QACf,IAAI,EAAE;YACJ,SAAS,EAAE,IAAI;YACf,MAAM,EAAE,gBAAgB;SACzB;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,wBAAwB,CAAC,GAAW;IAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CACxB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,wBAAwB,CAAC,EACnD,wBAAwB,CACzB,CAAC;IACF,MAAM,MAAM,GAAG,2BAA2B,CAAC,SAAS,CAAC,CAAC;IACtD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,uEAAuE;QACvE,oEAAoE;QACpE,0BAA0B;QAC1B,MAAM,IAAI,KAAK,CACb,8CAA8C,GAAG,eAAe,SAAS,GAAG,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/engines/rothConversion.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Roth Conversion tax-impact engine — lifted from
+ * site/src/pages/roth-conversion-calculator/roth-conversion-calculator.js
+ * (functions in tax-brackets.js + calculateBreakEvenYears) and
+ * site/src/utils/tax-brackets.js (calculateIncrementalTax, getMarginalRate).
+ *
+ * Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
+ * parity test against the source site engine.
+ *
+ * Scope (S141 Wave 1A Item #2, per S141 Risk #2): SINGLE-CONVERSION tax
+ * impact only. Multi-year scenario simulation / optimization is deferred to a
+ * future tool (`dc.calculator.rothConversion.multiYearOptimization`). This
+ * tool answers "if I convert $X today, what's my federal tax owed?" and
+ * "when do I break even on the upfront tax?"
+ *
+ * NOT MODELED (intentional scope limits):
+ * - State tax on the conversion (caller's responsibility; conversion is
+ *   typically taxed by state at ordinary-income rates).
+ * - IRMAA tier impact (the site calculator surfaces this; out of scope for
+ *   the MCP v0.3.0 tool).
+ * - 5-year rule timing for individual contributions (we report whether the
+ *   5-year rule applies based on age < 59.5, but don't model the per-
+ *   conversion clock).
+ *
+ * Math reference:
+ *   For taxable income I and conversion amount C:
+ *     beforeTax    = bracketTax(I, brackets[filingStatus])
+ *     afterTax     = bracketTax(I + C, brackets[filingStatus])
+ *     taxOwed      = afterTax − beforeTax              (incremental)
+ *     marginalRate = top bracket spanned by (I + C)
+ *     effectiveRate = taxOwed / C
+ *
+ *   Break-even years (when conversion tax savings recoup themselves, given
+ *   the user's retirement marginal rate is lower than the conversion
+ *   marginal rate and tax-free Roth growth at real return r):
+ *     If retirementMarginalRate >= conversionMarginalRate → 0
+ *       (already break-even because future bracket ≥ today's)
+ *     Else:
+ *       savingsPerYear ≈ futureBalance × (conversionMarginalRate −
+ *                                          retirementMarginalRate)
+ *       breakEvenYears = log((1 − totalConvRate) / (1 − totalFutureRate))
+ *                        / log(1 + r)
+ *       (where totalConvRate ≈ effectiveRateOnConversion,
+ *              totalFutureRate ≈ retirementMarginalRate)
+ *
+ *   This is the same break-even math the site `calculateBreakEvenYears`
+ *   function uses (we drop the explicit state-tax term; caller-side).
+ *
+ * Source: IRS Rev. Proc. 2025-32 (2026 federal tax brackets).
+ *         Last verified: 2026-05-09.
+ */
+import { type FilingStatus } from "./data/federalTax.js";
+/**
+ * SemVer of the Roth conversion engine. Per ADR-0039 § 5 (reaffirmed in
+ * ADR-0041 Position #4a): major bump = math change; minor = additive output;
+ * patch = numerical correction. NOT bumped for cosmetic refactors.
+ * - 1.0.0: initial v1 lift from roth-conversion-calculator.js + tax-brackets.js
+ *          (S141 Wave 1A).
+ */
+export declare const ENGINE_VERSION = "1.0.0";
+/** Inputs to the Roth conversion tax-impact engine. */
+export interface RothConversionTaxImpactInput {
+    /** Conversion amount (USD). Must be > 0 to compute taxes. */
+    conversionAmount: number;
+    /** User's current age (used for 5-year rule flag). */
+    age: number;
+    /** Federal filing status. */
+    filingStatus: FilingStatus;
+    /** Current federal taxable income (before adding the conversion), USD. */
+    currentTaxableIncome: number;
+    /**
+     * Expected retirement marginal federal tax rate, whole-number percent
+     * (e.g., 12 for 12%). Optional — when omitted, `breakEvenYears` is `null`.
+     */
+    retirementMarginalRatePercent?: number;
+    /**
+     * Expected real (inflation-adjusted) annual return on the converted Roth
+     * balance, whole-number percent. Defaults to 7 (a reasonable real-return
+     * assumption for a diversified portfolio). Used only for break-even math.
+     */
+    expectedReturnPercent?: number;
+}
+/** Result payload returned by the engine. */
+export interface RothConversionTaxImpactResult {
+    /** Incremental federal income tax on the conversion amount, USD. */
+    taxOwed: number;
+    /**
+     * Top marginal federal bracket the conversion pushes the user into,
+     * expressed as a decimal (e.g., 0.32 for 32%).
+     */
+    marginalRateOnConversion: number;
+    /** taxOwed / conversionAmount, as a decimal. 0 if conversionAmount = 0. */
+    effectiveRateOnConversion: number;
+    /**
+     * Whether the Roth 5-year rule clock applies for this conversion:
+     * true if user is under age 59.5 at conversion. (Conversions made when
+     * the account holder is < 59.5 incur a separate 5-year clock for
+     * penalty-free withdrawal of converted principal.)
+     */
+    fiveYearRuleApplies: boolean;
+    /**
+     * Years until tax-free Roth growth offsets the upfront conversion tax,
+     * assuming retirementMarginalRate < conversionMarginalRate. `null` if
+     * `retirementMarginalRatePercent` was not provided. `0` if retirement
+     * rate ≥ conversion rate (already break-even). May be `Infinity` if
+     * mathematically unreachable.
+     */
+    breakEvenYears: number | null;
+    /** Provenance metadata. */
+    meta: {
+        /** IRS tax year these brackets apply to. */
+        tableYear: number;
+        /** Source authority. */
+        source: string;
+    };
+}
+/**
+ * Compute Roth conversion tax impact (single conversion).
+ *
+ * 1-to-1 port of the federal-tax + incremental-tax + marginal-rate +
+ * break-even logic the site uses, with state tax / IRMAA omitted per scope.
+ */
+export declare function taxImpact(input: RothConversionTaxImpactInput): RothConversionTaxImpactResult;
+//# sourceMappingURL=rothConversion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rothConversion.d.ts","sourceRoot":"","sources":["../../src/engines/rothConversion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,uDAAuD;AACvD,MAAM,WAAW,4BAA4B;IAC3C,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,0EAA0E;IAC1E,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,6CAA6C;AAC7C,MAAM,WAAW,6BAA6B;IAC5C,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,wBAAwB,EAAE,MAAM,CAAC;IACjC,2EAA2E;IAC3E,yBAAyB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAC7B;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2BAA2B;IAC3B,IAAI,EAAE;QACJ,4CAA4C;QAC5C,SAAS,EAAE,MAAM,CAAC;QAClB,wBAAwB;QACxB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AA4BD;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,4BAA4B,GAClC,6BAA6B,CAoE/B"}

package/dist/engines/rothConversion.js

@@ -0,0 +1,145 @@
+/**
+ * Roth Conversion tax-impact engine — lifted from
+ * site/src/pages/roth-conversion-calculator/roth-conversion-calculator.js
+ * (functions in tax-brackets.js + calculateBreakEvenYears) and
+ * site/src/utils/tax-brackets.js (calculateIncrementalTax, getMarginalRate).
+ *
+ * Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
+ * parity test against the source site engine.
+ *
+ * Scope (S141 Wave 1A Item #2, per S141 Risk #2): SINGLE-CONVERSION tax
+ * impact only. Multi-year scenario simulation / optimization is deferred to a
+ * future tool (`dc.calculator.rothConversion.multiYearOptimization`). This
+ * tool answers "if I convert $X today, what's my federal tax owed?" and
+ * "when do I break even on the upfront tax?"
+ *
+ * NOT MODELED (intentional scope limits):
+ * - State tax on the conversion (caller's responsibility; conversion is
+ *   typically taxed by state at ordinary-income rates).
+ * - IRMAA tier impact (the site calculator surfaces this; out of scope for
+ *   the MCP v0.3.0 tool).
+ * - 5-year rule timing for individual contributions (we report whether the
+ *   5-year rule applies based on age < 59.5, but don't model the per-
+ *   conversion clock).
+ *
+ * Math reference:
+ *   For taxable income I and conversion amount C:
+ *     beforeTax    = bracketTax(I, brackets[filingStatus])
+ *     afterTax     = bracketTax(I + C, brackets[filingStatus])
+ *     taxOwed      = afterTax − beforeTax              (incremental)
+ *     marginalRate = top bracket spanned by (I + C)
+ *     effectiveRate = taxOwed / C
+ *
+ *   Break-even years (when conversion tax savings recoup themselves, given
+ *   the user's retirement marginal rate is lower than the conversion
+ *   marginal rate and tax-free Roth growth at real return r):
+ *     If retirementMarginalRate >= conversionMarginalRate → 0
+ *       (already break-even because future bracket ≥ today's)
+ *     Else:
+ *       savingsPerYear ≈ futureBalance × (conversionMarginalRate −
+ *                                          retirementMarginalRate)
+ *       breakEvenYears = log((1 − totalConvRate) / (1 − totalFutureRate))
+ *                        / log(1 + r)
+ *       (where totalConvRate ≈ effectiveRateOnConversion,
+ *              totalFutureRate ≈ retirementMarginalRate)
+ *
+ *   This is the same break-even math the site `calculateBreakEvenYears`
+ *   function uses (we drop the explicit state-tax term; caller-side).
+ *
+ * Source: IRS Rev. Proc. 2025-32 (2026 federal tax brackets).
+ *         Last verified: 2026-05-09.
+ */
+import { FEDERAL_TAX_BRACKETS_2026, } from "./data/federalTax.js";
+/**
+ * SemVer of the Roth conversion engine. Per ADR-0039 § 5 (reaffirmed in
+ * ADR-0041 Position #4a): major bump = math change; minor = additive output;
+ * patch = numerical correction. NOT bumped for cosmetic refactors.
+ * - 1.0.0: initial v1 lift from roth-conversion-calculator.js + tax-brackets.js
+ *          (S141 Wave 1A).
+ */
+export const ENGINE_VERSION = "1.0.0";
+/**
+ * Progressive bracket lookup — verbatim port of site `calculateBracketTax`.
+ */
+function bracketTax(taxable, brackets) {
+    if (!brackets.length || taxable <= 0)
+        return 0;
+    for (let i = brackets.length - 1; i >= 0; i--) {
+        const b = brackets[i];
+        if (taxable > b.min) {
+            return b.baseTax + (taxable - b.min) * b.rate;
+        }
+    }
+    return 0;
+}
+/**
+ * Get the marginal (top) bracket rate for a given taxable income —
+ * verbatim port of site `getMarginalRate` (returns as decimal).
+ */
+function marginalRateFor(taxable, brackets) {
+    if (taxable <= 0)
+        return brackets[0]?.rate ?? 0;
+    for (let i = brackets.length - 1; i >= 0; i--) {
+        if (taxable > brackets[i].min)
+            return brackets[i].rate;
+    }
+    return brackets[0]?.rate ?? 0;
+}
+/**
+ * Compute Roth conversion tax impact (single conversion).
+ *
+ * 1-to-1 port of the federal-tax + incremental-tax + marginal-rate +
+ * break-even logic the site uses, with state tax / IRMAA omitted per scope.
+ */
+export function taxImpact(input) {
+    const { conversionAmount, age, filingStatus, currentTaxableIncome, retirementMarginalRatePercent, expectedReturnPercent = 7, } = input;
+    const brackets = FEDERAL_TAX_BRACKETS_2026[filingStatus];
+    // Incremental federal tax — bracket walk before + after the conversion.
+    const beforeTax = bracketTax(currentTaxableIncome, brackets);
+    const afterTax = bracketTax(currentTaxableIncome + conversionAmount, brackets);
+    const taxOwed = Math.max(0, afterTax - beforeTax);
+    // Marginal rate the conversion pushes us into (top spanned bracket).
+    const marginalRateOnConversion = marginalRateFor(currentTaxableIncome + conversionAmount, brackets);
+    // Effective rate (averaged across the brackets the conversion spans).
+    const effectiveRateOnConversion = conversionAmount > 0 ? taxOwed / conversionAmount : 0;
+    // 5-year rule applies for under-59.5 conversions.
+    const fiveYearRuleApplies = age < 59.5;
+    // Break-even years — only when retirementMarginalRatePercent is provided.
+    // We use the same log-ratio form as the site calculator's
+    // calculateBreakEvenYears (state tax omitted here per scope).
+    let breakEvenYears = null;
+    if (typeof retirementMarginalRatePercent === "number") {
+        const futureRate = retirementMarginalRatePercent / 100;
+        const conversionRate = effectiveRateOnConversion;
+        const r = expectedReturnPercent / 100;
+        if (futureRate >= conversionRate) {
+            // Future tax rate ≥ today's conversion rate → already break-even.
+            breakEvenYears = 0;
+        }
+        else if (conversionRate >= 1) {
+            breakEvenYears = Infinity;
+        }
+        else if (r <= 0) {
+            breakEvenYears = Infinity;
+        }
+        else {
+            // log((1 - futureRate) / (1 - conversionRate)) / log(1 + r)
+            const numerator = Math.log((1 - futureRate) / (1 - conversionRate));
+            const denominator = Math.log(1 + r);
+            const raw = numerator / denominator;
+            breakEvenYears = raw < 0 ? 0 : raw;
+        }
+    }
+    return {
+        taxOwed,
+        marginalRateOnConversion,
+        effectiveRateOnConversion,
+        fiveYearRuleApplies,
+        breakEvenYears,
+        meta: {
+            tableYear: 2026,
+            source: "IRS Rev. Proc. 2025-32",
+        },
+    };
+}
+//# sourceMappingURL=rothConversion.js.map

package/dist/engines/rothConversion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rothConversion.js","sourceRoot":"","sources":["../../src/engines/rothConversion.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,29 +2,41 @@
 /**
  * @markcolabs/mcp — MCP server entrypoint.
  *
- * v0.2.0 (per ADR-0039 + ADR-0041 reconciliation). Registers:
- *   - 5 tools:
+ * v0.3.0 (per ADR-0039 + ADR-0041 reconciliation; S141 Wave 1A + 1B).
+ * Registers:
+ *   - 9 tools:
  *       dc.calculator.mortgage.monthlyPayment           (S135 Item 5)
  *       dc.calculator.compoundInterest.futureValue      (S135 Item 5)
  *       dc.calculator.retirement401k.projection         (S136 Item 3, renamed v0.2.0 per ADR-0041 D2)
  *       dc.calculator.socialSecurity.estimatedBenefit   (S136 Item 3, renamed v0.2.0 per ADR-0041 D2)
  *       dc.calculator.paycheck.netPay                   (S136 Item 3)
+ *       dc.calculator.ira.contributionLimit             (S141 Wave 1A)
+ *       dc.calculator.rothConversion.taxImpact          (S141 Wave 1A)
+ *       dc.calculator.rmd.distributionAmount            (S141 Wave 1B — new)
+ *       dc.calculator.hsa.contributionLimit             (S141 Wave 1B — new)
  *   - 1 resource: dc://disclaimers/ymyl (canonical YMYL disclaimer)
  *
  * Transport: stdio (default for local MCP clients).
  *
- * S136 hits O5-KR1 5-tool target. Post-S136: methodology resources
- * (dc://methodologies/*) and the `plan-retirement` prompt template (O5-KR2).
+ * S141 Wave 1A took tool coverage 5 → 7; Wave 1B finalizes 7 → 9 (v0.3.0).
  */
 export { execute as executeMortgageTool } from "./tools/mortgage.js";
 export { execute as executeCompoundInterestTool } from "./tools/compoundInterest.js";
 export { execute as executeRetirement401kTool } from "./tools/retirement401k.js";
 export { execute as executeSocialSecurityTool } from "./tools/socialSecurity.js";
 export { execute as executePaycheckTool } from "./tools/paycheck.js";
+export { execute as executeIraTool } from "./tools/ira.js";
+export { execute as executeRothConversionTool } from "./tools/rothConversion.js";
+export { execute as executeRmdTool } from "./tools/rmd.js";
+export { execute as executeHsaTool } from "./tools/hsa.js";
 export * as mortgageEngine from "./engines/mortgage.js";
 export * as compoundInterestEngine from "./engines/compoundInterest.js";
 export * as retirement401kEngine from "./engines/retirement401k.js";
 export * as socialSecurityEngine from "./engines/socialSecurity.js";
 export * as paycheckEngine from "./engines/paycheck.js";
+export * as iraEngine from "./engines/ira.js";
+export * as rothConversionEngine from "./engines/rothConversion.js";
+export * as rmdEngine from "./engines/rmd.js";
+export * as hsaEngine from "./engines/hsa.js";
 export * from "./envelope.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;GAgBG;AAwBH,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AACrF,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,sBAAsB,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,oBAAoB,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,oBAAoB,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AACxD,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG;AA4BH,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AACrF,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,sBAAsB,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,oBAAoB,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,oBAAoB,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,oBAAoB,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAC;AAC9C,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -2,19 +2,23 @@
 /**
  * @markcolabs/mcp — MCP server entrypoint.
  *
- * v0.2.0 (per ADR-0039 + ADR-0041 reconciliation). Registers:
- *   - 5 tools:
+ * v0.3.0 (per ADR-0039 + ADR-0041 reconciliation; S141 Wave 1A + 1B).
+ * Registers:
+ *   - 9 tools:
  *       dc.calculator.mortgage.monthlyPayment           (S135 Item 5)
  *       dc.calculator.compoundInterest.futureValue      (S135 Item 5)
  *       dc.calculator.retirement401k.projection         (S136 Item 3, renamed v0.2.0 per ADR-0041 D2)
  *       dc.calculator.socialSecurity.estimatedBenefit   (S136 Item 3, renamed v0.2.0 per ADR-0041 D2)
  *       dc.calculator.paycheck.netPay                   (S136 Item 3)
+ *       dc.calculator.ira.contributionLimit             (S141 Wave 1A)
+ *       dc.calculator.rothConversion.taxImpact          (S141 Wave 1A)
+ *       dc.calculator.rmd.distributionAmount            (S141 Wave 1B — new)
+ *       dc.calculator.hsa.contributionLimit             (S141 Wave 1B — new)
  *   - 1 resource: dc://disclaimers/ymyl (canonical YMYL disclaimer)
  *
  * Transport: stdio (default for local MCP clients).
  *
- * S136 hits O5-KR1 5-tool target. Post-S136: methodology resources
- * (dc://methodologies/*) and the `plan-retirement` prompt template (O5-KR2).
+ * S141 Wave 1A took tool coverage 5 → 7; Wave 1B finalizes 7 → 9 (v0.3.0).
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -25,6 +29,10 @@ import * as compoundInterestTool from "./tools/compoundInterest.js";
 import * as retirement401kTool from "./tools/retirement401k.js";
 import * as socialSecurityTool from "./tools/socialSecurity.js";
 import * as paycheckTool from "./tools/paycheck.js";
+import * as iraTool from "./tools/ira.js";
+import * as rothConversionTool from "./tools/rothConversion.js";
+import * as rmdTool from "./tools/rmd.js";
+import * as hsaTool from "./tools/hsa.js";
 import { YMYL_DISCLAIMER, YMYL_DISCLAIMER_URI, } from "./disclaimers/ymyl.js";
 // Re-export the tool execute functions and engines so consumers (and parity
 // tests) can import them directly without spinning up the MCP transport.
@@ -33,18 +41,26 @@ export { execute as executeCompoundInterestTool } from "./tools/compoundInterest
 export { execute as executeRetirement401kTool } from "./tools/retirement401k.js";
 export { execute as executeSocialSecurityTool } from "./tools/socialSecurity.js";
 export { execute as executePaycheckTool } from "./tools/paycheck.js";
+export { execute as executeIraTool } from "./tools/ira.js";
+export { execute as executeRothConversionTool } from "./tools/rothConversion.js";
+export { execute as executeRmdTool } from "./tools/rmd.js";
+export { execute as executeHsaTool } from "./tools/hsa.js";
 export * as mortgageEngine from "./engines/mortgage.js";
 export * as compoundInterestEngine from "./engines/compoundInterest.js";
 export * as retirement401kEngine from "./engines/retirement401k.js";
 export * as socialSecurityEngine from "./engines/socialSecurity.js";
 export * as paycheckEngine from "./engines/paycheck.js";
+export * as iraEngine from "./engines/ira.js";
+export * as rothConversionEngine from "./engines/rothConversion.js";
+export * as rmdEngine from "./engines/rmd.js";
+export * as hsaEngine from "./engines/hsa.js";
 export * from "./envelope.js";
 // ---------------------------------------------------------------------------
 // Server setup
 // ---------------------------------------------------------------------------
 const server = new Server({
     name: "@markcolabs/mcp",
-    version: "0.2.0",
+    version: "0.3.0",
 }, {
     capabilities: {
         tools: {},
@@ -54,6 +70,20 @@ const server = new Server({
 // ---------------------------------------------------------------------------
 // tools/list
 // ---------------------------------------------------------------------------
+/**
+ * Tool annotations per Anthropic Claude Connectors Directory spec
+ * (MCP-AUDIT-023, S141 Item #5):
+ *   - title:           human-readable display name (sentence-case)
+ *   - readOnlyHint:    true — all our tools are pure functions, no mutation
+ *   - destructiveHint: false — no tool modifies any state
+ *
+ * Applied uniformly across all 9 tools — the package is read-only by design
+ * (MCP-AUDIT-008 audit-bundle conclusion).
+ */
+const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+};
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
         tools: [
@@ -61,26 +91,82 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 name: mortgageTool.TOOL_NAME,
                 description: mortgageTool.TOOL_DESCRIPTION,
                 inputSchema: zodToJsonSchema(mortgageTool.MortgageMonthlyPaymentInputSchema),
+                annotations: {
+                    title: "Mortgage Monthly Payment",
+                    ...READ_ONLY_ANNOTATIONS,
+                },
             },
             {
                 name: compoundInterestTool.TOOL_NAME,
                 description: compoundInterestTool.TOOL_DESCRIPTION,
                 inputSchema: zodToJsonSchema(compoundInterestTool.CompoundInterestFutureValueInputSchema),
+                annotations: {
+                    title: "Compound Interest Future Value",
+                    ...READ_ONLY_ANNOTATIONS,
+                },
             },
             {
                 name: retirement401kTool.TOOL_NAME,
                 description: retirement401kTool.TOOL_DESCRIPTION,
                 inputSchema: zodToJsonSchema(retirement401kTool.Retirement401kProjectionInputSchema),
+                annotations: {
+                    title: "401(k) Retirement Projection",
+                    ...READ_ONLY_ANNOTATIONS,
+                },
             },
             {
                 name: socialSecurityTool.TOOL_NAME,
                 description: socialSecurityTool.TOOL_DESCRIPTION,
                 inputSchema: zodToJsonSchema(socialSecurityTool.SocialSecurityEstimateInputSchema),
+                annotations: {
+                    title: "Social Security Estimated Benefit",
+                    ...READ_ONLY_ANNOTATIONS,
+                },
             },
             {
                 name: paycheckTool.TOOL_NAME,
                 description: paycheckTool.TOOL_DESCRIPTION,
                 inputSchema: zodToJsonSchema(paycheckTool.PaycheckNetPayInputSchema),
+                annotations: {
+                    title: "Paycheck Net Pay",
+                    ...READ_ONLY_ANNOTATIONS,
+                },
+            },
+            {
+                name: iraTool.TOOL_NAME,
+                description: iraTool.TOOL_DESCRIPTION,
+                inputSchema: zodToJsonSchema(iraTool.IraContributionLimitInputSchema),
+                annotations: {
+                    title: "IRA Contribution Limit",
+                    ...READ_ONLY_ANNOTATIONS,
+                },
+            },
+            {
+                name: rothConversionTool.TOOL_NAME,
+                description: rothConversionTool.TOOL_DESCRIPTION,
+                inputSchema: zodToJsonSchema(rothConversionTool.RothConversionTaxImpactInputSchema),
+                annotations: {
+                    title: "Roth Conversion Tax Impact",
+                    ...READ_ONLY_ANNOTATIONS,
+                },
+            },
+            {
+                name: rmdTool.TOOL_NAME,
+                description: rmdTool.TOOL_DESCRIPTION,
+                inputSchema: zodToJsonSchema(rmdTool.RmdDistributionAmountInputSchema),
+                annotations: {
+                    title: "RMD Distribution Amount",
+                    ...READ_ONLY_ANNOTATIONS,
+                },
+            },
+            {
+                name: hsaTool.TOOL_NAME,
+                description: hsaTool.TOOL_DESCRIPTION,
+                inputSchema: zodToJsonSchema(hsaTool.HsaContributionLimitInputSchema),
+                annotations: {
+                    title: "HSA Contribution Limit",
+                    ...READ_ONLY_ANNOTATIONS,
+                },
             },
         ],
     };
@@ -107,6 +193,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         case paycheckTool.TOOL_NAME:
             result = paycheckTool.execute(args);
             break;
+        case iraTool.TOOL_NAME:
+            result = iraTool.execute(args);
+            break;
+        case rothConversionTool.TOOL_NAME:
+            result = rothConversionTool.execute(args);
+            break;
+        case rmdTool.TOOL_NAME:
+            result = rmdTool.execute(args);
+            break;
+        case hsaTool.TOOL_NAME:
+            result = hsaTool.execute(args);
+            break;
         default:
             return {
                 isError: true,
@@ -181,7 +279,7 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // eslint-disable-next-line no-console
-    console.error("[@markcolabs/mcp] v0.2.0 ready (stdio) — 5 tools registered.");
+    console.error("[@markcolabs/mcp] v0.3.0 ready (stdio) — 9 tools registered.");
 }
 // Run only when invoked as a binary, not when imported by parity tests.
 const isDirect = import.meta.url === `file://${process.argv[1]}` ||