Dice Rolling MCP

🚀 骰子滚动MCP服务器

这是一个全面的基于TypeScript的模型上下文协议（MCP）服务器，为AI助手提供高级的骰子滚动功能。非常适合桌面游戏、角色扮演游戏（RPG），以及任何需要具有游戏机制的复杂随机数生成的应用程序。

🚀 快速开始

本MCP服务器可作为AI助手与实际随机数生成之间的桥梁，让AI助手能够提供真正随机的骰子滚动结果。以下是使用该服务器的相关步骤：

1. 远程MCP集成：本服务器已部署，可与Claude Desktop配合使用。需配置claude_desktop_config.json文件。
2. 本地安装：通过克隆仓库、安装依赖和构建项目来完成本地部署。
3. 使用方法：可在Claude Desktop中添加配置，也可作为独立服务器运行。

✨ 主要特性

标准骰子表示法

• 基本滚动：支持1d20、3d6、2d10等基本表示法。
• 修饰符：可使用1d20+5、2d6 - 3、1d8*2等修饰符。
• 多种骰子类型：支持1d20+2d6+3等多种骰子类型组合。
• 百分骰子：支持1d%（即d100）。
• 福吉骰子：支持4dF（Fate/Fudge系统）。

高级机制

• 优势/劣势：支持2d20kh1（保留最高值）、2d20kl1（保留最低值）。
• 丢弃机制：支持4d6dl1（丢弃最低值）、4d6dh1（丢弃最高值）。
• 爆炸骰子：支持3d6!（最大值时重新滚动并累加）。
• 重新滚动机制：支持4d6r1（重新滚动1点）。
• 成功计数：支持5d10>7（统计大于等于7的成功次数）。

MCP工具

dice_roll

使用标准表示法执行骰子滚动，支持可选的标签和详细输出。

• 参数：
  • notation（必需）：骰子表示法字符串（例如，"3d6+2"）。
  • label（可选）：滚动的描述性标签。
  • verbose（可选）：显示单个骰子的详细分解。

dice_validate

验证骰子表示法而不执行滚动，并提供表示法含义的详细分解。

• 参数：
  • notation（必需）：要验证的骰子表示法字符串。

📦 安装指南

本地安装

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

💻 使用示例

基础用法

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集成

本服务器已部署，可与Claude Desktop配合使用。配置claude_desktop_config.json文件如下：

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

使用方法

与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

项目结构

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

添加新机制

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

配置

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

• 每次滚动的最大骰子数量
• 最大骰子面数
• 随机数源选择
• 历史记录大小限制

🔧 技术细节

核心组件

• 解析器 (src/parser/)：使用基于正则表达式的解析方法对骰子表示法进行分词和解析。
• 滚动器 (src/roller/)：使用加密安全的随机数生成执行骰子表达式。
• MCP服务器 (src/index.ts)：实现用于AI助手集成的模型上下文协议。
• 类型系统 (src/types.ts)：为所有骰子机制提供全面的TypeScript定义。

关键设计决策

• 安全性：使用Node.js的crypto.randomInt()实现加密安全的随机性。
• 可扩展性：模块化架构支持轻松添加新的骰子机制。
• 兼容性：以ES2022为目标，提供回退机制以支持更广泛的Node.js版本。
• 类型安全：完全使用TypeScript实现，并进行严格的类型检查。

测试

npm test

测试套件覆盖以下内容：

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

技术规格

安全考虑

• 输入验证可防止恶意骰子表达式。
• 资源限制可防止通过极大滚动进行拒绝服务攻击。
• 使用加密安全的随机数生成。
• 无外部网络依赖。

📄 许可证

本项目采用ISC许可证。

贡献说明

欢迎贡献代码！请确保：

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

相关链接

• 仓库：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/