使用说明

🎲 骰子掷骰器 MCP 服务器

一个全面的模型上下文协议（MCP）服务器，将桌面游戏的骰子机制直接引入Claude桌面应用。使用自然语言指令来掷骰子、抛硬币，并处理Dungeons & Dragons 5e（第五版龙与地下城）的机制。

✨ 特点

🎯 核心骰子掷骰

标准记号使用熟悉的格式进行滚动，比如 3d6， 1d20+5， 2d8-1
定制骰子掷一个2到1000面的任意骰子
**百分位数掷骰（或百分位数判定）**带有情境风味描述的d100（百分比骰子）

🪙 硬币抛掷

单次或多次（最多100次）抛硬币
多次翻转的自动统计

🐉 D&D 5e（龙与地下城第五版）机制

属性值生成4d6去掉最低值的方法
优势/劣势掷两次，取较高的/较低的分数
完成修正值计算

🎨 丰富输出

增强表情符号的结果（🎲，🪙，⭐，💀）
对重要数字使用粗体格式
单个卷材的详细分解
针对百分位数掷骰的上下文风味描述

🚀 快速入门

先决条件

Docker Desktop（桌面版）
克劳德桌面版
Docker MCP 工具包

安装

克隆并构建服务器：

git clone <your-repo>
cd dice-roller-mcp-server
docker build -t dice-roller-mcp .

设置MCP配置：

创建或更新 ~/.docker/mcp/registry.yaml:

registry:
  dice-roller:
    ref: "dice-roller-mcp:latest"

创建或更新 ~/.docker/mcp/catalogs/custom.yaml：

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  dice-roller:
    description: "Roll dice, flip coins, and handle D&D mechanics"
    title: "Dice Roller"
    type: server
    image: dice-roller-mcp:latest
    tools:
      - name: roll_dice_notation
      - name: flip_coin
      - name: roll_dnd_stats
      - name: roll_percentile
      - name: roll_advantage
      - name: roll_disadvantage
      - name: roll_custom_die
    metadata:
      category: productivity
      tags: [gaming, dice, dnd, rpg]

配置Claude桌面版：

更新 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock",
        "-v",
        "/Users/[YOUR_USERNAME]/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--registry=/mcp/registry.yaml",
        "--transport=stdio"
      ]
    }
  }
}

替换 [YOUR_USERNAME] 使用你实际的用户名。

重启Claude桌面版

🎮 使用示例

配置完成后，您可以使用自然语言与Claude交流：

基本骰子滚动

“掷3个6面骰子计算伤害”
“掷一个20面骰子来决定行动顺序”
“掷两个8面骰子加3点来治疗”

《龙与地下城》角色创建

“为我的新角色生成能力值”
“使用4d6并去掉最低点来计算属性值”

战斗机制

“为我的攻击掷一个有利条件的d20”
“以不利条件进行潜行检定”
“为狂野魔法掷一个百分比骰子”

实用卷纸（或多功能卷纸）

“抛硬币决定”
“掷一个100面的骰子”
“抛5枚硬币，然后告诉我结果”

🛠️ 可用工具

工具	描述	示例用法
`roll_dice_notation` 标准骰子记法 `3d6`， `1d20+5`， `2d8-1`
`roll_custom_die`	定制边的骰子	`d13`， `d47`， `d1000`
`flip_coin`	硬币抛掷	`1` 硬币或 `10` 硬币
`roll_percentile`	d100 带有风味	自动风味文本
`roll_dnd_stats`	D&D 能力值生成方式	4次6面骰子掷出后去掉最低值 × 6
`roll_advantage`	D&D 优势机制	投掷两次，取较高值
`roll_disadvantage`	D&D（龙与地下城）劣势	投掷两次，取较低结果

🔧 开发

本地测试

# Test the server directly (requires mcp package)
python3 dice_roller_server.py

# Test with Docker
docker run --rm -i dice-roller-mcp

# Verify MCP tools
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | docker run --rm -i dice-roller-mcp

添加新功能

添加新的工具功能到 dice_roller_server.py
用……装饰 @mcp.tool()
更新目录，加入新工具名称
重建Docker镜像
重启Claude桌面版

🔒 安全功能

无网络访问权限仅限纯数学运算
输入验证防止恶意或过度输入
资源限制最多100个骰子，每个骰子1000个面
非Root执行在容器中以无特权用户身份运行
无文件系统访问权限无状态操作

🎯 骰子符号参考

格式	描述	示例
`dX`	单个芯片（或单颗芯片）	`d6` 掷一个六面骰子
`NdX`	多个骰子	`3d6` 掷3个六面骰子
`NdX+Y`	带有修饰符的骰子	`1d20+5` = d20加5
`NdX-Y`	带惩罚的骰子	`2d8-1` = 2次8面骰子的点数之和减1

限制：

每次掷骰最多100个
每个骰子最多1000个面
修饰符：-999 至 +999

🎨 输出示例

标准卷

🎲 3d6+2: [4, 2, 6] + 2 = **14**

优势滚动（或“有利滚动”，具体含义可能根据上下文有所不同）

🎲 **Advantage** 1d20+3: [8, 15] → 15 + 3 = **18**

D&D 统计数据（或“D&D 属性值”）

🎲 **D&D Ability Scores** (4d6 drop lowest):

**Strength**: 15 (+2) - Rolled: [6, 5, 4]
**Dexterity**: 12 (+1) - Rolled: [4, 4, 4]
...
📊 **Total Modifier**: +8

带有风味的百分位数

🎲 **Percentile Roll**: 95% ⭐ Excellent!

🐛 故障排除

工具未显示

验证Docker镜像是否成功构建： docker images | grep dice-roller
检查MCP配置文件中的语法错误
确保Claude Desktop的配置指向正确的用户名路径
完全重启Claude桌面版

连接问题

验证Docker MCP网关是否正在运行： docker mcp server list
检查 Docker 套接字权限
验证配置文件中的YAML语法

无效的骰子记法

使用标准格式： 3d6， 1d20+5
检查骰子表示法中的拼写错误
确保数字在限定范围内

致谢

这个项目受到以下优秀教程的启发，并在该教程的基础上构建而成： **NetworkChuck（注：这是一个专有名词，直接翻译为“网络查克”可能无法准确传达其原意，通常保留原名，但在此提供直译以供参考）**他的视频为使用Docker集成创建MCP服务器提供了基础和指导。

NetworkChuck YouTube频道: https://www.youtube.com/@NetworkChuck（中文可表述为：“YouTube上的NetworkChuck频道”）
教程参考你需要立刻学习MCP（模型上下文协议）

特别感谢NetworkChuck，他让复杂的概念变得易于理解，并激励开发者们去打造酷炫的项目！

📄 许可证

MIT 许可证 - 请随意修改和分发！

🤝 贡献

为仓库创建分支（或“克隆仓库”）
创建一个特性分支
为新功能添加测试
提交一个拉取请求

祝你玩得开心！ 🎲（骰子）

在NetworkChuck教程的指导下构建