Random Number Mcp

随机数 MCP

Python 标准库中的必备随机数生成工具，包括用于整数、浮点数、加权选择、列表打乱和安全令牌生成的伪随机及密码学安全操作。

想了解 Agent 技能版本？random-number-skills 以 Agent 技能而非 MCP 服务的形式，实现了相同的随机数生成策略。

演示视频

https://github.com/user-attachments/assets/303a441a-2b10-47e3-b2a5-c8b51840e362

工具

工具	用途	Python 函数
random_int	生成随机整数	random.randint()
random_float	生成随机浮点数	random.uniform()
random_choices	从列表中选择项目（可选加权）	random.choices()
random_shuffle	返回项目顺序已打乱的新列表	random.sample()
random_sample	从总体中选择 k 个不重复的项目	random.sample()
secure_token_hex	生成密码学安全的十六进制令牌	secrets.token_hex()
secure_random_int	生成密码学安全的整数	secrets.randbelow()

设置

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "random-number": {
      "command": "uvx",
      "args": ["random-number-mcp"]
    }
  }
}

工具参考

random_int

生成一个介于 low 和 high 之间（含两端）的随机整数。

参数：

• low（int）：下限（含）
• high（int）：上限（含）

示例：

{
  "name": "random_int",
  "arguments": {
    "low": 1,
    "high": 100
  }
}

random_float

生成一个介于 low 和 high 之间的随机浮点数。

参数：

• low（float，可选）：下限（默认值：0.0）
• high（float，可选）：上限（默认值：1.0）

示例：

{
  "name": "random_float",
  "arguments": {
    "low": 0.5,
    "high": 2.5
  }
}

random_choices

从总体中有放回地选择 k 个项目，可选择按权重抽取。

参数：

• population（list）：供选择的项目列表
• k（int，可选）：要选择的项目数（默认值：1）
• weights（list，可选）：各项目的权重（默认值：权重相等）

示例：

{
  "name": "random_choices",
  "arguments": {
    "population": ["red", "blue", "green", "yellow"],
    "k": 2,
    "weights": [0.4, 0.3, 0.2, 0.1]
  }
}

random_shuffle

返回一个项目顺序随机排列的新列表。

参数：

• items（list）：要打乱的项目列表

示例：

{
  "name": "random_shuffle",
  "arguments": {
    "items": [1, 2, 3, 4, 5]
  }
}

random_sample

从总体中无放回地选择 k 个不重复的项目。

参数：

• population（list）：供选择的项目列表
• k（int）：要选择的项目数

示例：

{
  "name": "random_sample",
  "arguments": {
    "population": ["a", "b", "c", "d", "e"],
    "k": 2
  }
}

secure_token_hex

生成密码学安全的随机十六进制令牌。

参数：

• nbytes（int，可选）：随机字节数（默认值：32）

示例：

{
  "name": "secure_token_hex",
  "arguments": {
    "nbytes": 16
  }
}

secure_random_int

生成一个小于 upper_bound 的密码学安全随机整数。

参数：

• upper_bound（int）：上限（不含）

示例：

{
  "name": "secure_random_int",
  "arguments": {
    "upper_bound": 1000
  }
}

安全注意事项

此软件包同时提供标准伪随机函数（适用于模拟、游戏等）和密码学安全函数（适用于令牌、密钥等）：

• 标准函数（random_int、random_float、random_choices、random_shuffle）：使用 Python 的 random 模块，速度快，但不具备密码学安全性
• 安全函数（secure_token_hex、secure_random_int）：使用 Python 的 secrets 模块，速度较慢，但具备密码学安全性

开发

前提条件

• Python 3.10+
• uv 包管理器

设置

# Clone the repository
git clone https://github.com/example/random-number-mcp
cd random-number-mcp

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linting
uv run ruff check --fix
uv run ruff format

# Type checking
uv run mypy src/

MCP 客户端配置

{
  "mcpServers": {
    "random-number-dev": {
      "command": "uv",
      "args": [
        "--directory",
        "<path_to_your_repo>/random-number-mcp",
        "run",
        "random-number-mcp"
      ]
    }
  }
}

**注意：**将 <path_to_your_repo>/random-number-mcp 替换为克隆仓库的绝对路径。

构建

# Build package
uv build

# Test installation
uv run --with dist/*.whl random-number-mcp

发布检查清单

1. 更新版本：

   • 在 pyproject.toml、src/random_number_mcp/__init__.py 和 server.json 中递增 version 编号。

2. 更新变更日志：

   • 在 CHANGELOG.md 中为此次发布添加新条目。

     • 使用编码 Agent 根据 git diff 上下文起草说明。

     Update the @CHANGELOG.md for the latest release.
     List all significant changes, bug fixes, and new features.
     Here's the git diff:
     [GIT_DIFF]
     

   • 与其他所有待处理更改一起提交。

3. 创建 GitHub 发布：

   • 在 GitHub UI 上起草新发布。
     • 使用 UI 标记发布。
   • GitHub 工作流会自动构建软件包并发布到 PyPI。

使用 MCP Inspector 测试

如需探索和／或开发此服务，请使用 MCP Inspector npm 实用工具：

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run local development server with the inspector
npx @modelcontextprotocol/inspector uv run random-number-mcp

# Run PyPI production server with the inspector
npx @modelcontextprotocol/inspector uvx random-number-mcp

MCP Registry

mcp-name: io.github.zazencodes/random-number-mcp

许可证

MIT 许可证——详情请参阅 LICENSE 文件。