182 lines
7.0 KiB
Markdown
182 lines
7.0 KiB
Markdown
# 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,
|
|
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.
|
|
|
|
## 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 ».
|
|
|
|
## 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` | 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`).
|