MCP Distant

mcp-server/README.md

@@ -1,7 +1,7 @@
 # crowdlending-mcp-server
 
-Serveur MCP local (stdio) pour le portefeuille de crowdlending. Il expose en
-lecture seule les données d'un investisseur (investissements, remboursements,
+Serveur MCP pour le portefeuille de crowdlending. Il expose en lecture seule
+les données d'un investisseur (investissements, remboursements,
 dépôts/retraits, dashboard) à un client MCP — Claude Desktop, Claude Code,
 ou tout autre client compatible — en s'appuyant sur l'API publique `/api/v1`
 du backend.
@@ -9,6 +9,21 @@ du backend.
 Il ne fait aucune écriture : toutes les modifications restent à faire dans
 l'app web.
 
+Deux modes, deux fichiers :
+
+- **Local (`index.js`, stdio)** — lancé comme process enfant par Claude
+  Desktop sur votre propre machine. Nécessite Node.js et ce dépôt cloné en
+  local. Inclut l'outil `crowdlending_fetch_url` (lecture de page web).
+- **Distant (`http-server.js`, HTTP)** — un service déployé une fois (par
+  l'administrateur de l'instance) sur `mcp.crowdlending.croguennec.net`,
+  accessible à n'importe quel utilisateur distant sans rien installer :
+  juste une URL + sa clé API personnelle à coller dans son client MCP.
+  N'inclut PAS `crowdlending_fetch_url` (voir plus bas).
+
+Les deux partagent le même code pour les 6 outils de lecture de données
+(`tools.js`) — leur comportement ne peut donc pas diverger entre les deux
+modes.
+
 ## Prérequis
 
 - Node.js ≥ 18 (fetch natif requis)
@@ -122,6 +137,68 @@ dans son titre (ex. « Synthèse du portefeuille [PROD] ») et sa description
 se termine par la source exacte interrogée — de quoi lever toute ambiguïté
 si vous demandez « mon encours en prod » vs « mon encours en dev ».
 
+## Serveur distant — pour les utilisateurs sans installation locale
+
+Si vous n'êtes pas sur la machine qui héberge ce dépôt (pas de Node.js, pas
+envie de cloner le repo), vous pouvez vous connecter directement au serveur
+MCP distant déployé sur `https://mcp.crowdlending.croguennec.net` — aucune
+installation nécessaire, juste votre clé API personnelle.
+
+**1. Créer votre clé API** — dans l'app, Mon compte → Clés API → Nouvelle
+clé (elle ne sera affichée qu'une seule fois, copiez-la).
+
+**2. Ajouter le serveur dans Claude Desktop** — Réglages → Développeur →
+Serveurs MCP locaux → Modifier la config, puis ajoutez :
+
+```json
+{
+  "mcpServers": {
+    "crowdlending-distant": {
+      "url": "https://mcp.crowdlending.croguennec.net/mcp",
+      "headers": {
+        "X-API-Key": "clk_live_..."
+      }
+    }
+  }
+}
+```
+
+**3. Redémarrez Claude Desktop.** Les 6 outils `crowdlending_*` doivent
+apparaître (sans `crowdlending_fetch_url`, réservé au serveur local).
+
+### Différences avec le serveur local
+
+- **Pas de `crowdlending_fetch_url`** : lire une page web arbitraire pour un
+  utilisateur tiers non maîtrisé augmenterait le risque SSRF sans bénéfice
+  réel pour ce cas d'usage. Cet outil reste réservé au serveur local.
+- **Authentification par requête, pas par process** : le serveur local a une
+  clé API fixée une fois pour toutes via une variable d'environnement — un
+  process = un utilisateur. Le serveur distant sert plusieurs utilisateurs en
+  parallèle : chaque session est créée à partir de la clé API envoyée dans
+  l'en-tête `X-API-Key` de la requête qui l'initialise, puis liée à cette
+  session uniquement. Deux utilisateurs ne partagent jamais de données.
+- **Exposé publiquement, sans la liste blanche d'IP** qui protège le reste de
+  l'app (`ipwhitelist-all`) : la clé API est la seule barrière d'accès.
+  Traitez-la comme un mot de passe — ne la partagez pas, révoquez-la
+  immédiatement en cas de doute (Mon compte → Clés API).
+- **Limite de débit** : 60 requêtes/minute par adresse IP, au-delà l'API
+  répond `429`.
+- **Sessions** : une session inactive plus de 30 minutes est fermée côté
+  serveur (mémoire uniquement, aucune persistance) ; votre client MCP en
+  recréera une automatiquement à la prochaine requête.
+
+### Déploiement (administrateur de l'instance)
+
+Le service `crowdlending-mcp` du `docker-compose.yml` construit et lance
+`http-server.js`, exposé via Traefik sur `mcp.crowdlending.croguennec.net`
+(certificat TLS automatique, même resolver que le reste de l'app). Un
+enregistrement DNS pour ce sous-domaine, pointant vers la même IP que
+`crowdlending.croguennec.net`, est nécessaire avant le premier déploiement.
+Variables d'environnement du service : `CROWDLENDING_API_URL` (URL interne
+du backend sur le réseau Docker, déjà configurée) et `MCP_ALLOWED_HOSTS`
+(validation de l'en-tête `Host`, protection anti DNS-rebinding — doit
+correspondre exactement au(x) nom(s) de domaine exposé(s)).
+
 ## Tester sans Claude Desktop
 
 Le [MCP Inspector](https://github.com/modelcontextprotocol/inspector) permet
@@ -144,7 +221,7 @@ Tous en lecture seule (`readOnlyHint: true`) :
 | `crowdlending_get_investissement` | Détail d'un investissement + ses remboursements |
 | `crowdlending_list_remboursements` | Historique des remboursements, filtrable par période |
 | `crowdlending_list_depots_retraits` | Historique des mouvements de cash |
-| `crowdlending_fetch_url` | Lit une page web (annonce de projet) et en extrait le texte propre — voir ci-dessous |
+| `crowdlending_fetch_url` | *(serveur local uniquement)* Lit une page web (annonce de projet) et en extrait le texte propre — voir ci-dessous |
 
 ## Lire une annonce de projet (`crowdlending_fetch_url`)