# Roman numeral convert

`roman-numeral-convert` · version 1.0.0 · Numbers & math · free, no key needed

Convert integers 1–3999 to canonical Roman numerals and strictly parse canonical numerals back to integers.

**Use when you need to: convert integer to canonical roman numeral · strictly parse a roman numeral · roman numeral conversion both directions.**

## Decide before calling

Read the [versioned contract](/v1/tools/roman-numeral-convert/versions/1.0.0) and the supported scope below. Reuse `roman-numeral-convert@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `roman-numeral-convert@1.0.0` for convert integer to canonical roman numeral. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- convert integer to canonical roman numeral
- strictly parse a roman numeral
- roman numeral conversion both directions
- format a number using roman numerals
- decode canonical subtractive roman notation
- validate and convert roman numeral text
- turn a roman numeral into an integer

## Not supported

- historical additive or non-canonical notation
- numbers below 1 or above 3999
- Unicode Roman numeral code points
- fractions or vinculum notation

## Behavior

- operation format requires value and forbids numeral; operation parse requires numeral and forbids value.
- Formatting uses the unique conventional modern form and only the subtractive pairs IV, IX, XL, XC, CD, and CM.
- Parsing accepts only uppercase ASCII canonical standard form; no whitespace trimming, case folding, or Unicode numeral normalization occurs.
- Both operations return the exact canonical pair {value, numeral}; no approximation, rounding, or tie-breaking occurs.
- At most 15 UTF-8 numeral bytes are accepted, and values are bounded to integers from 1 through 3999.

## Input

- `operation` (one of "format", "parse", required)
- `value` (integer, optional): min 1; max 3999
- `numeral` (string, optional): min length 1; max length 15; pattern `^[IVXLCDM]+$`

## Output

- `value` (integer, required): min 1; max 3999
- `numeral` (string, required): min length 1; max length 15; pattern `^[IVXLCDM]+$`

## Limits

- max numeral bytes: 15
- max value: 3999

## Example

Request input:

```json
{
  "operation": "format",
  "value": 1994
}
```

Response:

```json
{
  "result": {
    "value": 1994,
    "numeral": "MCMXCIV"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "roman-numeral-convert",
  "version": "1.0.0",
  "input": {
    "operation": "format",
    "value": 1994
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/roman-numeral-convert/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"operation":"format","value":1994}'
```

The machine-readable contract is at [/v1/tools/roman-numeral-convert/versions/1.0.0](/v1/tools/roman-numeral-convert/versions/1.0.0).

### CLI

```sh
node cli.mjs run roman-numeral-convert 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Number engineering format](/tools/number-engineering-format): Format an exact decimal in scientific or engineering notation with explicit precision and rounding.
- [Rational power](/tools/rational-power): Raise a rational number to an integer exponent and return the exact reduced result.
- [Array integer clamp](/tools/array-integer-clamp): Clamp an array of canonical integer strings to optional inclusive min and max bounds.
- [Array integer GCD](/tools/array-integer-gcd): Compute the non-negative greatest common divisor of an array of canonical integer strings.
- [Array integer LCM](/tools/array-integer-lcm): Compute the non-negative least common multiple of an array of canonical integer strings.
- [Integer divisors](/tools/integer-divisors): List every positive divisor of a positive integer, ascending.