irs-taxpayer-mcp

Instructions

Implementation Reference

• src/tools/advanced-tools.ts:608-741 (handler)

  The complete handler implementation for 'analyze_relocation_taxes' tool. Calculates federal tax, compares state taxes between two states, projects multi-year savings with optional income growth, analyzes SALT cap impact, and generates a comprehensive markdown report showing current year comparison, local tax considerations, and cumulative savings projection.
  server.tool( "analyze_relocation_taxes", "In-depth relocation tax analysis comparing two states. Includes state income tax, " + "effective combined rate, local taxes, and multi-year savings projection.", { taxYear: z.number().describe("Tax year"), filingStatus: FilingStatusEnum, grossIncome: z.number().min(0).describe("Annual gross income"), fromState: z.string().length(2).describe("Current state code"), toState: z.string().length(2).describe("Target state code"), selfEmploymentIncome: z.number().min(0).optional(), capitalGains: z.number().optional(), dependents: z.number().int().min(0).optional(), yearsToProject: z.number().int().min(1).max(10).optional().describe("Years to project savings (default: 5)"), incomeGrowthRate: z.number().min(0).max(0.5).optional().describe("Annual income growth rate (e.g., 0.03 for 3%)"), }, async (params) => { const projYears = params.yearsToProject ?? 5; const growth = params.incomeGrowthRate ?? 0; // Federal tax (same regardless of state) const federal = calculateTax({ taxYear: params.taxYear, filingStatus: params.filingStatus, grossIncome: params.grossIncome, selfEmploymentIncome: params.selfEmploymentIncome, capitalGains: params.capitalGains, capitalGainsLongTerm: true, dependents: params.dependents, }); const stateFS = params.filingStatus === "married_filing_jointly" ? "married" as const : "single" as const; const fromResult = calculateStateTax({ stateCode: params.fromState, taxableIncome: federal.adjustedGrossIncome, filingStatus: stateFS }); const toResult = calculateStateTax({ stateCode: params.toState, taxableIncome: federal.adjustedGrossIncome, filingStatus: stateFS }); if (!fromResult || !toResult) { return ERRORS.invalidState(params.fromState); } const annualSavings = fromResult.tax - toResult.tax; // Multi-year projection let cumulativeSavings = 0; const projections: Array<{ year: number; income: number; fromTax: number; toTax: number; savings: number; cumulative: number }> = []; for (let i = 0; i < projYears; i++) { const yearIncome = Math.round(params.grossIncome * Math.pow(1 + growth, i)); const yearFederal = calculateTax({ taxYear: Math.min(params.taxYear + i, 2025), filingStatus: params.filingStatus, grossIncome: yearIncome, }); const yearFrom = calculateStateTax({ stateCode: params.fromState, taxableIncome: yearFederal.adjustedGrossIncome, filingStatus: stateFS }); const yearTo = calculateStateTax({ stateCode: params.toState, taxableIncome: yearFederal.adjustedGrossIncome, filingStatus: stateFS }); const yearSavings = (yearFrom?.tax ?? 0) - (yearTo?.tax ?? 0); cumulativeSavings += yearSavings; projections.push({ year: params.taxYear + i, income: yearIncome, fromTax: yearFrom?.tax ?? 0, toTax: yearTo?.tax ?? 0, savings: yearSavings, cumulative: cumulativeSavings, }); } const lines = [ `## 🏠 Relocation Tax Analysis`, `**${fromResult.stateName}** → **${toResult.stateName}** | $${fmt(params.grossIncome)} income`, "", `### Current Year Comparison`, `| | ${fromResult.stateName} | ${toResult.stateName} | Difference |`, `|---|---|---|---|`, `| Tax Type | ${fromResult.taxType} | ${toResult.taxType} | — |`, `| State Tax | $${fmt(fromResult.tax)} | $${fmt(toResult.tax)} | ${annualSavings >= 0 ? "-" : "+"}$${fmt(Math.abs(annualSavings))} |`, `| Effective Rate | ${(fromResult.effectiveRate * 100).toFixed(2)}% | ${(toResult.effectiveRate * 100).toFixed(2)}% | ${((toResult.effectiveRate - fromResult.effectiveRate) * 100).toFixed(2)}pp |`, `| Federal Tax | $${fmt(federal.totalFederalTax)} | $${fmt(federal.totalFederalTax)} | $0 |`, `| **Combined Tax** | **$${fmt(federal.totalFederalTax + fromResult.tax)}** | **$${fmt(federal.totalFederalTax + toResult.tax)}** | **${annualSavings >= 0 ? "-" : "+"}$${fmt(Math.abs(annualSavings))}** |`, "", ]; if (annualSavings > 0) { lines.push(`💰 Moving to ${toResult.stateName} saves **$${fmt(annualSavings)}/year** ($${fmt(Math.round(annualSavings / 12))}/month) in state taxes.`); } else if (annualSavings < 0) { lines.push(`📈 Moving to ${toResult.stateName} costs **$${fmt(Math.abs(annualSavings))}/year** more in state taxes.`); } else { lines.push(`➡️ No state tax difference between ${fromResult.stateName} and ${toResult.stateName}.`); } // Local taxes warning if (fromResult.hasLocalTaxes || toResult.hasLocalTaxes) { lines.push( "", `### ⚠️ Local Tax Considerations`, fromResult.hasLocalTaxes ? `- ${fromResult.stateName} has local/city income taxes (not included above)` : "", toResult.hasLocalTaxes ? `- ${toResult.stateName} has local/city income taxes (not included above)` : "", `Use \`get_state_tax_info\` for specific local tax rates.`, ); } // Multi-year projection lines.push( "", `### ${projYears}-Year Projection${growth > 0 ? ` (${(growth * 100).toFixed(0)}% annual income growth)` : ""}`, `| Year | Income | ${fromResult.stateName} Tax | ${toResult.stateName} Tax | Annual Savings | Cumulative |`, `|------|--------|---|---|---|---|`, ...projections.map((p) => `| ${p.year} | $${fmt(p.income)} | $${fmt(p.fromTax)} | $${fmt(p.toTax)} | $${fmt(p.savings)} | $${fmt(p.cumulative)} |` ), "", `**${projYears}-year total savings: $${fmt(cumulativeSavings)}**`, ); // SALT deduction impact const saltCap = getSaltCap(params.taxYear, params.filingStatus, params.grossIncome); if (fromResult.tax > saltCap) { lines.push( "", `### SALT Deduction Impact`, `Your ${fromResult.stateName} tax ($${fmt(fromResult.tax)}) exceeds the SALT cap ($${fmt(saltCap)}).`, `You lose $${fmt(fromResult.tax - saltCap)} in deductions due to the cap.`, toResult.tax <= saltCap ? `In ${toResult.stateName}, your full state tax would be deductible.` : "", ); } lines.push( "", `> ⚠️ Does not include property tax, sales tax, or cost of living differences. These can significantly affect the total financial impact of relocation.`, ); return { content: [{ type: "text", text: lines.filter(Boolean).join("\n") }] }; } );
• src/tools/advanced-tools.ts:612-623 (schema)

  Input parameter schema using zod validation for the relocation tax analysis tool. Defines required parameters (taxYear, filingStatus, grossIncome, fromState, toState) and optional parameters (selfEmploymentIncome, capitalGains, dependents, yearsToProject, incomeGrowthRate).
  { taxYear: z.number().describe("Tax year"), filingStatus: FilingStatusEnum, grossIncome: z.number().min(0).describe("Annual gross income"), fromState: z.string().length(2).describe("Current state code"), toState: z.string().length(2).describe("Target state code"), selfEmploymentIncome: z.number().min(0).optional(), capitalGains: z.number().optional(), dependents: z.number().int().min(0).optional(), yearsToProject: z.number().int().min(1).max(10).optional().describe("Years to project savings (default: 5)"), incomeGrowthRate: z.number().min(0).max(0.5).optional().describe("Annual income growth rate (e.g., 0.03 for 3%)"), },
• src/tools/advanced-tools.ts:608-611 (registration)

  Tool registration with the MCP server. Defines the tool name 'analyze_relocation_taxes' and its description: 'In-depth relocation tax analysis comparing two states. Includes state income tax, effective combined rate, local taxes, and multi-year savings projection.'
  server.tool( "analyze_relocation_taxes", "In-depth relocation tax analysis comparing two states. Includes state income tax, " + "effective combined rate, local taxes, and multi-year savings projection.",
• src/index.ts:199-199 (registration)

  Tool documentation entry in the help output listing 'analyze_relocation_taxes' under the Advanced tools section, showing it as one of 5 advanced tools available in the server.
  analyze_relocation_taxes State relocation analysis