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