259 lines
11 KiB
Markdown
259 lines
11 KiB
Markdown
# crowdlending-mcp-server
|
|
|
|
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.
|
|
|
|
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)
|
|
- Une clé API générée dans l'app : **Mon compte → Clés API → Nouvelle clé**
|
|
- Le backend accessible (en local `http://localhost:4000`, ou l'URL de votre
|
|
instance en production)
|
|
|
|
## Installation
|
|
|
|
```
|
|
cd mcp-server
|
|
npm install
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Trois variables d'environnement :
|
|
|
|
| Variable | Obligatoire | Défaut | Exemple |
|
|
|---|---|---|---|
|
|
| `CROWDLENDING_API_KEY` | oui | — | `clk_live_...` |
|
|
| `CROWDLENDING_API_URL` | non | `http://localhost:4000/api/v1` | `https://mon-domaine.fr/api/v1` |
|
|
| `CROWDLENDING_LABEL` | non | — | `dev`, `prod` |
|
|
|
|
`CROWDLENDING_LABEL` sert uniquement à distinguer plusieurs instances
|
|
connectées en même temps (voir [Faire tourner dev et prod en même
|
|
temps](#faire-tourner-dev-et-prod-en-même-temps)) : il apparaît dans le nom
|
|
du serveur, dans le titre de chaque outil (`[DEV]` / `[PROD]`) et dans la
|
|
description (avec l'URL API ciblée), pour que l'agent — et vous — sachiez
|
|
toujours quel environnement est interrogé.
|
|
|
|
## Utiliser avec Claude Desktop
|
|
|
|
Localisez le fichier de config Claude Desktop — le chemin diffère selon la
|
|
provenance de l'installation Windows :
|
|
|
|
- **Installeur classique** (téléchargé depuis claude.ai) :
|
|
`%APPDATA%\Claude\claude_desktop_config.json`
|
|
- **Microsoft Store** : Windows redirige `%APPDATA%` vers un dossier virtualisé
|
|
propre à l'app —
|
|
`%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json`
|
|
(le `<id>` est un identifiant généré, propre à votre installation).
|
|
|
|
Le plus fiable dans les deux cas : Réglages → Développeur → Serveurs MCP
|
|
locaux → **Modifier la config**, qui ouvre directement le bon fichier quelle
|
|
que soit la provenance de l'installation.
|
|
|
|
Ajoutez une entrée dans `mcpServers` :
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"crowdlending": {
|
|
"command": "node",
|
|
"args": ["C:\\dev\\crowdlending-app\\mcp-server\\index.js"],
|
|
"env": {
|
|
"CROWDLENDING_API_KEY": "clk_live_...",
|
|
"CROWDLENDING_API_URL": "http://localhost:4000/api/v1"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Redémarrez Claude Desktop. L'icône 🔌 (ou le menu des outils MCP) doit
|
|
afficher les 7 outils `crowdlending_*` ci-dessous.
|
|
|
|
Pour pointer vers votre instance de production plutôt que le backend local,
|
|
changez uniquement `CROWDLENDING_API_URL` (et utilisez une clé API générée
|
|
sur cette instance).
|
|
|
|
## Faire tourner dev et prod en même temps
|
|
|
|
Claude Desktop peut se connecter à plusieurs serveurs MCP simultanément : il
|
|
suffit de déclarer deux entrées avec des clés distinctes dans `mcpServers`.
|
|
Chaque outil est alors automatiquement rattaché à son serveur d'origine —
|
|
pas de collision technique possible entre les deux, même si les noms
|
|
d'outils (`crowdlending_get_dashboard`, etc.) sont identiques des deux côtés.
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"crowdlending-dev": {
|
|
"command": "node",
|
|
"args": ["C:\\dev\\crowdlending-app\\mcp-server\\index.js"],
|
|
"env": {
|
|
"CROWDLENDING_API_KEY": "clk_live_...",
|
|
"CROWDLENDING_API_URL": "http://localhost:4000/api/v1",
|
|
"CROWDLENDING_LABEL": "dev"
|
|
}
|
|
},
|
|
"crowdlending-prod": {
|
|
"command": "node",
|
|
"args": ["C:\\dev\\crowdlending-app\\mcp-server\\index.js"],
|
|
"env": {
|
|
"CROWDLENDING_API_KEY": "clk_live_...",
|
|
"CROWDLENDING_API_URL": "https://mon-domaine.fr/api/v1",
|
|
"CROWDLENDING_LABEL": "prod"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Utilisez deux clés API différentes (une par instance, générées séparément
|
|
sur chaque backend) : ça permet de révoquer l'une sans affecter l'autre, et
|
|
c'est cohérent avec le principe d'une clé par usage.
|
|
|
|
Avec `CROWDLENDING_LABEL` renseigné, chaque outil affiche son environnement
|
|
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
|
|
de lister et appeler les outils depuis une interface web, sans configurer de
|
|
client :
|
|
|
|
```
|
|
CROWDLENDING_API_KEY=clk_live_... npm run inspect
|
|
```
|
|
|
|
## Outils exposés
|
|
|
|
Tous en lecture seule (`readOnlyHint: true`) :
|
|
|
|
| Outil | Description |
|
|
|---|---|
|
|
| `crowdlending_get_investisseur` | Profil de l'investisseur lié à la clé |
|
|
| `crowdlending_get_dashboard` | Synthèse KPI : capital investi, capital en risque, intérêts perçus (filtrable par année), cash |
|
|
| `crowdlending_list_investissements` | Liste des investissements, filtrable par statut |
|
|
| `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` | *(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`)
|
|
|
|
Cet outil récupère une page web et en extrait le contenu lisible (titre +
|
|
texte principal) via [Readability](https://github.com/mozilla/readability),
|
|
la librairie du mode lecture de Firefox — menus, pubs, scripts et bandeaux
|
|
cookies sont éliminés automatiquement.
|
|
|
|
Il ne fait **aucune extraction métier** côté serveur (pas de tentative de
|
|
deviner taux/montant/durée par regex) : c'est l'agent qui lit le texte
|
|
retourné et en extrait les informations pertinentes dans la conversation,
|
|
pour vous les proposer avant toute saisie. Cohérent avec le reste du
|
|
serveur : lecture seule, aucune création automatique d'investissement (l'API
|
|
v1 n'a pas de capacité d'écriture).
|
|
|
|
Exemple d'usage : *« Regarde cette page et propose-moi les infos pour créer
|
|
l'investissement : https://plateforme.fr/projets/xxx »*.
|
|
|
|
Garde-fous :
|
|
- http/https uniquement, pages HTML uniquement.
|
|
- Hôtes locaux/privés bloqués (`localhost`, `127.0.0.1`, plages `10.x`/`172.16-31.x`/`192.168.x`...) —
|
|
l'outil ne peut pas cibler votre réseau local, y compris votre propre backend.
|
|
- Texte tronqué à 8000 caractères sur les pages très longues (le champ
|
|
`truncated` de la réponse l'indique).
|
|
|
|
## Dépannage
|
|
|
|
- **`ERREUR : CROWDLENDING_API_KEY est requise`** — la variable d'env n'est
|
|
pas transmise. Vérifiez la section `env` de votre config MCP.
|
|
- **`Clé API invalide ou révoquée`** — régénérez une clé dans Mon compte →
|
|
Clés API et mettez à jour la config.
|
|
- **`Impossible de joindre l'API`** — le backend n'est pas démarré, ou
|
|
`CROWDLENDING_API_URL` pointe au mauvais endroit (vérifiez le port et le
|
|
suffixe `/api/v1`).
|