@trailfolio/mcp 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trailfolio
+
+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,86 @@
+# @trailfolio/mcp
+
+Canadian financial calculator tools for AI assistants, via the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+Mortgage affordability, income tax, closing costs, Canada Child Benefit, Smith Manoeuvre, and more — powered by the [Trailfolio](https://trailfolio.com) API.
+
+## Setup
+
+### 1. Get an API key
+
+Create one at [trailfolio.com/settings/api-keys](https://trailfolio.com/settings/api-keys).
+
+### 2. Configure your MCP client
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "Trailfolio": {
+      "command": "npx",
+      "args": ["-y", "@trailfolio/mcp"],
+      "env": {
+        "TRAILFOLIO_API_KEY": "tf_live_..."
+      }
+    }
+  }
+}
+```
+
+**Windows:** Use `cmd` as the command:
+
+```json
+{
+  "mcpServers": {
+    "Trailfolio": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@trailfolio/mcp"],
+      "env": {
+        "TRAILFOLIO_API_KEY": "tf_live_..."
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+```bash
+claude mcp add trailfolio -- npx -y @trailfolio/mcp
+```
+
+Then set your API key as an environment variable or in your shell profile:
+
+```bash
+export TRAILFOLIO_API_KEY="tf_live_..."
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TRAILFOLIO_API_KEY` | Yes | — | API key from [trailfolio.com/settings/api-keys](https://trailfolio.com/settings/api-keys) |
+| `TRAILFOLIO_API_URL` | No | `https://api.trailfolio.com/v1` | API base URL override |
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `calculate_mortgage_affordability` | Max purchase price with stress test (CMHC/OSFI rules) |
+| `calculate_buyer_closing_costs` | Land transfer tax, CMHC insurance, legal fees |
+| `calculate_seller_closing_costs` | Realtor commission, legal fees, discharge fee |
+| `calculate_canadian_income_tax` | Federal + provincial tax, CPP/EI, dividends, capital gains |
+| `get_tax_constants` | CPP/EI rates, RRSP/FHSA limits, dividend gross-up rates |
+| `calculate_mortgage_timeline` | Amortization schedule with renewal/refinance events |
+| `calculate_canada_child_benefit` | CCB monthly payments with income phaseout |
+| `calculate_heloc_interest` | Interest split: tax-deductible vs personal |
+| `calculate_smith_manoeuvre` | Convert mortgage debt to deductible investment debt |
+
+All tools use `snake_case` parameters (MCP convention). The server translates to `camelCase` for the API.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+/**
+ * HTTP client for the Trailfolio API.
+ */
+export type ApiResponse = Record<string, any>;
+export declare class TrailfolioAPIError extends Error {
+    readonly statusCode: number;
+    readonly detail: string;
+    constructor(statusCode: number, detail: string);
+}
+export declare class TrailfolioClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private get authHeaders();
+    post(path: string, body: Record<string, unknown>): Promise<ApiResponse>;
+    get(path: string): Promise<ApiResponse>;
+}

package/dist/client.js

@@ -0,0 +1,78 @@
+/**
+ * HTTP client for the Trailfolio API.
+ */
+export class TrailfolioAPIError extends Error {
+    statusCode;
+    detail;
+    constructor(statusCode, detail) {
+        super(`API error ${statusCode}: ${detail}`);
+        this.statusCode = statusCode;
+        this.detail = detail;
+        this.name = "TrailfolioAPIError";
+    }
+}
+export class TrailfolioClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    get authHeaders() {
+        return { "X-API-Key": this.apiKey };
+    }
+    async post(path, body) {
+        const payload = Object.fromEntries(Object.entries(body).filter(([, v]) => v !== undefined && v !== null));
+        const url = `${this.baseUrl}/calculators/${path}`;
+        let res;
+        try {
+            res = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...this.authHeaders,
+                },
+                body: JSON.stringify(payload),
+            });
+        }
+        catch (err) {
+            throw new TrailfolioAPIError(0, `Connection error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!res.ok) {
+            let detail;
+            try {
+                const json = await res.json();
+                detail = json.detail ?? res.statusText;
+            }
+            catch {
+                detail = res.statusText;
+            }
+            throw new TrailfolioAPIError(res.status, detail);
+        }
+        return res.json();
+    }
+    async get(path) {
+        const url = `${this.baseUrl}/calculators/${path}`;
+        let res;
+        try {
+            res = await fetch(url, {
+                headers: this.authHeaders,
+            });
+        }
+        catch (err) {
+            throw new TrailfolioAPIError(0, `Connection error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!res.ok) {
+            let detail;
+            try {
+                const json = await res.json();
+                detail = json.detail ?? res.statusText;
+            }
+            catch {
+                detail = res.statusText;
+            }
+            throw new TrailfolioAPIError(res.status, detail);
+        }
+        return res.json();
+    }
+}

package/dist/formatting.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Response formatters — convert API JSON responses to structured text for LLM consumption.
+ */
+import type { ApiResponse } from "./client.js";
+export declare function formatAffordability(data: ApiResponse): string;
+export declare function formatBuyerClosingCosts(data: ApiResponse): string;
+export declare function formatSellerClosingCosts(data: ApiResponse): string;
+export declare function formatMortgageTimeline(data: ApiResponse): string;
+export declare function formatIncomeTax(data: ApiResponse): string;
+export declare function formatTaxConstants(data: ApiResponse): string;
+export declare function formatCCB(data: ApiResponse): string;
+export declare function formatTFSARoom(data: ApiResponse): string;
+export declare function formatHELOC(data: ApiResponse): string;
+export declare function formatSmithManoeuvre(data: ApiResponse): string;

package/dist/formatting.js

@@ -0,0 +1,336 @@
+/**
+ * Response formatters — convert API JSON responses to structured text for LLM consumption.
+ */
+function fmt(n) {
+    if (typeof n !== "number" || !Number.isFinite(n))
+        return "N/A";
+    return n.toLocaleString("en-CA", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}
+function pct(n) {
+    if (typeof n !== "number" || !Number.isFinite(n))
+        return "N/A";
+    return `${(n * 100).toFixed(2)}%`;
+}
+function appendWarnings(lines, data) {
+    const warnings = data.warnings;
+    if (warnings && warnings.length > 0) {
+        lines.push("", "### Warnings");
+        for (const w of warnings) {
+            lines.push(`- ${w}`);
+        }
+    }
+}
+export function formatAffordability(data) {
+    const lines = [
+        "## Mortgage Affordability Results",
+        "",
+        `Maximum Purchase Price: $${fmt(data.maximumPurchasePrice)}`,
+        `Maximum Mortgage: $${fmt(data.maximumMortgageAmount)}`,
+        `Monthly Mortgage Payment: $${fmt(data.monthlyMortgagePayment)}`,
+        `Total Monthly Housing Cost: $${fmt(data.totalMonthlyHousingCost)}`,
+        "",
+        "### Monthly Breakdown",
+        `  Mortgage: $${fmt(data.monthlyMortgagePayment)}`,
+        `  Property Tax: $${fmt(data.monthlyPropertyTax)}`,
+        `  Heating: $${fmt(data.monthlyHeating)}`,
+        `  Condo Fees: $${fmt(data.monthlyCondoFees)}`,
+        "",
+        "### Stress Test",
+        `Stress Test Rate: ${pct(data.stressTestRate)}`,
+        `Stress Test Payment: $${fmt(data.stressTestPayment)}`,
+        `Passes Stress Test: ${data.passesStressTest ? "Yes" : "No"}`,
+        "",
+        "### Debt Service Ratios",
+        `GDS Ratio: ${pct(data.gdsRatio)} (limit ${pct(data.gdsLimit)})`,
+        `TDS Ratio: ${pct(data.tdsRatio)} (limit ${pct(data.tdsLimit)})`,
+    ];
+    if (data.requiresCmhcInsurance) {
+        lines.push("", "### CMHC Insurance (down payment < 20%)", `Premium Rate: ${pct(data.cmhcPremiumRate)}`, `Premium Amount: $${fmt(data.cmhcPremiumAmount)}`, `Total Mortgage with Insurance: $${fmt(data.totalMortgageWithInsurance)}`);
+    }
+    appendWarnings(lines, data);
+    return lines.join("\n");
+}
+export function formatBuyerClosingCosts(data) {
+    const lines = [
+        "## Buyer Closing Costs",
+        "",
+        `Purchase Price: $${fmt(data.purchasePrice)}`,
+        `Down Payment: $${fmt(data.downPayment)} (${pct(data.downPaymentPercent)})`,
+        `Mortgage Amount: $${fmt(data.mortgageAmount)}`,
+        "",
+        "### Closing Cost Breakdown",
+        `Land Transfer Tax: $${fmt(data.landTransferTax)}`,
+        `Legal Fees: $${fmt(data.legalFees)}`,
+        `Title Insurance: $${fmt(data.titleInsurance)}`,
+        `Home Inspection: $${fmt(data.homeInspection)}`,
+    ];
+    if (data.cmhcInsurance > 0) {
+        lines.push(`CMHC Insurance: $${fmt(data.cmhcInsurance)} (rate: ${pct(data.cmhcRate)})`);
+    }
+    lines.push("", "### Totals", `Total Closing Costs: $${fmt(data.totalClosingCosts)}`, `Total Cash Needed: $${fmt(data.totalCashNeeded)} (down payment + closing costs)`);
+    const ltt = data.landTransferTaxDetails;
+    if (ltt) {
+        lines.push("", `### Land Transfer Tax Details (${ltt.province})`);
+        if (ltt.name)
+            lines.push(`Tax Name: ${ltt.name}`);
+        if (ltt.gross != null)
+            lines.push(`Gross: $${fmt(ltt.gross)}`);
+        if (ltt.exemption != null && ltt.exemption > 0)
+            lines.push(`Exemption: -$${fmt(ltt.exemption)}`);
+        if (ltt.note)
+            lines.push(`Note: ${ltt.note}`);
+    }
+    appendWarnings(lines, data);
+    return lines.join("\n");
+}
+export function formatSellerClosingCosts(data) {
+    const lines = [
+        "## Seller Closing Costs",
+        "",
+        `Sale Price: $${fmt(data.salePrice)}`,
+        "",
+        "### Commission",
+        `Commission: $${fmt(data.commission)}`,
+        `Structure: ${data.commissionRateDescription}`,
+        `Tax on Commission: $${fmt(data.commissionTax)}`,
+        `Total Commission: $${fmt(data.commissionTotal)}`,
+        "",
+        "### Other Costs",
+        `Legal Fees: $${fmt(data.legalFees)}`,
+        `Mortgage Discharge: $${fmt(data.mortgageDischarge)}`,
+        "",
+        "### Totals",
+        `Total Closing Costs: $${fmt(data.totalClosingCosts)}`,
+        `Net Proceeds: $${fmt(data.netProceeds)}`,
+    ];
+    appendWarnings(lines, data);
+    return lines.join("\n");
+}
+export function formatMortgageTimeline(data) {
+    const lines = [
+        "## Mortgage Timeline",
+        "",
+        `Principal: $${fmt(data.initialPrincipal)}`,
+        `Initial Rate: ${pct(data.initialRate)}`,
+        `Term: ${data.initialTermYears} years`,
+        `Amortization: ${data.initialAmortizationYears} years`,
+        `Payment: $${fmt(data.initialPeriodicPayment)} (${data.paymentFrequency})`,
+    ];
+    const terms = data.terms;
+    if (terms && terms.length > 0) {
+        lines.push("", "### Terms");
+        for (const term of terms) {
+            const endLabel = term.endYear != null ? `Year ${term.endYear}` : "End";
+            lines.push("", `**Term ${term.termNumber}** (Year ${term.startYear}–${endLabel})` +
+                (term.eventType ? ` [${term.eventType}]` : ""), `  Rate: ${pct(term.annualRate)} | Payment: $${fmt(term.periodicPayment)}`, `  Balance: $${fmt(term.initialBalance)} → $${fmt(term.finalBalance)}`, `  Principal: $${fmt(term.totalPrincipal)} | Interest: $${fmt(term.totalInterest)}`);
+        }
+    }
+    const totals = data.totals;
+    if (totals) {
+        lines.push("", "### Lifetime Totals", `Total Principal: $${fmt(totals.totalPrincipal)}`, `Total Interest: $${fmt(totals.totalInterest)}`, `Total Payments: $${fmt(totals.totalPayment)}`, `Actual Amortization: ${totals.actualAmortizationYears} years`);
+        if (totals.interestSavingsVsOriginal > 0) {
+            lines.push(`Interest Savings vs Original: $${fmt(totals.interestSavingsVsOriginal)}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatIncomeTax(data) {
+    const summary = data.summary;
+    const taxes = data.taxes;
+    const payroll = data.payroll;
+    const income = data.income;
+    const deductions = data.deductions;
+    const lines = [
+        `## Canadian Income Tax — ${data.province} ${data.year}`,
+        "",
+        "### Summary",
+        `Taxable Income: $${fmt(summary.taxableIncome)}`,
+        `Total Tax: $${fmt(taxes.totalTax)}`,
+        `Effective Rate: ${pct(summary.effectiveRate)}`,
+        `Marginal Rate: ${pct(summary.marginalRate)}`,
+        `After-Tax Income: $${fmt(summary.afterTaxIncome)}`,
+        `Take-Home Income: $${fmt(summary.takeHomeIncome)}`,
+        "",
+        "### Income Breakdown",
+        `Total Income: $${fmt(income.totalIncome)}`,
+    ];
+    if (income.employmentIncome > 0)
+        lines.push(`  Employment: $${fmt(income.employmentIncome)}`);
+    if (income.selfEmploymentIncome > 0)
+        lines.push(`  Self-Employment: $${fmt(income.selfEmploymentIncome)}`);
+    if (income.interestIncome > 0)
+        lines.push(`  Interest: $${fmt(income.interestIncome)}`);
+    if (income.eligibleDividendsActual > 0)
+        lines.push(`  Eligible Dividends: $${fmt(income.eligibleDividendsActual)} (grossed-up: $${fmt(income.eligibleDividendsGrossed)})`);
+    if (income.ineligibleDividendsActual > 0)
+        lines.push(`  Ineligible Dividends: $${fmt(income.ineligibleDividendsActual)} (grossed-up: $${fmt(income.ineligibleDividendsGrossed)})`);
+    if (income.capitalGainsTotal > 0)
+        lines.push(`  Capital Gains: $${fmt(income.capitalGainsTotal)} (taxable: $${fmt(income.taxableCapitalGains)}, inclusion rate: ${pct(income.capitalGainsInclusionRate)})`);
+    if (income.rentalIncome > 0)
+        lines.push(`  Rental: $${fmt(income.rentalIncome)}`);
+    if (income.otherIncome > 0)
+        lines.push(`  Other: $${fmt(income.otherIncome)}`);
+    if (deductions.totalDeductions > 0) {
+        lines.push("", "### Deductions");
+        if (deductions.rrspDeduction > 0)
+            lines.push(`  RRSP: $${fmt(deductions.rrspDeduction)}`);
+        if (deductions.fhsaDeduction > 0)
+            lines.push(`  FHSA: $${fmt(deductions.fhsaDeduction)}`);
+        lines.push(`  Total Deductions: $${fmt(deductions.totalDeductions)}`);
+    }
+    lines.push("", "### Tax Breakdown", `Federal Tax: $${fmt(taxes.federalTax)}`, `Provincial Tax: $${fmt(taxes.provincialTax)}`, `Total Tax: $${fmt(taxes.totalTax)}`);
+    lines.push("", "### Payroll Deductions", `CPP: $${fmt(payroll.cppContribution)}`);
+    if (payroll.cpp2Contribution > 0)
+        lines.push(`CPP2: $${fmt(payroll.cpp2Contribution)}`);
+    lines.push(`EI: $${fmt(payroll.eiPremium)}`);
+    if (payroll.qpipPremium > 0)
+        lines.push(`QPIP: $${fmt(payroll.qpipPremium)}`);
+    lines.push(`Total Payroll: $${fmt(payroll.totalPayrollDeductions)}`);
+    appendWarnings(lines, data);
+    return lines.join("\n");
+}
+export function formatTaxConstants(data) {
+    const lines = [
+        `## Canadian Tax Constants — ${data.year}`,
+        "",
+        "### CPP (Canada Pension Plan)",
+        `Employee Rate: ${pct(data.cppRateEmployee)}`,
+        `Self-Employed Rate: ${pct(data.cppRateSelfEmployed)}`,
+        `YMPE: $${fmt(data.cppYmpe)}`,
+        `Basic Exemption: $${fmt(data.cppYbe)}`,
+        `Max Contribution: $${fmt(data.cppMaxContribution)}`,
+        "",
+        "### CPP2",
+        `Rate: ${pct(data.cpp2Rate)}`,
+        `YAMPE: $${fmt(data.cpp2Yampe)}`,
+        `Max Contribution: $${fmt(data.cpp2MaxContribution)}`,
+        "",
+        "### EI (Employment Insurance)",
+        `Rate: ${pct(data.eiRate)}`,
+        `Max Insurable Earnings: $${fmt(data.eiMaxInsurable)}`,
+        `Max Premium: $${fmt(data.eiMaxPremium)}`,
+        "",
+        "### Savings Limits",
+        `RRSP Limit: $${fmt(data.rrspLimit)}`,
+        `FHSA Annual Limit: $${fmt(data.fhsaAnnualLimit)}`,
+        `FHSA Lifetime Limit: $${fmt(data.fhsaLifetimeLimit)}`,
+        "",
+        "### Dividends",
+        `Eligible Gross-Up: ${pct(data.eligibleDividendGrossup)}`,
+        `Eligible DTC (Federal): ${pct(data.eligibleDividendDtcFederal)}`,
+        `Ineligible Gross-Up: ${pct(data.ineligibleDividendGrossup)}`,
+        `Ineligible DTC (Federal): ${pct(data.ineligibleDividendDtcFederal)}`,
+        "",
+        "### Capital Gains",
+        `Inclusion Rate: ${pct(data.capitalGainsInclusionRate)}`,
+    ];
+    if (data.capitalGainsTieredThreshold) {
+        lines.push(`Tiered Threshold: $${fmt(data.capitalGainsTieredThreshold)}`);
+    }
+    return lines.join("\n");
+}
+export function formatCCB(data) {
+    const lines = [
+        `## Canada Child Benefit — ${data.benefitYear}`,
+        "",
+        "### Family",
+        `Adjusted Family Net Income: $${fmt(data.adjustedFamilyNetIncome)}`,
+        `Children Under 6: ${data.childrenUnder6}`,
+        `Children 6-17: ${data.children6To17}`,
+        `Total Children: ${data.totalChildren}`,
+    ];
+    if (data.childrenWithDisability > 0) {
+        lines.push(`Children with Disability: ${data.childrenWithDisability}`);
+    }
+    lines.push("", "### Base Benefits (Annual)", `Under 6: $${fmt(data.baseBenefitUnder6)}`, `Ages 6-17: $${fmt(data.baseBenefit6To17)}`, `Total Base: $${fmt(data.totalBaseBenefit)}`);
+    if (data.childDisabilityBenefit > 0) {
+        lines.push(`Child Disability Benefit: $${fmt(data.childDisabilityBenefit)} (not income-tested)`);
+    }
+    if (data.totalReduction > 0) {
+        lines.push("", "### Income Phaseout", `Threshold 1: $${fmt(data.threshold1)} | Threshold 2: $${fmt(data.threshold2)}`, `Reduction Rate 1: ${pct(data.phaseoutRate1)} | Reduction: $${fmt(data.reductionFromRate1)}`, `Reduction Rate 2: ${pct(data.phaseoutRate2)} | Reduction: $${fmt(data.reductionFromRate2)}`, `Total Reduction: $${fmt(data.totalReduction)}`);
+    }
+    lines.push("", "### Final Benefit", `Annual CCB: $${fmt(data.annualCCB)}`, `Monthly CCB: $${fmt(data.monthlyCCB)}`);
+    appendWarnings(lines, data);
+    return lines.join("\n");
+}
+export function formatTFSARoom(data) {
+    const lines = [
+        "## TFSA Contribution Room",
+        "",
+        `**Available Room:** $${fmt(data.availableRoom)}`,
+        `**Total Room Accumulated:** $${fmt(data.totalContributionRoom)}`,
+        `**Total Contributed:** $${fmt(data.totalContributions)}`,
+        `**Total Withdrawn:** $${fmt(data.totalWithdrawals)}`,
+        `**Current Balance:** $${fmt(data.currentBalance)}`,
+        "",
+        `**First Eligible Year:** ${data.firstEligibleYear}`,
+        `**Eligible Years:** ${data.eligibleYears}`,
+    ];
+    const overContribution = data.overContributionAmount;
+    if (overContribution > 0) {
+        lines.push("", "### ⚠️ Over-Contribution Warning", `**Excess Amount:** $${fmt(overContribution)}`, `**Estimated Annual Penalty:** $${fmt(data.estimatedAnnualPenalty)} (1% per month)`, "Withdraw the excess immediately to stop penalties.");
+    }
+    const breakdown = data.yearlyBreakdown;
+    if (breakdown && breakdown.length > 0) {
+        lines.push("", "### Year-by-Year Breakdown", "| Year | Limit | Room Added | Contributed | Withdrawn | Restored | Available |", "|------|-------|-----------|-------------|-----------|----------|-----------|");
+        for (const row of breakdown) {
+            if (!row.eligible)
+                continue;
+            lines.push(`| ${row.year} | $${fmt(row.annualLimit)} | $${fmt(row.roomAdded)} | $${fmt(row.contributions)} | $${fmt(row.withdrawals)} | $${fmt(row.roomFromWithdrawals)} | $${fmt(row.availableRoom)} |`);
+        }
+    }
+    appendWarnings(lines, data);
+    return lines.join("\n");
+}
+export function formatHELOC(data) {
+    const lines = [
+        "## HELOC Interest Calculation",
+        "",
+        `Effective Rate: ${pct(data.effectiveRate)}`,
+        "",
+        "### Balances",
+        `Total Balance: $${fmt(data.totalBalance)}`,
+        `Investment (Deductible): $${fmt(data.investmentBalance)}`,
+        `Personal (Non-Deductible): $${fmt(data.personalBalance)}`,
+        `Available Credit: $${fmt(data.availableCredit)}`,
+        "",
+        "### Interest",
+        `Monthly Interest: $${fmt(data.monthlyInterest)}`,
+        `Annual Interest: $${fmt(data.annualInterest)}`,
+        `Tax-Deductible Interest: $${fmt(data.deductibleInterest)}`,
+        `Non-Deductible Interest: $${fmt(data.nonDeductibleInterest)}`,
+        `Deductible Ratio: ${pct(data.deductibleRatio)}`,
+    ];
+    return lines.join("\n");
+}
+export function formatSmithManoeuvre(data) {
+    const lines = [
+        "## Smith Manoeuvre Projection",
+        "",
+        "### Summary",
+        `Years to Mortgage Payoff: ${data.yearsToMortgagePayoff}`,
+        `Total Tax Savings: $${fmt(data.totalTaxSavings)}`,
+        `Final Portfolio Value: $${fmt(data.finalPortfolioValue)}`,
+        `Final HELOC Balance: $${fmt(data.finalHelocBalance)}`,
+        `Net Benefit: $${fmt(data.netBenefit)}`,
+        "",
+        "### Comparison",
+        `Traditional Net Worth: $${fmt(data.traditionalNetWorth)}`,
+        `Smith Manoeuvre Net Worth: $${fmt(data.smithManoeuvreNetWorth)}`,
+        `Advantage: $${fmt(data.advantage)}`,
+        `ROI on Borrowed Capital: ${pct(data.roiOnBorrowedCapital)}`,
+    ];
+    const yearly = data.yearlyResults;
+    if (yearly && yearly.length > 0) {
+        lines.push("", "### Year-by-Year Highlights");
+        lines.push("| Year | Mortgage | HELOC | Portfolio | Tax Refund | Net Worth |", "|------|----------|-------|-----------|------------|-----------|");
+        const milestones = [1, 5, 10, 15, 20, 25, 30];
+        for (const yr of yearly) {
+            if (milestones.includes(yr.year) ||
+                yr.year === yearly[yearly.length - 1].year) {
+                lines.push(`| ${yr.year} | $${fmt(yr.mortgageBalance)} | $${fmt(yr.helocBalance)} | $${fmt(yr.portfolioValue)} | $${fmt(yr.taxRefund)} | $${fmt(yr.netWorth)} |`);
+            }
+        }
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Trailfolio MCP Server — Canadian financial calculator tools for AI assistants.
+ *
+ * Environment variables:
+ *   TRAILFOLIO_API_KEY  - API key for authenticating with the Trailfolio API (required)
+ *   TRAILFOLIO_API_URL  - Base URL override (default: https://api.trailfolio.com/v1)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * Trailfolio MCP Server — Canadian financial calculator tools for AI assistants.
+ *
+ * Environment variables:
+ *   TRAILFOLIO_API_KEY  - API key for authenticating with the Trailfolio API (required)
+ *   TRAILFOLIO_API_URL  - Base URL override (default: https://api.trailfolio.com/v1)
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TrailfolioClient } from "./client.js";
+import { registerTools } from "./tools.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const DEFAULT_API_URL = "https://api.trailfolio.com/v1";
+const apiKey = process.env.TRAILFOLIO_API_KEY;
+const baseUrl = process.env.TRAILFOLIO_API_URL ?? DEFAULT_API_URL;
+if (!apiKey) {
+    console.error("Error: TRAILFOLIO_API_KEY is required. Get one at https://trailfolio.com/settings/api-keys");
+    process.exit(1);
+}
+const server = new McpServer({
+    name: "Trailfolio",
+    version: pkg.version,
+});
+const client = new TrailfolioClient(baseUrl, apiKey);
+registerTools(server, client);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP tool definitions — register all Trailfolio calculator tools.
+ *
+ * Each tool maps snake_case MCP params → camelCase API body, calls the API,
+ * and formats the response as structured text for LLM consumption.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TrailfolioClient } from "./client.js";
+export declare function registerTools(server: McpServer, client: TrailfolioClient): void;

package/dist/tools.js

@@ -0,0 +1,325 @@
+/**
+ * MCP tool definitions — register all Trailfolio calculator tools.
+ *
+ * Each tool maps snake_case MCP params → camelCase API body, calls the API,
+ * and formats the response as structured text for LLM consumption.
+ */
+import { z } from "zod";
+import { TrailfolioAPIError } from "./client.js";
+import { formatAffordability, formatBuyerClosingCosts, formatCCB, formatHELOC, formatIncomeTax, formatMortgageTimeline, formatSellerClosingCosts, formatSmithManoeuvre, formatTaxConstants, formatTFSARoom, } from "./formatting.js";
+// ── Result helpers ──────────────────────────────────────────────────
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+function errorResult(err) {
+    const message = err instanceof TrailfolioAPIError
+        ? `API Error (${err.statusCode}): ${err.detail}`
+        : `Error: ${err instanceof Error ? err.message : String(err)}`;
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function parseJsonParam(value, paramName) {
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed)) {
+            return errorResult(new Error(`${paramName} must be a valid JSON array.`));
+        }
+        return parsed;
+    }
+    catch {
+        return errorResult(new Error(`${paramName} must be a valid JSON array.`));
+    }
+}
+// ── Schemas ─────────────────────────────────────────────────────────
+const provinceCode = z
+    .string()
+    .default("BC")
+    .describe("Two-letter province code: BC, AB, SK, MB, ON, QC, NB, NS, PE, NL");
+const schemas = {
+    affordability: {
+        gross_annual_income: z.number().describe("Gross annual household income in dollars"),
+        down_payment: z.number().describe("Available down payment in dollars"),
+        interest_rate: z.number().describe("Mortgage interest rate as decimal (e.g., 0.055 for 5.5%)"),
+        monthly_debts: z.number().default(0).describe("Total monthly debt payments (car loans, credit cards, etc.)"),
+        property_tax_annual: z.number().default(3000).describe("Estimated annual property tax (default $3,000)"),
+        heating_cost_monthly: z.number().default(100).describe("Estimated monthly heating cost (default $100)"),
+        condo_fees_monthly: z.number().default(0).describe("Monthly condo/strata fees if applicable"),
+        amortization_years: z.number().int().default(25).describe("Amortization period in years (5-30, max 25 if down payment < 20%)"),
+    },
+    buyerClosingCosts: {
+        purchase_price: z.number().describe("Property purchase price in dollars"),
+        province: provinceCode,
+        down_payment_percent: z.number().default(0.2).describe("Down payment as decimal (e.g., 0.10 for 10%, default 0.20)"),
+        city: z.string().optional().describe("City for municipal taxes (e.g., 'Toronto' for Toronto MLTT)"),
+        is_first_time_buyer: z.boolean().default(false).describe("Whether buyer qualifies for first-time buyer exemptions"),
+        legal_fees: z.number().default(1500).describe("Legal/notary fees (default $1,500)"),
+        title_insurance: z.number().default(300).describe("Title insurance cost (default $300)"),
+        home_inspection: z.number().default(500).describe("Home inspection cost (default $500)"),
+    },
+    sellerClosingCosts: {
+        sale_price: z.number().describe("Property sale price in dollars"),
+        province: provinceCode,
+        region: z.string().optional().describe("Regional commission variation (SK only: 'standard' or 'prince_albert')"),
+        commission_rate: z.number().optional().describe("Custom commission rate as decimal (e.g., 0.04 for 4%), overrides province default"),
+        flat_fee: z.number().optional().describe("Flat commission fee in dollars (overrides percentage-based commission)"),
+        buyer_agent_split: z.number().default(0.5).describe("Buyer agent's share of commission (default 0.5 = 50%)"),
+        legal_fees: z.number().default(1500).describe("Legal fees (default $1,500)"),
+        mortgage_discharge: z.number().default(350).describe("Mortgage discharge fee (default $350)"),
+    },
+    incomeTax: {
+        province: z.string().describe("Two-letter province code (e.g., BC, ON, QC)"),
+        income_sources_json: z.string().describe('JSON array of income sources. Each source: {"incomeType": "employment"|"self_employment"|' +
+            '"capital_gains"|"eligible_dividends"|"ineligible_dividends"|"interest"|"rental"|"other", ' +
+            '"grossAmount": number}. For capital_gains use "proceeds" and "adjustedCostBase" instead. ' +
+            "For self_employment, optionally include \"businessExpenses\". " +
+            'Example: \'[{"incomeType": "employment", "grossAmount": 85000}]\''),
+        year: z.number().int().default(2025).describe("Tax year (default 2025)"),
+        rrsp_contribution: z.number().default(0).describe("RRSP contribution to deduct"),
+        fhsa_contribution: z.number().default(0).describe("FHSA contribution to deduct"),
+    },
+    taxConstants: {
+        year: z.number().int().default(2025).describe("Tax year (2000-2030, default 2025)"),
+    },
+    mortgage: {
+        principal: z.number().describe("Initial mortgage principal in dollars"),
+        annual_rate: z.number().describe("Annual interest rate as decimal (e.g., 0.05 for 5%)"),
+        amortization_years: z.number().int().describe("Amortization period in years (1-35)"),
+        term_years: z.number().int().default(5).describe("Fixed-rate term in years (1-10, default 5)"),
+        payment_frequency: z.string().default("monthly").describe('Payment frequency: "monthly", "biweekly", "weekly", "accelerated_biweekly", "accelerated_weekly", "semi_monthly"'),
+        events_json: z.string().optional().describe("Optional JSON array of renewal/refinance events. Each event: " +
+            '{"type": "renewal"|"refinance", "afterYears": number, "newRate": number}. ' +
+            'Refinance can include "newAmortizationYears" and "lumpSumPayment". ' +
+            'Example: \'[{"type": "renewal", "afterYears": 5, "newRate": 0.045}]\''),
+    },
+    ccb: {
+        adjusted_family_net_income: z.number().describe("Adjusted Family Net Income (AFNI) from previous year's tax return"),
+        children_under_6: z.number().int().default(0).describe("Number of children under age 6"),
+        children_6_to_17: z.number().int().default(0).describe("Number of children aged 6-17"),
+        children_with_disability: z.number().int().default(0).describe("Number of children eligible for the disability tax credit"),
+        benefit_year: z.string().default("2025-2026").describe('Benefit year (July-June): "2025-2026", "2024-2025", "2023-2024", etc.'),
+    },
+    tfsaRoom: {
+        birth_year: z.number().int().describe("Year of birth (used to determine eligibility at age 18)"),
+        current_year: z.number().int().default(2026).describe("Year to calculate room for (default 2026)"),
+        tax_resident_since: z.number().int().optional().describe("Year became Canadian tax resident (omit if always resident)"),
+        contributions_json: z.string().optional().describe('JSON object of contributions by year. Example: \'{"2020": 6000, "2021": 6000}\''),
+        withdrawals_json: z.string().optional().describe('JSON object of withdrawals by year. Example: \'{"2023": 5000}\''),
+    },
+    heloc: {
+        credit_limit: z.number().describe("Maximum HELOC credit limit in dollars"),
+        prime_rate: z.number().describe("Current Bank of Canada prime rate as decimal (e.g., 0.0545 for 5.45%)"),
+        investment_balance: z.number().default(0).describe("Balance used for investments (tax-deductible portion)"),
+        personal_balance: z.number().default(0).describe("Balance used for personal purposes (non-deductible)"),
+        prime_spread: z.number().default(0.005).describe("Rate spread over prime (default 0.005 = 0.5%)"),
+    },
+    smithManoeuvre: {
+        property_value: z.number().describe("Current property value in dollars"),
+        mortgage_balance: z.number().describe("Current mortgage balance (must be <= 80% of property value)"),
+        mortgage_rate: z.number().describe("Annual mortgage interest rate as decimal (e.g., 0.05 for 5%)"),
+        amortization_years: z.number().int().describe("Remaining amortization period in years"),
+        heloc_rate: z.number().describe("HELOC annual interest rate as decimal (Prime + spread)"),
+        marginal_tax_rate: z.number().describe("Marginal tax rate as decimal (e.g., 0.43 for 43%)"),
+        investment_return: z.number().default(0.07).describe("Expected annual investment return as decimal (default 0.07 = 7%)"),
+        dividend_yield: z.number().default(0.03).describe("Expected dividend yield as decimal (default 0.03 = 3%)"),
+        payment_frequency: z.string().default("monthly").describe("Mortgage payment frequency (default 'monthly')"),
+        projection_years: z.number().int().default(25).describe("Number of years to project (default 25, max 30)"),
+    },
+};
+/** Register a simple POST tool: snake_case params → camelCase body → format. */
+function registerPostTool(server, client, name, description, inputSchema, endpoint, mapParams, format) {
+    server.registerTool(name, { description, inputSchema }, async (params) => {
+        try {
+            const result = await client.post(endpoint, mapParams(params));
+            return textResult(format(result));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+export function registerTools(server, client) {
+    // ── Mortgage Affordability ──────────────────────────────────────────
+    registerPostTool(server, client, "calculate_mortgage_affordability", "Calculate maximum affordable home price with Canadian mortgage stress test (CMHC/OSFI). " +
+        "Applies stress test: qualify at higher of 5.25% or contract rate + 2%. " +
+        "GDS ratio must be <= 39%, TDS ratio <= 44%.", schemas.affordability, "affordability", (p) => ({
+        grossAnnualIncome: p.gross_annual_income,
+        downPayment: p.down_payment,
+        interestRate: p.interest_rate,
+        monthlyDebts: p.monthly_debts,
+        propertyTaxAnnual: p.property_tax_annual,
+        heatingCostMonthly: p.heating_cost_monthly,
+        condoFeesMonthly: p.condo_fees_monthly,
+        amortizationYears: p.amortization_years,
+    }), formatAffordability);
+    // ── Buyer Closing Costs ─────────────────────────────────────────────
+    registerPostTool(server, client, "calculate_buyer_closing_costs", "Calculate all closing costs for a property buyer in Canada. " +
+        "Includes land transfer tax (province-specific), CMHC insurance if down payment < 20%, " +
+        "legal fees, title insurance, and home inspection.", schemas.buyerClosingCosts, "closing-costs/buyer", (p) => ({
+        purchasePrice: p.purchase_price,
+        province: p.province,
+        downPaymentPercent: p.down_payment_percent,
+        city: p.city,
+        isFirstTimeBuyer: p.is_first_time_buyer,
+        legalFees: p.legal_fees,
+        titleInsurance: p.title_insurance,
+        homeInspection: p.home_inspection,
+    }), formatBuyerClosingCosts);
+    // ── Seller Closing Costs ────────────────────────────────────────────
+    registerPostTool(server, client, "calculate_seller_closing_costs", "Calculate all closing costs for a property seller in Canada. " +
+        "Includes realtor commission (province-specific tiered rates), legal fees, " +
+        "and mortgage discharge fee.", schemas.sellerClosingCosts, "closing-costs/seller", (p) => ({
+        salePrice: p.sale_price,
+        province: p.province,
+        region: p.region,
+        commissionRate: p.commission_rate,
+        flatFee: p.flat_fee,
+        buyerAgentSplit: p.buyer_agent_split,
+        legalFees: p.legal_fees,
+        mortgageDischarge: p.mortgage_discharge,
+    }), formatSellerClosingCosts);
+    // ── Canada Child Benefit ────────────────────────────────────────────
+    registerPostTool(server, client, "calculate_canada_child_benefit", "Calculate the Canada Child Benefit (CCB) — monthly tax-free payments to eligible families. " +
+        "Benefits are reduced based on family income using a two-tier phaseout. " +
+        "The Child Disability Benefit is NOT reduced by income.", schemas.ccb, "ccb", (p) => ({
+        adjustedFamilyNetIncome: p.adjusted_family_net_income,
+        childrenUnder6: p.children_under_6,
+        children6To17: p.children_6_to_17,
+        childrenWithDisability: p.children_with_disability,
+        benefitYear: p.benefit_year,
+    }), formatCCB);
+    // ── TFSA Contribution Room (custom: JSON parsing) ─────────────────
+    server.registerTool("calculate_tfsa_contribution_room", {
+        description: "Calculate TFSA contribution room based on birth year, residency, contributions, and withdrawals. " +
+            "Accounts for annual limits (2009-2026), age 18 eligibility, tax residency, " +
+            "withdrawal room restoration (Jan 1 of following year), and over-contribution penalties (1% per month).",
+        inputSchema: schemas.tfsaRoom,
+    }, async (params) => {
+        const body = {
+            birthYear: params.birth_year,
+            currentYear: params.current_year,
+        };
+        if (params.tax_resident_since != null) {
+            body.taxResidentSince = params.tax_resident_since;
+        }
+        if (params.contributions_json) {
+            try {
+                body.contributionsByYear = JSON.parse(params.contributions_json);
+            }
+            catch {
+                return errorResult(new Error("contributions_json must be a valid JSON object."));
+            }
+        }
+        if (params.withdrawals_json) {
+            try {
+                body.withdrawalsByYear = JSON.parse(params.withdrawals_json);
+            }
+            catch {
+                return errorResult(new Error("withdrawals_json must be a valid JSON object."));
+            }
+        }
+        try {
+            const result = await client.post("tfsa-room", body);
+            return textResult(formatTFSARoom(result));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // ── HELOC Interest ──────────────────────────────────────────────────
+    registerPostTool(server, client, "calculate_heloc_interest", "Calculate HELOC interest with tax-deductible/non-deductible split. " +
+        "Canadian HELOCs charge interest at Prime + spread. Interest on money " +
+        "borrowed for income-producing investments is tax-deductible (Smith Manoeuvre).", schemas.heloc, "heloc", (p) => ({
+        creditLimit: p.credit_limit,
+        primeRate: p.prime_rate,
+        primeSpread: p.prime_spread,
+        investmentBalance: p.investment_balance,
+        personalBalance: p.personal_balance,
+    }), formatHELOC);
+    // ── Smith Manoeuvre ─────────────────────────────────────────────────
+    registerPostTool(server, client, "calculate_smith_manoeuvre", "Project the Smith Manoeuvre strategy over time. " +
+        "Converts non-deductible mortgage debt into tax-deductible investment debt. " +
+        "Shows year-by-year projections of tax savings, portfolio growth, " +
+        "and comparison vs traditional mortgage paydown.", schemas.smithManoeuvre, "smith-manoeuvre", (p) => ({
+        propertyValue: p.property_value,
+        mortgageBalance: p.mortgage_balance,
+        mortgageRate: p.mortgage_rate,
+        amortizationYears: p.amortization_years,
+        helocRate: p.heloc_rate,
+        marginalTaxRate: p.marginal_tax_rate,
+        investmentReturn: p.investment_return,
+        dividendYield: p.dividend_yield,
+        paymentFrequency: p.payment_frequency,
+        projectionYears: p.projection_years,
+    }), formatSmithManoeuvre);
+    // ── Canadian Income Tax (custom: JSON parsing) ──────────────────────
+    server.registerTool("calculate_canadian_income_tax", {
+        description: "Calculate Canadian federal and provincial income tax. " +
+            "Supports employment, self-employment, capital gains, eligible/ineligible dividends, " +
+            "interest, rental, and other income. Calculates CPP/EI payroll deductions.",
+        inputSchema: schemas.incomeTax,
+    }, async (params) => {
+        const parsed = parseJsonParam(params.income_sources_json, "income_sources_json");
+        if (!Array.isArray(parsed))
+            return parsed;
+        const body = {
+            province: params.province,
+            year: params.year,
+            incomeSources: parsed,
+        };
+        if (params.rrsp_contribution > 0 || params.fhsa_contribution > 0) {
+            body.deductions = {
+                rrspContribution: params.rrsp_contribution,
+                fhsaContribution: params.fhsa_contribution,
+            };
+        }
+        try {
+            const result = await client.post("income-tax", body);
+            return textResult(formatIncomeTax(result));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // ── Tax Constants (GET endpoint) ───────────────────────────────────
+    server.registerTool("get_tax_constants", {
+        description: "Get Canadian tax constants for a specific year. " +
+            "Returns CPP/EI rates and limits, RRSP/FHSA contribution limits, " +
+            "dividend gross-up rates, and capital gains inclusion rates.",
+        inputSchema: schemas.taxConstants,
+    }, async (params) => {
+        try {
+            const result = await client.get(`income-tax/constants/${params.year}`);
+            return textResult(formatTaxConstants(result));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // ── Mortgage Timeline (custom: JSON parsing) ───────────────────────
+    server.registerTool("calculate_mortgage_timeline", {
+        description: "Calculate a mortgage amortization timeline with optional renewal/refinance events. " +
+            "Uses Canadian semi-annual compounding. Shows term-by-term breakdown and lifetime totals.",
+        inputSchema: schemas.mortgage,
+    }, async (params) => {
+        let events;
+        if (params.events_json) {
+            const parsed = parseJsonParam(params.events_json, "events_json");
+            if (!Array.isArray(parsed))
+                return parsed;
+            events = parsed;
+        }
+        try {
+            const result = await client.post("mortgage", {
+                principal: params.principal,
+                annualRate: params.annual_rate,
+                amortizationYears: params.amortization_years,
+                termYears: params.term_years,
+                paymentFrequency: params.payment_frequency,
+                events,
+            });
+            return textResult(formatMortgageTimeline(result));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@trailfolio/mcp",
+  "version": "0.4.0",
+  "description": "Trailfolio MCP Server — Canadian financial calculator tools for AI assistants",
+  "license": "MIT",
+  "author": "Trailfolio",
+  "homepage": "https://trailfolio.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gxsui/Trailfolio.git",
+    "directory": "src/mcp-server"
+  },
+  "bugs": "https://github.com/gxsui/Trailfolio/issues",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "canadian",
+    "finance",
+    "mortgage",
+    "tax",
+    "calculator"
+  ],
+  "type": "module",
+  "bin": {
+    "trailfolio-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/*.js",
+    "prepare": "npm run build",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "lint": "eslint src/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.2.1",
+    "eslint": "^9.39.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}