irs-taxpayer-mcp

Instructions

Implementation Reference

• src/tools/planning-tools.ts:341-412 (handler)

  Main handler function for analyze_mortgage_tax_benefit tool. Calculates tax benefit of mortgage interest deduction and property taxes, compares itemizing vs standard deduction, and provides recommendations based on SALT cap and tax savings.

  async (params) => {
    const stateIncome = params.stateIncomeTaxes ?? 0;
    const saltTotal = stateIncome + params.propertyTaxes;
    const saltCapAmount = getSaltCap(params.taxYear, params.filingStatus, params.grossIncome);
    const saltCapped = Math.min(saltTotal, saltCapAmount);
    const otherItemized = params.otherItemized ?? 0;
    const totalItemized = params.mortgageInterest + saltCapped + otherItemized;
  
    // With itemizing
    const withItemized = calculateTax({
      taxYear: params.taxYear,
      filingStatus: params.filingStatus,
      grossIncome: params.grossIncome,
      itemizedDeductions: totalItemized,
    });
  
    // With standard deduction
    const withStandard = calculateTax({
      taxYear: params.taxYear,
      filingStatus: params.filingStatus,
      grossIncome: params.grossIncome,
    });
  
    const savings = withStandard.totalFederalTax - withItemized.totalFederalTax;
    const recommendation = savings > 0 ? "itemize" : "standard";
  
    const lines = [
      `## Mortgage Tax Benefit Analysis — TY${params.taxYear}`,
      "",
      `### Itemized Deduction Breakdown`,
      `| Deduction | Amount | Notes |`,
      `|-----------|--------|-------|`,
      `| Mortgage Interest | $${fmt(params.mortgageInterest)} | On up to $750K debt |`,
      `| Property Taxes | $${fmt(params.propertyTaxes)} | Part of SALT |`,
      stateIncome > 0 ? `| State Income Taxes | $${fmt(stateIncome)} | Part of SALT |` : "",
      `| SALT (capped) | $${fmt(saltCapped)} | cap: $${fmt(saltCapAmount)} |`,
      saltTotal > saltCapped ? `| SALT lost to cap | $${fmt(saltTotal - saltCapped)} | Not deductible |` : "",
      otherItemized > 0 ? `| Other Itemized | $${fmt(otherItemized)} | |` : "",
      `| **Total Itemized** | **$${fmt(totalItemized)}** | |`,
      "",
      `### Comparison`,
      `| Scenario | Deduction | Federal Tax | Effective Rate |`,
      `|----------|-----------|-------------|---------------|`,
      `| Standard | $${fmt(withStandard.deductionAmount)} | $${fmt(withStandard.totalFederalTax)} | ${(withStandard.effectiveRate * 100).toFixed(2)}% |`,
      `| Itemized | $${fmt(totalItemized)} | $${fmt(withItemized.totalFederalTax)} | ${(withItemized.effectiveRate * 100).toFixed(2)}% |`,
      "",
      savings > 0
        ? `💡 **Recommendation**: Itemize — saves $${fmt(savings)}/year over standard deduction.`
        : `💡 **Recommendation**: Take the standard deduction — it's $${fmt(Math.abs(savings))} better than itemizing.`,
    ];
  
    if (params.mortgageBalance && params.interestRate) {
      const monthlyPayment = (params.mortgageBalance * (params.interestRate / 12)) /
        (1 - Math.pow(1 + params.interestRate / 12, -360));
      lines.push(
        "",
        `### Mortgage Info`,
        `| Detail | Value |`,
        `|--------|-------|`,
        `| Balance | $${fmt(params.mortgageBalance)} |`,
        `| Rate | ${(params.interestRate * 100).toFixed(2)}% |`,
        `| Est. Monthly Payment (30yr) | $${fmt(Math.round(monthlyPayment))} |`,
      );
    }
  
    lines.push(
      "",
      `> ⚠️ Simplified analysis. Does not account for AMT or state-specific rules.`,
    );
  
    return { content: [{ type: "text", text: lines.filter(Boolean).join("\n") }] };
  }

• src/tools/planning-tools.ts:326-413 (registration)

  Tool registration using server.tool() with name 'analyze_mortgage_tax_benefit', description, Zod schema definition, and async handler function.

  server.tool(
    "analyze_mortgage_tax_benefit",
    "Analyze the tax benefit of mortgage interest deduction and property taxes. " +
    "Compares itemizing with mortgage vs taking the standard deduction.",
    {
      taxYear: z.number().describe("Tax year"),
      filingStatus: FilingStatusEnum,
      grossIncome: z.number().min(0),
      mortgageInterest: z.number().min(0).describe("Annual mortgage interest paid"),
      propertyTaxes: z.number().min(0).describe("Annual property taxes paid"),
      stateIncomeTaxes: z.number().min(0).optional().describe("State/local income taxes paid"),
      otherItemized: z.number().min(0).optional().describe("Other itemized deductions (charity, medical, etc.)"),
      mortgageBalance: z.number().min(0).optional().describe("Current mortgage balance"),
      interestRate: z.number().min(0).optional().describe("Mortgage interest rate (e.g., 0.065 for 6.5%)"),
    },
    async (params) => {
      const stateIncome = params.stateIncomeTaxes ?? 0;
      const saltTotal = stateIncome + params.propertyTaxes;
      const saltCapAmount = getSaltCap(params.taxYear, params.filingStatus, params.grossIncome);
      const saltCapped = Math.min(saltTotal, saltCapAmount);
      const otherItemized = params.otherItemized ?? 0;
      const totalItemized = params.mortgageInterest + saltCapped + otherItemized;
  
      // With itemizing
      const withItemized = calculateTax({
        taxYear: params.taxYear,
        filingStatus: params.filingStatus,
        grossIncome: params.grossIncome,
        itemizedDeductions: totalItemized,
      });
  
      // With standard deduction
      const withStandard = calculateTax({
        taxYear: params.taxYear,
        filingStatus: params.filingStatus,
        grossIncome: params.grossIncome,
      });
  
      const savings = withStandard.totalFederalTax - withItemized.totalFederalTax;
      const recommendation = savings > 0 ? "itemize" : "standard";
  
      const lines = [
        `## Mortgage Tax Benefit Analysis — TY${params.taxYear}`,
        "",
        `### Itemized Deduction Breakdown`,
        `| Deduction | Amount | Notes |`,
        `|-----------|--------|-------|`,
        `| Mortgage Interest | $${fmt(params.mortgageInterest)} | On up to $750K debt |`,
        `| Property Taxes | $${fmt(params.propertyTaxes)} | Part of SALT |`,
        stateIncome > 0 ? `| State Income Taxes | $${fmt(stateIncome)} | Part of SALT |` : "",
        `| SALT (capped) | $${fmt(saltCapped)} | cap: $${fmt(saltCapAmount)} |`,
        saltTotal > saltCapped ? `| SALT lost to cap | $${fmt(saltTotal - saltCapped)} | Not deductible |` : "",
        otherItemized > 0 ? `| Other Itemized | $${fmt(otherItemized)} | |` : "",
        `| **Total Itemized** | **$${fmt(totalItemized)}** | |`,
        "",
        `### Comparison`,
        `| Scenario | Deduction | Federal Tax | Effective Rate |`,
        `|----------|-----------|-------------|---------------|`,
        `| Standard | $${fmt(withStandard.deductionAmount)} | $${fmt(withStandard.totalFederalTax)} | ${(withStandard.effectiveRate * 100).toFixed(2)}% |`,
        `| Itemized | $${fmt(totalItemized)} | $${fmt(withItemized.totalFederalTax)} | ${(withItemized.effectiveRate * 100).toFixed(2)}% |`,
        "",
        savings > 0
          ? `💡 **Recommendation**: Itemize — saves $${fmt(savings)}/year over standard deduction.`
          : `💡 **Recommendation**: Take the standard deduction — it's $${fmt(Math.abs(savings))} better than itemizing.`,
      ];
  
      if (params.mortgageBalance && params.interestRate) {
        const monthlyPayment = (params.mortgageBalance * (params.interestRate / 12)) /
          (1 - Math.pow(1 + params.interestRate / 12, -360));
        lines.push(
          "",
          `### Mortgage Info`,
          `| Detail | Value |`,
          `|--------|-------|`,
          `| Balance | $${fmt(params.mortgageBalance)} |`,
          `| Rate | ${(params.interestRate * 100).toFixed(2)}% |`,
          `| Est. Monthly Payment (30yr) | $${fmt(Math.round(monthlyPayment))} |`,
        );
      }
  
      lines.push(
        "",
        `> ⚠️ Simplified analysis. Does not account for AMT or state-specific rules.`,
      );
  
      return { content: [{ type: "text", text: lines.filter(Boolean).join("\n") }] };
    }
  );

• src/tools/planning-tools.ts:330-340 (schema)

  Zod input schema defining parameters for the mortgage tax benefit analysis tool including taxYear, filingStatus, grossIncome, mortgageInterest, propertyTaxes, stateIncomeTaxes, otherItemized, mortgageBalance, and interestRate.

  {
    taxYear: z.number().describe("Tax year"),
    filingStatus: FilingStatusEnum,
    grossIncome: z.number().min(0),
    mortgageInterest: z.number().min(0).describe("Annual mortgage interest paid"),
    propertyTaxes: z.number().min(0).describe("Annual property taxes paid"),
    stateIncomeTaxes: z.number().min(0).optional().describe("State/local income taxes paid"),
    otherItemized: z.number().min(0).optional().describe("Other itemized deductions (charity, medical, etc.)"),
    mortgageBalance: z.number().min(0).optional().describe("Current mortgage balance"),
    interestRate: z.number().min(0).optional().describe("Mortgage interest rate (e.g., 0.065 for 6.5%)"),
  },

• src/data/tax-brackets.ts:340-360 (helper)

  getSaltCap helper function that calculates the effective SALT deduction cap based on tax year, filing status, and AGI. Used by the mortgage tax benefit analyzer to cap state and local tax deductions.

  export function getSaltCap(
    taxYear: number,
    filingStatus: FilingStatus,
    agi: number
  ): number {
    const data = TAX_DATA[taxYear];
    if (!data) return 10000;
  
    const cap = data.saltCap;
    if (filingStatus === "married_filing_separately") return cap.mfs;
  
    if (cap.enhancedCap && cap.enhancedAgiThreshold) {
      if (agi <= cap.enhancedAgiThreshold) return cap.enhancedCap;
      // Phase down: for every $1K over threshold, reduce by $1K (simplified)
      const excess = agi - cap.enhancedAgiThreshold;
      const reduction = Math.min(excess, cap.enhancedCap - cap.base);
      return Math.max(cap.base, cap.enhancedCap - reduction);
    }
  
    return cap.base;
  }