使用说明

MCP骰子滚动服务器

一个使用标准角色扮演游戏（RPG）骰子标记的模型上下文协议（MCP）骰子投掷服务器。该服务器提供了一个工具，可以投掷不同大小的骰子，并返回详细的结果。

特点/功能

标准角色扮演游戏骰子支持（d4、d6、d8、d10、d12、d20、d100等）
一次性掷出多个骰子（例如，3个六面骰子）
骰子表示法解析（例如，“2d10”，“d20”）
全面的输入验证
详细结果，包括单个卷材和总计
使用 Jest 实现 100% 的测试覆盖率

安装

npm install
npm run build

运行测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

测试套件覆盖率

该项目包含一个全面的测试套件，共包含75项测试，涵盖：

核心骰子掷骰功能

骰子符号解析（例如，“3d6”，“d20”）
单次和多次骰子投掷
各种尺寸的骰子（d4、d6、d8、d10、d12、d20、d100）
随机数生成
结果格式化

输入验证

有效的骰子表示法格式
无效符号检测
参数边界检查
边缘情况处理（零值、负值、非常大的数字）
最大限制（最多1000个骰子，最多1,000,000面）

MCP工具集成

工具模式验证
请求/响应格式化
错误处理和消息传递
标准角色扮演游戏骰子使用流程
统计分布验证

测试结果

Test Suites: 2 passed, 2 total
Tests:       75 passed, 75 total
Coverage:    100% statements, 100% branches, 100% functions, 100% lines

使用方法/用途

作为MCP服务器

服务器通过标准输入输出（stdio）进行通信，并且可以与MCP兼容的客户端集成。

node dist/index.js

克劳德代码配置

要在Claude Code中使用此MCP服务器，请将以下配置添加到您的Claude Code设置文件中：.claude/claude_code_config.json 或全局设置）：

{
  "mcpServers": {
    "dice-roller": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "${workspaceFolder}/mcp-test-server"
    }
  }
}

更新 cwd 路径指向此项目的根目录。该 dist/index.js 路径是相对于……的 cwd。

添加配置后：

确保项目已构建： npm run build
重启Claude代码
这个（或“该”） roll_dice 该工具将可供使用

工具：掷骰子

使用标准骰子记号来掷骰子。

参数：

notation （字符串）：骰子表示法，格式为“NdS”，其中N表示骰子的数量，S表示骰子的面数
- 示例：“3d6”，“d20”，“2d10”
- N是可选参数，如果省略，则默认值为1

示例：

d6 - 掷一个6面骰子
d20 - 掷一个20面骰子
3d6 - 掷三个六面骰子
2d10 - 掷两个10面骰子
4d8 - 掷四个八面骰子

响应格式：

该工具返回两个文本项：

一种可读性强的格式化结果
一个包含详细信息的JSON对象

“3d6”的示例响应：

Rolled 3d6: [4, 2, 5] = 11

{
  "rolls": [4, 2, 5],
  "total": 11,
  "notation": "3d6",
  "count": 3,
  "sides": 6
}

骰子表示法

该服务器支持标准的角色扮演游戏（RPG）骰子记法：

符号	描述
`d4` 掷一个四面骰子
`d6`	掷一个六面骰子
`d8`	掷一个8面骰子
`d10`	掷一个10面骰子
`d12` 掷一个12面的骰子
`d20`	掷一个20面骰子
`d100`	掷一个100面的骰子（百分位数）
`3d6` 掷三个六面骰子
`2d10` 掷两个10面骰子
`NdS`	掷N个每面有S个边的骰子

验证规则

骰子数量必须为正整数（1-1000）
骰子面数必须是大于等于2的整数（最多可达1,000,000）
记号格式必须符合该模式 NdS 或者 dS
一次最多可以掷1000个骰子
每个骰子最多可有1,000,000个面

错误处理

服务器为无效输入提供了明确的错误信息：

无效的记号格式“无效的骰子表示法：{input}。期望格式：NdS（例如，3d6，d20）”
无效计数“骰子数量必须是正整数”
无效的边“骰子面数必须是大于或等于2的整数”
太多的骰子“一次不能掷超过1000个骰子”
太多方面“骰子的边数不能超过1,000,000条”

项目结构

mcp-dice-roller-server/
├── src/
│   ├── diceRoller.ts    # Core dice rolling logic
│   └── index.ts         # MCP server implementation
├── tests/
│   ├── diceRoller.test.ts  # Core functionality tests
│   └── mcpServer.test.ts   # MCP integration tests
├── dist/                # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md

发展

建筑

npm run build

手表模式

npm run watch

测试

该测试套件使用Jest并结合ts-jest来支持TypeScript。测试覆盖范围包括：

骰子记号解析 (15项测试)
- 有效的记号格式
- 无效符号检测
- 边缘情况和错误处理
参数验证 （10项测试）
- 有效的参数范围
- 边界条件
- 类型检查
掷骰子 （25项测试）
- 单个和多个骰子
- 范围验证
- 统计分布
- 结果结构
MCP集成 （25项测试）
- 工具模式合规性
- 请求/响应格式
- 错误处理
- 标准用例

技术细节

语言TypeScript
运行时Node.js >= 18.0.0
MCP SDK（MCP软件开发工具包）@modelcontextprotocol/sdk v1.20.0（注：这里的“@modelcontextprotocol/sdk”可能是一个特定库或框架的名称，由于没有具体的上下文，所以直接按原样翻译。在实际应用中，可能需要根据具体库或框架的名称进行适当的调整或解释。）
测试使用Jest，实现100%的代码覆盖率
模块系统ES 模块（ES Modules）

故障排除

服务器启动失败，提示“exports is not defined”

如果你看到这个错误：

ReferenceError: exports is not defined in ES module scope

解决方案TypeScript 编译器必须配置为输出 ES 模块。请确保 tsconfig.json has:（这个短语本身在中文中没有直接对应的翻译，因为它是一个英文单词，表示“有”的意思，但在这里作为单独的短语可能不需要翻译，如果需要解释其含义，可以翻译为“有”）

{
  "compilerOptions": {
    "module": "ES2020"
  }
}

然后重新构建：

npm run build

配置更改后测试失败

如果在修改TypeScript或Jest配置后测试失败：

清理构建目录：
```
rm -rf dist
```
重新构建项目：
```
npm run build
```
再次运行测试：
```
npm test
```

服务器未在Claude桌面版中显示

验证路径中的 claude_desktop_config.json 是绝对的
检查项目是否已构建完成
重启Claude桌面版
检查Claude桌面版的日志以查找错误

模块解析错误

如果你看到导入错误，请确保：

所有依赖项均已安装： npm install
该项目已建成： npm run build
package.json 有（在句中常作为助动词，用于构成现在完成时等时态，或表示存在） "type": "module"
tsconfig.json has（在中文中，这个单词本身是英语动词“have”的第三人称单数现在时形式，直接翻译为中文意为“有”，但具体翻译需结合上下文语境） "module": "ES2020"

许可证

麻省理工学院（MIT）