骰子滚动MCP服务器
一个基于TypeScript的全面模型上下文协议（MCP）服务器，为人工智能助手提供高级的掷骰功能。非常适合桌面游戏、角色扮演游戏以及任何需要结合游戏机制进行复杂随机数生成的应用。
问题：大型语言模型实际上无法掷骰子
当你让AI助手“掷骰子”时，它实际上并没有掷出任何东西。大型语言模型是确定性系统，它们根据训练数据中的模式来生成回应。当你要求它掷一个20面骰子时，它可能会回应说“我掷出了14”——但这个数字是通过文本预测生成的，而不是随机数生成。
这引发了几大问题：
- 没有真正的随机性结果并非真正随机，可能遵循可预测的模式
- 游戏诚信对于桌面角色扮演游戏而言至关重要，因为公平的骰子掷出会影响游戏进程
- 模拟精度统计模拟需要恰当的随机数生成
- 可重复性问题相同的提示可能会产生惊人相似的“随机”结果
解决方案：为人工智能打造真实骰子
这个MCP服务器充当了人工智能助手与实际随机数生成之间的桥梁。可以将其想象为，给你的AI助手提供了一副真实的骰子，而不是让它想象骰子的滚动。
其工作原理如下：
- AI助手接收骰子表示法（例如，“3d6+2”）
- MCP服务器解析请求并生成加密安全的随机数
- 采用了真实的骰子机制（优势、骰子爆炸、重掷等）
- 向人工智能返回真实的随机结果
结果：人工智能助手现在能够提供具有数学严谨性的真正随机骰子掷出结果，使其适用于实际游戏、模拟以及任何需要真正随机性的应用。
特点/特性
标准骰子表示法
- 基本卷（或基础卷）：
1d20，3d6，2d10 - 修饰符：
1d20+5，2d6-3 - 多种骰子类型：
1d20+2d6+3 - 百分位数骰子：
1d%(d100) - “Fudge dice”翻译成中文是“骰子（特指用于Fudge角色扮演系统的骰子）”或简化为“Fudge骰子”。在中文语境中，Fudge骰子通常指的是用于Fudge角色扮演游戏系统中的一种特殊骰子，这种骰子用于决定角色的属性、技能检定等游戏机制：
4dF（命运/骰子系统）
高级力学
- 优势/劣势：
2d20kh1（保留最高值），2d20kl1（保留最低值） - 掉落机制:
4d6dl1（去掉最低分），4d6dh1（去掉最高分） - 爆炸骰子：
3d6!（重新投掷并加到最大值） - 重新掷骰机制：
4d6r1（重新掷1次） - 成功计数：
5d10>7（成功次数≥7）
MCP 工具
search
发现可用的骰子掷骰操作和相关文档。 ChatGPT Connector 兼容性所需。
参数：
query（必填）：搜索查询以查找相关的掷骰子信息
返回值：
content包含搜索结果的JSONid，title，以及url田野（或领域，根据上下文可灵活翻译）structuredContent机器可读的搜索结果，附带相关性评分
fetch
通过ID检索特定骰子掷出主题的详细内容。
参数：
id（必填）：搜索结果中的主题ID
返回值：
content包含完整内容的JSON文档structuredContent元数据和结构化文档信息
dice_roll
使用标准记号执行骰子掷出，可选标签和详细输出。
参数：
notation（必填）：骰子表示法字符串（例如，“3d6+2”）label（可选）：为卷轴添加描述性标签verbose（可选）：显示单个骰子的详细分解情况
返回值：
content包含掷骰结果和表情符号的可读文本structuredContent完整的卷材数据，包括：
- notation原始骰子表示法 - total最终结果 - rolls带有元数据的单个芯片结果（掉落、爆炸等） - breakdown数学分解字符串 - criticald20骰子投掷中的关键成功/失败判定 - modifier应用的修饰符 - timestamp胶片的ISO时间戳
dice_validate
验证骰子记法而不执行掷骰操作，提供该记法的详细解析。
参数：
notation（必填）：要验证的骰子表示法字符串
返回值：
content可读的人类验证结果structuredContent结构化的验证数据包括：
- valid布尔验证状态 - expression解析后的骰子表达式（如有效） - breakdown骰子和修正值的结构化分析 - error错误消息（如无效）
结构化内容支持
所有工具都返回人类可读的格式以及 content 并且可机器读取 structuredContent 遵循……之后 OpenAI 应用程序开发工具包（SDK） 规格。这使得：
- 程序化访问 滚动结果和验证数据
- 组件模板 用于丰富的用户界面渲染（未来增强功能）
- 与人工智能工作流程的集成 需要结构化数据
- 高级功能 如滚动历史、统计数据和可视化展示
结构化内容包含每个操作的完整元数据，使其适合在骰子滚动功能之上构建高级应用程序。
远程MCP集成（支持流式HTTP）
这个MCP服务器支持 可流式传输的HTTP传输 用于远程连接，并实现了OpenAI MCP规范，包括所需的功能/要求 search 用于操作发现的工具。
兼容：
- 克劳德远程MCP连接器 （以及Claude Desktop）
- ChatGPT 连接器 （目前仅在开发者模式下可用）
- 任何MCP客户端 支持Streamable HTTP传输
连接端点：
- 本地开发:
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添加新机制
- 延长/扩展
DiceTerm接口在types.ts - 更新解析器中的正则表达式
dice-notation-parser.ts - 在（游戏中/系统中）实现该机制
dice-roller.ts - 添加全面测试
配置
该服务器通过（某种方式）支持多种配置选项 DiceRollerConfig 接口：
- 每次掷骰的最大骰子数量
- 最大芯片尺寸
- 随机数源选择
- 历史记录大小限制
技术规格
- 语言TypeScript 5.8+
- 运行时Node.js 18+（已测试版本为 v24.0.2）
- 协议；议定书MCP（模型上下文协议）2024-11-05
- OpenAI 兼容性实现了OpenAI MCP规范，满足所需要求
search工具 - 运输支持STDIO（本地Claude桌面）+ Streamable HTTP（远程连接）
- 依赖项最小化（zod，@modelcontextprotocol/sdk，@vercel/mcp-adapter）
- 模块系统ES 模块
- 测试框架使用 ts-jest 配置 Jest
安全考虑事项
- 输入验证防止恶意骰子表达式
- 资源限制防止通过极大规模的滚动进行拒绝服务攻击（DoS）
- 密码学安全的随机数生成
- 无外部网络依赖
链接
- 仓库（或存储库）：
- 现场演示: https://dice-rolling-mcp.vercel.app（这个网址翻译为中文表述时，通常我们不会直接翻译网址本身，而是描述其可能代表的内容或用途，但在这里为了符合要求，可以简单表述为“一个用于掷骰子的网页应用，托管在Vercel平台上”）
- MCP终端节点: https://dice-rolling-mcp.vercel.app/mcp（该网址可译为“骰子掷骰子MCP（多播放器兼容版）网站”，但通常网址直接保留原样，不进行翻译，这里仅为说明其含义）
作者
吉姆·麦克奎兰
- GitHub：
- 领英（LinkedIn）： https://www.linkedin.com/in/jimmcquillan/ （该网址翻译为中文表述即为：“领英（LinkedIn）上的jimmcquillan个人主页”，但通常网址本身不直接翻译，保持原样即可，因为网址是全球通用的，无需翻译。）
许可证
ISC（Internet Service Center，互联网服务中心）
贡献
欢迎投稿！请确保：
- 所有测试均通过（
npm test) - 代码遵循现有的模式和规范
- 新功能包括适当的测试覆盖率
- TypeScript 严格模式合规性