🎲 Dice Roller — MCP Server

Serveur MCP (Model Context Protocol) de lancer de dés pour parties de jeu de rôle, packagé avec Docker et exposé via le Docker MCP Toolkit.

🧰 Prérequis

• Docker Desktop installé et lancé
• Le plugin Docker MCP Toolkit activé : Docker Desktop → Settings → Beta features → MCP Toolkit
• Un client compatible MCP : Claude Desktop

🛠️ Outils disponibles

Outil	Description
flip_coin	Pile ou face
roll_dice	Lance N dés à X faces (sides, count)
roll_custom	Notation standard, ex : 2d6+3
roll_stats	Caractéristiques D&D (4d6, on garde les 3 meilleurs)
roll_advantage	Jet avec avantage (2 jets, garde le meilleur)
roll_disadvantage	Jet avec désavantage (2 jets, garde le pire)
roll_check	Jet + modificateur, comparaison optionnelle à une difficulté
roll_initiative	Ordre d'initiative pour une liste de joueurs

🚀 Installation

1. Construire l'image Docker

docker build -t dice-mcp-server .

Vérifier que l'image démarre correctement :

docker run -i --rm dice-mcp-server
# → doit afficher : INFO - Starting Dice Roller MCP server...
# Ctrl+C pour quitter

2. Créer un catalogue MCP personnalisé

docker mcp catalog create custom --title "Custom Catalog"

3. Ajouter le serveur dice au catalogue

L'image étant uniquement locale, on la décrit via le fichier catalog_entry.yaml fourni et on l'ajoute avec le schéma file:// :

docker mcp catalog server add custom:latest --server file://$(pwd)/catalog_entry.yaml

Vérifier :

docker mcp catalog show custom

4. Créer un profil incluant ce serveur

docker mcp profile create --name dev-tools --server catalog://custom:latest/dice

Vérifier :

docker mcp profile show dev_tools

5. Connecter le profil au client

Claude Desktop (scope global obligatoire, ce client ne supporte pas le scope projet) :

docker mcp client connect claude-desktop --profile dev_tools --global

Voir tous les clients disponibles :

docker mcp client ls

6. Redémarrer le client

Fermer complètement l'application et la relancer, afin qu'elle recharge la configuration MCP.

7. Tester

Dans le chat du client connecté, demander par exemple :

"Lance un dé à 20 faces" "Génère des caractéristiques de personnage D&D"

⚠️ Notes de compatibilité & pièges connus

Le SDK Python mcp v2.0.0 casse ce projet

Le SDK officiel mcp a publié une version 2.0.0 stable le 28 juillet 2026, qui restructure l'API en profondeur :

• FastMCP est renommé MCPServer
• Le chemin d'import mcp.server.fastmcp n'existe plus
• mcp.types est déplacé vers un package séparé mcp-types

➡️ requirements.txt doit impérativement épingler une version sous la v2 :

mcp[cli]>=1.2.0,<2

Mode "Dynamic MCP"

Par défaut, le gateway peut exposer uniquement des outils "méta" de découverte (mcp-find, mcp-exec, etc.) plutôt que les outils du serveur directement. Si docker mcp tools ls affiche 8 outils génériques au lieu des outils de dés, revenir à l'affichage classique (tous les outils visibles directement) :

docker mcp feature disable dynamic-tools

📁 Structure du projet

dice-roller/
├── Dockerfile           # Image Python 3.11-slim + serveur MCP
├── requirements.txt     # mcp[cli]>=1.2.0,<2
├── dice_server.py       # Code du serveur (FastMCP)
├── catalog_entry.yaml   # Description du serveur pour le catalogue Docker MCP
└── README.md            # Ce fichier

📜 Licence

MIT