@markcolabs/mcp 0.1.0

package/dist/engines/retirement401k.js

@@ -0,0 +1,126 @@
+/**
+ * 401(k) projection engine — lifted from
+ * site/src/pages/401k-retirement-calculator/401k-retirement-calculator.js
+ * (functions `calculateEmployerMatch`, `calculateFutureValue`,
+ * `generateYearlyBreakdown`, `getIRSLimit`, `getCatchUpAmount`,
+ * `calculate401kResults`).
+ *
+ * Per ADR-0039 § 5 (Calc-Engine Lift Pattern):
+ * - Pure synchronous functions of inputs → results. No DOM, no fetch.
+ * - ENGINE_VERSION bumps when math changes.
+ * - Parity tests at packages/mcp/test/parity/retirement401k.test.ts gate this
+ *   engine against the source site calculator JS.
+ *
+ * MCP-side enhancement on top of the lift: the kickoff-defined input
+ * `annualSalaryGrowthPercent` is honored in this engine. The site engine
+ * applies a *flat* annual contribution; here we step year-by-year so each
+ * year's employee contribution + employer match scales with the cumulative
+ * salary growth. When `annualSalaryGrowthPercent === 0` the math is identical
+ * to the site engine (parity test "happy path" covers this).
+ *
+ * Math reference (year-by-year, mirroring the site's Math.pow form when growth=0):
+ *   contrib_year_i  = annualSalary * (1 + g)^i * (employeePct/100)
+ *                       (capped per IRS limit)
+ *   match_year_i    = annualSalary * (1 + g)^i * (matchedPct/100) * (employerMatchPct/100)
+ *   balance_year_i  = balance_year_{i-1} * (1 + r) + contrib_year_i + match_year_i
+ *   balance_year_0  = currentBalance
+ *
+ * IRS limits: per IRS Notice 2025-67 (2026) — see engines/data/irs2026.ts.
+ */
+import { LIMITS_401K_2026 } from "./data/irs2026.js";
+/**
+ * SemVer of the 401(k) projection engine.
+ * - 0.2.0: initial port (S136). Co-incident with the package-wide S136 batch bump.
+ */
+export const ENGINE_VERSION = "0.2.0";
+const ROUND = (v) => Math.round(v * 100) / 100;
+/**
+ * IRS contribution cap for a given age, mirroring `getIRSLimit` in the site engine.
+ */
+function irsLimitForAge(age, catchUpEnabled) {
+    if (!catchUpEnabled ||
+        !Number.isFinite(age) ||
+        age < LIMITS_401K_2026.catchUpAge) {
+        return LIMITS_401K_2026.base;
+    }
+    if (age >= LIMITS_401K_2026.superCatchUpAgeStart &&
+        age <= LIMITS_401K_2026.superCatchUpAgeEnd) {
+        return LIMITS_401K_2026.totalWithSuperCatchUp;
+    }
+    return LIMITS_401K_2026.totalWithCatchUp;
+}
+/**
+ * Catch-up dollar amount for a given age, mirroring `getCatchUpAmount` in site engine.
+ */
+function catchUpForAge(age, catchUpEnabled) {
+    if (!catchUpEnabled ||
+        !Number.isFinite(age) ||
+        age < LIMITS_401K_2026.catchUpAge) {
+        return 0;
+    }
+    if (age >= LIMITS_401K_2026.superCatchUpAgeStart &&
+        age <= LIMITS_401K_2026.superCatchUpAgeEnd) {
+        return LIMITS_401K_2026.superCatchUp;
+    }
+    return LIMITS_401K_2026.catchUp;
+}
+/**
+ * Project a 401(k) balance year by year through retirement.
+ *
+ * Uses the same per-year accumulation pattern as the site's
+ * `generateYearlyBreakdown` / `calculateFutureValue` (compounded annual return,
+ * end-of-year contributions). Differs from the site only in honoring
+ * `annualSalaryGrowthPercent` per kickoff input list.
+ */
+export function projection(input) {
+    const { currentBalance, annualSalary, contributionPercent, employerMatchPercent, employerMatchLimitPercent, annualSalaryGrowthPercent, annualReturnPercent, currentAge, retirementAge, catchUpEnabled = true, } = input;
+    const years = Math.max(0, Math.floor(retirementAge - currentAge));
+    const r = annualReturnPercent / 100;
+    const g = annualSalaryGrowthPercent / 100;
+    // matchedPct = min(employee contribution %, employer cap %)
+    const matchedPct = Math.min(contributionPercent, employerMatchLimitPercent);
+    let balance = currentBalance;
+    let totalContributions = 0;
+    let employerContribTotal = 0;
+    const rows = [];
+    for (let i = 1; i <= years; i++) {
+        const ageThisYear = currentAge + i;
+        const salaryThisYear = annualSalary * Math.pow(1 + g, i - 1);
+        // Base employee contribution from salary %, plus catch-up if eligible.
+        let employeeContrib = salaryThisYear * (contributionPercent / 100) +
+            catchUpForAge(ageThisYear, catchUpEnabled);
+        // Cap at IRS limit for this year's age (catch-up windows shift over time).
+        const cap = irsLimitForAge(ageThisYear, catchUpEnabled);
+        if (employeeContrib > cap)
+            employeeContrib = cap;
+        // Employer match scales with salary, capped by employer-match limit %.
+        const employerMatch = salaryThisYear *
+            (matchedPct / 100) *
+            (employerMatchPercent / 100);
+        // End-of-year compounding: prior balance grows, then this year's
+        // contributions land. (Matches site `calculateFutureValue` for flat salary.)
+        const grownBalance = balance * (1 + r);
+        const growthThisYear = grownBalance - balance;
+        balance = grownBalance + employeeContrib + employerMatch;
+        totalContributions += employeeContrib;
+        employerContribTotal += employerMatch;
+        rows.push({
+            year: i,
+            age: ageThisYear,
+            employeeContribution: ROUND(employeeContrib),
+            employerMatch: ROUND(employerMatch),
+            growth: ROUND(growthThisYear),
+            endingBalance: ROUND(balance),
+        });
+    }
+    const principalPlusContribs = currentBalance + totalContributions + employerContribTotal;
+    const growthEarned = balance - principalPlusContribs;
+    return {
+        futureBalance: ROUND(balance),
+        totalContributions: ROUND(totalContributions),
+        employerContribTotal: ROUND(employerContribTotal),
+        growthEarned: ROUND(growthEarned),
+        yearByYear: rows,
+    };
+}
+//# sourceMappingURL=retirement401k.js.map

package/dist/engines/retirement401k.js.map

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

package/dist/engines/socialSecurity.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Social Security estimate engine — lifted from
+ * site/src/utils/social-security-engine.js (functions `estimateAIME`,
+ * `calculatePIA`, `calculateFRA`, `calculateAdjustedBenefit`,
+ * `calculateEarlyReduction`, `calculateDelayedCredit`,
+ * `calculateLifetimeBenefits`).
+ *
+ * Per ADR-0039 § 5: pure synchronous functions, ENGINE_VERSION constant,
+ * parity test against the site source as the gate.
+ *
+ * Math reference (mirrors SSA Publication 05-10035):
+ *   AIME = (min(salary, ssWageBase) * 0.65 * min(yearsWorked, 35)) / 420
+ *          (simplified site approximation; exact AIME requires 35-year history)
+ *   PIA  = 0.90 * min(AIME, BP1)
+ *        + 0.32 * (min(AIME, BP2) - BP1)            if AIME > BP1
+ *        + 0.15 * (AIME - BP2)                      if AIME > BP2
+ *        (rounded down to nearest $0.10)
+ *   benefit_at_claim = PIA * adjustment_factor(claimAge, FRA)
+ *
+ * Output values are USD monthly benefits (or USD lifetime totals).
+ */
+/**
+ * SemVer of the SS engine.
+ * - 0.2.0: initial port (S136). Co-incident with the package-wide S136 batch bump.
+ */
+export declare const ENGINE_VERSION = "0.2.0";
+/** Inputs to the SS estimate engine. */
+export interface SocialSecurityEstimateInput {
+    /** Birth year (1943-2004 supported). */
+    birthYear: number;
+    /** Current/final annual earnings, USD. */
+    currentEarnings: number;
+    /** Claiming age (62..70). */
+    claimAge: number;
+    /**
+     * Years of work earning SS credits. Used in the simplified AIME estimate.
+     * Defaults to 35 (the SSA averaging window).
+     */
+    yearsWorked?: number;
+    /** Life-expectancy assumption for lifetime projection. Default 85. */
+    lifeExpectancy?: number;
+}
+/** Result payload returned by the engine. */
+export interface SocialSecurityEstimateResult {
+    /** Monthly benefit at Full Retirement Age (PIA), USD. */
+    monthlyBenefitAtFRA: number;
+    /** Monthly benefit at the user's chosen claim age, USD. */
+    adjustedMonthlyBenefit: number;
+    /** Total benefit collected from claimAge through lifeExpectancy, USD. */
+    lifetimeBenefitProjection: number;
+    /** Full Retirement Age in decimal (e.g., 67.0 or 66.5). */
+    fraAge: number;
+    /** Eligibility year used for bend-point lookup (birthYear + 62). */
+    eligibilityYear: number;
+    /** Whether bend points are estimated (eligibility year beyond published table). */
+    bendPointsEstimated: boolean;
+}
+export declare function estimate(input: SocialSecurityEstimateInput): SocialSecurityEstimateResult;
+//# sourceMappingURL=socialSecurity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"socialSecurity.d.ts","sourceRoot":"","sources":["../../src/engines/socialSecurity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAQH;;;GAGG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,wCAAwC;AACxC,MAAM,WAAW,2BAA2B;IAC1C,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,4BAA4B;IAC3C,yDAAyD;IACzD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,sBAAsB,EAAE,MAAM,CAAC;IAC/B,yEAAyE;IACzE,yBAAyB,EAAE,MAAM,CAAC;IAClC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAsGD,wBAAgB,QAAQ,CACtB,KAAK,EAAE,2BAA2B,GACjC,4BAA4B,CAiC9B"}

package/dist/engines/socialSecurity.js

@@ -0,0 +1,135 @@
+/**
+ * Social Security estimate engine — lifted from
+ * site/src/utils/social-security-engine.js (functions `estimateAIME`,
+ * `calculatePIA`, `calculateFRA`, `calculateAdjustedBenefit`,
+ * `calculateEarlyReduction`, `calculateDelayedCredit`,
+ * `calculateLifetimeBenefits`).
+ *
+ * Per ADR-0039 § 5: pure synchronous functions, ENGINE_VERSION constant,
+ * parity test against the site source as the gate.
+ *
+ * Math reference (mirrors SSA Publication 05-10035):
+ *   AIME = (min(salary, ssWageBase) * 0.65 * min(yearsWorked, 35)) / 420
+ *          (simplified site approximation; exact AIME requires 35-year history)
+ *   PIA  = 0.90 * min(AIME, BP1)
+ *        + 0.32 * (min(AIME, BP2) - BP1)            if AIME > BP1
+ *        + 0.15 * (AIME - BP2)                      if AIME > BP2
+ *        (rounded down to nearest $0.10)
+ *   benefit_at_claim = PIA * adjustment_factor(claimAge, FRA)
+ *
+ * Output values are USD monthly benefits (or USD lifetime totals).
+ */
+import { SSA_BEND_POINTS, SS_WAGE_BASE, DEFAULT_LIFE_EXPECTANCY, } from "./data/ssa.js";
+/**
+ * SemVer of the SS engine.
+ * - 0.2.0: initial port (S136). Co-incident with the package-wide S136 batch bump.
+ */
+export const ENGINE_VERSION = "0.2.0";
+// ---------------------------------------------------------------------------
+// FRA lookup (mirrors site engine FRA_TABLE)
+// ---------------------------------------------------------------------------
+/** FRA in years.months for a given birth year. Returns total months for math use. */
+function fraTotalMonths(birthYear) {
+    if (birthYear <= 1954)
+        return 792; // 66.0
+    if (birthYear >= 1960)
+        return 804; // 67.0
+    // 1955-1959 transition: +2 months per year.
+    const map = {
+        1955: 794,
+        1956: 796,
+        1957: 798,
+        1958: 800,
+        1959: 802,
+    };
+    return map[birthYear] ?? 804;
+}
+function fraDecimal(birthYear) {
+    return fraTotalMonths(birthYear) / 12;
+}
+// ---------------------------------------------------------------------------
+// Bend points
+// ---------------------------------------------------------------------------
+function getBendPoints(eligibilityYear) {
+    if (SSA_BEND_POINTS[eligibilityYear]) {
+        return { ...SSA_BEND_POINTS[eligibilityYear], estimated: false };
+    }
+    const years = Object.keys(SSA_BEND_POINTS)
+        .map(Number)
+        .sort((a, b) => b - a);
+    const latest = years[0];
+    return { ...SSA_BEND_POINTS[latest], estimated: true };
+}
+// ---------------------------------------------------------------------------
+// AIME / PIA / claim-age adjustment (verbatim port of site math)
+// ---------------------------------------------------------------------------
+function estimateAIME(currentSalary, yearsWorked, taxYear) {
+    const wageBase = SS_WAGE_BASE[taxYear] ?? SS_WAGE_BASE[2026];
+    const cappedSalary = Math.min(currentSalary, wageBase);
+    const careerAverageFactor = 0.65;
+    const avgAnnualEarnings = cappedSalary * careerAverageFactor;
+    const effectiveYears = Math.min(yearsWorked, 35);
+    const totalEarnings = avgAnnualEarnings * effectiveYears;
+    return Math.floor(totalEarnings / 420);
+}
+function calculatePIA(aime, bp) {
+    let pia = 0.9 * Math.min(aime, bp.first);
+    if (aime > bp.first) {
+        pia += 0.32 * (Math.min(aime, bp.second) - bp.first);
+    }
+    if (aime > bp.second) {
+        pia += 0.15 * (aime - bp.second);
+    }
+    // PIA rounded down to nearest $0.10 per SSA convention.
+    return Math.floor(pia * 10) / 10;
+}
+/**
+ * Adjustment factor for claim age vs. FRA. < 1 is early reduction, > 1 is delayed credit.
+ * Mirrors site `calculateEarlyReduction` + `calculateDelayedCredit`.
+ */
+function adjustmentFactor(claimAgeMonths, fraMonths) {
+    if (claimAgeMonths === fraMonths)
+        return 1.0;
+    if (claimAgeMonths < fraMonths) {
+        const monthsEarly = fraMonths - claimAgeMonths;
+        let reduction = 0;
+        const first36 = Math.min(monthsEarly, 36);
+        reduction += first36 * (5 / 9) / 100;
+        if (monthsEarly > 36) {
+            reduction += (monthsEarly - 36) * (5 / 12) / 100;
+        }
+        return Math.max(0, 1 - reduction);
+    }
+    // Delayed credit: 2/3 of 1% per month (8%/yr), capped at 70 (= 840 months).
+    const cappedMonths = Math.min(claimAgeMonths, 840);
+    if (cappedMonths <= fraMonths)
+        return 1.0;
+    const monthsDelayed = cappedMonths - fraMonths;
+    return 1 + monthsDelayed * (2 / 3) / 100;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function estimate(input) {
+    const { birthYear, currentEarnings, claimAge, yearsWorked = 35, lifeExpectancy = DEFAULT_LIFE_EXPECTANCY, } = input;
+    const eligibilityYear = birthYear + 62;
+    const bp = getBendPoints(eligibilityYear);
+    const aime = estimateAIME(currentEarnings, yearsWorked, eligibilityYear);
+    const pia = calculatePIA(aime, bp);
+    const fraMonths = fraTotalMonths(birthYear);
+    const claimAgeMonths = claimAge * 12;
+    const adj = adjustmentFactor(claimAgeMonths, fraMonths);
+    const adjustedMonthly = Math.round(pia * adj * 100) / 100;
+    // Lifetime: monthly * 12 months * (lifeExpectancy − claimAge) years.
+    const yearsReceiving = Math.max(0, lifeExpectancy - claimAge);
+    const lifetime = Math.round(adjustedMonthly * 12 * yearsReceiving);
+    return {
+        monthlyBenefitAtFRA: pia,
+        adjustedMonthlyBenefit: adjustedMonthly,
+        lifetimeBenefitProjection: lifetime,
+        fraAge: fraDecimal(birthYear),
+        eligibilityYear,
+        bendPointsEstimated: bp.estimated,
+    };
+}
+//# sourceMappingURL=socialSecurity.js.map

package/dist/engines/socialSecurity.js.map

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

package/dist/envelope.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Result + Error envelopes per ADR-0039 § 3 and § 4.
+ *
+ * Every tool returns a `ToolResult<T>` on success or a `ToolError` on failure.
+ * The envelope shape is invariant across all tools — only the `result` payload
+ * type varies. Provenance (engineVersion, methodology, calculatedAt) is
+ * non-negotiable.
+ */
+/**
+ * Successful tool result envelope.
+ * @template T - Tool-specific payload type (always a structured object, never a bare number).
+ */
+export interface ToolResult<T> {
+    /** Tool-specific payload. Structured object. Monetary fields are bare USD numbers. */
+    result: T;
+    /** Canonical YMYL disclaimer string (single source of truth at packages/mcp/src/disclaimers/ymyl.ts). */
+    disclaimer: string;
+    /** Methodology pointer with versioned URL. */
+    methodology: {
+        /** Absolute URL to the methodology .md companion (ADR-0033) or HTML page if no companion. */
+        url: string;
+        /** ISO date of the methodology document's last-modified front-matter (per ADR-0035). */
+        version: string;
+    };
+    /** ISO-8601 UTC timestamp the tool was invoked. */
+    calculatedAt: string;
+    /** SemVer of the calc engine module that produced `result`. Bumped when math changes. */
+    engineVersion: string;
+}
+/**
+ * Error envelope namespaces per ADR-0039 § 4.
+ *
+ * - INPUT_VALIDATION: Zod or bounds validation failed. Not retriable.
+ * - BUSINESS_RULE:    Inputs valid but produce an undefined result. Not retriable.
+ * - INTERNAL:         Unexpected engine error. Not retriable; opaque message to caller.
+ * - RATE_LIMIT:       Free-tier rate limit hit. Retriable after the window resets.
+ */
+export type ToolErrorCode = "INPUT_VALIDATION" | "BUSINESS_RULE" | "INTERNAL" | "RATE_LIMIT";
+/**
+ * Failure envelope returned to the MCP transport with `isError: true`.
+ * Tools never throw to the transport — all failures funnel through this shape.
+ */
+export interface ToolError {
+    error: {
+        /** Stable machine-readable code, namespaced by tool family. */
+        code: ToolErrorCode;
+        /** Human-readable description (no PII; safe to surface to end-user). */
+        message: string;
+        /** For validation errors, the input field that failed. */
+        field?: string;
+        /** True if a retry with same inputs *might* succeed. Validation errors are always false. */
+        retriable: boolean;
+    };
+}
+/**
+ * Build a ToolResult envelope around a successful payload. Helper to keep tools terse.
+ */
+export declare function makeResult<T>(args: {
+    result: T;
+    methodology: {
+        url: string;
+        version: string;
+    };
+    engineVersion: string;
+    disclaimer: string;
+}): ToolResult<T>;
+/**
+ * Build a ToolError envelope for a failure path. Helper for terse call sites.
+ */
+export declare function makeError(args: {
+    code: ToolErrorCode;
+    message: string;
+    field?: string;
+    retriable?: boolean;
+}): ToolError;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,sFAAsF;IACtF,MAAM,EAAE,CAAC,CAAC;IACV,yGAAyG;IACzG,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,WAAW,EAAE;QACX,6FAA6F;QAC7F,GAAG,EAAE,MAAM,CAAC;QACZ,wFAAwF;QACxF,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GACrB,kBAAkB,GAClB,eAAe,GACf,UAAU,GACV,YAAY,CAAC;AAEjB;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE;QACL,+DAA+D;QAC/D,IAAI,EAAE,aAAa,CAAC;QACpB,wEAAwE;QACxE,OAAO,EAAE,MAAM,CAAC;QAChB,0DAA0D;QAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,4FAA4F;QAC5F,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE;IAClC,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,UAAU,CAAC,CAAC,CAAC,CAQhB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,SAAS,CASZ"}

package/dist/envelope.js

@@ -0,0 +1,34 @@
+/**
+ * Result + Error envelopes per ADR-0039 § 3 and § 4.
+ *
+ * Every tool returns a `ToolResult<T>` on success or a `ToolError` on failure.
+ * The envelope shape is invariant across all tools — only the `result` payload
+ * type varies. Provenance (engineVersion, methodology, calculatedAt) is
+ * non-negotiable.
+ */
+/**
+ * Build a ToolResult envelope around a successful payload. Helper to keep tools terse.
+ */
+export function makeResult(args) {
+    return {
+        result: args.result,
+        disclaimer: args.disclaimer,
+        methodology: args.methodology,
+        calculatedAt: new Date().toISOString(),
+        engineVersion: args.engineVersion,
+    };
+}
+/**
+ * Build a ToolError envelope for a failure path. Helper for terse call sites.
+ */
+export function makeError(args) {
+    return {
+        error: {
+            code: args.code,
+            message: args.message,
+            field: args.field,
+            retriable: args.retriable ?? args.code === "RATE_LIMIT",
+        },
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuDH;;GAEG;AACH,MAAM,UAAU,UAAU,CAAI,IAK7B;IACC,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtC,aAAa,EAAE,IAAI,CAAC,aAAa;KAClC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,IAKzB;IACC,OAAO;QACL,KAAK,EAAE;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY;SACxD;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * @markcolabs/mcp — MCP server entrypoint.
+ *
+ * Sprint 136 v0.1.0 (per ADR-0039). Registers:
+ *   - 5 tools:
+ *       dc.calculator.mortgage.monthlyPayment       (S135 Item 5)
+ *       dc.calculator.compoundInterest.futureValue  (S135 Item 5)
+ *       dc.calculator.401k.projection               (S136 Item 3)
+ *       dc.calculator.socialSecurity.estimate       (S136 Item 3)
+ *       dc.calculator.paycheck.netPay               (S136 Item 3)
+ *   - 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).
+ */
+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 * 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 * from "./envelope.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}