matthewholliday/mcp-dice-roller

MCP Dice Roller Server

A Model Context Protocol (MCP) server for rolling dice using standard RPG dice notation. This server provides a tool that can roll various-sized dice and return detailed results.

Features

• Standard RPG dice support (d4, d6, d8, d10, d12, d20, d100, and more)
• Roll multiple dice at once (e.g., 3d6)
• Dice notation parsing (e.g., "2d10", "d20")
• Comprehensive input validation
• Detailed results including individual rolls and totals
• 100% test coverage with Jest

Installation

npm install
npm run build

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Test Suite Coverage

The project includes a comprehensive test suite with 75 tests covering:

Core Dice Rolling Functionality

• Dice notation parsing (e.g., "3d6", "d20")
• Single and multiple dice rolls
• Various dice sizes (d4, d6, d8, d10, d12, d20, d100)
• Random number generation
• Result formatting

Input Validation

• Valid dice notation formats
• Invalid notation detection
• Parameter bounds checking
• Edge case handling (zero, negative values, very large numbers)
• Maximum limits (1000 dice max, 1,000,000 sides max)

MCP Tool Integration

• Tool schema validation
• Request/response formatting
• Error handling and messaging
• Standard RPG dice workflows
• Statistical distribution verification

Test Results

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

Usage

As an MCP Server

The server communicates via stdio and can be integrated with MCP-compatible clients.

node dist/index.js

Claude Code Configuration

To use this MCP server with Claude Code, add the following configuration to your Claude Code settings file (.claude/claude_code_config.json or global settings):

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

Update the cwd path to point to the root directory of this project. The dist/index.js path is relative to the cwd.

After adding the configuration:

1. Ensure the project is built: npm run build
2. Restart Claude Code
3. The roll_dice tool will be available for use

Tool: roll_dice

Roll dice using standard dice notation.

Parameters:

• notation (string): Dice notation in the format "NdS" where N is the number of dice and S is the number of sides
  • Examples: "3d6", "d20", "2d10"
  • N is optional and defaults to 1 if omitted

Examples:

• d6 - Roll one 6-sided die
• d20 - Roll one 20-sided die
• 3d6 - Roll three 6-sided dice
• 2d10 - Roll two 10-sided dice
• 4d8 - Roll four 8-sided dice

Response Format:

The tool returns two text items:

1. A human-readable formatted result
2. A JSON object with detailed information

Example response for "3d6":

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

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

Dice Notation

The server supports standard RPG dice notation:

Validation Rules

• Dice count must be a positive integer (1-1000)
• Dice sides must be an integer ≥ 2 (up to 1,000,000)
• Notation format must match the pattern NdS or dS
• Maximum of 1000 dice can be rolled at once
• Maximum of 1,000,000 sides per die

Error Handling

The server provides clear error messages for invalid inputs:

• Invalid notation format: "Invalid dice notation: {input}. Expected format: NdS (e.g., 3d6, d20)"
• Invalid count: "Dice count must be a positive integer"
• Invalid sides: "Dice sides must be an integer greater than or equal to 2"
• Too many dice: "Cannot roll more than 1000 dice at once"
• Too many sides: "Dice cannot have more than 1,000,000 sides"

Project Structure

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

Development

Building

npm run build

Watch Mode

npm run watch

Testing

The test suite uses Jest with ts-jest for TypeScript support. Tests cover:

1. Dice Notation Parsing (15 tests)

   • Valid notation formats
   • Invalid notation detection
   • Edge cases and error handling

2. Parameter Validation (10 tests)

   • Valid parameter ranges
   • Boundary conditions
   • Type checking

3. Dice Rolling (25 tests)

   • Single and multiple dice
   • Range validation
   • Statistical distribution
   • Result structure

4. MCP Integration (25 tests)

   • Tool schema compliance
   • Request/response format
   • Error handling
   • Standard use cases

Technical Details

• Language: TypeScript
• Runtime: Node.js >= 18.0.0
• MCP SDK: @modelcontextprotocol/sdk v1.20.0
• Testing: Jest with 100% code coverage
• Module System: ES Modules

Troubleshooting

Server fails to start with "exports is not defined"

If you see this error:

ReferenceError: exports is not defined in ES module scope

Solution: The TypeScript compiler must be configured to output ES modules. Ensure tsconfig.json has:

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

Then rebuild:

npm run build

Tests fail after configuration changes

If tests fail after modifying the TypeScript or Jest configuration:

1. Clean the build directory:

   rm -rf dist
   

2. Rebuild the project:

   npm run build
   

3. Run tests again:

   npm test
   

Server not appearing in Claude Desktop

1. Verify the path in claude_desktop_config.json is absolute
2. Check that the project has been built
3. Restart Claude Desktop
4. Check the Claude Desktop logs for errors

Module resolution errors

If you see import errors, ensure:

• All dependencies are installed: npm install
• The project is built: npm run build
• package.json has "type": "module"
• tsconfig.json has "module": "ES2020"

License

MIT