Skip to main content
Glama
strength-formulas-mcp

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).