Dice Rolling MCP

🚀 骰子滾動MCP服務器

這是一個基於TypeScript的全面的模型上下文協議（MCP）服務器，為AI助手提供高級的骰子滾動功能。非常適合桌面遊戲、角色扮演遊戲（RPG）以及任何需要結合遊戲機制進行復雜隨機數生成的應用程序。

🚀 快速開始

本MCP服務器充當AI助手與實際隨機數生成之間的橋樑。使用時，AI助手接收骰子符號（例如，“3d6+2”），MCP服務器解析請求並生成加密安全的隨機數，應用真實的骰子機制（優勢、爆炸骰子、重擲等），最後將真正的隨機結果返回給AI。

✨ 主要特性

標準骰子符號

• 基本滾動：1d20、3d6、2d10
• 修飾符：1d20+5、2d6 - 3、1d8*2
• 多種骰子類型：1d20+2d6+3
• 百分骰子：1d%（d100）
• 福吉骰子：4dF（命運/福吉系統）

高級機制

• 優勢/劣勢：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

🔧 技術細節

核心組件

• 解析器 (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

添加新機制

1. 在types.ts中擴展DiceTerm接口。
2. 更新dice-notation-parser.ts中的解析器正則表達式。
3. 在dice-roller.ts中實現該機制。
4. 添加全面的測試。

配置

服務器通過DiceRollerConfig接口支持各種配置選項：

• 每次滾動的最大骰子數量。
• 最大骰子面數。
• 隨機數源選擇。
• 歷史記錄大小限制。

技術規格

安全考慮

• 輸入驗證可防止惡意骰子表達式。
• 資源限制可防止通過極大滾動進行拒絕服務攻擊。
• 加密安全的隨機數生成。
• 無外部網絡依賴。

📄 許可證

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/