strength-formulas-mcp
by amirdoit
README.md
# strength-formulas
Strength-sport math you can verify, and that AI agents can call instead of guessing.
- **`strength-formulas`**: a zero-dependency TypeScript library. Wilks, Wilks-2020, DOTS, IPF GL, legacy IPF Points, seven one-rep-max estimators, and plate loading.
- **`strength-formulas-mcp`**: an [MCP](https://modelcontextprotocol.io) server exposing the same math as five tools.
- **`skills/lifting-math`**: an [Agent Skill](https://agentskills.io) that tells an agent to use those tools and not do the arithmetic from memory.
Language models are bad at long-coefficient polynomials. Ask one for your DOTS score and you get a plausible number that is wrong. This repo makes the right number one tool call away.
## Install
Not published to npm yet, so install from source (Node 18+):
```bash
git clone https://github.com/amirdoit/strength-formulas
cd strength-formulas
npm ci && npm run build
```
## Library
```ts
// from the repo root after building; the package name will be "strength-formulas" once it is on npm
import { dots, goodlift, wilks2020, estimateOneRepMax, estimateOneRepMaxAll, weightForReps, platesPerSide } from "./packages/core/dist/index.js";
dots("male", 93, 800); // 509.00
goodlift("female", 70.5, 122.5, { equipment: "raw", event: "bench" }); // 96.78
wilks2020("female", 56, 612.5); // 847.27
estimateOneRepMax(100, 5, "epley"); // 116.67
estimateOneRepMaxAll(100, 5); // every formula + mean + spread
weightForReps(150, 5); // what to load for 5 reps off a 150 max
platesPerSide(142.5); // { perSide: [25, 25, 10, 1.25], exact: true, ... }
platesPerSide(225, { unit: "lb" }); // { perSide: [45, 45], ... }
```
Weights in scoring functions are **kilograms**. Plate math and 1RM work in any unit you pass.
## MCP server
After building (see Install), point your MCP client at the built server. Use the absolute path to your clone:
```json
{
"mcpServers": {
"strength-formulas": { "command": "node", "args": ["/absolute/path/to/strength-formulas/packages/mcp/dist/index.js"] }
}
}
```
Claude Code: `claude mcp add strength-formulas -- node /absolute/path/to/strength-formulas/packages/mcp/dist/index.js`
| Tool | What it does |
|---|---|
| `strength_scores` | Wilks, Wilks-2020, DOTS, IPF GL and IPF Points for a bodyweight and total |
| `estimate_one_rep_max` | One formula or all seven, with mean and spread. Optional RPE |
| `weight_for_reps` | Weight for a rep target given a 1RM |
| `plate_loading` | Plates per side, closest load at or below the target |
| `convert_weight` | kg and lb with the exact international pound |
All tools are read-only and make no network calls.
## Agent skill
Copy `skills/lifting-math/` into your agent's skills directory (for Claude Code: `.claude/skills/`). With a GitHub CLI that has `gh skill`: `gh skill install amirdoit/strength-formulas lifting-math`.
## Why you can trust the numbers
- **1,440 golden vectors** are generated by an independent Python implementation (`scripts/gen-vectors.py`) that regex-parses the constants out of the MIT-licensed [OpenPowerlifting coefficients crate](https://github.com/sstangl/openpowerlifting/tree/master/crates/coefficients) (vendored in `scripts/opl-sources/`). A typo in a TypeScript constant fails the suite. A mutation check confirms it: changing the last digit of one DOTS or IPF GL constant turns the suite red.
- **OpenPowerlifting's own published test cases** (IPF GL for the 2019 Worlds, Wilks-2020 official tables, IPF Points) are asserted directly.
- **Cross-checked against two published npm packages** (`wilks` 2.3.0 and `powerlifting-formulas` 0.2.3) over a grid of bodyweights and totals: agreement to their two-decimal rounding. Run `node scripts/cross-check-npm.mjs` to reproduce.
- **End-to-end MCP tests** spawn the built server over stdio and call every tool through the official SDK client.
- A weekly workflow re-downloads upstream and fails if OpenPowerlifting changes a coefficient.
## Conventions worth knowing
- Bodyweights outside a formula's valid range are clamped to its edge (same as OpenPowerlifting, so results match public meet data). IPF GL returns 0 below 35 kg and IPF Points below 40 kg.
- Non-positive bodyweight or total scores 0. `NaN` and `Infinity` throw a `TypeError`.
- A one-rep set returns the weight lifted as the 1RM. Several formulas would otherwise report a 1RM above a weight you actually lifted.
- Reps are limited to 1 through 36 (Brzycki and Lander are singular at 37 and 38). Estimates above roughly 10 reps are rough, and the docs say so.
- The RPE option adds `10 - RPE` reps in reserve before estimating. That is a common coaching shortcut, not a validated model.
- Plate loading assumes unlimited plates of each size and works in integer hundredths, so 2.5 + 1.25 + 0.25 never becomes 3.9999999999999996.
- Wilks-2020 is on a 600-point scale and is not a drop-in replacement for original Wilks (500).
## Other packages
Several solid scoring libraries already exist, including [`wilks`](https://www.npmjs.com/package/wilks), [`powerlifting-formulas`](https://www.npmjs.com/package/powerlifting-formulas) and the Python [`liftmath`](https://pypi.org/project/liftmath/). On the scoring formulas this library gives the same numbers, which is the point. What it adds is the 1RM and plate math in one place, strict input handling, a verification story you can reproduce, and the MCP server and skill for agents.
## Not in v0.1
Sinclair (Olympic weightlifting) coefficients, because they are not in the reference source and I would not ship constants I cannot verify. A PHP port is planned.
## Development
```bash
npm install
npm run build
npm test # core unit and golden-vector tests, MCP end-to-end tests
python3 scripts/gen-vectors.py # regenerate vectors (offline, deterministic)
python3 scripts/validate-skill.py
```
## License
MIT. Coefficient references and notices are in [NOTICE.md](NOTICE.md).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues