irs-taxpayer-mcp

Instructions

Implementation Reference

• src/tools/credit-tools.ts:255-305 (handler)

  The MCP tool handler that registers 'calculate_eitc' with the server, validates input using Zod schema, calls the calculateEITC function, and formats the result into a user-friendly markdown response.

  server.tool(
    "calculate_eitc",
    "Calculate the exact Earned Income Tax Credit (EITC) amount. " +
    "The EITC is one of the largest refundable credits for low-to-moderate income workers.",
    {
      taxYear: z.number().describe("Tax year (2024 or 2025)"),
      filingStatus: z.enum(["single", "married_filing_jointly", "married_filing_separately", "head_of_household"]),
      earnedIncome: z.number().min(0).describe("Earned income (wages, salary, self-employment)"),
      agi: z.number().min(0).describe("Adjusted Gross Income"),
      qualifyingChildren: z.number().int().min(0).max(3).describe("Number of qualifying children (0-3)"),
      investmentIncome: z.number().min(0).optional().describe("Investment income (interest, dividends, capital gains)"),
    },
    async (params) => {
      const result = calculateEITC(params);
  
      if (!result.eligible) {
        const lines = [
          `## EITC Calculation — TY${params.taxYear}`,
          "",
          `❌ **Not eligible for EITC**`,
          result.reason ? `Reason: ${result.reason}` : `Income exceeds the limit for ${result.qualifyingChildren} qualifying children.`,
          "",
          `> The EITC is available for earned income up to ~$${result.incomeLimit > 0 ? result.incomeLimit.toLocaleString() : "varies"} (depending on filing status and children).`,
        ];
        return { content: [{ type: "text", text: lines.join("\n") }] };
      }
  
      const lines = [
        `## EITC Calculation — TY${params.taxYear}`,
        "",
        `| Item | Value |`,
        `|------|-------|`,
        `| Filing Status | ${params.filingStatus.replace(/_/g, " ")} |`,
        `| Earned Income | $${params.earnedIncome.toLocaleString()} |`,
        `| AGI | $${params.agi.toLocaleString()} |`,
        `| Qualifying Children | ${result.qualifyingChildren} |`,
        `| Phase | ${result.phase} |`,
        `| Max Possible Credit | $${result.maxPossibleCredit.toLocaleString()} |`,
        `| **Your EITC** | **$${result.credit.toLocaleString()}** |`,
        "",
        `✅ **Fully refundable** — you get this even if you owe no tax.`,
        "",
        result.phase === "phase-in" ? `📈 Your credit increases as your income rises (up to $${result.maxPossibleCredit.toLocaleString()}).` : "",
        result.phase === "phase-out" ? `📉 Your credit is being reduced as income exceeds the phase-out threshold.` : "",
        "",
        `> ⚠️ EITC refunds are typically delayed until mid-February. File early to get your refund sooner.`,
      ].filter(Boolean);
  
      return { content: [{ type: "text", text: lines.join("\n") }] };
    }
  );

• src/calculators/eitc-calculator.ts:63-128 (handler)

  The core calculation function that implements the EITC calculation logic, including eligibility checks (filing status, investment income limits), phase-in/plateau/phase-out calculations based on IRS parameters for tax years 2024 and 2025.

  export function calculateEITC(input: EITCInput): EITCResult {
    const yearData = EITC_DATA[input.taxYear];
    if (!yearData) {
      return { eligible: false, credit: 0, maxPossibleCredit: 0, phase: "ineligible", reason: `TY${input.taxYear} not supported`, qualifyingChildren: 0, incomeLimit: 0 };
    }
  
    // MFS not eligible
    if (input.filingStatus === "married_filing_separately") {
      return { eligible: false, credit: 0, maxPossibleCredit: 0, phase: "ineligible", reason: "Married filing separately cannot claim EITC", qualifyingChildren: 0, incomeLimit: 0 };
    }
  
    // Investment income check
    const investLimit = INVESTMENT_INCOME_LIMIT[input.taxYear] ?? 11600;
    if ((input.investmentIncome ?? 0) > investLimit) {
      return { eligible: false, credit: 0, maxPossibleCredit: 0, phase: "ineligible", reason: `Investment income exceeds $${investLimit.toLocaleString()} limit`, qualifyingChildren: input.qualifyingChildren, incomeLimit: 0 };
    }
  
    const children = Math.min(input.qualifyingChildren, 3); // max 3 for EITC
    const params = yearData[children];
    if (!params) {
      return { eligible: false, credit: 0, maxPossibleCredit: 0, phase: "ineligible", reason: "Invalid parameters", qualifyingChildren: children, incomeLimit: 0 };
    }
  
    const isMFJ = input.filingStatus === "married_filing_jointly";
    const phaseoutStart = isMFJ ? params.phaseoutStartMFJ : params.phaseoutStart;
    const incomeLimit = isMFJ
      ? params.completionThreshold + (params.phaseoutStartMFJ - params.phaseoutStart)
      : params.completionThreshold;
  
    // Use the greater of earned income or AGI for phase-out
    const phaseoutIncome = Math.max(input.earnedIncome, input.agi);
  
    let credit: number;
    let phase: "phase-in" | "plateau" | "phase-out" | "ineligible";
  
    if (input.earnedIncome <= 0) {
      credit = 0;
      phase = "ineligible";
    } else if (input.earnedIncome <= params.earnedIncomeThreshold) {
      // Phase-in: credit increases with income
      credit = input.earnedIncome * params.creditRate;
      phase = "phase-in";
    } else if (phaseoutIncome <= phaseoutStart) {
      // Plateau: max credit
      credit = params.maxCredit;
      phase = "plateau";
    } else if (phaseoutIncome < incomeLimit) {
      // Phase-out: credit decreases
      credit = params.maxCredit - (phaseoutIncome - phaseoutStart) * params.phaseoutRate;
      phase = "phase-out";
    } else {
      credit = 0;
      phase = "ineligible";
    }
  
    credit = Math.max(0, Math.round(credit));
  
    return {
      eligible: credit > 0,
      credit,
      maxPossibleCredit: params.maxCredit,
      phase,
      qualifyingChildren: children,
      incomeLimit,
    };
  }

• src/tools/credit-tools.ts:259-266 (schema)

  Zod input validation schema defining the required parameters for calculate_eitc: taxYear, filingStatus, earnedIncome, agi, qualifyingChildren, and optional investmentIncome with constraints.

  {
    taxYear: z.number().describe("Tax year (2024 or 2025)"),
    filingStatus: z.enum(["single", "married_filing_jointly", "married_filing_separately", "head_of_household"]),
    earnedIncome: z.number().min(0).describe("Earned income (wages, salary, self-employment)"),
    agi: z.number().min(0).describe("Adjusted Gross Income"),
    qualifyingChildren: z.number().int().min(0).max(3).describe("Number of qualifying children (0-3)"),
    investmentIncome: z.number().min(0).optional().describe("Investment income (interest, dividends, capital gains)"),
  },

• src/calculators/eitc-calculator.ts:44-60 (schema)

  TypeScript interface definitions for EITCInput (tax year, filing status, income, children) and EITCResult (eligibility, credit amount, phase, reason) used by the calculator.

  export interface EITCInput {
    taxYear: number;
    filingStatus: FilingStatus;
    earnedIncome: number;
    agi: number;
    qualifyingChildren: number;
    investmentIncome?: number;
  }
  
  export interface EITCResult {
    eligible: boolean;
    credit: number;
    maxPossibleCredit: number;
    phase: "phase-in" | "plateau" | "phase-out" | "ineligible";
    reason?: string;
    qualifyingChildren: number;
    incomeLimit: number;

• src/tools/credit-tools.ts:255-256 (registration)

  Tool registration point where 'calculate_eitc' is registered with the MCP server using server.tool() with the tool name and description.

  server.tool(
    "calculate_eitc",