mcp-dice: A MCP Server for Rolling Dice

Overview: What is mcp-dice MCP Server?

mcp-dice is an MCP (Model Context Protocol) server specifically designed to facilitate Large Language Models (LLMs) in rolling dice. By leveraging standard dice notation, it provides both individual rolls and their total sum, which can be seamlessly integrated into various AI applications. This server supports a wide range of dice roll expressions like 1d20, 3d6, and 2d8+1, ensuring flexibility for diverse use cases.

This solution is particularly valuable because MCP serves as a universal adapter protocol akin to USB-C, connecting AI applications with specific data sources and tools through standardized communication. By adopting mcp-dice, developers can enhance their AI workflows, making it easier to integrate dice rolling functionality across different platforms such as Claude Desktop, Continue, Cursor, and more.

🔧 Core Features & MCP Capabilities

mcp-dice is built with several key features that make it highly compatible and versatile within the Model Context Protocol ecosystem:

Support for Standard Dice Notation

The server supports a variety of dice notation formats, including:

• 1d20 (one twenty-sided die)
• 3d6 (three six-sided dice)
• 2d8+1 (two eight-sided dice plus one modifier)

This versatility ensures that users can roll any type of dice they need for their projects or applications.

Roll and Sum Responses

mcp-dice returns detailed responses, including individual rolls, the total sum, modifiers, and even a timestamp. This comprehensive output provides a clear record of each dice roll, which is essential for both developers and end-users.

For example, an input query like:

{
  "notation": "2d6+3"
}

would return:

{
  "rolls": [
    3,
    1
  ],
  "sum": 4,
  "modifier": 3,
  "total": 7,
  "notation": "2d6+3",
  "timestamp": "2024-12-03T16:36:38.926452"
}

Easy Integration with Claude Desktop

mcp-dice is designed to work seamlessly with Claude Desktop, a popular AI assistant desktop application. It can be easily configured and used within the application's interface, offering a user-friendly experience for both new and experienced users.

Compatibility with MCP Inspector

For developers looking to debug or optimize their MCP servers, mcp-dice integrates well with the MCP Inspector tool. This tool allows for real-time monitoring and troubleshooting of MCP communication, ensuring that the server operates smoothly in complex environments.

⚙️ MCP Architecture & Protocol Implementation

mcp-dice is architected to adhere strictly to the Model Context Protocol (MCP) specifications, facilitating seamless integration with various AI applications. The protocol implementation ensures fast and reliable data exchange between the client and the server.

Protocol Flow Diagram

graph TD
    A[AI Application] -->|MCP Client| B[MCP Protocol]
    B --> C[mcp-dice Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8

This diagram illustrates the flow of data and commands from an AI application through an MCP client, to the mcp-dice server, and finally, to a targeted data source or tool.

Data Architecture Diagram

graph TD
    A[Client Request] --> B[MCP Protocol]
    B --> C[mcp-dice Server API]
    C --> D[MCP Server Logic]
    D --> E[Dice Roll Logic & Database]
    E --> F[Response Formatting]
    style A fill:#d0f3e6
    style C fill:#e8f5f5
    style D fill:#ede6f5
    style E fill:#faead7
    style F fill:#cfe2f3

This diagram highlights the key components involved in processing requests and formatting responses, emphasizing the robustness of the server's architecture.

🚀 Getting Started with Installation

To get started with mcp-dice, follow these steps:

1. Make uv Available: Ensure you have uv available on your system. You can find detailed installation instructions here.

2. Clone the Repository:

   git clone https://github.com/yourusername/mcp-dice.git
   cd mcp-dice
   

3. Install Development Dependencies (Optional for basic usage):

   uv pip install -e ".[dev]"
   

4. Run the Server:

   uvx mcp-dice
   

💡 Key Use Cases in AI Workflows

Scenario 1: Adventure Game Development

Imagine you are developing an adventure game where players need to roll dice for combat or exploration scenarios. Using mcp-dice, developers can integrate this functionality easily, providing real-time roll outcomes that can be displayed within the game's UI. The server ensures reliable and consistent data handling, making it a valuable asset in complex AI-driven applications.

Scenario 2: Educational Tool Integration

In the development of educational tools, such as language learning or strategy training applications, dice rolls can serve as interactive elements to reinforce concepts or keep users engaged. mcp-dice allows these applications to roll virtual dice accurately and efficiently, enhancing user experience and interaction.

🔌 Integration with MCP Clients

mcp-dice is designed to work seamlessly with several popular AI clients:

macOS Configuration

To connect mcp-dice with your AI client on macOS:

{
  "mcpServers": {
    "dice": {
      "command": "uvx",
      "args": ["mcp-dice"]
    }
  }
}

WSL Configuration for Windows Users (WSL)

For users running the application in a WSL environment on Windows:

{
  "mcpServers": {
    "dice": {
      "command": "wsl",
      "args": [
        "-e",
        "zsh",
        "-lc",
        "uvx mcp-dice"
      ]
    }
  }
}

📊 Performance & Compatibility Matrix

mcp-dice is compatible with several MCP clients:

MCP Client	Resources	Tools	Prompts	Status
Claude Desktop	✅	✅	✅	Full Support
Continue	✅	✅	✅	Full Support
Cursor	❌	✅	❌	Tools Only

The table above outlines the current compatibility matrix, highlighting which clients support resource management, tool integration, and prompt handling.

🛠️ Advanced Configuration & Security

Running Tests

To ensure mcp-dice functions correctly, you can run the server's tests using:

uv run pytest

Using MCP Inspector for Debugging

The MCP Inspector is a useful tool for debugging your MCP server. You can install and run it using npm:

npx @modelcontextprotocol/inspector uvx mcp-dice

Development Configuration

For local development on macOS, the configuration might look like this:

{
  "mcpServers": {
    "dice": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "path/to/mcp-dice-repo",
        "mcp-dice"
      ]
    }
  }
}

Similarly, for a WSL development environment on Windows:

{
  "mcpServers": {
    "dice": {
      "command": "wsl",
      "args": [
        "-e",
        "zsh",
        "-lc",
        "uv run --directory path/to/mcp-dice-repo mcp-dice"
      ]
    }
  }
}

❓ Frequently Asked Questions (FAQ)

1. Q: How does mcp-dice handle large numbers of dice rolls?
   A: mcp-dice is optimized to handle multiple dice rolls efficiently, ensuring that even large numbers of rolls are processed quickly and accurately.

2. Q: Can mcp-dice be used with other AI clients besides those listed in the compatibility matrix?
   A: While currently only fully supported by Claude Desktop,Continue, and Cursor, mcp-dice can still be integrated with other MCP-compliant clients through customization or future updates.

3. Q: Is it possible to modify the response data format for specific use cases?
   A: Yes, you can customize the response data format by modifying the server's logic or configuration using additional environmental variables and settings.

4. Q: How does mcp-dice ensure data privacy during dice rolls?
   A: All data is handled securely within the mcp-dice server, ensuring that individual roll outcomes are not stored or transmitted beyond the brief processing period.

5. Q: What steps should developers take to secure their MCP servers against vulnerabilities?
   A: Regularly update dependencies, implement security best practices, and use tools like MCP Inspector for continuous monitoring and alerting of potential security issues.

👨‍💻 Development & Contribution Guidelines

To contribute to mcp-dice development:

1. Fork the Repository: Visit GitHub and click on "Fork" to create your own copy.
2. Clone Locally:

   git clone https://github.com/yourusername/mcp-dice.git
   cd mcp-dice
   

3. Install Dependencies (including development dependencies):

   uv pip install -e ".[dev]"
   

4. Run Tests:

   uv run pytest
   

Pull requests are welcome, and any contributions to enhance the server’s capabilities or fix issues are greatly appreciated.

🌐 MCP Ecosystem & Resources

For more insights into the Model Context Protocol (MCP) ecosystem, explore additional resources such as the official MCP documentation and community forums. These resources provide valuable information for integrating MCP servers like mcp-dice with various AI applications.

By leveraging mcp-dice within your AI workflows, you can enhance the functionality of your applications and ensure seamless integration with a wide range of tools and clients.