Décisions de conception MCP

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284

# Décisions de conception MCP

Ce document explique les principales décisions de conception prises lors de l'implémentation de la prise en charge MCP (Model Context Protocol) dans mini-me.

## Table des matières

- [Transport HTTP uniquement](#transport-http-uniquement)
- [Prise en charge du texte uniquement](#prise-en-charge-du-texte-uniquement)
- [Pas de transport stdio (pour l'instant)](#pas-de-transport-stdio-pour-linstant)
- [Pas de prise en charge OAuth 2.0](#pas-de-prise-en-charge-oauth-20)
- [Pas de mise en cache](#pas-de-mise-en-cache)
- [Pas de découverte paresseuse](#pas-de-découverte-paresseuse)
- [Préfixage des noms d'outils](#préfixage-des-noms-doutils)
- [Filtrage des outils](#filtrage-des-outils)
- [Authentification via variables d'environnement](#authentification-via-variables-denvironnement)
- [Système de permissions](#système-de-permissions)
- [Gestion des erreurs](#gestion-des-erreurs)

---

## Transport HTTP uniquement

**Décision :** Implémenter uniquement le transport HTTP (HTTP streamable), pas stdio.

**Justification :**

1. **Simplicité :** Le transport HTTP est plus simple à implémenter et à déboguer
2. **Cas d'utilisation courant :** La plupart des serveurs MCP hébergés utilisent le transport HTTP
3. **Sécurité :** HTTP sur TLS fournit une sécurité intégrée
4. **Compatibilité :** Fonctionne avec tous les services MCP hébergés (GitHub, Context7, Wikipedia, etc.)
5. **Effort d'implémentation :** Stdio nécessite la gestion de sous-processus, ce qui ajoute de la complexité

**Compromis :**

- Ne peut pas utiliser les serveurs MCP locaux basés sur stdio
- Ne peut pas utiliser les serveurs MCP basés sur Docker qui n'exposent que stdio

**Futur :** Le transport stdio sera ajouté lorsqu'il y aura une demande pour les serveurs MCP locaux.

---

## Prise en charge du texte uniquement

**Décision :** Ne prendre en charge que les outils MCP qui utilisent des entrées/sorties texte. Filtrer les outils binaires.

**Justification :**

1. **Philosophie de conception :** Mini-me est conçu comme un agent basé sur le texte
2. **Sécurité :** Les données binaires peuvent être dangereuses (images, exécutables, etc.)
3. **Simplicité :** Le texte est plus facile à gérer, journaliser et afficher
4. **Compatibilité :** Tous les principaux serveurs MCP (GitHub, Context7, Wikipedia) utilisent des outils texte uniquement
5. **Contexte :** La fenêtre de contexte de mini-me est basée sur le texte

**Implémentation :**

Les outils qui nécessitent des données binaires (format `binary` ou type `binary`) sont automatiquement filtrés lors de la découverte des outils, avec un avertissement affiché au démarrage.

---

## Pas de transport stdio (pour l'instant)

**Décision :** Reporter l'implémentation du transport stdio.

**Justification :**

1. **HTTP est suffisant :** Tous les serveurs MCP publics connus actuellement utilisent HTTP
2. **Complexité :** Stdio nécessite la gestion de sous-processus, le streaming d'entrée/sortie
3. **Priorités :** Se concentrer sur le transport HTTP en premier, ajouter stdio plus tard si nécessaire
4. **Cas d'utilisation :** Stdio est principalement pour les serveurs MCP locaux/auto-hébergés

**Solution de contournement :** Utilisez des serveurs MCP basés sur HTTP ou exécutez des serveurs MCP comme services HTTP.

**Futur :** Sera implémenté lorsque les utilisateurs demanderont des serveurs MCP locaux basés sur stdio.

---

## Pas de prise en charge OAuth 2.0

**Décision :** Ne prendre en charge que l'authentification par token Bearer et par clé API. Pas de flux OAuth 2.0.

**Justification :**

1. **Simplicité :** OAuth 2.0 nécessite une gestion complexe du flux d'authentification via navigateur
2. **Cas d'utilisation :** Les serveurs MCP actuels n'ont pas besoin d'OAuth 2.0
3. **Sécurité :** Les tokens Bearer et clés API sont plus simples à gérer avec les variables d'environnement
4. **Complexité :** OAuth 2.0 nécessite des callbacks, le stockage de l'état, la gestion des rafraîchissements de tokens

**Compromis :**

- Ne peut pas utiliser les serveurs MCP qui nécessitent OAuth 2.0
- Les utilisateurs doivent utiliser des tokens personnels ou des clés API

**Solution de contournement :** Utilisez des serveurs MCP auto-hébergés qui acceptent des tokens Bearer ou des clés API.

**Futur :** L'implémentation d'OAuth 2.0 sera ajoutée si des serveurs MCP populaires l'exigent.

---

## Pas de mise en cache

**Décision :** Ne pas mettre en cache les résultats des outils MCP.

**Justification :**

1. **Actualité :** Les données des outils MCP (code, documentation, etc.) peuvent changer fréquemment
2. **Simplicité :** Pas besoin de gérer l'invalidation du cache
3. **Espace :** La mise en cache nécessiterait du stockage et de la gestion de la mémoire
4. **Prédictibilité :** Les utilisateurs s'attendent à des données en temps réel

**Compromis :**

- Réexécution des mêmes requêtes retourne des données fraîches
- Pas de gain de performance pour les requêtes répétées

**Futur :** La mise en cache pourrait être ajoutée pour des outils spécifiques où c'est utile (ex : documentation statique).

---

## Pas de découverte paresseuse

**Décision :** Découvrir tous les outils MCP au démarrage, pas à la demande.

**Justification :**

1. **Prédictabilité :** Tous les outils sont disponibles dès le départ
2. **Simplicité :** Pas besoin de gérer la découverte à la demande
3. **Bannière :** La bannière de démarrage affiche tous les outils disponibles
4. **Erreurs préventives :** Les erreurs de configuration sont détectées tôt

**Compromis :**

- Temps de démarrage plus long si de nombreux serveurs MCP sont configurés
- Les serveurs MCP non disponibles ne sont pas disponibles pour toute la session

**Futur :** La découverte paresseuse pourrait être implémentée pour améliorer les performances de démarrage.

---

## Préfixage des noms d'outils

**Décision :** Préfixer tous les noms d'outils MCP avec le nom du serveur.

**Justification :**

1. **Éviter les collisions :** Plusieurs serveurs peuvent avoir des outils avec le même nom (ex : `search`)
2. **Clarté :** Les noms préfixés indiquent clairement la source de l'outil (ex : `github_search_code`)
3. **Consistance :** Nettoyage des noms pour garantir des identifiants valides

**Format :** `{nom_serveur}_{nom_original_outil}`

**Nettoyage :**
- Les caractères non alphanumériques deviennent des underscores
- Les tirets deviennent des underscores
- Les underscores multiples sont réduits à un seul

**Exemple :**
- `resolve-library-id` → `context7_resolve_library_id`
- `query-docs` → `context7_query_docs`

---

## Filtrage des outils

**Décision :** Permettre aux utilisateurs de filtrer quels outils de chaque serveur sont exposés.

**Justification :**

1. **Sécurité :** Limiter les outils disponibles réduit la surface d'attaque
2. **Simplicité :** Les utilisateurs n'ont pas besoin de voir tous les outils d'un serveur
3. **Performance :** Moins d'outils = démarrage plus rapide
4. **Contrôle :** Les utilisateurs peuvent désactiver des outils spécifiques qu'ils ne veulent pas

**Implémentation :**

```yaml
servers:
  - name: github
    tools:  # Seuls ces outils seront disponibles
      - get_me
      - list_repositories
      - search_code
```

---

## Authentification via variables d'environnement

**Décision :** Charger les tokens d'authentification uniquement depuis des variables d'environnement.

**Justification :**

1. **Sécurité :** Évite de committer des secrets dans le contrôle de version
2. **Flexibilité :** Permet aux utilisateurs d'utiliser leurs propres mécanismes de gestion de secrets
3. **Compatibilité :** Fonctionne avec tous les systèmes (Linux, macOS, Windows)
4. **Bonnes pratiques :** Suit les principes de sécurité standard (12-factor app)

**Implémentation :**

```yaml
auth:
  type: bearer
  tokenEnv: GITHUB_PERSONAL_ACCESS_TOKEN
```

Le token est chargé depuis la variable d'environnement `GITHUB_PERSONAL_ACCESS_TOKEN`.

---

## Système de permissions

**Décision :** Implémenter un système de permissions pour les outils MCP.

**Justification :**

1. **Sécurité :** Prévenir l'exécution inattendue d'outils qui pourraient être dangereux
2. **Contrôle :** Donner aux utilisateurs le contrôle sur quels outils peuvent être exécutés
3. **Transparence :** Les utilisateurs savent quand un outil MCP est sur le point de s'exécuter

**Modes :**

- `ask` : Demande à l'utilisateur avant d'exécuter chaque outil MCP (par défaut)
- `auto` : Exécute les outils MCP automatiquement sans demande

**Configuration globale :**

```yaml
mcp:
  permissions: ask  # Mode par défaut pour tous les serveurs
```

**Configuration par serveur :**

```yaml
servers:
  - name: github
    permissions: auto  # Remplace le mode global pour ce serveur
```

---

## Gestion des erreurs

**Décision :** Gérer les erreurs MCP de manière transparente avec des messages clairs.

**Justification :**

1. **Expérience utilisateur :** Les utilisateurs doivent comprendre pourquoi un outil a échoué
2. **Débogage :** Les messages d'erreur clairs aident à diagnostiquer les problèmes
3. **Résilience :** Mini-me doit continuer à fonctionner même si un serveur MCP échoue

**Stratégie :**

- **Erreurs de configuration** : Détectées au démarrage, affichées comme avertissements
- **Erreurs de connexion** : Le serveur est ignoré avec un avertissement
- **Erreurs d'exécution** : Retournées à l'utilisateur avec un message clair
- **Erreurs de timeout** : Gérées comme des échecs de connexion

---

## Parsing SSE

**Décision :** Implémenter un parseur SSE (Server-Sent Events) robuste pour les réponses MCP.

**Justification :**

1. **Spécification MCP :** Le protocole MCP utilise SSE pour la communication
2. **Fiabilité :** Le parsing doit gérer les événements partiels, les erreurs, les timeouts
3. **Performance :** Le parsing doit être efficace pour ne pas ralentir les requêtes

**Implémentation :**

Le parseur SSE de mini-me gère :
- Les événements complets
- Les événements partiaux (streaming)
- Les erreurs de parsing
- Les timeouts

---

## Voir aussi

- [Architecture MCP](architecture.md)
- [Configuration MCP](reference/configuration.md)
- [Outils MCP disponibles](reference/outils-disponibles.md)