Skip to content
Back to search

tip-overtime-w2

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/2016judea--tip-overtime-w2/badge.svg)](/listings/2016judea--tip-overtime-w2)

HTML

<a href="/listings/2016judea--tip-overtime-w2"><img src="/api/listings/2016judea--tip-overtime-w2/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 169 lines
  1. # Tip & Overtime W-2s
  2. **Live:** https://tip-overtime-w2.vercel.app
  3. Works out the federal **"no tax on tips"** and **"no tax on overtime"** deductions, and the new 2026
  4. Form W-2 boxes behind them, in code, with the math shown and a citation for every rule. Two people
  5. ask the question, so it has two front doors:
  6. - **The person asking an AI** (since 2026-11-19). A worker says "how much of my tips and overtime can
  7. I deduct?" to Claude or ChatGPT. The connector at **`https://tip-overtime-w2.vercel.app/mcp`**
  8. works it out from their W-2 boxes or pay stubs, line by line on Schedule 1-A, and hands back a
  9. link that opens the filled-in [worksheet](https://tip-overtime-w2.vercel.app/worksheet/) to print
  10. or give to a preparer. A bookkeeper pastes payroll rows and gets each employee's box 12 TP, TT and
  11. box 14b. Setup: [/ai/](https://tip-overtime-w2.vercel.app/ai/).
  12. - **The owner on Clover.** A Clover app that reads the register and gives every employee's W-2
  13. figures. Unchanged; described from "How it works" down.
  14. And one page of numbers nobody else publishes:
  15. [what no tax on tips is worth, by tipped occupation](https://tip-overtime-w2.vercel.app/no-tax-on-tips-by-occupation/)
  16. (BLS OEWS May 2025 pay for all 71 IRS tipped occupations, run through the 2026 tax tables: a median
  17. waiter saves $120 per $1,000 of tips and at most $2,048 a year).
  18. **It calculates and shows. Nobody here files anything, and the connector stores nothing it is sent.**
  19. ## The connector (MCP)
  20. Streamable HTTP, stateless, no auth: `site/api/mcp.js`, rewritten from `/mcp`.
  21. | Tool | For | Computes with |
  22. |---|---|---|
  23. | `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` |
  24. | `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` |
  25. | `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` |
  26. A model is never the source of a number: the assistant passes figures in and carries the answer out.
  27. **Privacy, by design.** The worksheet link carries the figures in the URL **fragment**
  28. (`/worksheet/?src=mcp#w1.<base64 JSON>`). Browsers never send a fragment to a server, so the figures
  29. never reach Vercel's logs. The page's first script copies the fragment into memory and deletes it
  30. from the address bar *before* PostHog or Vercel Analytics load, so they see only `/worksheet/?src=mcp`.
  31. A short-lived server token was the alternative and was rejected: it means storing the figures.
  32. Employer labels are dropped from the link; nothing is written to storage.
  33. **Analytics.** Each call sends one PostHog `mcp_tool_call` event: `tool`, `ok`, `ms`, `client`,
  34. `client_ua`, and coarse booleans (`has_tips`, `has_ot`, `source` w2/estimate, `year`, `blocked`;
  35. `employees` count for the owner tool). Never an amount, a name or an argument, and no IP: claude.ai
  36. connector calls arrive from Anthropic's servers, so an IP-based id counts servers, not people
  37. (`distinct_id` is a fresh random id per call). **People are counted on the web side**: PostHog
  38. pageviews whose `$current_url` contains `src=mcp`, plus `worksheet_opened` (`prefilled`
  39. worker/owner/none, `src`), `worksheet_computed`, `worksheet_printed`, `worth_tried`,
  40. `connector_url_copied`. Mark a test call with header `x-tow-test: 1`.
  41. ## The rules, verified 2026-11-19 from primary sources
  42. Copies of every source are in `regs/` and `tests/sources.test.js` checks that each rule the code
  43. quotes is verbatim in its copy.
  44. | Rule | Source |
  45. |---|---|
  46. | 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) |
  47. | Overtime: up to $12,500, $25,000 joint | § 225(b)(1) |
  48. | 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) |
  49. | Married filing separately: nothing. SSN valid for work required | § 224(e)-(f), § 225(d)-(e) |
  50. | Tax years 2025-2028 | § 224(h), § 225(g) |
  51. | 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 |
  52. | SSTB exclusion not enforced for listed occupations until final SSTB regs (reserved in 1.224-1(g)) | Notice 2025-69 |
  53. | Qualified overtime: only the FLSA half (hours over 40 × 0.5 × regular rate) | § 225(c)(1); 2026 W-2 instructions, code TT |
  54. | 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) |
  55. | 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 |
  56. | 2026 rates and standard deduction ($16,100 single) for the tax-saved estimate | Rev. Proc. 2025-32 |
  57. ## How the Clover app works
  58. 1. A merchant installs from the Clover App Market (or opens it from their dashboard). Clover sends
  59. them to `/clover` (`site/api/clover/launch.js`), which starts OAuth v2. `/clover/callback`
  60. exchanges the code, seals the token pair (AES-256-GCM) into Cloudflare D1, and sets a 12-hour
  61. signed session cookie.
  62. 2. `/report/` calls `/api/data`. That reads the year from Clover in 85-day windows (the API caps a
  63. time filter at 90 days): employees, shifts, and payments with `expand=tender,order,employee,refunds,serviceCharge`.
  64. Refresh tokens are single-use and are rotated and saved before use. `site/api/_clover.js` maps the
  65. rows to the engine's input.
  66. 3. **The engine** (`site/api/_engine.js`) is pure, deterministic JavaScript with no model and no
  67. network. The browser runs the same file, so every answer the owner gives recomputes instantly.
  68. Answers save to D1 (`/api/answers`).
  69. 4. Anything Clover can't tell us is asked, with a visible default, and flagged until confirmed: pay
  70. rates, exempt status, workweek start, tip credit, tip sharing done off the register, bonuses,
  71. whether service charges go to staff, and occupation codes. `DATA_MODEL.md` has the field-by-field
  72. check.
  73. 5. Download CSV: the W-2 figures, every workweek, every tip row.
  74. ## The Clover engine's rules, and where they come from
  75. Cited in code where applied (`site/api/_engine.js` header):
  76. - IRS, [2026 General Instructions for Forms W-2 and W-3](https://www.irs.gov/instructions/iw2w3): codes TP and TT, Box 14b (up to two codes; "000" if any tips came from a nonqualifying occupation).
  77. - IRS [FS-2026-13](https://www.irs.gov/pub/taxpros/fs-2026-13.pdf), 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).
  78. - IRS [tipped occupations list](https://www.irs.gov/tippedoccupations), transcribed to `site/api/_ttoc.js`.
  79. - DOL Fact Sheets [#15](https://www.dol.gov/agencies/whd/fact-sheets/15-tipped-employees-flsa) (tip credit: OT on the full minimum wage; service charges are not tips but are wages in the regular rate), [#23](https://www.dol.gov/agencies/whd/fact-sheets/23-flsa-overtime-pay), [#56A](https://www.dol.gov/agencies/whd/fact-sheets/56a-regular-rate).
  80. One judgment call: workweeks hold the owner's **local** start (Sunday 00:00 stays Sunday 00:00 all
  81. year), so the two weeks with a DST change run 167 and 169 hours. Stepping a strict 168 hours put
  82. summer boundaries at 01:00 and moved a Saturday-night hour into the wrong week in the sandbox run.
  83. ## Tests
  84. npm test # 61: engine (18), deduction (15), sources verbatim (22), MCP (6)
  85. python3 scripts/fetch_oews.py # BLS OEWS May 2025 pay for every related SOC (needs BLS_API_KEY)
  86. node scripts/build_pages.js # → _occupations.json, the by-occupation page, llms(-full).txt, sitemap
  87. python3 scripts/indexnow.py # ping Bing/IndexNow with every sitemap URL after a deploy
  88. node scripts/check_sandbox.js # live pull from the sandbox merchant vs. hand-worked figures (3/3)
  89. ## Clover
  90. Tool skill: `~/.claude/skills/clover-api/SKILL.md`. Developer account and sandbox test merchant
  91. `4ZNNY5AK5SNT1` are shared with Block Brief.
  92. - **Sandbox app** `VRS0YGB8BCFY2` (NA sandbox, Private + Web). Read: Employees, Merchant, Orders,
  93. Payments. Site URL `https://tip-overtime-w2.vercel.app/clover`, launch path `/clover`, OAuth Code.
  94. Secret in `.env` and Vercel (`CLOVER_APP_ID`, `CLOVER_APP_SECRET`, `CLOVER_ENV=sandbox`).
  95. - **Proved end to end on 2026-11-02:** install from the sandbox App Market → Open the app → `/clover`
  96. → OAuth → `/clover/callback` → `/report/` showing 28 shifts and 7 payments. Then pay rates were
  97. entered in the page. TP $353.00, TT $205.50, and every employee's figures match the hand-worked
  98. ones. Answers persisted across a reload. The final install held READ permissions only. Seeding
  99. (`scripts/seed_sandbox.js`) briefly needed WRITE, which was removed and the app reinstalled.
  100. - **Production:** the developer account is verifying (Aidan's ID documents, ~11/14). Listing copy,
  101. permission reasons, icon, cover, screenshots and the walkthrough video are in `listing/`.
  102. ## Running it
  103. set -a; . ~/Desktop/workspace/bricks/.env; set +a # VERCEL_TOKEN
  104. node scripts/make_sample.js # rebuild the SAMPLE café
  105. python3 scripts/deploy.py # Vercel over REST (copies the engine to public/js first)
  106. python3 scripts/vercel_env.py KEY… # push .env keys to Vercel
  107. `.env` (gitignored): `ACCESS_SECRET`, `CLOUDFLARE_API_TOKEN`, `CLOVER_ENV`, `CLOVER_APP_ID`,
  108. `CLOVER_APP_SECRET` (later `CLOVER_PROD_APP_ID`, `CLOVER_PROD_APP_SECRET`). D1 database
  109. `tip-overtime-w2` (`2bfd0140-…`), Vercel project `prj_z2TmV6xcMppgVzpzIPamqulmcWn3`, Web Analytics on.
  110. ## Price
  111. Draft: one tier, **$29/month**, billed by Clover. Not set live. An owner installs in December,
  112. runs it in January, and can uninstall after W-2s go out, so the season costs about $58. That is
  113. less than an hour of an accountant rebuilding the same figures by hand, and the same price as
  114. Block Brief on the same marketplace.
  115. ## Expectation (written 2026-11-19, before the connector was listed anywhere)
  116. The read is **2027-02-26**, four weeks after W-2s are due (Jan 31) and seven before filing ends
  117. (Apr 15). Second read 2027-04-16.
  118. - **Base rates.** heistclips' connector sent 151 people to its site via `src=mcp` links in
  119. 11/16-11/19 (54% used it), where people already ask an AI the exact question. The Brick & Mortar
  120. business connector, same channel, got zero human calls in 7 days. Directory review for both
  121. Claude and ChatGPT has taken weeks; until a listing is live, the only way in is the custom URL
  122. or the data page being cited.
  123. - **Expected:** 40 people landing on `/worksheet/?src=mcp` by 2027-02-26, and 30 more arriving at
  124. the by-occupation page from search or AI citations. Most of it depends on a directory listing
  125. being live by mid-January.
  126. - **Would surprise us upward:** more than 300 `src=mcp` people by the read date. That would mean
  127. the filing-season question pulls through the directories the way the clipping question did.
  128. - **Would surprise us downward:** zero `src=mcp` people with a directory listing live for 30 days.
  129. That would mean assistants answer this from their own knowledge and never call a tool (the
  130. business-connector pattern), and the page is the only channel.
  131. - **Count with:** PostHog, `$host` tip-overtime-w2.vercel.app, pageviews where `$current_url`
  132. contains `src=mcp`, unique persons; `mcp_tool_call` counts calls, not people.
  133. ## Licence
  134. MIT.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.