Skip to main content
Glama
README.md
# bodymeasure

How tall is a 30-year-old man at the 50th percentile in the
US? And which percentile does a measured popliteal height of
43.1 cm land on for a 34-year-old woman? bodymeasure asks the
Humanform API — a service of anthropometric reference data —
and returns its answers as JSON, in both directions:

- **Forward:** give a percentile, get the measurement value
  that sits there for a person of a given sex, age, and
  country.
- **Reverse:** give a measured value, get the percentile it
  falls on for that same kind of person.

Two catalogue calls round out the surface: the measurement
names and body groups the API supports, and its country codes
and labels.

## Configuration

You bring your own Humanform API key:

```bash
export HUMANFORM_API_KEY="your key"
```

Without it, bodymeasure does not guess: every call fails with
`HUMANFORM_API_KEY is not set`, no request is made, and no
measurement is invented. `HUMANFORM_API_URL` overrides the
API base URL (`https://api.humanform.app` by default).

## CLI

Each subcommand takes its arguments as one JSON string; the
two list commands take `"{}"`.

```bash
HUMANFORM_API_KEY=... npx @reneturcios/bodymeasure predict_measurement '{"measurement":"Stature","sex":"Male","age":30,"percentile":50,"country":"US","unit":"cm"}'
HUMANFORM_API_KEY=... npx @reneturcios/bodymeasure percentile_lookup '{"measurement":"PoplitealHeight","sex":"Female","age":34,"country":"US","unit":"cm","value":43.1}'
HUMANFORM_API_KEY=... npx @reneturcios/bodymeasure list_measurements '{}'
HUMANFORM_API_KEY=... npx @reneturcios/bodymeasure list_countries '{}'
npx @reneturcios/bodymeasure --version
```

Output is the Humanform payload as JSON. Exit codes: `0` on
success, `1` on a runtime error (including a missing key, a
validation failure, or an upstream error), `2` on a usage
error.

Arguments are checked before any request: string arguments
must be non-empty, `age` must be a finite number greater
than 0, `percentile` must lie strictly between 0 and 100, and
a lookup `value` must be finite. When the API itself answers
with an error body carrying `error` and `message` fields,
that pair is reported as `<error>: <message>`.

## MCP server

```bash
npx -y @reneturcios/bodymeasure mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "bodymeasure": {
      "command": "npx",
      "args": ["-y", "@reneturcios/bodymeasure", "mcp"],
      "env": { "HUMANFORM_API_KEY": "your key" }
    }
  }
}
```

### Tools

- `predict_measurement` — Forward lookup: percentile →
  measurement value. Requires `measurement`, `sex`, `age`,
  `percentile`, `country`, and `unit`.
- `percentile_lookup` — Reverse lookup: measured value →
  percentile. Requires `measurement`, `sex`, `age`, `country`,
  `unit`, and `value`.
- `list_measurements` — List all supported measurement names
  and body groups. No arguments.
- `list_countries` — List supported country codes and labels.
  No arguments.

## Docker

```bash
docker run -i -e HUMANFORM_API_KEY="your key" ghcr.io/cloudcorprecords/bodymeasure
docker run --rm -e HUMANFORM_API_KEY="your key" ghcr.io/cloudcorprecords/bodymeasure list_countries '{}'
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios