# 🎲 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](https://docs.docker.com/desktop/) installé et **lancé**
- Le plugin **Docker MCP Toolkit** activé : `Docker Desktop → Settings → Beta features → MCP Toolkit`
- Un client compatible MCP : [Claude Desktop](https://claude.ai/download)

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

```bash
docker build -t dice-mcp-server .
```

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

```bash
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é

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

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

Vérifier :
```bash
docker mcp catalog show custom
```

### 4. Créer un profil incluant ce serveur

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

Vérifier :
```bash
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) :
```bash
docker mcp client connect claude-desktop --profile dev_tools --global
```

**Voir tous les clients disponibles :**
```bash
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) :
```bash
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