{
  "markdown": "# Random Number MCP\n\nEssential random number generation utilities from the Python standard library, including pseudorandom and cryptographically secure operations for integers, floats, weighted selections, list shuffling, and secure token generation.\n\n> Looking for the agent skill version? [random-number-skills](https://github.com/zazencodes/random-number-skills) implements the same random number generation strategy as an agent skill instead of an MCP server.\n\n## Demo Video\n\nhttps://github.com/user-attachments/assets/303a441a-2b10-47e3-b2a5-c8b51840e362\n\n<a href=\"https://glama.ai/mcp/servers/@zazencodes/random-number-mcp\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@zazencodes/random-number-mcp/badge\" alt=\"Random Number MCP server\" />\n</a>\n\n## Tools\n\n\n| Tool                | Purpose                                      | Python function   |\n| ------------------- | -------------------------------------------- | --------------------- |\n| `random_int`        | Generate random integers                     | `random.randint()`    |\n| `random_float`      | Generate random floats                       | `random.uniform()`    |\n| `random_choices`    | Choose items from a list (optional weights)  | `random.choices()`    |\n| `random_shuffle`    | Return a new list with items shuffled        | `random.sample()`     |\n| `random_sample`     | Choose k unique items from population        | `random.sample()`     |\n| `secure_token_hex`  | Generate cryptographically secure hex tokens | `secrets.token_hex()` |\n| `secure_random_int` | Generate cryptographically secure integers   | `secrets.randbelow()` |\n\n\n## Setup\n\n### Claude Desktop\n\nAdd this to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`   \n**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"random-number\": {\n      \"command\": \"uvx\",\n      \"args\": [\"random-number-mcp\"]\n    }\n  }\n}\n```\n\n## Tool Reference\n\n### `random_int`\n\nGenerate a random integer between low and high (inclusive).\n\n**Parameters:**\n- `low` (int): Lower bound (inclusive)\n- `high` (int): Upper bound (inclusive)\n\n**Example:**\n```json\n{\n  \"name\": \"random_int\",\n  \"arguments\": {\n    \"low\": 1,\n    \"high\": 100\n  }\n}\n```\n\n### `random_float`\n\nGenerate a random float between low and high.\n\n**Parameters:**\n- `low` (float, optional): Lower bound (default: 0.0)\n- `high` (float, optional): Upper bound (default: 1.0)\n\n**Example:**\n```json\n{\n  \"name\": \"random_float\",\n  \"arguments\": {\n    \"low\": 0.5,\n    \"high\": 2.5\n  }\n}\n```\n\n### `random_choices`\n\nChoose k items from a population with replacement, optionally weighted.\n\n**Parameters:**\n- `population` (list): List of items to choose from\n- `k` (int, optional): Number of items to choose (default: 1)\n- `weights` (list, optional): Weights for each item (default: equal weights)\n\n**Example:**\n```json\n{\n  \"name\": \"random_choices\",\n  \"arguments\": {\n    \"population\": [\"red\", \"blue\", \"green\", \"yellow\"],\n    \"k\": 2,\n    \"weights\": [0.4, 0.3, 0.2, 0.1]\n  }\n}\n```\n\n### `random_shuffle`\n\nReturn a new list with items in random order.\n\n**Parameters:**\n- `items` (list): List of items to shuffle\n\n**Example:**\n```json\n{\n  \"name\": \"random_shuffle\",\n  \"arguments\": {\n    \"items\": [1, 2, 3, 4, 5]\n  }\n}\n```\n\n### `random_sample`\n\nChoose k unique items from population without replacement.\n\n**Parameters:**\n- `population` (list): List of items to choose from\n- `k` (int): Number of items to choose\n\n**Example:**\n```json\n{\n  \"name\": \"random_sample\",\n  \"arguments\": {\n    \"population\": [\"a\", \"b\", \"c\", \"d\", \"e\"],\n    \"k\": 2\n  }\n}\n```\n\n### `secure_token_hex`\n\nGenerate a cryptographically secure random hex token.\n\n**Parameters:**\n- `nbytes` (int, optional): Number of random bytes (default: 32)\n\n**Example:**\n```json\n{\n  \"name\": \"secure_token_hex\",\n  \"arguments\": {\n    \"nbytes\": 16\n  }\n}\n```\n\n### `secure_random_int`\n\nGenerate a cryptographically secure random integer below upper_bound.\n\n**Parameters:**\n- `upper_bound` (int): Upper bound (exclusive)\n\n**Example:**\n```json\n{\n  \"name\": \"secure_random_int\",\n  \"arguments\": {\n    \"upper_bound\": 1000\n  }\n}\n```\n\n## Security Considerations\n\nThis package provides both standard pseudorandom functions (suitable for simulations, games, etc.) and cryptographically secure functions (suitable for tokens, keys, etc.):\n\n- **Standard functions** (`random_int`, `random_float`, `random_choices`, `random_shuffle`): Use Python's `random` module - fast but not cryptographically secure\n- **Secure functions** (`secure_token_hex`, `secure_random_int`): Use Python's `secrets` module - slower but cryptographically secure\n\n## Development\n\n### Prerequisites\n\n- Python 3.10+\n- [uv](https://docs.astral.sh/uv/) package manager\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/example/random-number-mcp\ncd random-number-mcp\n\n# Install dependencies\nuv sync --dev\n\n# Run tests\nuv run pytest\n\n# Run linting\nuv run ruff check --fix\nuv run ruff format\n\n# Type checking\nuv run mypy src/\n```\n\n### MCP Client Config\n\n```json\n{\n  \"mcpServers\": {\n    \"random-number-dev\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"<path_to_your_repo>/random-number-mcp\",\n        \"run\",\n        \"random-number-mcp\"\n      ]\n    }\n  }\n}\n```\n\n**Note:** Replace `<path_to_your_repo>/random-number-mcp` with the absolute path to your cloned repository.\n\n### Building\n\n```bash\n# Build package\nuv build\n\n# Test installation\nuv run --with dist/*.whl random-number-mcp\n```\n\n### Release Checklist\n\n1.  **Update Version:**\n    - Increment the `version` number in `pyproject.toml`, `src/random_number_mcp/__init__.py`, and `server.json`.\n\n2.  **Update Changelog:**\n    - Add a new entry in `CHANGELOG.md` for the release.\n        - Draft notes with coding agent using `git diff` context.\n\n        ```\n        Update the @CHANGELOG.md for the latest release.\n        List all significant changes, bug fixes, and new features.\n        Here's the git diff:\n        [GIT_DIFF]\n        ```\n        \n    - Commit along with any other pending changes.\n\n3.  **Create GitHub Release:**\n    - Draft a new release on the GitHub UI.\n        - Tag release using UI.\n    - The GitHub workflow will automatically build and publish the package to PyPI.\n\n## Testing with MCP Inspector\n\nFor exploring and/or developing this server, use the MCP Inspector npm utility:\n\n```bash\n# Install MCP Inspector\nnpm install -g @modelcontextprotocol/inspector\n\n# Run local development server with the inspector\nnpx @modelcontextprotocol/inspector uv run random-number-mcp\n\n# Run PyPI production server with the inspector\nnpx @modelcontextprotocol/inspector uvx random-number-mcp\n```\n\n## MCP Registry\n\nmcp-name: io.github.zazencodes/random-number-mcp\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n",
  "bytes": 6832,
  "sha": "2182e671995f8ed34f583c674ef954ed3a6744f0814136e09b1f76e07e002490",
  "repo_slug": "zazencodes/random-number-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_zazencodes_random_number_mcp_fad01c17/readme"
}