# 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

```bash
npm install
npm run build
```

## Running Tests

```bash
# 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.

```bash
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):

```json
{
  "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:

| Notation | Description |
|----------|-------------|
| `d4` | Roll one 4-sided die |
| `d6` | Roll one 6-sided die |
| `d8` | Roll one 8-sided die |
| `d10` | Roll one 10-sided die |
| `d12` | Roll one 12-sided die |
| `d20` | Roll one 20-sided die |
| `d100` | Roll one 100-sided die (percentile) |
| `3d6` | Roll three 6-sided dice |
| `2d10` | Roll two 10-sided dice |
| `NdS` | Roll N dice with S sides each |

## 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

```bash
npm run build
```

### Watch Mode

```bash
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:
```json
{
  "compilerOptions": {
    "module": "ES2020"
  }
}
```

Then rebuild:
```bash
npm run build
```

### Tests fail after configuration changes

If tests fail after modifying the TypeScript or Jest configuration:

1. Clean the build directory:
   ```bash
   rm -rf dist
   ```

2. Rebuild the project:
   ```bash
   npm run build
   ```

3. Run tests again:
   ```bash
   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