# 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_\LocalCache\Roaming\Claude\claude_desktop_config.json` (le `` 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`).