Diceport

diceport

diceport rolls dice, flips coins, and picks random integers. It is built for the moments when a script or an agent needs a fair, explainable bit of chance: a roll reports every face that went into its total, and any call can take a seed that makes the outcome reproducible — same seed, same result, every time.

Install

npx @reneturcios/diceport roll 2d6

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/diceport

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

# Roll dice in NdM notation, with an optional +N / -N modifierdiceport roll 2d6# 2d6: [3, 5] total 8diceport roll 3d8+2 --seed 42   # reproducible
# Flip a coindiceport flip                   # heads (or tails)diceport flip --seed 7 --json
# Pick an integer between two bounds, inclusivediceport random 1 100diceport random 1 100 --seed 42
diceport --version

Notation is NdM: roll N dice with M sides each. The count may be left off (d20 rolls one die) and a flat modifier may be appended (2d6+3, 1d100-5).

Exit codes: 0 on success, 1 when a roll or range cannot be done (bad notation, an inverted range — the error says why), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/diceport mcp

MCP client configuration:

{  "mcpServers": {    "diceport": {      "command": "npx",      "args": ["-y", "@reneturcios/diceport", "mcp"]    }  }}

Tools

Seeded calls use a mulberry32 generator, so a seed fully determines the outcome and any reported result can be replayed. Unseeded calls draw from the platform random source.

Development

npm installnpm run build   # tsc -> dist/npm test        # node test runner over test/*.test.ts, no networknpm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.