STARWARCLOUD STARWAR.AI
返回市场
骰子滚动MCP

骰子滚动MCP

作者：jimmcq5 星标更新：2025-11-19
安装使用来源：spider==github.com

项目介绍

Dice Rolling MCP Server

一个基于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（命运/Fudge系统）

高级机制

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

MCP工具

search

发现可用的骰子投掷操作和文档。需要与ChatGPT连接器兼容。

参数：

  • 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：错误消息（如果无效）

结构化内容支持

所有工具都返回人类可读的content和机器可读的structuredContent，遵循OpenAI Apps SDK规范。这使得：

  • 程序访问投掷结果和验证数据
  • 组件模板用于丰富的UI渲染（未来增强）
  • 与需要结构化数据的AI工作流集成
  • 高级功能如投掷历史、统计数据和可视化

结构化内容包括关于每个操作的完整元数据，使其适合构建在骰子投掷能力之上的高级应用程序。

远程MCP集成（可流式传输HTTP）

此MCP服务器支持远程连接的可流式传输HTTP传输，并实现了OpenAI MCP规范，包括所需的search工具以发现操作。

兼容性：

  • Claude远程MCP连接器（以及Claude桌面）
  • ChatGPT连接器（目前仅限开发者模式）
  • 任何支持可流式传输HTTP传输的MCP客户端

连接端点：

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

search和fetch工具使Claude和ChatGG能够自动发现可用的骰子投掷操作。

本地MCP集成（STDIO）

为了本地Claude桌面集成，配置你的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: 投掷3d6+2作为伤害
Assistant: 你投掷了3d6+2作为伤害：
🎲 总计：13
📊 分解：3d6:[4,2,5] + 2

优势系统

Human: 使用优势投掷2d20kh1+5进行攻击
Assistant: 你使用优势投掷了2d20kh1+5进行攻击：
🎲 总计：23
📊 分解：2d20:[12,18] 保留最高 + 5

验证

Human: “4d6kh3+2d8+5”是有效的骰子记号吗？
Assistant: ✅ 有效的骰子记号：4d6kh3+2d8+5

分解：
• 4d6（保留最高3）
• 2d8
• 修正值：+5

发现（远程MCP集成）

Human: 可用的骰子操作有哪些？
Assistant: [调用带有查询“dice”的search工具]
🎲 找到了骰子投掷操作：
- 基本骰子记号：学习标准XdY格式
- D&D优势和劣势：2d20kh1机制
- 战斗投掷示例：攻击、伤害、法术
- 能力分数生成：4d6kh3用于角色属性

架构

核心组件

  • 解析器（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服务器实现
│   ├── parser/               # 骰子记号解析器
│   ├── roller/               # 骰子投掷引擎
│   ├── statistics/           # 统计分析工具
│   └── types.ts              # TypeScript定义
├── __tests__/                # 测试套件
├── dist/                     # 编译后的JavaScript
└── examples/                 # 使用示例

添加新机制

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

配置

服务器通过DiceRollerConfig接口支持各种配置选项：

  • 每次投掷的最大骰子数量
  • 最大骰子面数
  • 随机数源选择
  • 历史大小限制

技术规格

  • 语言：TypeScript 5.8+
  • 运行时：Node.js 18+（已测试v24.0.2）
  • 协议：MCP（模型上下文协议）2024-11-05
  • OpenAI兼容性：实现OpenAI MCP规范，包含必需的search工具
  • 传输支持：STDIO（本地Claude桌面）+ 可流式传输HTTP（远程连接）
  • 依赖项：最小（zod，@modelcontextprotocol/sdk，@vercel/mcp-adapter）
  • 模块系统：ES模块
  • 测试框架：Jest with ts-jest

安全考虑

  • 输入验证防止恶意骰子表达式
  • 资源限制防止通过极大投掷造成DoS
  • 加密安全的随机数生成
  • 无外部网络依赖

链接

作者

Jim McQuillan

许可证

ISC

贡献

欢迎贡献！请确保：

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