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",