Repository avatar
Other Tools
v0.1.0
active

tip-overtime-w2

io.github.2016judea/tip-overtime-w2

Works out the no-tax-on-tips and no-tax-on-overtime deductions and W-2 boxes, with the math shown

Documentation

Tip & Overtime W-2s

Live: https://tip-overtime-w2.vercel.app

Works out the federal "no tax on tips" and "no tax on overtime" deductions, and the new 2026 Form W-2 boxes behind them, in code, with the math shown and a citation for every rule. Two people ask the question, so it has two front doors:

  • The person asking an AI (since 2026-11-19). A worker says "how much of my tips and overtime can I deduct?" to Claude or ChatGPT. The connector at https://tip-overtime-w2.vercel.app/mcp works it out from their W-2 boxes or pay stubs, line by line on Schedule 1-A, and hands back a link that opens the filled-in worksheet to print or give to a preparer. A bookkeeper pastes payroll rows and gets each employee's box 12 TP, TT and box 14b. Setup: /ai/.
  • The owner on Clover. A Clover app that reads the register and gives every employee's W-2 figures. Unchanged; described from "How it works" down.

And one page of numbers nobody else publishes: what no tax on tips is worth, by tipped occupation (BLS OEWS May 2025 pay for all 71 IRS tipped occupations, run through the 2026 tax tables: a median waiter saves $120 per $1,000 of tips and at most $2,048 a year).

It calculates and shows. Nobody here files anything, and the connector stores nothing it is sent.

The connector (MCP)

Streamable HTTP, stateless, no auth: site/api/mcp.js, rewritten from /mcp.

ToolForComputes with
tip_overtime_deductiona worker: W-2 box 12 TP/TT/14b, Form 4137, 1099s, or pay stubs → both deductions, every Schedule 1-A line, the Form 1040 line, federal tax saved, flags, citations, worksheet linksite/api/_deduction.js
w2_tip_overtime_boxesan owner or bookkeeper: one row per employee per workweek → TP, TT, 14b per employee, each overtime week's regular rate, printable sheet linksite/api/_payroll.js → the Clover engine site/api/_engine.js
tipped_occupation_code"does my job qualify?": the TTOC for a job title, its IRS description, BLS median pay, what the deduction is worth theresite/api/_occupations.json

A model is never the source of a number: the assistant passes figures in and carries the answer out.

Privacy, by design. The worksheet link carries the figures in the URL fragment (/worksheet/?src=mcp#w1.<base64 JSON>). Browsers never send a fragment to a server, so the figures never reach Vercel's logs. The page's first script copies the fragment into memory and deletes it from the address bar before PostHog or Vercel Analytics load, so they see only /worksheet/?src=mcp. A short-lived server token was the alternative and was rejected: it means storing the figures. Employer labels are dropped from the link; nothing is written to storage.

Analytics. Each call sends one PostHog mcp_tool_call event: tool, ok, ms, client, client_ua, and coarse booleans (has_tips, has_ot, source w2/estimate, year, blocked; employees count for the owner tool). Never an amount, a name or an argument, and no IP: claude.ai connector calls arrive from Anthropic's servers, so an IP-based id counts servers, not people (distinct_id is a fresh random id per call). People are counted on the web side: PostHog pageviews whose $current_url contains src=mcp, plus worksheet_opened (prefilled worker/owner/none, src), worksheet_computed, worksheet_printed, worth_tried, connector_url_copied. Mark a test call with header x-tow-test: 1.

The rules, verified 2026-11-19 from primary sources

Copies of every source are in regs/ and tests/sources.test.js checks that each rule the code quotes is verbatim in its copy.

RuleSource
Tips: up to $25,000 per return, any filing status26 U.S.C. § 224(b)(1); 26 CFR 1.224-1(b)(1) (T.D. 10044, 91 FR 19026, Apr. 13 2026)
Overtime: up to $12,500, $25,000 joint§ 225(b)(1)
Each falls $100 per full $1,000 of MAGI over $150,000 ($300,000 joint); thousands round DOWN§ 224(b)(2), § 225(b)(2); Schedule 1-A 2026 draft lines 13, 25 (2025: lines 11, 19)
Married filing separately: nothing. SSN valid for work required§ 224(e)-(f), § 225(d)-(e)
Tax years 2025-2028§ 224(h), § 225(g)
Qualified tips: voluntary, in an occupation on the IRS list (71 codes); service charges and automatic gratuities never count§ 224(d); 1.224-1(c)(4); irs.gov/tippedoccupations
SSTB exclusion not enforced for listed occupations until final SSTB regs (reserved in 1.224-1(g))Notice 2025-69
Qualified overtime: only the FLSA half (hours over 40 × 0.5 × regular rate)§ 225(c)(1); 2026 W-2 instructions, code TT
Pay-stub estimates: total at 1.5x ÷ 3, at 2x ÷ 4; stated premium ×1 or ÷2Notice 2025-69 methods A-D (Examples 1-4 are unit tests)
2026 lines: tips per employer on line 4 (larger of box 12 TP and Form 4137 line 1 col c), deduction line 15; overtime line 16 (box 12 TT), deduction line 27; total to Form 1040 line 13aSchedule 1-A and Form 1040 2026 drafts (6/16/26, 8/19/26): line numbers can still move
2026 rates and standard deduction ($16,100 single) for the tax-saved estimateRev. Proc. 2025-32

How the Clover app works

  1. A merchant installs from the Clover App Market (or opens it from their dashboard). Clover sends them to /clover (site/api/clover/launch.js), which starts OAuth v2. /clover/callback exchanges the code, seals the token pair (AES-256-GCM) into Cloudflare D1, and sets a 12-hour signed session cookie.
  2. /report/ calls /api/data. That reads the year from Clover in 85-day windows (the API caps a time filter at 90 days): employees, shifts, and payments with expand=tender,order,employee,refunds,serviceCharge. Refresh tokens are single-use and are rotated and saved before use. site/api/_clover.js maps the rows to the engine's input.
  3. The engine (site/api/_engine.js) is pure, deterministic JavaScript with no model and no network. The browser runs the same file, so every answer the owner gives recomputes instantly. Answers save to D1 (/api/answers).
  4. Anything Clover can't tell us is asked, with a visible default, and flagged until confirmed: pay rates, exempt status, workweek start, tip credit, tip sharing done off the register, bonuses, whether service charges go to staff, and occupation codes. DATA_MODEL.md has the field-by-field check.
  5. Download CSV: the W-2 figures, every workweek, every tip row.

The Clover engine's rules, and where they come from

Cited in code where applied (site/api/_engine.js header):

  • IRS, 2026 General Instructions for Forms W-2 and W-3: codes TP and TT, Box 14b (up to two codes; "000" if any tips came from a nonqualifying occupation).
  • IRS FS-2026-13, Q10–Q17: per-workweek formula, fixed recurring workweek with no averaging, regular rate = all remuneration ÷ FLSA hours, only the FLSA half counts (Q16 worked example is a unit test).
  • IRS tipped occupations list, transcribed to site/api/_ttoc.js.
  • DOL Fact Sheets #15 (tip credit: OT on the full minimum wage; service charges are not tips but are wages in the regular rate), #23, #56A.

One judgment call: workweeks hold the owner's local start (Sunday 00:00 stays Sunday 00:00 all year), so the two weeks with a DST change run 167 and 169 hours. Stepping a strict 168 hours put summer boundaries at 01:00 and moved a Saturday-night hour into the wrong week in the sandbox run.

Tests

npm test                      # 61: engine (18), deduction (15), sources verbatim (22), MCP (6)
python3 scripts/fetch_oews.py # BLS OEWS May 2025 pay for every related SOC (needs BLS_API_KEY)
node scripts/build_pages.js   # → _occupations.json, the by-occupation page, llms(-full).txt, sitemap
python3 scripts/indexnow.py   # ping Bing/IndexNow with every sitemap URL after a deploy
node scripts/check_sandbox.js # live pull from the sandbox merchant vs. hand-worked figures (3/3)

Clover

Tool skill: ~/.claude/skills/clover-api/SKILL.md. Developer account and sandbox test merchant 4ZNNY5AK5SNT1 are shared with Block Brief.

  • Sandbox app VRS0YGB8BCFY2 (NA sandbox, Private + Web). Read: Employees, Merchant, Orders, Payments. Site URL https://tip-overtime-w2.vercel.app/clover, launch path /clover, OAuth Code. Secret in .env and Vercel (CLOVER_APP_ID, CLOVER_APP_SECRET, CLOVER_ENV=sandbox).
  • Proved end to end on 2026-11-02: install from the sandbox App Market → Open the app → /clover → OAuth → /clover/callback → /report/ showing 28 shifts and 7 payments. Then pay rates were entered in the page. TP $353.00, TT $205.50, and every employee's figures match the hand-worked ones. Answers persisted across a reload. The final install held READ permissions only. Seeding (scripts/seed_sandbox.js) briefly needed WRITE, which was removed and the app reinstalled.
  • Production: the developer account is verifying (Aidan's ID documents, ~11/14). Listing copy, permission reasons, icon, cover, screenshots and the walkthrough video are in listing/.

Running it

set -a; . ~/Desktop/workspace/bricks/.env; set +a   # VERCEL_TOKEN
node scripts/make_sample.js               # rebuild the SAMPLE café
python3 scripts/deploy.py                 # Vercel over REST (copies the engine to public/js first)
python3 scripts/vercel_env.py KEY…        # push .env keys to Vercel

.env (gitignored): ACCESS_SECRET, CLOUDFLARE_API_TOKEN, CLOVER_ENV, CLOVER_APP_ID, CLOVER_APP_SECRET (later CLOVER_PROD_APP_ID, CLOVER_PROD_APP_SECRET). D1 database tip-overtime-w2 (2bfd0140-…), Vercel project prj_z2TmV6xcMppgVzpzIPamqulmcWn3, Web Analytics on.

Price

Draft: one tier, $29/month, billed by Clover. Not set live. An owner installs in December, runs it in January, and can uninstall after W-2s go out, so the season costs about $58. That is less than an hour of an accountant rebuilding the same figures by hand, and the same price as Block Brief on the same marketplace.

Expectation (written 2026-11-19, before the connector was listed anywhere)

The read is 2027-02-26, four weeks after W-2s are due (Jan 31) and seven before filing ends (Apr 15). Second read 2027-04-16.

  • Base rates. heistclips' connector sent 151 people to its site via src=mcp links in 11/16-11/19 (54% used it), where people already ask an AI the exact question. The Brick & Mortar business connector, same channel, got zero human calls in 7 days. Directory review for both Claude and ChatGPT has taken weeks; until a listing is live, the only way in is the custom URL or the data page being cited.
  • Expected: 40 people landing on /worksheet/?src=mcp by 2027-02-26, and 30 more arriving at the by-occupation page from search or AI citations. Most of it depends on a directory listing being live by mid-January.
  • Would surprise us upward: more than 300 src=mcp people by the read date. That would mean the filing-season question pulls through the directories the way the clipping question did.
  • Would surprise us downward: zero src=mcp people with a directory listing live for 30 days. That would mean assistants answer this from their own knowledge and never call a tool (the business-connector pattern), and the page is the only channel.
  • Count with: PostHog, $host tip-overtime-w2.vercel.app, pageviews where $current_url contains src=mcp, unique persons; mcp_tool_call counts calls, not people.

Licence

MIT.