# Random MCP

A local Python MCP server for pseudorandom sampling. Uses the
[official MCP Python SDK](https://py.sdk.modelcontextprotocol.io/).

## Install and run

Requires Python 3.10 or newer. From this directory:

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/random-mcp
```

The server communicates over stdio and waits for an MCP client. It also supports
`python -m random_mcp` from the environment where it is installed. On Windows,
use `.venv\Scripts\python.exe` and `.venv\Scripts\random-mcp.exe`.

Configure your MCP host with an absolute path to the installed command:

```json
{
  "mcpServers": {
    "random": {
      "command": "/absolute/path/to/random-mcp/.venv/bin/random-mcp",
      "args": []
    }
  }
}
```

## Tools

- `random_number()` returns `{"value": 0.375}`: one uniform float in `[0, 1)`.
- `random_interval(minimum, maximum, kind="float")` returns `{"value": ...}`.
  Choose `"integer"` for whole numbers, with both endpoints included. Float
  sampling follows Python's `random.uniform`; rounding can include the upper
  endpoint. Equal bounds return that value. Reversed bounds, non-finite values,
  fractional integer bounds, and non-finite sampling results produce tool errors.
- `random_normal(mean=0, standard_deviation=1)` returns `{"value": ...}` from
  a normal distribution. Both parameters must be finite; standard deviation
  must be positive. Non-finite results produce tool errors.

Values shown are examples. Sampling uses Python's standard pseudorandom
generator, without public seed parameters. Each number call returns one sample.

### Dice

`roll_dice(expression, detail="auto")` accepts `NdM`, such as `1d10`, `2d10`,
or `100d10`, and sums such as `1d10 + 2d100 + 5d4`.
Each die is sampled independently from 1 through M, inclusive.
Whitespace, uppercase `D`, and leading zeros are accepted. Counts and sides
must be positive integers. Only addition is supported: modifiers, subtraction,
multiplication, and parentheses are rejected. Terms remain in input order.

- `auto`: include individual rolls for up to 100 total dice; use compact above 100.
- `full`: always include individual rolls.
- `compact`: return aggregates without individual rolls or roll arrays in memory.

For example, `roll_dice("1000d4")` returns this shape (totals vary):

```json
{
  "expression": "1000d4",
  "detail": "compact",
  "total_dice": 1000,
  "total": 2500,
  "terms": [{"count": 1000, "sides": 4, "subtotal": 2500}]
}
```

Full mode adds a `rolls` array to each term. Auto considers the total count across
all terms. Limits are 10,000 total dice, 100 terms, 1,000,000 sides per die,
and 10,000 expression characters. Invalid requests
return tool errors before any dice are rolled.

## Development

Install the development tools with `python -m pip install -e '.[dev]'` using
the virtual environment's Python. Run all checks before committing:

```sh
.venv/bin/python -m ruff check .
.venv/bin/python -m ruff format --check .
.venv/bin/python -m mypy
.venv/bin/python -m pytest
```

Apply automatic lint fixes and formatting with:

```sh
.venv/bin/python -m ruff check --fix .
.venv/bin/python -m ruff format .
```

[Ruff](https://docs.astral.sh/ruff/configuration/) checks application code and tests
for common errors, import ordering, and consistent formatting, with Python 3.10
as the target. [Mypy](https://mypy.readthedocs.io/en/stable/config_file.html) runs
in strict mode on `src`; pytest covers sampling, dice parsing, MCP validation,
and stdio calls. Tool settings live in `pyproject.toml`.

Features are delivered in five commits: uniform sampling, intervals, normal
sampling, simple dice, then compound dice. Each stage includes tests and docs.