
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/mcpworks 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.
| Tool | For | Computes with |
|---|---|---|
tip_overtime_deduction | a 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 link | site/api/_deduction.js |
w2_tip_overtime_boxes | an owner or bookkeeper: one row per employee per workweek → TP, TT, 14b per employee, each overtime week's regular rate, printable sheet link | site/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 there | site/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.
| Rule | Source |
|---|---|
| Tips: up to $25,000 per return, any filing status | 26 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 ÷2 | Notice 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 13a | Schedule 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 estimate | Rev. Proc. 2025-32 |
How the Clover app works
- 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/callbackexchanges the code, seals the token pair (AES-256-GCM) into Cloudflare D1, and sets a 12-hour signed session cookie. /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 withexpand=tender,order,employee,refunds,serviceCharge. Refresh tokens are single-use and are rotated and saved before use.site/api/_clover.jsmaps the rows to the engine's input.- 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). - 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.mdhas the field-by-field check. - 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 URLhttps://tip-overtime-w2.vercel.app/clover, launch path/clover, OAuth Code. Secret in.envand 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=mcplinks 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=mcpby 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=mcppeople 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=mcppeople 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,
$hosttip-overtime-w2.vercel.app, pageviews where$current_urlcontainssrc=mcp, unique persons;mcp_tool_callcounts calls, not people.
Licence
MIT.
No installation packages available.
Remote
Related Servers
io.github.2016judea/appeal-draft
Is my Twin Cities property tax assessment too high? County value vs. recorded sales, when to appeal
io.github.2016judea/breach-to-claim
Am I owed money from a data breach? Open settlements, deadlines, payouts and official claim sites
io.github.2016judea/small-business-intelligence
Free joined public records for small business and CRE: Twin Cities parcels, sales, licences