Skip to main content
Glama
trpg-dice-mcp

trpg-dice-mcp

TRPG 掷骰 MCP Server v2.0

密码学安全随机的 TRPG 掷骰服务器,支持完整骰子表达式引擎、多系统规则预设、暗骰保密。

快速开始

配置 MCP 客户端

在你的 MCP 客户端配置中添加:

{
  "mcpServers": {
    "trpg-dice": {
      "command": "npx",
      "args": ["-y", "trpg-dice-mcp"]
    }
  }
}

Windows 客户端

部分 Windows 环境需要:

{
  "mcpServers": {
    "trpg-dice": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "trpg-dice-mcp"]
    }
  }
}

Related MCP server: MCP Dice Roller

工具一览

工具

用途

示例

roll_dice

掷骰表达式求值

3d6+2, 4d6kh3, d%, (8d6)/2

roll_table

随机表抽取(范围/权重/等概率)

遭遇表、战利品表

roll_check

技能/属性检定

CoC 7e、D&D 5e、PbtA、GURPS

roll_pool

骰池检定

Shadowrun、WoD、Year Zero

roll_fate

FATE 检定

4dF + 修正值

pick_random

随机抽取

先攻排序、抽牌

get_roll_history

查询历史

最近掷骰记录

reveal_hidden_roll

揭示暗骰

追溯查看之前暗骰的完整结果

opposed_check

双方对抗检定

技能对抗、先攻对抗

支持的骰子表达式

基本语法

表达式

含义

3d6

掷 3 颗 6 面骰

1d20+5

d20 + 修正 5

4d6kh3

4d6 取最高的 3 个(D&D 属性)

2d20kl1

2d20 取最低的 1 个(劣势)

3d6!

爆炸骰(出 6 追加一骰)

1d6r2

重骰直到结果 > 2

(8d6)/2

8d6 结果除以 2(向下取整)

floor(3d6/2)

同上,显式 floor

特殊骰

记号

含义

d% / d100

百分骰(1–100)

dF

Fudge 骰(-1/0/+1)

d66

查表骰(11–66,36 个离散值)

修饰符

修饰符

含义

khN

保留最高的 N 个

klN

保留最低的 N 个

dhN

丢弃最高的 N 个

dlN

丢弃最低的 N 个

!

爆炸(出最大值追加一骰)

!!

复合爆炸(累计为单骰值)

!>N

阈值爆炸(出 ≥N 追加)

rN

递归重骰直到结果 > N

规则预设

预设

系统

骰子

判定

coc7

克苏鲁的呼唤 7 版

1d100

≤ 技能

dnd5e

D&D 5 版

1d20+mod

≥ DC

pbta

Powered by the Apocalypse

2d6+mod

固定阈值

gurps

GURPS

3d6

≤ 技能

runequest

RuneQuest

1d100

≤ 技能

fate

FATE

4dF+mod

vs 难度

模型可通过 rules://presets/{name} 资源查阅详细判定规则。

安全性

  • 随机源:使用 node:crypto.randomInt(),密码学安全,无模偏差

  • 暗骰:hidden: true 时,文本和结构化响应均只返回保密回执;完整结果写入本地 JSONL 文件。文件未加密。

  • 揭示控制:暗骰揭示默认启用,GM 可通过 reveal_hidden_roll 工具回溯查看暗骰结果

响应与批量抽取

所有工具同时返回完整 JSON 文本和 structuredContent,其中 summary 是可读摘要。查询历史和揭示暗骰的明细也包含在文本响应中。

roll_table 的 results 包含每次抽取;顶层 selected、roll 等字段保留第一次结果。unique=true 表示同一选项最多选一次,权重模式按剩余权重抽取。等概率模式只需提供 label,无需构造骰子表达式。

shared_subroll=true 可让同一次调用中重复选中的条目共享其子掷骰结果,默认 false。子表的等概率/权重模式使用自身选项;范围子表沿用父表表达式。范围表必须显式传 dice,并完整覆盖值域,除非设置 allow_gap=true。

取整与检定

  • 除法默认向下取整;rounding 只改变除法的取整方式,普通小数加减保留小数。

  • 显式函数覆盖内部除法的自动取整,如 ceil(5/2)=3;函数内部先按原值计算,再对整个参数取整。

  • PbtA 无需 target。CoC 奖励/惩罚骰共用个位,比较完整百分骰候选值,00 按 100 处理。

  • 优劣势要求表达式中恰好有一组未修饰的 1d20;奖励骰要求恰好有一组未修饰的 1d100/d%。

  • 自定义 degrees 按顺序首个命中生效,覆盖预设;条件支持 roll/total/target/margin、比较、四则运算、括号和取整函数,不支持三元表达式。无效条件明确报错。

  • GURPS 等预设沿用规则资源中声明的简化实现。tens_crit 保留每颗 d10 骰出 10 额外加一成功的简化行为,不包含 V5 的完整暴击规则。

本地数据与并发

默认目录为 ~/.trpg-dice-mcp,可通过 MCP 进程的 TRPG_DICE_DATA_DIR 环境变量指定其他目录。不同目录可以隔离不同跑团的历史。

  • roll-history.json:持久化计数器和最近 1000 条历史;单次查询最多 50 条。历史查询不会产生新的掷骰记录。

  • hidden-rolls.jsonl:暗骰完整结果和揭示事件,兼容旧版 JSONL 记录。暗骰日志不随普通历史裁剪。

  • 多个新版进程共享目录时,文件锁保护读写与编号分配;进程异常退出后可回收过期锁。

  • 新写入的普通历史不会保存暗骰结果;旧文件不自动清理。reveal_hidden_roll 是显式揭示工具,客户端仍需自行管理谁可以调用它。

表达式最多 200 字符、每组最多 500 颗骰;每次工具调用含批量、重骰及爆炸在内最多 5000 颗。单颗爆炸达到 100 次迭代会返回截断提示。随机表最多 200 项、批量最多 100 次、嵌套深度最多 3 层。

测试包含原有解析器/属性测试,以及规则回归、工具 schema、暗骰脱敏、历史分页和两个真实 stdio 进程共享存储。所有存储测试均使用独立临时目录。

打包会自动构建 dist/。修改源码后需重新连接 MCP;使用同一数据目录的旧版进程也应一并重启。完整变更见 CHANGELOG.md。

开发

npm ci
npm run typecheck
npm test
npm pack --dry-run

项目结构

src/
├── index.ts          # stdio 入口
├── server.ts         # MCP 工具注册
├── rng/              # 随机数核心(SecureRng / SeededRng)
├── dice/             # 表达式引擎(tokenizer/parser/eval/range/table)
├── rules/            # 规则预设 + degrees DSL
├── resources/        # MCP Resources(规则速查)
├── state/            # 历史记录 + 暗骰存储
├── tools/            # 9 个 MCP 工具
└── utils/            # 格式化 / i18n

许可

MIT

Available Tools

9 tools
get_roll_historyA
Read-only

查询掷骰历史。暗骰条目只显示"结果保密"。

示例:

  • 最近 10 条:limit=10

  • 按标签过滤:tag="理智检定"

  • 分页:limit=10, offset=10

Inputs: tag, tool, limit, locale, +2 more.

opposed_checkA

双方对抗检定。比较两名角色的 margin/total/成功等级判定胜负。

示例:

  • CoC 对抗:preset="coc7", actor1={"modifier":0}, actor2={"modifier":0}, target=60

  • D&D 先攻对抗:dice="1d20", actor1={"modifier":3}, actor2={"modifier":1}, mode="roll_over"

Inputs: dice, mode, tags, times, +9 more.

pick_randomA

从列表中随机抽取。Fisher-Yates 洗牌 + 密码学随机。

示例:

  • 先攻排序:items=["Alice","Bob","Carol","Dave"](不放回抽取全部)

  • 抽 3 张牌:items=["♠A","♠K","♠Q","♠J","♠10"], count=3

Inputs: items (required), tags, count, hidden, +3 more.

reveal_hidden_rollA

解锁查看暗骰结果,返回完整掷骰明细。

示例:

  • reveal_hidden_roll roll_id="h7"

  • reveal_hidden_roll roll_id="#h12" reason="战斗结束后揭示"

Inputs: roll_id (required), locale, reason.

roll_checkB

技能/属性检定。支持多种规则预设和自定义成功等级。

示例:

  • CoC 7e 技能检定:preset="coc7", target=60

  • D&D 5e 攻击:preset="dnd5e", dice="1d20+5", target=15

  • PbtA 检定:preset="pbta", dice="2d6+1"

  • 优势攻击:dice="1d20+5", target=15, advantage="adv"

Inputs: dice, mode, tags, times, +8 more.

roll_diceA

掷骰并计算完整算术表达式。支持四则运算、括号、取整函数及全部修饰符。

示例:

  • 普通掷骰:expression="3d6+2"

  • 优弃:expression="4d6kh3"(4d6 取最高的 3 个)

  • 爆炸骰:expression="3d6!"(骰出 6 追加一骰)

  • 带除法:expression="(8d6)/2"

  • 百分骰:expression="d%"

  • Fudge骰:expression="4dF"

  • d66查表骰:expression="d66"

Inputs: expression (required), tags, times, hidden, +3 more.

roll_fateB

FATE 系统专用:4dF + 修正值,带梯形评价。

示例:

  • roll_fate modifier=3 difficulty=2

Inputs: tags, hidden, locale, reason, +2 more.

roll_poolA

骰池检定(Shadowrun / WoD / Year Zero 等)。统计满足条件的成功骰数。

示例:

  • Shadowrun:count=10, sides=6, success_condition=">=target", target=5, ones_glitch=true

  • WoD:count=6, sides=10, target=8, ones_cancel=true, tens_crit=true

  • Year Zero:count=8, sides=6, target=6

Inputs: count (required), target (required), tags, sides, +11 more.

roll_tableA

从随机表中抽取结果。支持三种模式互斥:显式范围、权重、等概率。支持嵌套触发。

示例:

  • 范围模式:options=[{"label":"哥布林","min":1,"max":8},{"label":"兽人","min":9,"max":14}], dice="1d20"

  • 权重模式:options=[{"label":"普通","weight":70},{"label":"稀有","weight":25},{"label":"传说","weight":5}]

  • 等概率:options=[{"label":"红","min":1,"max":1},{"label":"蓝","min":2,"max":2}], dice="1d2"(或不传 dice)

  • 嵌套触发:options=[{"label":"遭遇","min":1,"max":5,"trigger_roll":"1d4+1"}]

Inputs: options (required), dice, tags, times, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of TRPG rolling: basic dice expressions, tables, skill checks, dice pools, FATE dice, arbitrary selection, history, hidden roll reveal, and opposed checks. No two tools have overlapping purposes, and the descriptions clarify niche uses like d66 or nested triggers.

    Naming Consistency5/5

    All tool names follow a clear verb_first_noun pattern in snake_case (roll_dice, roll_table, pick_random, get_roll_history, reveal_hidden_roll). The roll_* prefix is used for dice-related tools, with only opposed_check deviating slightly but still readable and consistent in style.

    Tool Count5/5

    9 tools is well-scoped for a TRPG dice server, covering the core surface without bloat. Each tool serves a distinct gameplay need, from basic rolls to history management, making the count appropriate.

    Completeness5/5

    The tool set covers the full life cycle of dice rolls: rolling (multiple types), evaluating checks/pools, handling tables, tracking history, revealing hidden rolls, and even opposed checks. Missing operations like clearing history or editing rolls are not essential for the domain, so the surface feels complete.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides tools for rolling dice using standard notation, flipping coins, and selecting random items from lists. It supports advanced tabletop gaming features such as character stat generation and keep-highest/lowest mechanics.
      6
      19 PyPI
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides comprehensive TRPG dice rolling functionality including standard notation, advantage/disadvantage mechanics, and success-counting dice pools. It enables users to perform complex dice logic and track roll history through an MCP-compliant interface.
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables dice rolling for RPG games using standard dice notation, supporting complex expressions like keep/drop, reroll, exploding dice, and batch rolls.
      4
      4
      MIT