no-tax-on-tips-mcp

MCP server exposing the OBBBA "No Tax on Tips" federal deduction logic as callable tools (stdio transport).

DISCLAIMERS

1. Informational only — NOT tax advice. This tool provides estimates based on publicly available statutory and regulatory information. It is NOT legal or tax advice. Verify all results against IRS guidance at irs.gov/TippedOccupations and consult a qualified tax professional before making any tax decision.

2. Occupation codes are placeholder slugs — NOT validated Treasury codes. The TTOC occupation codes in this server (e.g. "bartender_barback") are DESCRIPTIVE PLACEHOLDER SLUGS. They are NOT the validated 3-digit numeric Treasury codes from the IRS final regulations (Federal Register 2026-07104). Operator validation is pending (reviewed_by_operator_at_utc = 0 in source). Do not use these codes for official filings.

3. Applies to tax years 2025-2028 only (OBBBA sunset window). The OBBBA No-Tax-on-Tips deduction is effective for tax years 2025 through 2028 (inclusive). Per-filing-status caps and MAGI phase-outs apply. Tax year 2025 has transition relief (separate-reporting requirement waived).

4. module_version: 1.0.0-2026-04-13 This matches the IRS final regulations date (Federal Register 2026-07104). If IRS guidance changes, the module version must be updated and cached deduction results invalidated.

---

Installation

npm install
npm run build

Running

npm start

Or in development (no build step):

npm run dev

Testing

npm test

MCP Client Configuration

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "no-tax-on-tips": {
      "command": "node",
      "args": ["C:/Users/cruzr/no-tax-on-tips-mcp/dist/index.js"]
    }
  }
}

---

Tools

check_tip_deduction_eligibility

Checks eligibility without computing a dollar amount.

Input:

{
  "occupation_code": "wait_staff",
  "magi_usd": 75000,
  "filing_status": "single",
  "tax_year": 2026
}

Output:

{
  "in_sunset_window": true,
  "transition_relief": false,
  "ttoc_eligible": true,
  "phase_out_fraction": 0,
  "eligible": true,
  "notes": ["..."]
}

eligible = in_sunset_window && ttoc_eligible && phase_out_fraction < 1

---

estimate_tip_deduction

Full deduction estimate. USD in, USD out. Internal math uses integer cents.

Input:

{
  "qualified_tips_usd": 23000,
  "filing_status": "single",
  "tax_year": 2026,
  "magi_usd": 75000
}

Output:

{
  "qualified_tips_usd": 23000,
  "cap_usd": 25000,
  "phase_out_fraction": 0,
  "deduction_usd": 23000,
  "disclaimer": "..."
}

---

list_eligible_occupations

Returns the onboarding picker subset (11 occupation codes + 1 lookup placeholder).

---

get_obbba_reference

Returns caps, phase-out bands, sunset window, module version, source URLs, and disclaimers.

---

Caps and Phase-Out Bands (2025-2028)

Filing Status	Cap	Phase-Out Threshold	Full Phase-Out
Single	$25,000	$150,000	$400,000
Head of Household	$25,000	$150,000	$400,000
Married Filing Jointly	$25,000	$300,000	$550,000
Married Filing Separately	$12,500	$150,000	$275,000

Phase-out is linear: $100 reduction per $1,000 (or fraction) of MAGI over threshold.

---

Source

Tax logic copied verbatim from nightshift-v2/src/features/tax-engine/jurisdictions/us-fed/deductions/obbba-no-tax-on-tips/ (read-only source). No formulas were re-derived. Import paths adjusted for this standalone package; no other modifications.

Source references:

• IRS Tipped Occupations: https://www.irs.gov/TippedOccupations
• Federal Register 2026-07104: https://www.federalregister.gov/documents/2026/04/13/2026-07104/occupations-that-customarily-and-regularly-received-tips-definition-of-qualified-tips

---

Publishing

Do NOT publish to npm or push to a remote without operator sign-off. This is a local build only. Publishing is a separate operator step.