Dice Rolling Mcp

Name: Dice Rolling Mcp
Author: jimmcq

本地服务

github.com/jimmcq游戏娱乐840 周前更新

代码仓库

关于 Dice Rolling Mcp

Dice Rolling Mcp 是一个 TypeScript MCP 服务，使用密码学安全随机数为 AI 助手和桌面角色扮演游戏玩家掷骰。它解析标准及高级骰子记法，并返回结构化的掷骰与验证数据。

主要功能

01按标准骰子记法和修正值掷骰
02支持优势、重掷和爆骰
03支持成功计数与弃骰规则
04无需掷骰即可验证记法
05返回结构化结果和计算明细

适用场景

01为桌面角色扮演游戏生成公平骰点
02使用前检查骰子表达式
03在模拟中使用随机结果

MCP 相关

提供 dice_roll 和 dice_validate 工具，并通过 search 和 fetch 发现骰子主题。支持 STDIO 和 Streamable HTTP 传输，供本地或远程 MCP 客户端连接。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "dice-rolling": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/client-stdio"
      ]
    }
  }
}

启动命令npx -y @modelcontextprotocol/client-stdio

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@modelcontextprotocol/client-stdiostdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

掷骰子 MCP 服务

一个功能全面的 TypeScript 模型上下文协议（MCP）服务，为 AI 助手提供高级掷骰子功能。非常适合桌面游戏、RPG，以及任何需要结合游戏机制进行复杂随机数生成的应用。

问题：大模型无法真正掷骰子

当你让 AI 助手“掷骰子”时，它们实际上什么也没掷。大语言模型是确定性系统，会根据训练数据中的模式生成回答。当你让它掷一个 d20 时，它可能会回答“我掷出了 14”——但这个数字是通过文本预测生成的，并非随机数生成。

这会带来几个问题：

没有真正的随机性：结果并非真正随机，可能遵循可预测的模式
游戏公平性：对于桌面 RPG 至关重要，因为公平的骰子结果会影响游戏进程
模拟准确性：统计模拟需要正确的随机数生成
可复现性问题：相同的提示词可能会产生可疑地相似的“随机”结果

解决方案：让 AI 使用真正的骰子

这个 MCP 服务充当 AI 助手与实际随机数生成之间的桥梁。可以把它想象成给 AI 助手一套真正的骰子，而不是让它们想象自己在掷骰子。

工作原理：

AI 助手接收骰子记法（例如，“3d6+2”）
MCP 服务解析请求，并生成加密安全的随机数
应用真实的骰子机制（优势、爆炸骰、重掷等）
将真正随机的结果返回给 AI

结果是：AI 助手现在可以提供真正随机且符合数学公平性的掷骰结果，适用于实际游戏、模拟，以及任何需要真实随机性的应用。

功能

标准骰子记法

基础掷骰：1d20、3d6、2d10
修正值：1d20+5、2d6-3
多种骰子类型：1d20+2d6+3
百分骰：1d%（d100）
Fudge 骰：4dF（Fate/Fudge 系统）

高级机制

优势/劣势：2d20kh1（保留最高值）、2d20kl1（保留最低值）
丢弃机制：4d6dl1（丢弃最低值）、4d6dh1（丢弃最高值）
爆炸骰：3d6!（掷出最大值时重掷并累加）
重掷机制：4d6r1（重掷 1 点）
成功次数统计：5d10>7（统计 ≥7 的成功次数）

MCP 工具

`search`

发现可用的掷骰操作和文档。ChatGPT Connector 兼容性必需。

参数：

query（必需）：用于查找相关掷骰信息的搜索查询

返回：

content：包含 id、title 和 url 字段的搜索结果 JSON
structuredContent：包含相关性评分的机器可读搜索结果

`fetch`

根据 ID 获取特定掷骰主题的详细内容。

参数：

id（必需）：来自搜索结果的主题 ID

返回：

content：包含完整内容的 JSON 文档
structuredContent：元数据和结构化文档信息

`dice_roll`

使用标准记法执行掷骰，并可选择添加标签和输出详细信息。

参数：

notation（必需）：骰子记法字符串（例如，“3d6+2”）
label（可选）：掷骰的描述性标签
verbose（可选）：显示单个骰子的详细结果

返回：

content：包含掷骰结果和表情符号的易读文本
structuredContent：完整的掷骰数据，包括：
- notation：原始骰子记法
- total：最终结果
- rolls：单个骰子的结果及元数据（已丢弃、爆炸等）
- breakdown：数学计算明细字符串
- critical：检测 d20 掷骰是否大成功/大失败
- modifier：应用的修正值
- timestamp：掷骰的 ISO 时间戳

`dice_validate`

验证骰子记法，但不执行掷骰，并详细说明该记法的含义。

参数：

notation（必填）：要验证的骰子记法字符串

返回值：

content：易于阅读的验证结果
structuredContent：结构化验证数据，包括：
- valid：布尔类型的验证状态
- expression：解析后的骰子表达式（如果有效）
- breakdown：骰子和修饰符的结构化细分
- error：错误消息（如果无效）

结构化内容支持

所有工具都会按照 OpenAI Apps SDK 规范，同时返回易于阅读的 content 和机器可读的 structuredContent。这使得以下功能成为可能：

以编程方式访问掷骰结果和验证数据
使用组件模板进行丰富的 UI 渲染（未来增强）
与需要结构化数据的 AI 工作流集成
实现掷骰历史记录、统计数据和可视化等高级功能

结构化内容包含每项操作的完整元数据，适用于基于掷骰功能构建高级应用程序。

远程 MCP 集成（Streamable HTTP）

此 MCP 服务支持用于远程连接的 Streamable HTTP 传输，并实现 OpenAI MCP 规范，包括用于发现操作的必需 search 工具。

兼容：

Claude 远程 MCP 连接器（以及 Claude Desktop）
ChatGPT 连接器（目前仅限 Developer Mode）
任何支持 Streamable HTTP 传输的 MCP 客户端

连接端点：

本地开发：http://localhost:3000/mcp
生产环境：https://dice-rolling-mcp.vercel.app/mcp

search 和 fetch 工具可让 Claude 和 ChatGPT 自动发现可用的掷骰操作。

本地 MCP 集成（STDIO）

要与 Claude Desktop 本地集成，请配置你的 claude_desktop_config.json：

{
  "mcpServers": {
    "dice-rolling-remote": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/client-stdio", 
        "connect", 
        "https://dice-rolling-mcp.vercel.app/mcp"
      ]
    }
  }
}

本地安装

git clone https://github.com/jimmcq/dice-rolling-mcp
cd dice-rolling-mcp
npm install
npm run build

用法

与 Claude Desktop 搭配使用

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "dice-roller": {
      "command": "node",
      "args": ["path/to/dice-rolling-mcp/dist/index.js"]
    }
  }
}

特定平台示例：

Windows（WSL）：

{
  "mcpServers": {
    "dice-roller": {
      "command": "wsl",
      "args": ["node", "/path/to/dice-rolling-mcp/dist/index.js"]
    }
  }
}

macOS/Linux：

{
  "mcpServers": {
    "dice-roller": {
      "command": "node",
      "args": ["/path/to/dice-rolling-mcp/dist/index.js"]
    }
  }
}

独立服务端

npm run start

示例

基本掷骰

Human: Roll 3d6+2 for damage
Assistant: You rolled 3d6+2 for damage:
🎲 Total: 13
📊 Breakdown: 3d6:[4,2,5] + 2

优势系统

Human: Roll 2d20kh1+5 for attack with advantage
Assistant: You rolled 2d20kh1+5 for attack with advantage:
🎲 Total: 23
📊 Breakdown: 2d20:[12,18] keep highest + 5

验证

Human: Is "4d6kh3+2d8+5" valid dice notation?
Assistant: ✅ Valid dice notation: 4d6kh3+2d8+5

Breakdown:
• 4d6 (keep highest 3)
• 2d8
• Modifier: +5

发现（远程 MCP 集成）

Human: What dice operations are available?
Assistant: [Calls search tool with query "dice"]
🎲 Found dice rolling operations:
- Basic Dice Notation: Learn standard XdY format
- D&D Advantage and Disadvantage: 2d20kh1 mechanics
- Combat Roll Examples: Attack, damage, spells
- Ability Score Generation: 4d6kh3 for character stats

架构

核心组件

解析器（src/parser/）：使用基于正则表达式的解析对骰子记法进行分词和解析
掷骰器（src/roller/）：使用经过加密保护的随机数生成执行骰子表达式
MCP 服务（src/index.ts）：实现模型上下文协议，以集成 AI 助手
类型系统（src/types.ts）：为所有骰子机制提供全面的 TypeScript 定义

关键设计决策

安全性：使用 Node.js crypto.randomInt() 生成经过加密保护的随机数
可扩展性：模块化架构支持轻松添加新的骰子机制
兼容性：目标为 ES2022，并提供回退方案以支持更多 Node.js 版本
类型安全：完整的 TypeScript 实现，并启用严格类型检查

测试

npm test

测试套件涵盖：

对所有支持机制的骰子记法解析
使用模拟随机数生成执行掷骰
边缘情况和错误处理
MCP 协议合规性

开发

项目结构

dice-rolling-mcp/
├── src/
│   ├── index.ts              # MCP server implementation
│   ├── parser/               # Dice notation parser
│   ├── roller/               # Dice rolling engine
│   ├── statistics/           # Statistical analysis tools
│   └── types.ts              # TypeScript definitions
├── __tests__/                # Test suite
├── dist/                     # Compiled JavaScript
└── examples/                 # Usage examples

添加新机制

在 types.ts 中扩展 DiceTerm 接口
更新 dice-notation-parser.ts 中的解析器正则表达式
在 dice-roller.ts 中实现该机制
添加全面的测试

配置

该服务通过 DiceRollerConfig 接口支持多种配置选项：

每次掷骰的最大骰子数
骰子的最大面数
随机数来源选择
历史记录大小限制

技术规格

语言：TypeScript 5.8+
运行时：Node.js 18+（已使用 v24.0.2 测试）
协议：MCP（Model Context Protocol）2024-11-05
OpenAI 兼容性：实现 OpenAI MCP 规范，并提供必需的 search 工具
传输支持：STDIO（本地 Claude Desktop）+ Streamable HTTP（远程连接）
依赖项：精简（zod、@modelcontextprotocol/sdk、@vercel/mcp-adapter）
模块系统：ES Modules
测试框架：Jest 与 ts-jest

安全注意事项

输入验证可防止恶意骰子表达式
资源限制可防止通过极大规模的掷骰导致 DoS
使用密码学安全的随机数生成
无外部网络依赖

链接

代码仓库：https://github.com/jimmcq/dice-rolling-mcp
在线演示：https://dice-rolling-mcp.vercel.app
MCP 端点：https://dice-rolling-mcp.vercel.app/mcp

作者

Jim McQuillan

GitHub：https://github.com/jimmcq
LinkedIn：https://www.linkedin.com/in/jimmcquillan/

许可证

ISC

贡献

欢迎贡献！请确保：

所有测试均通过（npm test）
代码遵循现有模式和约定
新功能包含适当的测试覆盖
符合 TypeScript 严格模式要求

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Dice Rolling Mcp

关于 Dice Rolling Mcp

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

掷骰子 MCP 服务

问题：大模型无法真正掷骰子

解决方案：让 AI 使用真正的骰子

功能

标准骰子记法

高级机制

MCP 工具

search

fetch

dice_roll

dice_validate

结构化内容支持

远程 MCP 集成（Streamable HTTP）

兼容：

连接端点：

本地 MCP 集成（STDIO）

本地安装

用法

与 Claude Desktop 搭配使用

独立服务端

示例

基本掷骰

优势系统

验证

发现（远程 MCP 集成）

架构

核心组件

关键设计决策

测试

开发

项目结构

添加新机制

配置

技术规格

安全注意事项

链接

作者

许可证

贡献

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

`search`

`fetch`

`dice_roll`

`dice_validate`