金大哥 - dice-rolling-mcp MCP 详情

article

README

🚀 骰子滚动MCP服务器

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

🚀 快速开始

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

远程MCP集成：本服务器已部署，可与Claude Desktop配合使用。需配置claude_desktop_config.json文件。
本地安装：通过克隆仓库、安装依赖和构建项目来完成本地部署。
使用方法：可在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

添加新机制

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

配置

服务器通过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协议合规性

技术规格

| 属性 | 详情 | |------|------| | 语言 | TypeScript 5.8+ | | 运行时 | Node.js 18+（已在v24.0.2上测试） | | 协议 | MCP（模型上下文协议）2024 - 11 - 05 | | 依赖项 | 最少（zod，@modelcontextprotocol/sdk） | | 模块系统 | ES模块 | | 测试框架 | Jest with ts - jest |

安全考虑

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

📄 许可证

本项目采用ISC许可证。

贡献说明

欢迎贡献代码！请确保：

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

作者

Jim McQuillan

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

dice-rolling-mcp