# Serveur MCP de notes techniques

Serveur exposant quatre outils à un agent IA via le Model Context
Protocol. L'agent découvre les outils disponibles et décide lui-même
lesquels appeler selon la demande de l'utilisateur.

## Le principe

Le MCP est un standard ouvert publié par Anthropic pour connecter des
modèles à des outils et des sources de données externes. Sans lui,
chaque intégration est spécifique à un client. Avec lui, un même serveur
fonctionne avec Claude Desktop, Claude Code, Cursor ou n'importe quel
client compatible.

L'architecture est simple. Le serveur déclare des outils avec leur nom,
leur description et leurs paramètres. Le client interroge le serveur pour
connaître les outils disponibles, les présente au modèle, et le modèle
décide quand les appeler. Le serveur exécute et renvoie le résultat.

## Les outils exposés

| Outil | Rôle |
|---|---|
| `rechercher_notes` | Recherche plein texte, renvoie des extraits contextualisés |
| `lire_note` | Lit une note complète |
| `creer_note` | Crée une note à partir d'un titre et d'un contenu |
| `lister_notes` | Liste les notes les plus récemment modifiées |

## Installation

```bash
pip install mcp
python server.py
```

Le dossier des notes est `./notes` par défaut. Il peut être changé avec
la variable `NOTES_DIR`.

## Branchement sur Claude Code

```bash
claude mcp add notes-techniques -- /chemin/absolu/.venv/bin/python /chemin/absolu/server.py
claude mcp list
```

Pointer vers le Python de l'environnement virtuel et non vers le Python
système, sinon le paquet `mcp` ne sera pas trouvé.

Une fois enregistré, l'agent choisit lui-même l'outil à appeler. Une
demande formulée en langage naturel comme « cherche dans mes notes ce qui
concerne le chunking » déclenche un appel à `rechercher_notes` avec le
bon paramètre, sans que l'outil soit nommé.

## Branchement sur Claude Desktop

Ajouter dans le fichier de configuration de Claude Desktop :

```json
{
  "mcpServers": {
    "notes-techniques": {
      "command": "python",
      "args": ["/chemin/absolu/vers/server.py"],
      "env": { "NOTES_DIR": "/chemin/absolu/vers/notes" }
    }
  }
}
```

Le fichier se trouve dans `~/Library/Application Support/Claude/` sur
macOS et dans `%APPDATA%\Claude\` sur Windows. Redémarrer l'application
après modification.

## Les choix de conception

**Validation des chemins.** La fonction `_chemin_sur` vérifie que toute
note demandée reste dans le dossier prévu. Sans ce contrôle, un agent
pourrait demander `../../etc/passwd`. C'est le point le plus important
du serveur : un outil exposé à un modèle doit valider ses entrées comme
s'il était exposé à un utilisateur non fiable. Le modèle n'est pas
malveillant, mais il peut être manipulé par le contenu qu'il traite.

**Extraits plutôt que documents entiers.** La recherche renvoie le
contexte autour de l'occurrence trouvée, pas la note complète. Renvoyer
tout saturerait la fenêtre de contexte du modèle et dégraderait ses
réponses.

**Descriptions soignées.** Chaque outil a une docstring explicite, parce
que c'est elle que le modèle lit pour décider s'il doit l'appeler. Une
description vague produit des appels au mauvais moment. C'est du prompt
engineering appliqué à la définition d'outils.

**Messages d'erreur utiles.** Quand une note est introuvable, le serveur
renvoie la liste des notes disponibles. L'agent peut alors se corriger
seul au lieu d'échouer.

## Ce qui manquerait en production

Une gestion des droits, pour qu'un utilisateur n'accède qu'aux notes
qui le concernent.

Une limitation du nombre d'appels, pour éviter qu'un agent en boucle ne
sature le service.

Une journalisation des appels, indispensable pour comprendre après coup
ce qu'un agent a fait.

Une confirmation explicite avant les actions destructrices. Ici la
création est sans risque, mais une suppression devrait demander
validation à l'utilisateur plutôt que d'être décidée par le modèle.